Skip to content

docs(unstable-v2): require -32602 for a systemPrompt the Agent cannot apply - #2870

Merged
benbrandt merged 1 commit into
mainfrom
docs/v2-system-prompt-error-code
Nov 18, 2026
Merged

benbrandt merged 1 commit into
mainfrom
docs/v2-system-prompt-error-code

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Summary

Two v2 pages disagreed on the error code for a systemPrompt the Agent cannot apply.

  • The extensibility page says a request that cannot be fulfilled without understanding an unknown variant MUST be rejected with -32602.
  • The system prompt rule and the error page required an error but only recommended -32602, including for an unadvertised mode or an unsupported content block type.

This makes -32602 required in the system prompt rule. The related rules for an unadvertised MCP transport and an unadvertised prompt content type already require it.

Changes

  • Session setup: when the systemPrompt value is the cause (an unadvertised mode, an unsupported content block type, or content that exceeds the Agent's limits), the error MUST be -32602. The Agent still MUST return an error and MUST NOT create or resume the session for any systemPrompt it cannot apply.
  • Error page: the sentence that called -32602 recommended now lists the same three causes as getting -32602.
  • Migration guide: one new bullet in "Errors", with the other rules that were SHOULD in v1 and are MUST in v2.

The session setup and error pages are changed in the stable page and its draft/ copy. v1 is unchanged.

Notes

  • Content that exceeds the Agent's limits is not an unknown variant, so the extensibility rule did not already cover it. It is included so one rule covers every case where the value is the cause.
  • claude-agent-acp and codex-acp already answer -32602 for each systemPrompt they reject.

Checks

  • Prettier and typos pass on the changed files.
  • All links and anchors in the changed files resolve.

… apply

The extensibility page requires `-32602` for a request that cannot be
fulfilled without understanding an unknown variant. The system prompt
rule only recommended that code for an unadvertised mode or an
unsupported content block type.

- Require `-32602` when the `systemPrompt` value is the cause: an
  unadvertised mode, an unsupported content block type, or content that
  exceeds the Agent's limits.
- Drop the "recommended" wording from the error page.
- List the rule in the migration guide with the other error rules that
  were SHOULD in v1 and are MUST in v2.
@benbrandt
benbrandt requested a review from a team as a code owner November 18, 2026 12:33
@benbrandt
benbrandt enabled auto-merge (squash) November 18, 2026 12:34
@benbrandt
benbrandt merged commit 3c0a15b into main Nov 18, 2026
10 checks passed
@benbrandt
benbrandt deleted the docs/v2-system-prompt-error-code branch November 18, 2026 12:38
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