Add Rust SDK (technical preview)

[tclem]

Adds a Rust SDK alongside the existing Node, Python, Go, and .NET SDKs in this repo. Same JSON-RPC client model, same protocol, same session lifecycle — just in Rust.

Important

Technical preview. This is published as github-copilot-sdk = "0.1" (pre-1.0) and the public API is subject to breaking changes as we iterate. Pin to an exact version, expect churn, and please file issues for friction or missing parity.

See rust/README.md for the full overview, examples, and the build/test commands. Generated types follow the same schema-driven flow used by the other SDKs (scripts/codegen/rust.ts).

CI for the new crate runs in .github/workflows/rust-sdk-tests.yml.

  _{Generated via Copilot (Claude Opus 4.7) on behalf of @tclem}

[Copilot]

Pull request overview

Adds a new Rust SDK crate (copilot-sdk, library name copilot) to the monorepo, mirroring the existing SDKs’ JSON-RPC client/session model, and wires it into repo workflows and scenario coverage.

Changes:

• Introduces the Rust SDK crate with protocol types, JSON-RPC transport, session/handler abstractions, examples, and tests.
• Extends scenario samples and verification scripts to build/run Rust implementations alongside TS/Python/Go/C#.
• Updates repo automation: codegen, just tasks, scenario-build CI, Rust SDK CI, and release/publish workflows.

Show a summary per file

