claude-code-agent
Rust SDK for Claude Code. It drives the claude CLI over its stream-json control protocol. Verified against 2.1.329; Session::spawn refuses an older CLI (MIN_CLI_VERSION).
- one persistent
claudeprocess per session;close()ends the whole process group (process tree on Windows) - every
claude --helpflag an SDK session can use, as a typedSessionOptionsfield (extra_argsfor the rest) - every public control request as a
Sessionmethod: model, effort, thinking, permission mode, interrupt, MCP servers, settings, usage, rewind, … - a lossless event stream: text, thinking, tool calls and their results, subagent events, every
systemframe, the full turn result - hook callbacks,
can_use_tool, MCP elicitation and user-dialog handlers as async Rust closures - Rust functions as tools (
#[claude_tool]+ SDK MCP bridge), executed in-process, cancellable - Code Mode (
REPLtool) forced on withcode_mode: true - text, image and document prompts (
UserMessage::blocks) - record/replay for tests without a process, session pool,
tracingspans
Install
= { = "0.6", = ["macros"] }
Quick start
use ;
use StreamExt;
async
Hooks — async Rust closures
Hooks are declared before spawn — the CLI learns them from the initialize request.
use ;
use ;
let mut hooks = new;
// Block a tool (matcher = tool-name regex)
hooks.on;
// Inject context into every subagent
hooks.on;
let opts = SessionOptions ;
let session = spawn.await?;
Session pool — high throughput
use ;
let pool = new;
pool.warm.await; // pre-warm 2 idle processes
let s = pool.acquire.await?; // waits while max_sessions are checked out
let mut stream = new.prompt.await?;
// … drop `s` to return it; the next acquire() resets it with /clear first
Every pooled session uses PoolConfig::options (hooks, MCP servers, model). pool.acquire_with(Checkout { model: Some("haiku".into()), ..Default::default() }) hands out a session with its own model, effort or permission mode; None keeps the pool's value. A returned session is reset before reuse: /clear (local, no API call, new session id) empties the conversation, and model, effort and permission mode are set for the next checkout. A task may switch them for itself without affecting the next task.
Rust functions as tools — #[claude_tool] + SDK MCP server
use ;
/// Search files matching a glob pattern
async
let opts = SessionOptions ;
let session = spawn.await?;
// Claude now sees `mcp__files__search_files`; calls run in-process.
The macro generates search_files_tool_def() -> ToolDef and search_files_tool() -> SdkTool.
Arguments are decoded with serde; Result<T, E> maps to a result or an error result.
SDK tools are added to --allowedTools automatically. Enable with claude-code-agent = { features = ["macros"] }.
Events and results
Agent::prompt streams one turn's AgentEvents and ends with Done(TurnResult) or Error(TurnError):
| Event | Carries |
|---|---|
Text, Thinking, RedactedThinking |
model output |
ToolUse { id, name, input, server } |
a tool call (server: true for API-run tools such as web search) |
ToolResult { tool_use_id, content, is_error, structured } |
the result; structured is the tool's full output, e.g. Bash {stdout, stderr, …} |
Subagent { parent_tool_use_id, event } |
any event of a subagent |
System { subtype, data }, Other { kind, data } |
every other frame, verbatim (api_retry, task_started, rate_limit_event, …) |
Done(TurnResult) |
result text, structured_output, cost, tokens, num_turns, model_usage, permission_denials, terminal_reason |
Error(TurnError) |
kind (Execution, MaxTurns, MaxBudget, Api, …), message, and the TurnResult so far |
Structured output: set Initialize::json_schema; the parsed value arrives in TurnResult::structured_output (examples/structured_output.rs).
Agent::watch() streams every turn, including the ones the CLI starts itself after a background task finishes (TurnResult::origin set). examples/watch.rs.
Cancelling
Dropping a turn's stream before Done/Error cancels the prompt: a queued prompt is withdrawn, a running one is interrupted. Another prompt's turn is never touched. Session::cancel_prompt(uuid) does the same explicitly; Session::interrupt() stops whatever runs; Session::interrupt_all() also cancels every queued prompt. A prompt withdrawn before it ran ends its stream with TurnErrorKind::Cancelled. A prompt sent with UserMessage::with_priority(Priority::Now) aborts the running turn and runs at once; the aborted turn ends with Done and terminal_reason: "aborted_streaming".
When the CLI withdraws a request it asked the host (e.g. can_use_tool during an interrupt), the handler's future is dropped and no answer is sent. An interrupted SDK tool call drops its handler the same way.
MCP servers
- in-process:
SessionOptions::mcp_servers(SdkMcpServer), withtimeout, tooltitle/annotations/output_schema, andToolResulttext, image, resource andstructuredcontent.SdkTool::with_contextgives the handler the call'stool_use_id. - external (stdio, http, sse):
Initialize::mcp_servers. - at runtime:
Session::set_mcp_servers(sdk, external),mcp_status,mcp_toggle,mcp_reconnect,mcp_call(external servers, no model turn). - elicitation:
SessionOptions::on_elicitationanswers an MCP server asking the user for input.
Record / replay — tests without a process or API cost
let opts = SessionOptions ;
// … run a live session once …
let session = replay.await?;
Compaction
let mut stream = compact.await?;
// yields AgentEvent::Compacted { trigger: "manual", pre_tokens, post_tokens }, then Done
Observability
tracing spans claude.turn, claude.hook, claude.tool — export with any subscriber (e.g. tracing-opentelemetry).
Code Mode
let opts = SessionOptions ;
Experimental and unsupported by Anthropic: Code Mode is gated server-side, and this option forces it on. Claude gets the REPL tool and works by writing JavaScript that calls its tools. The stock CLI refuses Code Mode for every non-interactive session, so the SDK runs a patched copy. It is built on first use (about 6 s), cached under ~/.cache/claude-code-agent/code-mode/, and re-signed on macOS. The installed claude is not modified. The patch changes only the Code Mode opt-in module: the eligibility check passes, the caveats count as accepted, and the server gate counts as open. See DESIGN.md.
Session options worth knowing
| Option | Effect |
|---|---|
permission_mode: Some(PermissionMode::…) |
--permission-mode (default, acceptEdits, bypassPermissions, plan, dontAsk, auto) |
setting_sources: Some(vec![]) |
ignore user/project settings (--setting-sources ""); auth still works |
settings: Some(json) |
extra settings (--settings): an object, or a file path string; e.g. shell hooks |
clear_env: true |
child gets only env, not the parent environment (default inherits, like the official SDKs) |
resume: Some(id) / Session::reconnect |
continue a previous conversation (--resume); with fork_session: true under a new id |
continue_conversation: true |
continue the latest conversation in cwd |
include_partial: true |
text arrives as stream deltas |
model, fallback_model, effort, thinking |
model choice; switch mid-session with set_model, set_effort, set_max_thinking_tokens |
max_turns, max_budget_usd, task_budget |
limits; a turn past one ends with TurnErrorKind::MaxTurns / MaxBudget |
tools, allowed_tools, disallowed_tools, add_dirs |
tool set and file access |
persist_session: false |
no transcript on disk |
on_stderr |
every CLI stderr line, live |
extra_args |
flags without a field |
Keeping up with the CLI
python3 -I scripts/cli-parity.py lists every claude --help flag and public control request the SDK does not cover (exit 1 when any is left). Deliberate omissions, each with its reason, are in scripts/cli-parity-ignore.txt. Run it after each Claude Code update.
Hook events
HookEventKind has all 33 event names in the 2.1.328 binary. Observed firing for SDK callbacks in a live run (examples/hook_coverage.rs): PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, UserPromptSubmit, SessionStart, Stop, SubagentStart, SubagentStop, PreCompact, PostCompact, MessageDisplay. CwdChanged and FileChanged reach shell hooks in settings but not SDK callbacks. The others need situations that run did not produce (elicitation, worktrees, teammates, …).
PreToolUse · PostToolUse · PostToolUseFailure · PostToolBatch · UserPromptSubmit · UserPromptExpansion · SessionStart · SessionEnd · Stop · StopFailure · SubagentStart · SubagentStop · PreCompact · PostCompact · PreModelSwitch · PostModelSwitch · PermissionRequest · PermissionDenied · Setup · TeammateIdle · TaskCreated · TaskCompleted · Elicitation · ElicitationResult · ConfigChange · WorktreeCreate · WorktreeRemove · InstructionsLoaded · CwdChanged · FileChanged · DirectoryAdded · MessageDisplay · Notification
User dialogs
Some CLI flows stop and ask the host app a question (request_user_dialog). Declare the kinds your app renders and answer from on_user_dialog; the CLI sends no other kind.
let opts = SessionOptions ;
let init = Initialize ;
CLI 2.1.329 routes these kinds to an SDK host. The handler receives every kind the same way; the table says what each answer does.
| Kind | When | Answers | Checked against the real CLI |
|---|---|---|---|
auto_mode_server_fallback |
auto mode falls back to billed classifier requests (e.g. API key behind a gateway) | "continue" runs the classifier; "interrupt" and cancelled() reject the tool call and end the turn |
yes |
refusal_fallback_prompt |
a model refuses and a fallback model is set | "retry_fallback" retries on the fallback model; "edit_prompt" and cancelled() end the turn with the refusal |
yes |
fable_overage_consent_prompt |
a subscription reaches its Fable usage limit | per payload; an answer can turn on overage billing | no: a real account below its limit gets no dialog |
send_to_project_remote_control_offer |
sending to another project needs Remote Control | "turned_on", "already_on", "declined", "failed" |
not sent to SDK sessions: 2.1.329 refuses /send-to-project there ("isn't available in this environment") |
enum_prompt |
routed, but no flow in 2.1.329 sends it | per payload | not sent by 2.1.329 |
cancelled() means the user dismissed the dialog; the CLI applies the dialog's default.
Limitations
code_moderuns a patched copy of the CLI. The patch anchors on minified code, so a CLI release that changes the Code Mode module makes spawn fail withCodeModeError::Anchoruntil the anchors are updated. Verified on 2.1.329.- Tools of servers added with
set_mcp_serversare not pre-allowed: the permission mode andcan_use_tooldecide. mcp_callandmcp_read_resourcereach external MCP servers only; the CLI refuses in-process ones.set_system_promptworks only while the session runs the account's default model (CLI 2.1.329 cannot confirm another);set_model_and_system_promptworks always.UserMessage::with_timestampis sent, but CLI 2.1.329 records its own receive time.- No credential handling: the CLI uses its own login.
Releasing
Bump version in both Cargo.toml files (the crate and claude-code-agent-macros, plus the dependency on it), push to main, then push the matching tag:
&&
.github/workflows/release.yml runs the CI checks on Linux, macOS and Windows, then publishes both crates through crates.io Trusted Publishing. No token is stored in the repository.
License
MIT