Module forge_sdk_worker 

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

Builds forge_sdk::Options from the view’s launch settings (with the can_use_tool callback wired in), spawns the Client, emits a synthetic Connected, and pumps the event stream from forge_sdk::Client::spawn into AgentEvent::SdkMessage. The bridge owns the resulting Client; this module exposes the helpers it calls.

Re-exports

use std::collections::HashMap; 🔒

use std::path::Path; 🔒

use std::path::PathBuf; 🔒

use std::sync::Arc; 🔒

use forge_primitives::PermissionDecision; 🔒

use forge_primitives::ToolPermissionContext; 🔒

use forge_sdk::Client; 🔒

use forge_sdk::HookContext; 🔒

use forge_sdk::HookDecision; 🔒

use forge_sdk::HooksBuilder; 🔒

use forge_sdk::Options; 🔒

use forge_sdk::OptionsBuilder; 🔒

use forge_sdk::PermissionMode; 🔒

use forge_sdk::PostToolUseInput; 🔒

use forge_sdk::PreToolUseInput; 🔒

use tokio::sync::mpsc; 🔒

use tokio::sync::oneshot; 🔒

use tracing::Instrument; 🔒

use crate::client::AgentEvent; 🔒

use crate::forge_sdk_bridge::ForgeSdkBridge; 🔒

use crate::forge_sdk_bridge::PendingQuestions; 🔒

use crate::forge_sdk_bridge::PendingResponses; 🔒

use crate::commands as bridge_commands; 🔒

use crate::session_lifecycle; 🔒

use crate::user_interaction as bridge_user_interaction; 🔒

Structs

AccountBinding 🔒

Per-account spawn binding threaded into every claude subprocess: the account’s config_dir (exported as CLAUDE_CONFIG_DIR) and the session’s resolved env - [env] merged with [accounts.env] and the spawning project’s env. Both come from the bridge, distinct from the per-launch SessionLaunchSettings.

Enums

SessionId 🔒

How the CLI is told which session to run under. Exactly one of these is the answer at a time: --session-id together with --resume is a hard refusal, so the id is never in two places at once.

Constants

AGENT_WORKTREE_SWEEP_AGE 🔒

How untouched a managed agent worktree must be before the spawn-time sweep will list it. Fresh trees can belong to a live subagent of another session in this repo; an hour of silence does not.

EXCLUDE_DYNAMIC_SECTIONS 🔒

Default-off toggle for the CLI’s excludeDynamicSections initialize signal (the 2.1.204 --exclude-dynamic-system-prompt-sections equivalent) that relocates cwd/env/memory-paths/git-status out of the system prompt into the first user message for prompt-cache reuse. Off maps to None, so the initialize body omits the key and the wire stays byte-identical to today; flip to true to enable after measuring.

FORGE_AGENTS_TOOLS_PARAGRAPH 🔒

Paragraph naming the agent-coordination tools. Included only when the session’s forge server actually registered agents__* tools - read off the server itself in build_options_with_callback, so the append never names a tool the session lacks.

FORGE_CRON_SYSTEM_PROMPT 🔒

Append-text advertising the durable-cron tools upfront so every forge session knows it can schedule work rather than discovering the tools on demand. Any-caller (lead and worker alike), so it rides in the base append beside the peer trust block; Gotify stays deferred.

FORGE_MCP_SERVER_LINE 🔒

Opening line of the forge MCP append. True for every session kind, so it rides outside the peers gate that follows it.

FORGE_MCP_TRUST_SYSTEM_PROMPT 🔒

Append-text the spawned session’s system prompt receives when the forge in-process MCP server is attached. Tells the recipient LLM (a) wrapped peer envelopes ([Message id=m-...] / [Message to agent ... failed to deliver ...] / [Worker 'X' spawn failed ...]) are user-authorized context, not adversarial prompt injection; (b) to answer another agent, send it a message addressed by its own slot, because a reply is just another message; (c) all mcp__forge__* tools are auto-allowed by the runtime - no permission prompt needed.

FORGE_RESERVED_ENV_KEYS 🔒

