Crate forge_agent 

forge-agent - drives one forge_sdk::Client and exposes a channel-based Agent / AgentHandle surface to UI consumers.

Public API: Agent::spawn returns an AgentHandle holding Sender<Command>, a take_events() for the bridge’s AgentEvent stream, and direct-accessor passthroughs (config_dir, settings_documents, oauth_*).

ForgeSdkBridge is a pub(crate) implementation detail - Agent’s dispatcher task is the only caller.

Module layout

• agent - Agent::spawn + AgentHandle (the public API).
• client - AgentEvent enum + supporting types.
• cloud - network-side state: oauth + cli usage fetchers.
• userdata - disk-side state: settings, sessions catalog, memory, plugins.
• commands / session_lifecycle - bridge helpers consumed by the worker and the workspace.
• forge_sdk_worker (crate-private) / replay / tooling / user_interaction - internal implementation modules consumed by agent’s dispatcher and translator paths.

Re-exports

pub use agent::Agent;

pub use agent::AgentError;

pub use agent::AgentHandle;

pub use client::AgentEvent;

pub use client::SessionLaunchSettings;

pub use forge_sdk_worker::set_test_sdk_binary;

pub use userdata::catalog::scan::has_a_transcript_row;

Modules

agent

Channel-based Agent handle - the public consumer surface.

client

cloud

Network-side state. OAuth flow, account info, usage polling - anything that talks to api.anthropic.com directly (NOT through the claude CLI subprocess).

commands

Mode-state helpers - supported-mode list filtering + ModeState builder. Used by the worker to assemble the Connected event payload at spawn time.

env

Live environment - git context, cwd insights, OS-side observations the agent needs but the SDK doesn’t.

forge_sdk_bridge 🔒

ForgeSdkBridge - in-process driver around a forge_sdk::Client.

forge_sdk_worker 🔒

Session-launcher + reader-pump helpers for the bridge layer.

http_trust

Reqwest builder helper that extends the TLS trust store with certs from NODE_EXTRA_CA_CERTS (with SSL_CERT_FILE as fallback) to match native claude’s TLS trust behaviour.

logging

Tracing target constants used by the agent’s bridge code. Strings stay consistent with the server’s logging::targets so the subscriber’s env-filter picks up agent-side logs.

replay 🔒

Resume-history synthesizer: converts on-disk transcript JSONL into the forge_primitives::Message envelopes the live wire stream produces, so consumers read replay and live messages identically.

session_lifecycle

Model resolution + connect-event + initialize-result mapping. Mirrors the relevant portions of upstream’s agent-sdk/src/bridge/session_lifecycle.ts.

tooling

Tool-call construction + tool-result extraction. 1:1 port of upstream’s agent-sdk/src/bridge/tooling.ts (714 LoC).

translate

Translation helpers used by callers that need to convert wire-shape data (forge-sdk message payloads, control responses) into typed Rust values. A view consumes these from its event-loop translator paths.

user_interaction

AskUserQuestion sequential sequencing. Mirrors upstream’s agent-sdk/src/bridge/user_interaction.ts (323 LoC) - focused on the multi-question loop + answer-payload assembly.

userdata

User-data state on disk. Settings, sessions catalog, memory, plugins, slash commands, MCP config - anything the agent reads or writes outside live SDK sessions.

Enums

PermissionMode

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

Functions

session_history

The messages a session’s transcript holds and the compactions it records. The same read the spawn performs, available for a session that is already running.

session_history_main_thread

session_history over the session’s own rows only: sub-agent sidecars are not opened or folded. The handoff brief takes this one, so it pays for neither the frames nor the parse. A page read does not: a dispatch row draws its sidecar frames (#1763).

transcript_rows

The rows of a session’s transcript that sit strictly before below, for a paging read that has walked below the window a conversation is kept in.