feat: sync CLI 1.0.100-1 MCP and event contracts

.copilot-schema-version

@@ -1 +1 @@
-1.0.99-2
+1.0.100-1

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           repository: github/copilot-sdk
-          ref: 404304416ac5358651e3877a33bc9e8f4e482162
+          ref: b96cd2b54f7eb87458fd50f485a751c712e88f62
           path: .upstream/copilot-sdk
           persist-credentials: false
           fetch-depth: 0

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. This change
 ## [Unreleased]
 
 ### Added (post-v1.0.22 sync)
+- Added capability-gated MCP OAuth runtime refresh handoff, persisted recovery
+  outcomes, live-only MCP tool-readiness events, and request-compression fallback
+  diagnostics on usage and failure events.
+  ([upstream snapshot](https://github.com/github/copilot-sdk/commit/b96cd2b54f7eb87458fd50f485a751c712e88f62))
 - Added creation-time session names; discovery-only agent and hook directories;
   interactive-user telemetry and read-only GitHub-cache-store options; and
   declarative custom-agent hooks with preserved JSON keys.
@@ -13,6 +17,8 @@ All notable changes to this project will be documented in this file. This change
   ([upstream snapshot](https://github.com/github/copilot-sdk/commit/404304416ac5358651e3877a33bc9e8f4e482162))
 
 ### Fixed (post-v1.0.22 sync)
+- Explicit MCP OAuth cancellation takes precedence over a supplied token;
+  empty or non-string tokens cancel rather than reaching the runtime as tokens.
 - Forward discovery-root strings unchanged so the runtime can trim whitespace
   and ignore blank entries consistently across skills, instructions, agents,
   and file hooks.
@@ -24,7 +30,9 @@ All notable changes to this project will be documented in this file. This change
 - **BREAKING**: Removed the retired `::specs/factory-run-id` contract; use
   `:workflow-run-id` for subagent Workflow attribution. Historical event maps
   still pass through unknown fields.
-- Advanced CLI compatibility and schema provenance to `1.0.99-2`, preserving
+- Documented additional startup directories as authorization for repository
+  hooks, including containing Git roots, cold-resume scope, and hook controls.
+- Advanced CLI compatibility and schema provenance to `1.0.100-1`, preserving
   historical certification and explicitly inventorying source-only snapshots
   without upstream tests. New experimental and internal APIs remain excluded.
   The library version remains `1.0.16.0`; no release, tag, or deployment is cut.

doc/adr/2026-10-19-mcp-recovery-and-readiness.md

@@ -0,0 +1,57 @@
+# ADR: Preserve MCP recovery and readiness contracts
+
+- Status: Accepted
+- Related: [upstream snapshot](https://github.com/github/copilot-sdk/commit/b96cd2b54f7eb87458fd50f485a751c712e88f62)
+
+## Context
+
+The Node SDK lets an MCP OAuth handler delegate advertised, noninteractive
+credential renewal to the runtime. New events distinguish authorization
+recovery completion from accepting the host response, and MCP tool readiness
+from connection status. Usage and failure events gain compression-fallback
+diagnostics. Other additions remain experimental or internal.
+
+## Decision
+
+Use the canonical handler result `{:kind :runtime-refresh}` and send
+`"runtimeRefresh"` only when the request has `:runtime-refresh-supported true`.
+Preserve omission and explicit false in callback data. Explicit cancellation
+takes precedence over a token; a nonempty string token takes precedence over
+handoff. Preserve bare-token maps and existing optional-token-field omission.
+Malformed results and handler exceptions are logged and cancel the host request.
+The same callback path serves create, resume, join, and channel variants.
+
+Keep renewal, grant storage, reconnect, and cancellation runtime-owned.
+Handoff acceptance is not completion. Expose the persisted
+`:copilot/mcp.oauth_recovery_completed` event with its request/server identity
+and exact `"succeeded"`, `"cancelled"`, or `"failed"` outcome.
+Expose ephemeral `:copilot/session.mcp_server_tools_loaded` with string server
+name and the schema's integer tool count. Do not infer readiness from
+`"connected"`, impose event ordering, or fabricate history for an ephemeral event.
+
+Expose the three optional compression diagnostic fields on both usage and
+failure events. Preserve string enums and the schema's integer status range
+of 0-999. Omission is not zero; explicit `nil` is invalid. Keep payload maps
+open for future fields and preserve live/history behavior without new coercion.
+
+Retain the existing `:additional-directories` and `:enable-file-hooks` APIs.
+Document startup directories as trust in repository commands and prompts,
+including the containing Git root. Prove enabled/disabled and cold-resume
+behavior with isolated repositories and a local model provider. Do not add
+runtime discovery or authorization logic to the SDK.
+
+Keep skill-provider supporting files, Azure ML model acquisition, catalog
+category filtering, hosting discovery hints, and generated MCP configuration
+observations outside the supported API. Internal provider-type telemetry and
+the durable compression-disable marker remain wire-only.
+
+## Consequences
+
+The public snapshot adds event/spec membership and the existing OAuth
+dispatcher's fdef, without new client or session operations. Complete
+symbol-based evidence extends the historical certification at its original pin.
+The target has no Node test tree; retained upstream tests remain historical,
+while new behavior is checked through local protocol and real-runtime tests.
+
+CLI compatibility and schema provenance advance to `1.0.100-1`. The library
+version stays `1.0.16.0`; this decision does not cut a release, tag, or deployment.

doc/api/2026-10-19-mcp-recovery-and-readiness.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html PUBLIC ""
+    "">
+<html><head><meta charset="UTF-8" /><title>ADR: Preserve MCP recovery and readiness contracts</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name"></span> <span class="project-version"></span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="2026-08-08-query-seq-scoped-lifecycle.html"><div class="inner"><span>ADR: Add scope-bound query sequences before deprecating query-seq!</span></div></a></li><li class="depth-1 "><a href="2026-08-10-host-owned-inference-boundary.html"><div class="inner"><span>ADR: Defer a host-owned inference boundary</span></div></a></li><li class="depth-1 "><a href="2026-09-27-dynamic-workflow-migration.html"><div class="inner"><span>ADR: Migrate the existing orchestration API to Dynamic Workflows</span></div></a></li><li class="depth-1 "><a href="2026-09-30-model-policy-and-lifecycle-sync.html"><div class="inner"><span>ADR: Separate stable model policy from experimental host controls</span></div></a></li><li class="depth-1 "><a href="2026-10-02-transcript-recovery-and-owned-exit.html"><div class="inner"><span>ADR: Expose transcript recovery and bound owned-runtime disconnection</span></div></a></li><li class="depth-1 "><a href="2026-10-04-byok-provider-telemetry.html"><div class="inner"><span>ADR: Separate BYOK configuration identity from runtime telemetry</span></div></a></li><li class="depth-1 "><a href="2026-10-05-callback-and-event-contracts.html"><div class="inner"><span>ADR: Preserve callback, filesystem, and event authority boundaries</span></div></a></li><li class="depth-1 "><a href="2026-10-09-extensible-routing-and-event-contracts.html"><div class="inner"><span>ADR: Preserve extensible identifiers and policy boundaries</span></div></a></li><li class="depth-1 "><a href="2026-10-12-transport-diagnostics-and-opaque-policy.html"><div class="inner"><span>ADR: Preserve transport diagnostics and opaque policy</span></div></a></li><li class="depth-1 "><a href="2026-10-16-session-hooks-and-compaction.html"><div class="inner"><span>ADR: Preserve session, hook, and compaction contracts</span></div></a></li><li class="depth-1  current"><a href="2026-10-19-mcp-recovery-and-readiness.html"><div class="inner"><span>ADR: Preserve MCP recovery and readiness contracts</span></div></a></li><li class="depth-1 "><a href="API.html"><div class="inner"><span>API Reference</span></div></a></li><li class="depth-1 "><a href="azure-managed-identity.html"><div class="inner"><span>Azure Managed Identity with BYOK</span></div></a></li><li class="depth-1 "><a href="byok.html"><div class="inner"><span>BYOK (Bring Your Own Key)</span></div></a></li><li class="depth-1 "><a href="codegen.html"><div class="inner"><span>Schema-Driven Code Generation</span></div></a></li><li class="depth-1 "><a href="custom-agents.html"><div class="inner"><span>Custom Agents &amp; Sub-Agent Orchestration</span></div></a></li><li class="depth-1 "><a href="debugging.html"><div class="inner"><span>MCP Server Debugging Guide</span></div></a></li><li class="depth-1 "><a href="dynamic-workflows.html"><div class="inner"><span>Dynamic Workflows</span></div></a></li><li class="depth-1 "><a href="getting-started.html"><div class="inner"><span>Getting Started with the Copilot SDK for Clojure</span></div></a></li><li class="depth-1 "><a href="doc-auth-index.html"><div class="inner"><span>Authentication</span></div></a></li><li class="depth-1 "><a href="doc-index.html"><div class="inner"><span>Documentation</span></div></a></li><li class="depth-1 "><a href="overview.html"><div class="inner"><span>Using MCP Servers with the Copilot SDK for Clojure</span></div></a></li><li class="depth-1 "><a href="style.html"><div class="inner"><span>Documentation Style Guide</span></div></a></li><li class="depth-1 "><a href="upstream-doc-gap-matrix.html"><div class="inner"><span>Upstream Documentation Gap Matrix</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>github</span></div></div></li><li class="depth-2"><a href="github.copilot-sdk.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>copilot-sdk</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.client.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>client</span></div></a></li><li class="depth-3"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>generated</span></div></div></li><li class="depth-4 branch"><a href="github.copilot-sdk.generated.coerce.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>coerce</span></div></a></li><li class="depth-4 branch"><a href="github.copilot-sdk.generated.event-metadata.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>event-metadata</span></div></a></li><li class="depth-4"><a href="github.copilot-sdk.generated.event-specs.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>event-specs</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.helpers.html"><div class="inner"><span class="tree" style="top: -114px;"><span class="top" style="height: 123px;"></span><span class="bottom"></span></span><span>helpers</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.instrument.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>instrument</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.logging.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>logging</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.process.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>process</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.protocol.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>protocol</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.session.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>session</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.specs.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>specs</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.teardown.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>teardown</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.tool-set.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>tool-set</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.tools.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>tools</span></div></a></li><li class="depth-3 branch"><a href="github.copilot-sdk.util.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>util</span></div></a></li><li class="depth-3"><a href="github.copilot-sdk.workflow.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>workflow</span></div></a></li></ul></div><div class="document" id="content"><div class="doc"><div class="markdown"><h1><a href="#adr-preserve-mcp-recovery-and-readiness-contracts" id="adr-preserve-mcp-recovery-and-readiness-contracts"></a>ADR: Preserve MCP recovery and readiness contracts</h1>
+<ul>
+<li>Status: Accepted</li>
+<li>Related: <a href="https://github.com/github/copilot-sdk/commit/b96cd2b54f7eb87458fd50f485a751c712e88f62">upstream snapshot</a></li>
+</ul>
+<h2><a href="#context" id="context"></a>Context</h2>
+<p>The Node SDK lets an MCP OAuth handler delegate advertised, noninteractive credential renewal to the runtime. New events distinguish authorization recovery completion from accepting the host response, and MCP tool readiness from connection status. Usage and failure events gain compression-fallback diagnostics. Other additions remain experimental or internal.</p>
+<h2><a href="#decision" id="decision"></a>Decision</h2>
+<p>Use the canonical handler result <code>{:kind :runtime-refresh}</code> and send <code>"runtimeRefresh"</code> only when the request has <code>:runtime-refresh-supported true</code>. Preserve omission and explicit false in callback data. Explicit cancellation takes precedence over a token; a nonempty string token takes precedence over handoff. Preserve bare-token maps and existing optional-token-field omission. Malformed results and handler exceptions are logged and cancel the host request. The same callback path serves create, resume, join, and channel variants.</p>
+<p>Keep renewal, grant storage, reconnect, and cancellation runtime-owned. Handoff acceptance is not completion. Expose the persisted <code>:copilot/mcp.oauth_recovery_completed</code> event with its request/server identity and exact <code>"succeeded"</code>, <code>"cancelled"</code>, or <code>"failed"</code> outcome. Expose ephemeral <code>:copilot/session.mcp_server_tools_loaded</code> with string server name and the schema’s integer tool count. Do not infer readiness from <code>"connected"</code>, impose event ordering, or fabricate history for an ephemeral event.</p>
+<p>Expose the three optional compression diagnostic fields on both usage and failure events. Preserve string enums and the schema’s integer status range of 0-999. Omission is not zero; explicit <code>nil</code> is invalid. Keep payload maps open for future fields and preserve live/history behavior without new coercion.</p>
+<p>Retain the existing <code>:additional-directories</code> and <code>:enable-file-hooks</code> APIs. Document startup directories as trust in repository commands and prompts, including the containing Git root. Prove enabled/disabled and cold-resume behavior with isolated repositories and a local model provider. Do not add runtime discovery or authorization logic to the SDK.</p>
+<p>Keep skill-provider supporting files, Azure ML model acquisition, catalog category filtering, hosting discovery hints, and generated MCP configuration observations outside the supported API. Internal provider-type telemetry and the durable compression-disable marker remain wire-only.</p>
+<h2><a href="#consequences" id="consequences"></a>Consequences</h2>
+<p>The public snapshot adds event/spec membership and the existing OAuth dispatcher’s fdef, without new client or session operations. Complete symbol-based evidence extends the historical certification at its original pin. The target has no Node test tree; retained upstream tests remain historical, while new behavior is checked through local protocol and real-runtime tests.</p>
+<p>CLI compatibility and schema provenance advance to <code>1.0.100-1</code>. The library version stays <code>1.0.16.0</code>; this decision does not cut a release, tag, or deployment.</p>
+</div></div></div></body></html>