Struct AgentHandle 

pub struct AgentHandle {
    pub commands: UnboundedSender<AgentCommand>,
    agent_events: Mutex<Option<UnboundedReceiver<AgentEvent>>>,
    bridge: Arc<ForgeSdkBridge>,
}

Handle returned by Agent::spawn. Owns the channels + a thin passthrough to the bridge’s direct-return accessors.

Fields

commands: UnboundedSender<AgentCommand>

UI → agent commands. Used internally by the inherent command-shorthand methods (prompt_text, cancel, etc.). Public so callers can send(AgentCommand::...) directly when richer flows are needed.

agent_events: Mutex<Option<UnboundedReceiver<AgentEvent>>>

Bridge’s raw AgentEvent receiver. Single-take via AgentHandle::take_events - the workspace’s session task consumes this and translates it into SessionUpdates.

bridge: Arc<ForgeSdkBridge>

Bridge handle used for direct-return accessors (config_dir, settings_documents, …) plus internal command dispatch.

Implementations

impl AgentHandle

pub fn take_events(&self) -> Option<UnboundedReceiver<AgentEvent>>

Take ownership of the bridge’s AgentEvent receiver. Returns Some exactly once.

pub fn config_dir(&self) -> PathBuf

pub fn claude_pid(&self) -> Option<u32>

OS PID of the bound claude child, when one is currently attached. Surfaces to forge-workspace for the Inspector pane’s PROCESSES OS-walk.

pub fn kill_process_group(&self)

Take the session’s process group down without the async drain.

For a session that never got a task to run its exit path: dropping the handle alone SIGKILLs the direct child and leaves the tools the CLI already started behind.

pub fn project_memory_path(&self, cwd: &Path) -> PathBuf

pub fn settings_documents(&self, cwd: Option<&Path>) -> SettingsDocuments

pub fn display_name(&self) -> Option<String>

Returns a clone of the bridge’s bound forge-account display_name (when forge-workspace picked one). Used by the connect-flow to emit a ForgeAccountIdentityReady event right after spawn - eliminates the welcome-message flicker that would otherwise wait for the slow status snapshot to arrive from the CLI.

pub fn env(&self) -> HashMap<String, String>

The bridge’s resolved forge.toml env. Test-only, and one hop short of what the child receives - the subprocess also gets CLAUDE_CONFIG_DIR and the SDK version. It exists so a test can observe the map a spawn carries rather than what the resolution helper returned.

pub async fn disconnect(&self)

Disconnect the bound claude subprocess: take the bridge’s client slot and run the SDK’s graceful shutdown (signal the reader task, drain, close the child). Both layers are idempotent via Option::take, so repeated calls on clones are no-ops. Called from SessionTask’s exit path so release / despawn / teardown paths actually kill the subprocess instead of leaving it alive until forge exits.

fn send(&self, cmd: AgentCommand) -> Result<(), AgentError>

pub fn new_session( &self, session_id: Option<String>, cwd: String, launch_settings: SessionLaunchSettings, ) -> Result<(), AgentError>

Start a session under session_id, or under an id the CLI picks when that is None.

pub fn resume_session( &self, session_id: String, cwd: String, launch_settings: SessionLaunchSettings, ) -> Result<(), AgentError>

pub fn resume_or_new_session( &self, session_id: String, cwd: String, launch_settings: SessionLaunchSettings, ) -> Result<(), AgentError>

Resume the recorded session_id; if resume fails (stale catalog entry, cross-account scan, deleted .jsonl), retry as a fresh session in cwd. The user only sees a ConnectionFailed event when both attempts fail.

pub fn prompt_text( &self, session_id: String, text: String, uuid: String, ) -> Result<(), AgentError>

pub fn prompt_with_images( &self, session_id: String, text: String, images: Vec<ImageAttachment>, uuid: String, ) -> Result<(), AgentError>

pub fn cancel(&self, session_id: String) -> Result<(), AgentError>

pub fn cancel_queued( &self, session_id: String, uuid: String, ) -> Result<(), AgentError>

pub fn set_mode( &self, session_id: String, mode: PermissionMode, ) -> Result<(), AgentError>

pub fn set_model( &self, session_id: String, model: String, ) -> Result<(), AgentError>

pub fn get_context_usage(&self, session_id: String) -> Result<(), AgentError>

pub fn get_mcp_snapshot(&self, session_id: String) -> Result<(), AgentError>

pub fn permission_response( &self, session_id: String, tool_call_id: String, outcome: PermissionOutcome, ) -> Result<(), AgentError>

pub fn question_response( &self, session_id: String, tool_call_id: String, outcome: QuestionOutcome, ) -> Result<(), AgentError>