Crate forge_sdk 

forge-sdk

A peer reference implementation in Rust of a client for Anthropic’s claude CLI. Spawns the binary as a subprocess and speaks stream-json over stdio. Wire compatibility with the CLI is the only hard external invariant; API shape is whatever serves forge-agent (and through it the views) best.

Design

The SDK is a thin wrapper around the claude binary. All agentic work - tool dispatch, conversation history, session persistence - happens inside the CLI itself. This crate is responsible for:

• Spawning the subprocess with the right flags.
• Parsing the stream-json output into typed Rust values.
• Serialising user messages into stream-json input.
• Bridging the can_use_tool callback (when enabled) across the wire.
• Hosting in-process MCP tool servers that the claude binary can call.

Client is Clone-able; all commands take &self. Internally a reader task owns the subprocess after init, decodes lines, dispatches inbound control_requests on detached tasks, and routes outbound control_responses to per-request waiters.

Minimal example

use forge_sdk::{Client, OptionsBuilder};

let options = OptionsBuilder::new().build();
let (client, mut events) = Client::spawn(options).await?;
client.send_user_message("hello").await?;
while let Some(item) = events.recv().await {
    let event = item?;
    println!("{event:?}");
}
client.disconnect().await?;

Re-exports

pub use crate::mcp::macros::__private;

pub use client::Client;

pub use client::ClientEvents;

pub use client::INIT_HANDSHAKE_TIMEOUT;

pub use error::Error;

pub use hooks::HookCallback;

pub use hooks::HookDecision;

pub use hooks::Hooks;

pub use hooks::HooksBuilder;

pub use options::Options;

pub use options::OptionsBuilder;

pub use paths::app_support_dir;

pub use paths::config_dir_hash;

pub use paths::config_dir_store_key;

pub use paths::projects_dir_for;

pub use permissions::CanUseToolCallback;

pub use transport::process::CLOSE_WAIT_TIMEOUT;

Modules

argv

Pure-function argv composition. Takes an Options and produces the Vec<String> to pass to the claude subprocess. Kept separate from transport::process so the transport layer doesn’t import MCP orchestration types.

client 🔒

Public Client - the entry point consumers hold.

control

Control-protocol messages exchanged over the main stream-json stdio channel.

error 🔒

Error type for the forge-sdk crate.

hooks

Hook callbacks - 10 hook kinds dispatched by opaque callback_id.

logging 🔒

Tracing target constants for forge-sdk.

mcp

In-process MCP server hosting.

options 🔒

Configuration for spawning a Client.

paths

Path helpers around the claude CLI’s on-disk config layout.

permissions 🔒

Permission callback trait + tests. Wire-data lives in forge-primitives - consumers import from there directly.

request_id

Request ID generator for outbound control_request frames.

subagents

Subagent declarations - re-export shim. Wire-shape data lives in forge-primitives.

transport

Subprocess transport for the claude binary.

Macros

tool

Declarative tool-trait impl.

Structs

BaseHookInput

Fields shared by every hook input the CLI emits. Every concrete input type below flattens this struct so callbacks can access session_id, transcript_path, cwd, and (optionally) permission_mode without reaching back into super::HookContext.

HookContext

Context carried alongside every hook invocation.

NotificationInput

Input payload for Notification.

PermissionRequestInput

Input payload for PermissionRequest.

PostToolUseFailureInput

Input payload for PostToolUseFailure.

PostToolUseInput

Input payload for PostToolUse.

PreCompactInput

Input payload for PreCompact.

PreToolUseHookSpecificOutput

hookSpecificOutput shape for PreToolUse hook responses.

PreToolUseInput

Input payload for PreToolUse.

StopInput

Input payload for Stop.

SubagentContext

Optional sub-agent attribution present on tool-lifecycle hook inputs (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest). Fields are populated when the hook fires inside a Task-spawned sub-agent so tool events can be attributed back to the right agent when multiple sub-agents interleave over the same control channel.

SubagentStartInput

Input payload for SubagentStart.

SubagentStopInput

Input payload for SubagentStop.

UserPromptSubmitHookSpecificOutput

hookSpecificOutput shape for UserPromptSubmit.

UserPromptSubmitInput

Input payload for UserPromptSubmit.

Enums

HookKind

Identifies which hook point a callback is registered for. Sixteen event kinds mirrored from the CLI v0.1.64, plus Unknown as a fallback for forward-compatibility.

PermissionMode

Which permission flow the claude binary should use for tool invocations. Mirrors the upstream CLI’s six-variant set.

SdkPluginConfig

Plugin config. Wraps the CLI’s SdkPluginConfig ({"type": "local", "path": str}).

SystemPromptKind

System-prompt configuration. Wraps the CLI’s discriminated union of str | SystemPromptPreset | SystemPromptFile.

Type Aliases

Result

Convenient alias for Result<T, forge_sdk::Error>.