Upstream sync: post-v1.0.0-beta.4 round 5 (schema 1.0.55-1, postToolUseFailure)

[krukow]

_{Generated via Copilot on behalf of @krukow}

Summary

Extends the in-flight post-v1.0.0-beta.4 round 5 sync with two more upstream changes:

1. Schema bump 1.0.52 → 1.0.55-1 — picks up #1408, #1410, #1411, #1412, #1432. The schema regen surfaces two new canvas event types in the wire-only generated layer but those are intentionally not added to the curated public ::event-type set yet — the canvas runtime is deferred (see below).
2. :on-post-tool-use-failure hook (upstream #1421) — new lifecycle hook that fires after a tool execution whose result was "failure". :on-post-tool-use only fires for successful results, so register this handler to observe failed tool outcomes.

Round 5 (cumulative)

This PR is the full round 5 of the post-v1.0.0-beta.4 sync. The three earlier commits already on the branch:

Commit	Summary
22cc8fa	chore(schema): bump to 1.0.52-4 (upstream #1393)
73774e9	feat: drop v2 protocol back-compat + runtime_instructions + mcp_app event
78f6464	fix(docs): align customize-mode section list with specs; bump schema to 1.0.52

And the three new commits added in this iteration:

Commit	Summary
e527bc2	chore(schema): bump to 1.0.55-1 and surface canvas event types
cdd2f2e	feat(hooks): add :on-post-tool-use-failure lifecycle hook (upstream #1421)
ded2f19	fix(review): address multi-model review on schema bump

Changes

Added

• :on-post-tool-use-failure hook in the :hooks map. Input map: {:tool-name :tool-args :error :session-id :timestamp :cwd}. Optional return: {:additional-context "..."} — appended as hidden guidance to the model alongside the failed tool result. Other fields (e.g. :modified-result, :suppress-output) are not honored for failure hooks. Note: "rejected", "denied", and "timeout" results do not trigger this hook — only "failure" does.

Wiring sites for the new hook

• specs.clj: ::on-post-tool-use-failure fn? + added to ::hooks :opt-un
• session.clj: handle-hooks-invoke! case maps "postToolUseFailure" → :on-post-tool-use-failure
• client.clj: create-session docstring lists the new hook key
• doc/reference/API.md: hook example documents input/output shape
• CHANGELOG.md

Schema bump details

.copilot-schema-version advanced from 1.0.52 to 1.0.55-1. Regenerated src/github/copilot_sdk/generated/event_specs.clj from the bumped schemas. The new canvas event types (session.canvas.opened, session.canvas.registry_changed) appear in the wire-only generated.event-specs/event-types set but are not in the curated public ::event-type set, because their payloads include x-opaque-json fields (data.input, nested canvases[].inputSchema, canvases[].actions[].inputSchema) and we haven't yet implemented opaque-field preservation for canvas. Canvas event types and their preservation will land together when the canvas runtime is ported.

Deferred to a future round

• Canvas runtime support (#1401, #1413) — major new surface (canvases, requestCanvasRenderer, requestExtensions, extensionInfo, openCanvases, the canvas.ts module, ~700 LOC). Warrants its own dedicated review.
• Cross-SDK RPC E2E coverage (#1424) — upstream test infra only.

Validation

• bb test — 277 tests / 1325 assertions, 0 failures
• bb test with COPILOT_E2E_TESTS=true — same, with one pre-existing E2E flake unrelated to this PR (test-e2e-blob-attachment times out on an image-attachment send; reproduces on clean main from before these changes)
• ./run-all-examples.sh — all 23 example runs pass
• bb validate-docs — 13 files, 0 warnings
• bb jar — clean build

Multi-model review

Both reviewers cleared after one round:

Source	Finding	Decision
Claude Opus 4.7	CHANGELOG positional version/PR pairing was wrong for the first two items	Fixed in ded2f19
GPT-5.5	Canvas events declare x-opaque-json fields; surfacing them publicly without preservation would leak mangled JSON-Schema keys	Removed canvas events from the curated public set in ded2f19; deferred with rest of canvas runtime
GPT-5.5	toolArgs is not preserved as opaque for hook inputs — recursive wire->clj rewrites source-defined tool argument keys	Out of scope — pre-existing issue affecting preToolUse / postToolUse too; the new failure hook is consistent with its siblings. Tracked as a separate follow-up (see below).

Known follow-up

• toolArgs opacity for hook inputs — upstream types toolArgs: unknown, but protocol/normalize-incoming's hooks.invoke branch only preserves opaque fields for preMcpToolCall. Source-defined keys nested under :tool-args on preToolUse, postToolUse, and postToolUseFailure hook inputs are recursively kebab-cased. Pre-existing; affects all three sibling hooks identically. Worth tracking as a separate issue.

---

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> (commit trailer in commits only).

[Copilot]

Pull request overview

This PR completes round 5 of the post-v1.0.0-beta.4 upstream sync: it bumps the pinned upstream schema from 1.0.52 to 1.0.55-1 (regenerating wire-only event specs), raises the minimum supported CLI protocol version from 2 to 3 (removing the v2 tool.call / permission.request RPC dispatcher shims and their tests), and adds the :on-post-tool-use-failure lifecycle hook (upstream PR #1421). It also surfaces :copilot/mcp_app.tool_call_complete (SEP-1865) with opaque-key preservation for :arguments / :result, adds the :runtime-instructions system-message section + system-message-sections alias (upstream PR #1377), and updates docs/CHANGELOG. The wire-only canvas event types intentionally remain out of the curated public set pending a future canvas runtime port.

Changes:

• Schema bump to 1.0.55-1 + regenerated generated/event_specs.clj; new opaque preservation for mcp_app.tool_call_complete in protocol/normalize-incoming.
• BREAKING: drop v2 protocol back-compat — sdk-protocol-version-min is now 3, request-handler v2 cases removed, mock server's protocol version made configurable.
• New :on-post-tool-use-failure hook wired through specs/session/client/docs; new :runtime-instructions section + system-message-sections alias.

Show a summary per file

File	Description
.copilot-schema-version, schemas/README.md, schemas/*.schema.json	Pin and check in upstream schema 1.0.55-1 (canvas, MCP Apps, runtime instructions, service-request-id, etc.).
src/github/copilot_sdk/generated/event_specs.clj	Regenerated wire specs — adds mcp_app.tool_call_complete, canvas events, new optional fields.
src/github/copilot_sdk/protocol.clj	Preserve opaque :arguments / :result on mcp_app.tool_call_complete; drop v2 tool.call argument preservation branch; refresh docstring.
src/github/copilot_sdk/client.clj	Raise min protocol version to 3, remove v2 tool.call / permission.request dispatcher cases, document new failure hook in create-session.
src/github/copilot_sdk/session.clj	Map hooks.invoke type "postToolUseFailure" → :on-post-tool-use-failure.
src/github/copilot_sdk/specs.clj	Add ::on-post-tool-use-failure to ::hooks; add :runtime-instructions section + system-message-sections/::system-message-section aliases; add :copilot/mcp_app.tool_call_complete to event types.
src/github/copilot_sdk/util.clj	Add :runtime-instructions ↔ "runtime_instructions" mapping.
src/github/copilot_sdk.clj	Add :copilot/mcp_app.tool_call_complete to public event-types.
doc/reference/API.md, CHANGELOG.md	Document new hook, new event, runtime-instructions section, BREAKING protocol bump.
test/github/copilot_sdk/mock_server.clj	Make reported protocol version a configurable atom (default 3).
test/github/copilot_sdk/integration_test.clj	Update ping/status assertions to v3; delete v2-only RPC tests; add tests for new failure hook, opaque MCP-app preservation, schema additions, and a v2-rejection regression test.

Copilot's findings

• Files reviewed: 14/15 changed files
• Comments generated: 0

[Copilot]

Copilot's findings

• Files reviewed: 10/11 changed files
• Comments generated: 0 new