# Functional Requirements — VS Code Copilot Telegram Hook

## Provenance

- Kind: derived functional specification.
- Derived from:
    - [`h-001-original-requirement-brief.md`](./h-001-original-requirement-brief.md)
    - [`h-002-human-confirmation-2026-03-13.md`](./h-002-human-confirmation-2026-03-13.md)
    - [`h-003-human-confirmation-2026-03-13-addendum.md`](./h-003-human-confirmation-2026-03-13-addendum.md)
    - [`h-004-human-confirmation-2026-03-14.md`](./h-004-human-confirmation-2026-03-14.md)
    - [`h-007-human-confirmation-2026-03-14-same-host-vscode-settings-targets.md`](./h-007-human-confirmation-2026-03-14-same-host-vscode-settings-targets.md)
    - [`h-008-human-confirmation-2026-03-16-stop-blocking-summary-flow.md`](./h-008-human-confirmation-2026-03-16-stop-blocking-summary-flow.md)
    - [`h-009-human-confirmation-2026-07-25-root-lifecycle-notifications.md`](./h-009-human-confirmation-2026-07-25-root-lifecycle-notifications.md)
        - [`nonfunctional-and-constraints-research.md`](./nonfunctional-and-constraints-research.md)
        - [`vscode-hook-inputs-research.md`](./vscode-hook-inputs-research.md)
- Purpose: translate the human-authored source inputs and supporting research
  into product-facing functional requirements.

This document defines **functional requirements only** for the VS Code GitHub Copilot Telegram hook solution in this project.

Non-functional requirements and implementation constraints are intentionally excluded from this document and are tracked separately in [`nonfunctional-and-constraints-research.md`](./nonfunctional-and-constraints-research.md).

Unless explicitly stated otherwise, this document does not standardize any
particular script structure, storage mechanism, or internal field name. The
per-turn `summary.json` handoff path and fields described below are part of the
supported notification contract.

## Terms

- **Chat turn**: one user request and Copilot response cycle that ends when Copilot attempts to stop for the current turn.
- **Session**: a VS Code GitHub Copilot chat session, which may contain multiple chat turns.
- **Root session**: the user-facing agent session that coordinates the current
  task and waits for the user's next instruction.
- **Subagent session**: a nested, background, reviewer, or other tool-call agent
  session whose completion is consumed by the root session.
- **Workspace**: the current working folder used by VS Code when running hooks.
- **Correlation context**: the data used to associate summary generation and Telegram delivery with the correct Copilot session and workspace.
- **Tracked result**: the completed turn result that the solution correlates across summary generation and Telegram delivery.
- **Summary record**: summary content prepared for a tracked result before
  notification delivery. For the assigned per-turn handoff, this is the
  `summary.json` file named by the Notification Assignment.

## Functional Scope

The solution shall provide a formally supported user-level capability for VS
Code GitHub Copilot that sends Telegram notifications to one configured
Telegram destination when the root agent finishes its current work and waits
for further user instructions, or when the root agent requests user input
through `ask_user`. Subagent lifecycle events shall not notify the user.

## Functional Requirements

### FR-001 User-level availability

The solution shall provide a user-level installation flow that makes the notification capability available across the user's VS Code workspaces.

### FR-002 User-level artifact and delivery configuration installation

The installation flow shall install or configure all user-level artifacts and delivery inputs required for:

1. hook execution, and
2. Telegram notification delivery.

This includes the Telegram bot token and target chat identifier required for notification authentication and routing.

For the supported same-host runtime styles, the installation flow shall also
register the managed user-level hook file in each VS Code settings target
required for user-level hook discovery on that host. For the current product
direction, this includes the host-local desktop VS Code settings target and the
VS Code Server Machine settings target on Linux hosts that may be used for the
same user's desktop and server-backed VS Code sessions, even when the server
settings file is not already present.

### FR-003 Correlation capability

The solution shall maintain enough correlation context to associate each summary record and Telegram notification with the correct Copilot session and workspace.

### FR-004 Correlation context persistence

The correlation context required for summary generation and Telegram delivery shall remain available across the hook invocations that participate in that flow.

### FR-005 Correlation data contents

The correlation context shall provide, at minimum, enough information to distinguish:

- the current workspace,
- the current Copilot session,
- the tracked result represented by the summary record, and
- which result is the newer one when multiple turn results exist.

### FR-006 Summary availability

The solution shall make summary content available for the current tracked result before final notification delivery is attempted, or otherwise surface that the summary is missing.

### FR-007 Summary handoff minimum capability

The summary handoff for a tracked result shall support, at minimum:

- a human-readable summary message when available,
- an explicit missing-summary indication when no summary is available, and
- any implementation-defined correlation or recency data needed internally for delivery coordination.

### FR-008 Summary handoff behavior

The solution shall provide a way for Copilot to update the summary content before it finishes work for the current chat turn.

### FR-009 Default non-blocking summary fallback

When the current tracked result's summary record is missing or invalid at
`Stop`, the default behavior shall not block stopping. If the missing or invalid
record represents a pending handoff that may still satisfy the same `Stop`, the
solution may defer notification without sending a fallback indefinitely while it
remains unresolved. Otherwise, the solution shall send a degraded fallback
notification that explicitly indicates the summary is missing or unusable.
Strict/debug summary-recovery modes, if introduced later, are outside the
default functional scope.

### FR-010 No default Stop blocking