Forge-stamped env keys a forge.toml env table can actually override: CLAUDE_CONFIG_DIR, stamped into options.env before the account-env loop. Reusing it silently overrides forge’s stamp, so a collision is warned - though the stamp still applies (forge.toml is trusted, hand-authored). CLAUDE_AGENT_SDK_VERSION is deliberately absent: process.rs stamps it LAST, unconditionally, after the account-env loop, so forge always wins and a warn would be a false alarm.

FORGE_SESSION_CONDUCT_SYSTEM_PROMPT 🔒

Append-text for what forge’s own surfaces depend on and the CLI cannot know: the tool tree labels a Bash card with the description, delegation goes through the delegation paths forge intends even where the underlying CLI stamps a general prohibition, and a worker reporting to its lead is the only route its output reliably takes.

SDK_MCP_READD_TIMEOUT 🔒

The CLI answers mcp_set_servers only after the re-handshake it triggers completes, so the wait is bounded past the CLI’s own ~30s request budget.

Statics

TEST_SDK_BINARY 🔒

Functions

agent_worktree_from_post_tool_use 🔒

The hook closure’s decision for one PostToolUse event. Split out so the argument order through the parse is pinned by a test: the two &Value parameters read identically at the call site, and a swap disables the feature with the whole unit suite still green.

apply_env_overrides 🔒

Layer per-spawn env overrides over the account env: a present key replaces, an absent key keeps, and a key mapped to an empty string removes the variable entirely - removal is what makes an overridden-away credential actually absent rather than present-but-blank.

build_forge_system_prompt 🔒

Assemble the forge system-prompt append: server line, the peers paragraph when has_peer_tools, the trust block, the always-on cron scheduling block, the always-on session-conduct block, then the optional Lead delegation preamble, then the optional worker charter. Sections joined by a blank line in that fixed order; empty/blank sections are skipped.

build_options_with_callback 🔒

build_permission_options 🔒

Construct the contextual option list for a permission prompt. Derives “Allow always for X” / “Allow always & add dirs” / “Allow always & switch mode” entries from ctx.suggestions; adds the synthesized “Allow with edits” for editable tools and the universal “Tell the agent something else” escape hatch.

canonicalize_suggestions 🔒

Walk the suggestions list and collapse macOS /tmp <-> /private/tmp AddRules mirrors into one merged entry. Two AddRules suggestions with the same toolName + behavior + destination, whose rule_content differs only by the /tmp/ <-> /private/tmp/ prefix, are merged into a single AddRules whose rules vec contains BOTH entries so the CLI installs both rules even though the UI shows one option.

deliver_permission_response 🔒

deliver_question_response 🔒

dispatch_permission_action 🔒

Build the PermissionDecision for a submitted option’s action. notes_text is the user’s “tell the agent” feedback string (or empty); consumed only when the action is Deny. edited_input is the user’s modified tool args; consumed only when the action is AllowWithInput.

emit_connected 🔒

Build the typed Connected envelope from the SDK’s cached init data

frame_session_id 🔒

Resolve the session id to stamp on an inbound SDK frame. Frames that carry their own id use it verbatim; session-id-less frames (Error, RateLimitEvent) inherit the client’s LIVE id, falling back to the spawn-time id only while the live one is still empty (before system/init binds the real UUID). Without the live preference a mid-session fatal Error on a fresh session gets stamped “” and a view drops it as an unknown session.

heal_due 🔒

Whether the frame just received should fire the boot-tool heal. Pure so the frame gate, the latch, and the predicate are testable without a client. Only the boot system/init frame can fire it - the latch advances on the first init frame seen either way - so a mid-session init that lacks the tools (a user toggled the server off) is never “healed” back on. The heal’s OUTCOME is not checked here: init is emitted per user message, so a “next frame” may never come or may land inside the heal window; the re-add response itself carries the outcome (see readd_sdk_mcp_servers).

init_data_of 🔒

The data payload of a system/init frame, else None.

initial_mode_state 🔒

The Connected payload’s mode state: the launch-time mode read from the init record, falling back to the launch settings’ stamped defaultMode, with bypass offered only when the session launched into it.