File	Description
test/scenarios/verify.sh	Shows Rust status in the aggregated scenario runner UI.
test/scenarios/transport/tcp/verify.sh	Builds/runs the Rust TCP transport scenario.
test/scenarios/transport/tcp/rust/Cargo.toml	Rust TCP scenario crate manifest.
test/scenarios/transport/tcp/rust/src/main.rs	Rust TCP sample using external host:port CLI server.
test/scenarios/transport/stdio/verify.sh	Builds/runs the Rust stdio transport scenario.
test/scenarios/transport/stdio/rust/Cargo.toml	Rust stdio scenario crate manifest.
test/scenarios/transport/stdio/rust/src/main.rs	Rust stdio sample spawning the CLI child process.
test/scenarios/transport/stdio/README.md	Documents Rust sample location/package name.
test/scenarios/tools/tool-overrides/verify.sh	Builds/runs Rust tool override scenario.
test/scenarios/tools/tool-overrides/rust/Cargo.toml	Rust tool-overrides scenario crate manifest (+derive).
test/scenarios/tools/tool-overrides/rust/src/main.rs	Rust sample overriding built-in tool behavior.
test/scenarios/tools/tool-filtering/verify.sh	Builds/runs Rust tool filtering scenario.
test/scenarios/tools/tool-filtering/rust/Cargo.toml	Rust tool-filtering scenario crate manifest.
test/scenarios/tools/tool-filtering/rust/src/main.rs	Rust sample limiting available tools.
test/scenarios/tools/skills/verify.sh	Builds/runs Rust skills scenario.
test/scenarios/tools/skills/rust/Cargo.toml	Rust skills scenario crate manifest.
test/scenarios/tools/skills/rust/src/main.rs	Rust sample configuring skill directories + hooks.
test/scenarios/tools/no-tools/verify.sh	Builds/runs Rust no-tools scenario.
test/scenarios/tools/no-tools/rust/Cargo.toml	Rust no-tools scenario crate manifest.
test/scenarios/tools/no-tools/rust/src/main.rs	Rust sample disabling tools + replacing system prompt.
test/scenarios/tools/mcp-servers/verify.sh	Builds/runs Rust MCP servers scenario.
test/scenarios/tools/mcp-servers/rust/Cargo.toml	Rust mcp-servers scenario crate manifest.
test/scenarios/tools/mcp-servers/rust/src/main.rs	Rust sample passing MCP servers config to CLI.
test/scenarios/tools/custom-agents/verify.sh	Builds/runs Rust custom agents scenario.
test/scenarios/tools/custom-agents/rust/Cargo.toml	Rust custom-agents scenario crate manifest (+derive).
test/scenarios/tools/custom-agents/rust/src/main.rs	Rust sample defining custom agents + custom tool.
test/scenarios/sessions/streaming/verify.sh	Builds/runs Rust streaming scenario.
test/scenarios/sessions/streaming/rust/Cargo.toml	Rust streaming scenario crate manifest.
test/scenarios/sessions/streaming/rust/src/main.rs	Rust sample counting streaming delta events.
test/scenarios/sessions/session-resume/verify.sh	Builds/runs Rust session resume scenario.
test/scenarios/sessions/session-resume/rust/Cargo.toml	Rust session-resume scenario crate manifest.
test/scenarios/sessions/session-resume/rust/src/main.rs	Rust sample creating + resuming session by ID.
test/scenarios/sessions/infinite-sessions/verify.sh	Builds/runs Rust infinite sessions scenario.
test/scenarios/sessions/infinite-sessions/rust/Cargo.toml	Rust infinite-sessions scenario crate manifest.
test/scenarios/sessions/infinite-sessions/rust/src/main.rs	Rust sample exercising infinite session thresholds.
test/scenarios/sessions/concurrent-sessions/verify.sh	Builds/runs Rust concurrent sessions scenario.
test/scenarios/sessions/concurrent-sessions/rust/Cargo.toml	Rust concurrent-sessions scenario crate manifest.
test/scenarios/sessions/concurrent-sessions/rust/src/main.rs	Rust sample running two sessions concurrently.
test/scenarios/prompts/system-message/verify.sh	Builds/runs Rust system-message scenario.
test/scenarios/prompts/system-message/rust/Cargo.toml	Rust system-message scenario crate manifest.
test/scenarios/prompts/system-message/rust/src/main.rs	Rust sample replacing system message.
test/scenarios/prompts/reasoning-effort/verify.sh	Builds/runs Rust reasoning-effort scenario.
test/scenarios/prompts/reasoning-effort/rust/Cargo.toml	Rust reasoning-effort scenario crate manifest.
test/scenarios/prompts/reasoning-effort/rust/src/main.rs	Rust sample setting reasoning_effort.
test/scenarios/modes/default/verify.sh	Builds/runs Rust default mode scenario.
test/scenarios/modes/default/rust/Cargo.toml	Rust default-mode scenario crate manifest.
test/scenarios/modes/default/rust/src/main.rs	Rust sample using default tool-enabled mode.
test/scenarios/callbacks/user-input/verify.sh	Builds/runs Rust user-input callback scenario.
test/scenarios/callbacks/user-input/rust/Cargo.toml	Rust user-input scenario crate manifest.
test/scenarios/callbacks/user-input/rust/src/main.rs	Rust sample handling ask_user prompts.
test/scenarios/callbacks/permissions/verify.sh	Builds/runs Rust permission callback scenario.
test/scenarios/callbacks/permissions/rust/Cargo.toml	Rust permissions scenario crate manifest.
test/scenarios/callbacks/permissions/rust/src/main.rs	Rust sample logging/approving permissions.
test/scenarios/callbacks/hooks/verify.sh	Builds/runs Rust hooks callback scenario.
test/scenarios/callbacks/hooks/rust/Cargo.toml	Rust hooks scenario crate manifest.
test/scenarios/callbacks/hooks/rust/src/main.rs	Rust sample implementing SessionHooks logging.
test/scenarios/RUST_COVERAGE.md	Documents Rust scenario parity coverage/gaps.
scripts/codegen/package.json	Adds Rust generation to codegen scripts.
nodejs/scripts/update-protocol-version.ts	Generates Rust SDK protocol version constant.
justfile	Adds Rust format/lint/test/codegen tasks.
.gitignore	Ignores Rust scenario build artifacts/lockfiles.
.github/workflows/scenario-builds.yml	Adds CI job building all Rust scenario crates.
.github/workflows/rust-sdk-tests.yml	Adds Rust SDK CI (fmt/clippy/doc/test/semver-checks).
.github/workflows/rust-release-pr.yml	Adds release-plz workflow to open Rust release PRs.
.github/workflows/rust-publish-release.yml	Adds release-plz workflow to publish Rust crate.
.github/workflows/codegen-check.yml	Ensures Rust codegen + protocol version regen in CI.
.github/skills/rust-coding-skill/SKILL.md	Adds repo-specific Rust engineering guidance.
.github/skills/rust-coding-skill/examples.md	Adds Rust SDK examples/patterns for contributors.
.github/copilot-instructions.md	Updates repo guidance to include Rust SDK + Rust skill.
rust/Cargo.toml	Defines the new copilot-sdk crate (features, deps, MSRV).
rust/Cargo.lock	Locks Rust dependencies for deterministic builds.
rust/README.md	Documents Rust SDK usage, architecture, and API surface.
rust/CHANGELOG.md	Establishes initial changelog and release-plz plan.
rust/RELEASING.md	Documents release/publish operations for maintainers.
rust/LICENSE	Rust crate license file.
rust/rust-toolchain.toml	Pins Rust toolchain version/components for the crate.
rust/release-plz.toml	Configures release-plz behavior for the Rust crate.
rust/clippy.toml	Configures Rust clippy rules (e.g., disallowed macros).
rust/.rustfmt.toml	Stable rustfmt config (edition 2024).
rust/.rustfmt.nightly.toml	Nightly rustfmt config enabling unstable formatting opts.
rust/.gitignore	Ignores Rust target dir and backup lock files.
rust/build.rs	Build-time CLI bundling/extraction codegen support.
rust/src/sdk_protocol_version.rs	Generated SDK protocol version constant for Rust.
rust/src/generated/mod.rs	Rust generated-type module root + re-exports.
rust/src/jsonrpc.rs	Content-Length framed JSON-RPC transport implementation.
rust/src/router.rs	Per-session routing of notifications/requests.
rust/src/handler.rs	Session handler traits/events + default handlers.
rust/src/permission.rs	Permission policy wrappers over SessionHandler.
rust/src/transforms.rs	System message transform extension point + dispatcher.
rust/src/session.rs	Session lifecycle/event loop plumbing (core runtime).
rust/tests/jsonrpc_test.rs	Tests for JSON-RPC framing/routing (feature-gated).
rust/tests/protocol_version_test.rs	Tests protocol version negotiation behavior.
rust/tests/integration_test.rs	Ignored integration tests against real CLI.
rust/examples/chat.rs	Interactive streaming chat example.
rust/examples/hooks.rs	Hooks example for logging/auditing.
rust/examples/tool_server.rs	Tool server example (feature-gated on derive).
rust/examples/lifecycle_observer.rs	Observer example for lifecycle/session event streams.

