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 · ● 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.

[stephentoub]

request_auto_mode_switch + on_auto_mode_switch handler —

Were these recently added in runtime? We haven't added anything for them yet in the other SDKs. Could we remove them from rust for now?

disabled_mcp_servers

Same here. This isn't exposed in any of the other SDKs.

If the desire ends up being to have this, we can add it across all of them, including Rust, in one fell swoop.

env_value_mode

Ditto. I'm not even sure what this is :)

[stephentoub]

Thanks!

[stephentoub]

(We will follow-up in a subsequent PR addressing the remaining feedback.)

[github-actions]

Cross-SDK Consistency Review — PR #1164 (Add Rust SDK)

This PR adds a brand-new Rust SDK. I reviewed it for cross-language API consistency with the Node.js, Python, Go, and .NET SDKs.

✅ Core API: well-aligned

The fundamental surface is consistent across all five SDKs:

Feature	Node	Python	Go	.NET	Rust
create_session / resume_session	✅	✅	✅	✅	✅
send / send_and_wait	✅	✅	✅	✅	✅
get_messages, abort, set_model, log	✅	✅	✅	✅	✅
disconnect / destroy	✅	✅	✅	✅	✅
force_stop, continue_pending_work	✅	✅	✅	✅	✅
ping, get_status, get_auth_status, list_models	✅	✅	✅	✅	✅
list_sessions, get_session_metadata, delete_session	✅	✅	✅	✅	✅
get_last_session_id, get/set_foreground_session_id	✅	✅	✅	✅	✅
Hooks, transforms, tools, permissions, elicitation	✅	✅	✅	✅	✅
Streaming, infinite sessions, telemetry, BYOK	✅	✅	✅	✅	✅

The intentional divergences (typed newtypes, enum Transport, Client::from_streams, SessionFsProvider registration style, on_auto_mode_switch) are well-explained in the README's "Differences From Other SDKs" section. ✅

⚠️ One documentation bug found

The README's ### Session reference block (lines 107–124) documents several session methods as if they are direct convenience methods on Session, but they are not implemented on the struct — only session.rpc().X() equivalents exist:

• session.get_model() — not implemented (use session.rpc().model().get_current())
• session.get_mode() / session.set_mode() — not implemented (use session.rpc().mode().get()/set())
• session.list_workspace_files() / session.read_workspace_file() — not implemented (use session.rpc().workspaces().*)
• session.read_plan() / session.update_plan() — not implemented (use session.rpc().plan().*)
• session.start_fleet() — not implemented (use session.rpc().fleet().start())

Since these are in rust,ignore blocks they aren't caught by cargo test --doc. An inline review comment has been left on the specific lines. The fix is either to implement the wrappers or update the code examples to use session.rpc().*.

This does not affect any other SDK — it's specific to the Rust README documentation.

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

[github-actions]

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

[github-actions]

Documentation bug: several session.X() calls shown here don't exist on Session

Lines 108–124 document the following as direct convenience methods on Session, but none of them are actually implemented on the struct (only set_model and get_messages / abort are):

Shown in README	Actual API
session.get_model()	session.rpc().model().get_current().await?
session.get_mode()	session.rpc().mode().get().await?
session.set_mode("autopilot")	session.rpc().mode().set(ModeSetRequest { mode: "autopilot".into() }).await?
session.list_workspace_files()	session.rpc().workspaces().list_files().await?
session.read_workspace_file("plan.md")	session.rpc().workspaces().read_file(WorkspacesReadFileRequest { path: "plan.md".into() }).await?
session.read_plan()	session.rpc().plan().read().await?
session.update_plan("...")	session.rpc().plan().update(PlanUpdateRequest { ... }).await?
session.start_fleet(Some("..."))	session.rpc().fleet().start(FleetStartRequest { ... }).await?

Because the code block uses rust,ignore, this isn't caught by cargo test --doc. A user copying these snippets from the README will get a compile error like no method named 'get_model' found for struct 'Session'.

Suggestion: Either implement these as ergonomic wrappers on Session (thin delegations to rpc()), or update this section to use session.rpc().* calls and add a note that the typed RPC namespace is the primary access point for these operations. If the wrappers are planned as a follow-up, it would be worth adding a // TODO: convenience wrapper note and linking to the "Typed RPC namespace" section so readers know the right path today.