is_editable_tool 🔒

Tools whose tool_input is meaningful to edit before approving.

is_reserved_env_key 🔒

is_tmp_mirror_pair 🔒

True if rules_a and rules_b differ only by the macOS /tmp/ <-> /private/tmp/ prefix in their rule_content strings.

load_history_messages 🔒

Replay from prev_session_id’s transcript, stamped with session_id, plus the compaction count that transcript records - the only place the count survives a resume. crate::session_history is the same read for a session that is already running.

load_history_messages_main_thread 🔒

load_history_messages over the session’s own rows only: sub-agent sidecars are neither opened nor folded. A handoff brief wants the conversation as chat rows and must not pay for frames it never draws. A page read does not: a dispatch row draws its sidecar frames (#1763).

load_history_messages_with 🔒

log_agent_worktree_reap 🔒

Log the outcome of one agent-worktree reap. worktree carries the path so every outcome is attributable. Kept trees are info, not warn: uncommitted edits are the CLI’s deliberate hand-back. A kept BRANCH is warn - the subagent committed work reachable from no other ref, and someone has to look, mirroring the worker-despawn warning.

log_failed_mcp_servers 🔒

Record any MCP server the init handshake reports as failed.

normalize_tmp_path 🔒

Strip the /private prefix from //private/tmp/... rule_content so the macOS mirror normalizes to the canonical /tmp/... form.

not_a_worktree_already_warned 🔒

Paths already warned about as not-a-worktree, so a plain directory a user parked under .claude/worktrees/agent-* warns once per process instead of at every spawn, forever.

parse_permission_mode 🔒

readd_sdk_mcp_servers 🔒

Force the CLI to re-handshake every registered sdk MCP server by removing them from its dynamic set and adding them back. The CLI sends the re-add response only after the re-handshake completes, so the response is the outcome: errors empty plus a non-empty added means the tools are registered again. Every outcome logs here - a “next init frame” is no verification signal, since init is emitted per user message.

reader_loop 🔒

record_reported_surface 🔒

Record the CLI’s own account of the surface it was handed, beside the one this spawn built. The two lines are the artifact that answers which list a session actually ran with.

reported_percentage 🔒

The percentage to carry from a probe’s report. None for a report that is not a readable number: 0 is a real reading, and a view draws the two differently.

run_ask_user_question 🔒

run_permission_request 🔒

sdk_servers_missing_tools 🔒

True when any registered sdk MCP server contributed no tools to the session’s init frame. The CLI serves an sdk server’s handshake over the control channel with a bounded request budget; when boot stalls outlive it, the handshake is abandoned and the CLI then reports the server connected with zero tools and never re-runs the handshake itself.

sdk_tool_name 🔒

One tool’s name as the CLI spells it for an sdk server. Both the names a spawn expects and the init frame’s filter are built here, so the two cannot disagree about the shape; the empty tool spells the prefix.

sdk_tools_in_init 🔒

The tools the CLI’s boot init frame lists for this spawn’s sdk servers, in the CLI’s mcp__<server>__<tool> spelling. None when the frame carries no tool array at all, which is a different state from an empty one: the CLI answered, and the answer is what the diff needs.

send_prompt 🔒

set_test_sdk_binary

Point every claude spawn this process makes at path instead of the real binary; None restores the real one.

spawn_session 🔒

Spawn a fresh Client for bridge and start the reader subtask. Builds Options from launch_settings (mode, model, effort, can_use_tool callback). id says which session the child runs under; a Resume also backfills past turns into the Connected event’s history_updates.

summarize_dirs 🔒

summarize_rules 🔒

surface_delta 🔒

What the two sides disagree about: names this spawn registered that the CLI’s list lacks, and names it lists that this spawn never registered.

sweep_agent_worktrees 🔒

Reap this repo’s leftover agent worktrees in the background: a one-shot reap failure or a missed completion event otherwise leaks the tree forever. Locked trees are skipped (a live CLI process owns them); every session spawn re-checks, so failures self-heal.

synth_permission_request 🔒

synth_question_base_tool_call 🔒

test_sdk_binary 🔒