Copilot's findings

• Files reviewed: 102/107 changed files
• Comments generated: 5

[github-actions]

Generated by SDK Consistency Review Agent for issue #1164 · ● 2.5M

[stephentoub]

Thanks for getting this up.

It'd be helpful to run an agent over the other SDKs and this new one to look for any inconsistencies / gaps / divergences, so that we can then evaluate each and decide whether it's acceptable or should be addressed. The more consistent we can be across the SDKs, the easier it'll be to maintain them moving forward, the more information / docs about one will translate to consumption of the others, the better we'll be able to evolve with reduced concerns for how something we want to add may not fit well in a particular SDK, etc.

[stephentoub]

Similarly here: is there a datetime type that could be used rather than string? The schema includes a format specifier to indicate when that'd be appropriate.

[tclem]

Same as uuid, we could bring in a dependency... if we think it's worth it. std::time is intentionally minimal and free of calendar complexity, timezones, etc.

Is this important for the sdk?

[stephentoub]

I think these timestamp ones are more worthwhile, so I'd go for this one if it's easy enough. Folks are more likely to actually use this data, compare time stamps, etc.

[tclem]

We'll need chrono for that.. which is a pretty big dependency to bring in for this capability... Let me audit in a bit more detail how many timestamps we're dealing with here and keep in might usage (like comparison) and see if I can propose something a bit more lightweight.

Ideally, we push a few 3rd party deps as possible on consumers.

[tclem]

https://crates.io/crates/time-format is the other options... though I kinda wonder if serde already has a dependency on one of these...

[stephentoub]

If it's going to be a problem, we can skip. C#, Go, and Python do all special-case this, though (TypeScript doesn't).

[tclem]

OK. If you feel strongly that we should make this a real type and not a string. My recommendation is time-format - zero dependencies, tiny (575 SLoC). chrono is 20K SLoC with a big list of dependencies.

[stephentoub]

I don't feel strongly about it. Up to you whether you think it's worth it.

[github-actions]

Generated by SDK Consistency Review Agent for issue #1164 · ● 3.4M

[github-actions]

Cross-SDK consistency gap: continue_pending_work missing from ResumeSessionConfig

All other SDKs expose a continuePendingWork flag on their resume config that instructs the CLI to preserve in-flight tool calls and permission requests across reconnections rather than treating them as interrupted. This field is absent from the Rust ResumeSessionConfig.

Other SDK equivalents:

• Node.js: ResumeSessionConfig.continuePendingWork?: boolean (nodejs/src/types.ts:1435)
• Go: ResumeSessionConfig.ContinuePendingWork bool (go/types.go:815)
• Python: continue_pending_work: bool | None in ResumeSessionConfig (python/copilot/client.py:1516)
• .NET: bool? ContinuePendingWork on ResumeSessionConfig (dotnet/src/Types.cs:2189)

The generated SessionResumeData event does have a continue_pending_work field (to reflect the server's decision at runtime), but the request side — the config the caller sends to opt in — is missing here.

Suggested addition (right before disable_resume):

/// When `true`, the runtime continues any tool calls or permission requests
/// that were still pending when the session was last disconnected.
/// When `false` (the default), pending work is treated as interrupted on resume.
///
/// For permission requests, the runtime re-emits `permission.requested`; for
/// external tool calls, supply the result via the corresponding low-level RPC.
#[serde(skip_serializing_if = "Option::is_none")]
pub continue_pending_work: Option<bool>,

A matching with_continue_pending_work(bool) builder method near with_disable_resume would complete the parity. This gap is not called out in the README's "Differences From Other SDKs" section, so it appears unintentional.

[github-actions]

Generated by SDK Consistency Review Agent for issue #1164 · ● 2.2M

[github-actions]

Generated by SDK Consistency Review Agent for issue #1164 · ● 1.9M

[github-actions]

Cross-SDK consistency gap: continue_pending_work missing from ResumeSessionConfig

All other SDKs expose a continuePendingWork / continue_pending_work / ContinuePendingWork field on their resume config, but the Rust ResumeSessionConfig doesn't include it:

SDK	Field
Node.js	continuePendingWork?: boolean
Python	continue_pending_work: bool
Go	ContinuePendingWork bool
.NET	bool? ContinuePendingWork
Rust	❌ missing

This field is important for the "pending work resume" pattern — when a session is abandoned mid-tool-execution (e.g. via force_stop), setting continue_pending_work: true on resume instructs the CLI to replay and complete those pending tool/permission requests.

Suggested addition (after disable_resume):

/// When `true`, instructs the runtime to continue any pending tool calls
/// or permission requests that were outstanding when the session was
/// last disconnected. Use in combination with [`Client::force_stop`] to
/// hand off a live session to a new client without losing in-flight work.
/// See [`SessionConfig`] for the equivalent field on initial session creation.
#[serde(skip_serializing_if = "Option::is_none")]
pub continue_pending_work: Option<bool>,

And a corresponding builder method in impl ResumeSessionConfig:

pub fn with_continue_pending_work(mut self, value: bool) -> Self {
    self.continue_pending_work = Some(value);
    self
}

Don't forget to include it in ResumeSessionConfig::new (as None) and in the Debug impl.

[github-actions]

Generated by SDK Consistency Review Agent for issue #1164 · ● 2.8M

[github-actions]

The "Rust-only API" section documents on_auto_mode_switch as a Rust-only typed handler with a note that "Cross-SDK parity is post-release follow-up." The on_exit_plan_mode handler on SessionHandler is in the same situation — it's a typed Rust-only callback for exit_plan_mode.requested (other SDKs expose this only as a raw SessionEvent with no typed dispatch path), but it isn't mentioned here.

Worth adding a parallel bullet for on_exit_plan_mode so consumers have the same explicit heads-up that they would for on_auto_mode_switch:

- **`SessionHandler::on_exit_plan_mode`** — typed handler for the CLI's
  plan-mode exit prompt (`exit_plan_mode.requested`). Returns
  `ExitPlanModeResult` (default: approved with no action). Cross-SDK parity
  is post-release follow-up — Node / Python / Go / .NET consumers currently
  observe the request as a raw event and must drive the wire response
  themselves.

Minor documentation gap only — no code change needed.

[github-actions]

Cross-SDK Consistency Review ✅

Reviewed the Rust SDK addition against the existing Node.js/TypeScript, Python, Go, and .NET SDK implementations.

Core API Alignment — Consistent ✅

All fundamental APIs from the other SDKs are present in Rust (following Rust naming conventions):

Feature	Node.js	Python	Go	.NET	Rust
Client lifecycle	start/stop/forceStop	same	Start/Stop/ForceStop	StartAsync/StopAsync/ForceStopAsync	start/stop/force_stop ✅
Session management	createSession/resumeSession	same	CreateSession/ResumeSession	CreateSessionAsync/ResumeSessionAsync	create_session/resume_session ✅
Send message	send/sendAndWait	send/send_and_wait	Send/SendAndWait	SendAsync/SendAndWaitAsync	send/send_and_wait ✅
Session teardown	disconnect/destroy	disconnect/destroy	Disconnect/Destroy	DisposeAsync	disconnect/destroy ✅
Abort	abort	abort	Abort	AbortAsync	abort ✅
Model switch	setModel	set_model	SetModel	SetModelAsync	set_model ✅
Event history	getMessages	get_messages	GetMessages	GetMessagesAsync	get_messages ✅
Session log	log	log	Log	LogAsync	log ✅
Client ops	ping/getStatus/getAuthStatus/listModels	same	Ping/GetStatus/GetAuthStatus/ListModels	PingAsync/GetStatusAsync/...	all present ✅
Session listing	listSessions/getSessionMetadata/deleteSession	same	same (Go)	same (Async)	all present ✅
Foreground session	getForeground/setForegroundSessionId	same	same (Go)	same (Async)	all present ✅
Capabilities / UI	capabilities/ui	capabilities/ui	Capabilities/UI	Capabilities/Ui	both ✅

Intentional Divergences — Well-Documented ✅

The README includes a thorough "Differences From Other SDKs" section. All deviations are intentional and explained:

• Additional Session convenience methods (get_model, set_mode/get_mode, set_name/get_name, plan/workspace/fleet APIs) — other SDKs expose these only via the generated rpc() namespace
• Client::send_telemetry / Session::send_telemetry — not yet exposed in other SDKs (not even via rpc())
• Client::get_quota — convenience wrapper; RPC endpoint is accessible cross-SDK via rpc() namespace
• Typed newtypes (SessionId, RequestId) — Rust type safety win
• permission:: module — composable policy builders
• Transport enum / from_streams — explicit transport selection

Minor Documentation Gap

Session::set_approve_all_permissions is a Rust-only convenience wrapper for session.permissions.setApproveAll (other SDKs use the generated RPC namespace, e.g. Go: session.RPC.Permissions.SetApproveAll()). It's used in tests but isn't listed in the README's "Rust-only API" section alongside the other first-class Session convenience methods. Worth adding a bullet there for completeness.

Similarly, the subscription model divergence (subscribe() returning a channel vs the callback-based on(handler) in Node.js/Python/Go/.NET) could be explicitly noted in the "Shape divergence" section — it's implied by the examples but isn't stated outright.

Scenario Coverage

test/scenarios/RUST_COVERAGE.md documents scenario parity clearly with deferred items well-justified. All major scenarios (transport, sessions, tools, callbacks, prompts) have Rust implementations.

---

Overall: This PR maintains strong cross-SDK consistency. The Rust SDK is a faithful implementation of the shared protocol with well-documented, idiomatic Rust divergences. No blocking consistency issues found.

Generated by SDK Consistency Review Agent for issue #1164 · ● 3M · ◷