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.

[github-actions]

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

[stephentoub]

Is this expected? I assume this means we've buried some unsafe usage and we're then putting it on the developer to know when they're using shared state and the borrowed checker won't help them?

[tclem]

No, this is confusing.

Not unsafe, that has a different meaning... this section is confusing... asking copilot to rewrite now.

[tclem]

Good catch on the framing -- it's misleading. The compiler does enforce this; nothing buried.

SessionHandler declares Send + Sync + 'static (rust/src/handler.rs:280), and Arc<dyn SessionHandler> is cloned into tokio::spawn(async move { ... }) for the concurrent dispatch paths. The RefCell example in the doc literally won't compile -- RefCell<T> is !Sync, so the impl SessionHandler for MyHandler line fails the trait bound. The borrow checker is doing the work; the doc is just teaching "use parking_lot::Mutex here so you don't waste time reaching for RefCell first."

Updated examples.md to make this explicit -- renamed the anti-pattern to "Won't compile", showed the actual trait-bound error, and added a one-paragraph note saying the compiler is what enforces it. The rejection should be obvious from the doc now without a reader having to mentally trace spawn -> Send + Sync -> RefCell !Sync.

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

[stephentoub]

Curious the lack of C# mentioned

[tclem]

This is probably keying off of my guidance and copilot giving up after looking at only a couple of examples. No python mentioned either.

Honestly, I'm not sure how helpful this is, but I do know that copilot's first pass at this was to write some very non-idiomatic rust. You have to prompt it to look at what the community projects do and what they avoid. This language can probably be tightened up...

[tclem]

Good catch — and your hunch that the framing was lopsided is right. Let me come back with a thorough rewrite.

