Skip to content

fix: match a permission request to background work by its session - #353

Merged
benbrandt merged 2 commits into
mainfrom
protocol-followups-2.8
Nov 18, 2026
Merged

benbrandt merged 2 commits into
mainfrom
protocol-followups-2.8

Conversation

@benbrandt

@benbrandt benbrandt commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

What is left of the v2 protocol docs follow-up after #351. That PR landed the -32601 default for tool_call/cancel and terminal/cancel, the example agent's systemPrompt check, and the handler docs for both. This branch now merges main and keeps only what #351 does not have.

Behavior change

ActiveSession.isForBackgroundWork

It compared the subject of any permission request with the session's listed tool calls and terminals. Those IDs are scoped to the session that reports them, so a child session's request with the same toolCallId as a listed tool call of the parent matched.

It now compares subjects only for a request of its own session. A request of another session is for listed work when that session is a listed subagent. A request of any other session, such as a listed child's own child, returns false, which the doc already describes as "not established".

Handler and module docs

  • tool_call/cancel, terminal/cancel: a child session that the Agent announced is not an unknown session, and sessionId names the child for an item that the child reports.
  • session/new: the app sends the response once the handler's promise settles, so a notification sent inside the handler goes out before it.
  • session/resume: each child session that a replay announces gets its own replay_complete, and the parent's replay_complete separates a replayed subagent_update from a current one. A child's sessionId is rejected with -32602.
  • session/cancel: the notification can name a child, is ignored for a child that does not advertise cancel, and covers the descendant work that the cancelled work waits on.
  • session/prompt: how long an idempotencyKey is recognized, for a retained message and for one that is not.
  • session/fork: the fork does not share its source's keys.

src/v2/stable/* is regenerated from src/v2/*.

Found, not fixed here

These need a decision first.

  • Child sessions over Streamable HTTP. The server routes each outbound message with a sessionId to that session's stream, and buffers it until the client opens a stream for that ID. A client opens one for a session it created or resumed, never for a child. So a child's updates and permission requests are not delivered, and the permission request stays pending. WebSocket and stdio deliver them. The transport RFD does not say where a child's traffic goes.
  • No after-response hook. A request handler cannot run code after its response is sent. An Agent that must send a state after the session/new response needs a timer.
  • ActiveSession and child sessions. nextUpdate() delivers only updates of the session's own sessionId, and an ActiveSession can only come from session/new, not from session/resume.

Tests

  • acp.test.ts: isForBackgroundWork is true for a request of a listed child, and false for a request of another session that names a listed ID.

npm run check passes.

… handler

Follows the v2 protocol docs that landed after schema v2.0.0-alpha.17.

A v2 agent app without a handler for `tool_call/cancel` or
`terminal/cancel` answered every such request with `-32602`. The protocol
now says that `-32602` is the answer of an Agent that implements the
method, and that such a request for an unknown session gets `-32002`, which
the default could not know. An app without the handler does not implement
the method, so it now answers `-32601`, as for any other method. An Agent
that advertises `capabilities.cancel` on a tool call or terminal registers
the handler.

- `ActiveSession.isForBackgroundWork` compares a request's subject with
  the listed tool calls and terminals only for a request of its own
  session, because those IDs are scoped to the session that reports them.
  A request of a child session is for listed work when the child is a
  listed `subagent`.
- The dual-version example agent rejects a `systemPrompt` with `-32602`
  and creates or resumes no session. It advertises no
  `session.systemPrompt`, and it used to ignore the field.
- Handler docs: the error codes of the two cancel requests, `-32602` for a
  `systemPrompt` the Agent cannot apply, a new session's non-idle state
  after the `session/new` response, the `replay_complete` of each replayed
  child session, the child session rules of `session/cancel`, how long an
  `idempotencyKey` is recognized, and that a fork does not share its
  source's keys.
@benbrandt benbrandt changed the title fix: answer -32601 for tool_call/cancel and terminal/cancel without a handler fix: match a permission request to background work by its session Nov 18, 2026
@benbrandt
benbrandt enabled auto-merge (squash) November 18, 2026 15:51
@benbrandt
benbrandt merged commit 91fb159 into main Nov 18, 2026
6 checks passed
@benbrandt
benbrandt deleted the protocol-followups-2.8 branch November 18, 2026 15:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant