Skip to content

docs(unstable-v2): send a new session's non-idle state after the response - #2871

Merged
benbrandt merged 1 commit into
mainfrom
docs/v2-new-session-state-after-response
Nov 18, 2026
Merged

benbrandt merged 1 commit into
mainfrom
docs/v2-new-session-state-after-response

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Summary

A new session defaults to idle. An Agent that starts work when the session is created reports running with a state_update, and that update may be sent before the session/new response. The same paragraph lets a Client drop notifications for a sessionId it does not know yet. A Client that drops them stays on the idle default while the Agent has reported running.

The response cannot close this gap, because it has no state field. This adds one rule for the Agent, which controls the order of its own messages.

Changes

  • Session setup: an Agent whose new session is not idle MUST send the session's state_update after the session/new response. Changed in the stable page and its draft/ copy.
  • Prompt lifecycle: the "Initial state and synchronization" section says state updates may arrive before or after the response. It now points to the rule. It adds no requirement of its own.
  • Schema description: the NewSessionResponse description already stated the Client half of this paragraph. It now states the Agent rule too. This regenerates schema/v2/schema.json, schema/v2/schema.unstable.json and both schema.mdx pages. Only the description text changes.

Notes

  • Clients are not required to buffer early updates. A Client cannot check a sessionId before the response names it.
  • The rule covers the state only. Other updates sent before the response stay under the existing SHOULD.
  • claude-agent-acp already holds its post-setup work until the response is sent, and codex-acp sends nothing for a new session before the response.

Checks

  • cargo clippy in the three configurations from npm run check, cargo test --all-features, and rustdoc with -D warnings pass.
  • Regenerating the schema a second time produces no diff.
  • Prettier, cargo fmt, the spellcheck script, and the link check pass.

…onse

A `state_update` for a new session may arrive before the `session/new`
response, and a Client may drop notifications for a `sessionId` it does
not know yet. The response cannot carry the state, so a Client that
drops early updates stays on the `idle` default while the Agent has
reported `running`.

- Require an Agent whose new session is not `idle` to send the
  session's `state_update` after the response.
- Point to the rule from the session states section of the prompt
  lifecycle page.
- State the rule in the `NewSessionResponse` schema description, which
  already carried the Client half of the paragraph.
@benbrandt
benbrandt requested a review from a team as a code owner November 18, 2026 12:42
@benbrandt
benbrandt enabled auto-merge (squash) November 18, 2026 12:43
@benbrandt
benbrandt merged commit e18f386 into main Nov 18, 2026
13 checks passed
@benbrandt
benbrandt deleted the docs/v2-new-session-state-after-response branch November 18, 2026 12:47
@acp-release-bot acp-release-bot Bot mentioned this pull request Nov 18, 2026
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