Doing a proper research pass across the section's four claims (event subscription, cancellation, optional fields, serde) and auditing the SDK's current code against them. The cancellation guidance in particular is too absolute — tokio_util::sync::CancellationToken is real and idiomatic for SDK-internal task coordination (it's what tonic does). Will follow up here once the doc rewrite + matching SDK refactor land.

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

[tclem]

Done. Two commits landed addressing this and your original "lopsided framing" callout:

• e96aea6 -- rewrites the SKILL "Idioms that don't port" section.
• 7202dfd -- refactors Session.shutdown from Arc<Notify> to tokio_util::sync::CancellationToken and exposes Session::cancellation_token().

Section is now language-agnostic -- title is "Idioms that don't port from other languages", lists Node / Python / C# / Go equivalents inline where pattern divergence is notable.

Cancellation guidance rewritten. The previous framing ("drop the future or call abort() -- there is no ctx.Done() analogue") was wrong. Drop-to-cancel is the primitive, but tokio_util::sync::CancellationToken IS the Rust analog to ctx.Done() / .NET's CancellationToken, just optional and explicit per-API. The right framing is two cases:

1. Caller-owned futures (send_message, send_and_wait, subscription streams): drop the future. select! / timeout / drop give the caller everything they need; adding a token parameter just duplicates that. This is what reqwest / sqlx / aws-sdk-* / tonic's client side do.
2. SDK-internal task coordination (event loop, subprocess reader, anything tokio::spawned): use CancellationToken. This is what tonic does for client-disconnect propagation. tokio-graceful-shutdown builds an entire framework on it.

The SDK now follows pattern 2 internally: Session.shutdown is a CancellationToken (refactored from the previous Arc<Notify>), and there's a public Session::cancellation_token() returning a child token so power users can bind their own work to the session lifetime via select!. Cancelling the child does NOT shut down the session -- isolation by design.

Other three idioms (event subscription, optional fields, serde JSON) -- guidance was correct but incomplete; doc enrichment landed in e96aea6 with the full primitive matrix, #[non_exhaustive] + builder pairing, and skip_serializing_if/default notes. No code refactor needed for those -- already idiomatic.

Citations for the cancellation framing:

• tokio-util CancellationToken docs
• tonic cancellation example
• withoutboats: Asynchronous clean-up
• Cybernetist: Rust tokio task cancellation patterns

Validation green: 237 tests (was 233; +4 from new builder + cancellation_token tests), full clippy / fmt / doc -D warnings clean.

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

[stephentoub]

Is this just documentation, or does this get recognized by the tooling in some way to let someone know they're using something experimental?

[tclem]

I'll have my agent respond too. It's just docs, there are some options to make it stronger, but it sounds like this sort of annotation isn't done consistently in the other languages right now...

[tclem]

Today, just documentation -- the schema's "stability": "experimental" flag is read by codegen and emitted as a rustdoc comment.

I just upgraded the rendering: instead of a single-line Stability: experimental note, codegen now emits a styled rustdoc warning admonition (<div class="warning">...</div>) so docs.rs renders a yellow callout box on every experimental method. Matches the visibility Python's Sphinx output already gets.

Stable Rust doesn't have a first-class #[experimental] attribute (#[unstable] is rustc-internal, std-only). If we want compile-time opt-in friction, the ecosystem patterns are:

• Cargo feature gate (e.g. tokio_unstable-style features = ["experimental"]) -- consumers can't call experimental methods without explicitly enabling the feature. Strongest signal.
• unstable module path -- e.g. session.rpc().unstable().agent().list(). Visible in the import.

Both are bigger codegen changes that affect every experimental RPC across all SDKs' surface. Punting on those for 0.1.0; happy to revisit in a follow-up if we want the harder opt-in.

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

[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]

Cross-SDK Consistency Review: Rust SDK Addition ✅

Reviewed PR #1164 (Rust SDK technical preview) for cross-SDK consistency against the existing Node.js/TypeScript, Python, Go, and .NET implementations.

Overall Assessment

The Rust SDK is well-aligned with the other SDKs at the protocol and architecture level. The JSON-RPC wire protocol, session lifecycle, session config/resume patterns, permissions, hooks, tools, elicitation, and streaming behavior are all consistent. The rust/README.md already has an excellent "Differences From Other SDKs" section that transparently documents the intentional divergences — great practice.

---

Identified Parity Gaps (all documented in rust/README.md)

The README correctly lists these as "Rust-only API" features, with post-release parity noted. Recording them here for visibility and future tracking:

1. First-class Session convenience methods (other SDKs require .rpc() namespace)

These RPCs exist in the generated RPC layer of all other SDKs but only the Rust SDK elevates them to top-level Session methods:

Rust method	Other SDKs (via generated RPC only)
session.get_model()	Node: rpc.model.getCurrent() / Go: Rpc.Model.GetCurrent() / .NET: Rpc.Model.GetCurrentAsync()
session.set_mode() / get_mode()	Node: rpc.mode.set() / Go: Rpc.Mode.Set()
session.get_name() / set_name()	Node: rpc.name.get/set() / Go: Rpc.Name.Get/Set()
session.read_plan() / update_plan() / delete_plan()	Node: rpc.plan.read/update/delete() / Go: Rpc.Plan.Read/Update/Delete()
session.list_workspace_files() / read_workspace_file() / create_workspace_file()	Node: rpc.workspaces.listFiles/readFile/createFile()
session.start_fleet()	Node: rpc.fleet.start() / Go: Rpc.Fleet.Start()
Client::get_quota()	Node: rpc.account.getQuota() / Go: Rpc.Account.GetQuota()

Suggestion (post-release): Adding these as convenience wrappers on Session/Client in Go, Python, Node.js, and .NET would improve ergonomics uniformly. Not a blocker.

2. Client::send_telemetry() and Session::send_telemetry() — Not in any other SDK

These call sendTelemetry / session.sendTelemetry RPCs that are not exposed even in the generated RPC namespace of the other SDKs. This is the only true protocol-level gap (vs a convenience wrapper gap).

Suggestion (post-release): Add sendTelemetry / session.sendTelemetry to the other SDKs' generated RPC layer and expose as first-class methods for parity.

3. SessionHandler::on_auto_mode_switch — Not in other SDKs

Rust has a typed handler for the autoModeSwitch.request callback. Other SDKs observe it as a raw event and must drive the wire response manually.

Suggestion (post-release): Port on_auto_mode_switch handling to Go, Python, Node.js, and .NET.

---

Rust-Only by Design (no parity needed)

These are idiomatic Rust features that don't translate to other languages:

• SessionId / RequestId newtypes (strong typing vs bare strings in other SDKs)
• enum Transport { Stdio, Tcp, External } (other SDKs use conditional config)
• permission::approve_all / deny_all / approve_if builder helpers
• Client::from_streams() (arbitrary AsyncRead/AsyncWrite for testing)
• CancellationToken / broadcast channel subscription model (subscribe() vs callback-based on())
• Session::stop_event_loop() / Session::cancellation_token() (Rust async lifecycle concern)
• Arc<dyn SessionFsProvider> direct registration (vs factory-closure in other SDKs)

---

Summary

The Rust SDK follows the same architecture and protocol as the other SDKs. All identified parity gaps are intentional and documented in rust/README.md. No consistency blockers found. The "Rust-only API" features (especially the convenience wrappers and telemetry methods) are good candidates for backporting to other SDKs as a post-release effort.

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