Struct SubAgent 

pub struct SubAgent {
    pub description_call: ToolDescription,
    /* private fields */
}

Tool for calling sub-agents.

A SINGLE visible tool dispatches to two implementations — the model sees only one: an external ACP agent harness when agent is provided, or an internal agent (a nested harness: fresh empty context, auto-approve, no persistence, final report only) when agent is omitted or empty. The harness routes the call; this struct owns the visible schema, the optional description note (see set_note), and the cross-call memory: the last input message (retry support) and the last ACP session id per agent (Phase 4 session resume).

Each instance keeps the last input message sent to a sub-agent, so a retry after a failed call does not require re-writing the whole prompt, plus the last ACP session id per agent name, so the next call with continue_session (the default) resumes that session. The harness creates one instance per agent loop, so neither ever leaks across sessions and no explicit clean() is needed.

Fields

description_call: ToolDescription

MCP Tool description for call.

Implementations

impl SubAgent

pub fn new() -> Self

Create a new SubAgent with a tool description tailored to only the ACP agent harnesses that are actually installed in PATH. Detection runs once per process (cached by detect_installed()).

pub fn set_note(&mut self, note: impl Into<String>)

Set an informational chunk that is interpolated NATURALLY into the tool description (inside the description prose — not prepended as a notice). The harness uses this to tell the model that omitting agent routes the call to an internal agent instead of an external ACP harness.

Rebuilds Self::description_call with the new chunk; an empty chunk keeps the original description byte-for-byte.

pub fn resolve_input(&self, input: Option<String>) -> Result<String, String>

Resolve the effective input message for a sub-agent call.

When input is provided (and non-empty), it is stored as the last message sent to a sub-agent in this session and returned. When omitted, the stored message is reused so the calling agent does not have to re-write a long prompt after a failed call.

Errors

Returns an error if input is omitted and no message is stored yet (i.e. no sub-agent has been called in this session).

Panics

Panics if the internal mutex is poisoned (only possible if another thread panicked while holding the lock).

pub fn store_session(&self, agent: &str, session_id: String)

Store the ACP session id a harness returned for agent (Phase 4).

Only successful turns are stored: a failed or timed-out turn leaves the previous id untouched (so None from [stored_session] makes the next call open a fresh session, and an older id that a failed turn ran on is retried on the next default call — a stale one self-heals via the session/new fallback in [open_or_resume_session]).

pub fn session_recorder(&self) -> Arc<Mutex<HashMap<String, String>>>

Cloneable recorder of the ACP session map, for BACKGROUND turns.

A background subagent_call spawns a detached task and returns immediately, so it cannot call Self::store_session after the (much later) turn ends — the dispatcher borrow is long gone. The detached task keeps this handle and records the session id at turn end, exactly where the synchronous path would. Sharing the same Arc<Mutex<..>> keeps background and synchronous bookkeeping in ONE map, so resume_id sees both.

pub fn stored_session(&self, agent: &str) -> Option<String>

The session id to resume for agent, when continue_session is requested and one is stored. None → the caller opens a fresh session (first call for this agent, or no id has ever been stored — failed turns do not clear a previously stored id).

pub fn resume_id(&self, agent: &str, continue_session: bool) -> Option<String>

The resume argument for acp::call: the stored session id when continue_session is requested (resume-by-default), None for the opt-out (continue_session: false) or when nothing is stored yet. Keeping the flag→id decision here makes the opt-out mapping unit-testable; the dispatch layer just forwards the result.

Trait Implementations

impl Default for SubAgent

fn default() -> Self

Returns the “default value” for a type.