The default `Stop` hook behavior shall not return a blocking decision for
missing or invalid summary content. Bounded blocking recovery is superseded for
the default notification flow and remains out of scope unless a future
strict/debug mode explicitly opts into it.

### FR-011 Assigned summary handoff contract

Notification delivery shall validate the assigned per-turn `summary.json` path
from the Notification Assignment. A completed delivery summary requires matching
`session_id`, `notification_turn_id`, and `notification_nonce`, a valid
UTC `updated_at` timestamp, and a non-empty human-readable `summary`. Pending and
degraded handling shall follow the Stop fallback rules in FR-009 and FR-015.

### FR-012 Summary language preference

The solution shall treat Chinese as the preferred notification-summary language on a best-effort basis. Notification delivery shall not depend on the available summary being Chinese text, and any additional structure beyond the human-readable summary text is implementation-defined.

### FR-013 Root completion detection

When the root Copilot session reaches a `Stop` event after completing its current
work, the solution shall attempt Telegram completion notification delivery.

### FR-014 Stop-event interpretation

For this solution, the completion trigger shall correspond to the point where
the root agent attempts to stop and wait for the user's next instruction. A
subagent attempting to stop is not a user notification trigger.

### FR-015 Missing-summary fallback

If the current root `Stop` event does not have usable summary content and no pending
handoff can still satisfy that `Stop`, the solution shall still send a
notification and shall explicitly indicate that the summary is missing. Pending
handoffs may defer notification without fallback while unresolved.

### FR-016 Telegram delivery target

The solution shall send notifications to a single Telegram destination per
user-level installation, identified by a bot token and a target chat
identifier.

### FR-017 Credential resolution for delivery

Before sending a notification, the solution shall resolve the credentials required to call the Telegram Bot API.

### FR-018 Notification format

The solution shall format the outgoing notification using a Telegram HTML-compatible text representation.

### FR-019 Required notification contents

Each notification shall include, at minimum:

- a human-readable completion or attention heading,
- either the concise completion summary, the `ask_user` question, or an explicit
  missing-content notice,
- a delivery timestamp, and
- enough identifying context to distinguish the delivered result from other notifications for the same workspace or session.

If the notification content for a tracked result cannot fit into a single
Telegram message while remaining valid under Telegram formatting rules, the
solution shall preserve the heading and identifying context and continue the
summary across additional Telegram messages.

### FR-020 Context enrichment

When available, each notification shall also include relevant execution context such as:

- Copilot session identifier,
- host name,
- execution environment,
- workspace path,
- repository display name,
- branch name,
- commit identifier, and
- transcript path.

### FR-021 Optional structured summary preview

When the implementation makes additional structured summary content available, the notification may include preview entries from that content.

### FR-022 Best-effort duplicate suppression

The solution shall prioritize notification delivery and limited retry over
perfect duplicate suppression. Duplicate suppression for the same root
completion or `ask_user` tool call shall be durable and best-effort.

### FR-023 Delivery opportunity for later turns

Each new root `Stop` event shall create a new delivery opportunity, including
later root turns in the same session. Subagent `Stop` events shall not.

### FR-024 Workspace isolation

The solution shall keep session correlation data and notification coordination state isolated per workspace.

### FR-025 Repository context probing

The solution shall inspect the current workspace to determine repository metadata when such metadata is available.

### FR-026 Operation without full repository metadata

The solution shall still be able to produce a notification when repository metadata is partially unavailable or missing.

### FR-027 Multi-turn session behavior

A single root Copilot session may produce multiple completion notifications over
time, provided that each notification corresponds to a distinct completed root
turn result.

### FR-028 Latest-result clarity

The summary handoff mechanism shall make the latest known summary unambiguous when multiple turn results exist for the same tracked context.

### FR-029 Persistent coordination state

The solution shall preserve sufficient persistent correlation and coordination state across hook invocations so that:

1. correlation,
2. summary generation, and
3. Telegram delivery

can coordinate without requiring in-memory state to survive across hook invocations.

### FR-030 Subagent notification suppression

The solution shall suppress session-start, prompt, tool-attention, and
completion notification processing for identified subagent or tool-call
sessions. Suppressed sessions shall not create notification protocol state or
send Telegram messages.

### FR-031 Root user-input attention

When a root session invokes the `ask_user` tool, the solution shall send an
attention notification containing the user-facing question. Repeated hook
delivery for the same tool invocation shall not send another notification after
any Telegram message for that invocation has already been accepted.

## Required Summary Semantics

The Notification Assignment shall provide Copilot an exact assigned per-turn
`summary.json` path for the current tracked result. Copilot shall write only
that assigned path. A completed summary handoff is valid only when it contains:

- `session_id` matching the assigned session,
- `notification_turn_id` matching the assigned turn,
- `notification_nonce` matching the assigned nonce,
- `updated_at` as a valid UTC timestamp, and
- a non-empty human-readable `summary`, with Chinese preferred on a best-effort
  basis.

A handoff whose assigned summary is missing, unreadable, invalid JSON, JSON
`null`, or an exact pending summary for the same `Stop` is pending and may defer
notification without degraded fallback while unresolved. Non-pending invalid or
unusable handoffs may produce a degraded fallback only when no pending handoff
can satisfy the `Stop`. Any additional changed-file lists, outcome labels, or
next-step lists are implementation-defined rather than part of the product
contract.
