A local-first multi-agent app development platform, built on PenguinHarness
/**
* run_subagent — delegates a subtask to a child Agent, supporting a switch to long-running
* background execution.
*
* The tool itself doesn't depend on Agent/Session, only holding an injected `SubagentRunner`
* (breaking the circular dependency). The model may freely choose the child Agent (`agent_id`),
* model (`model_id`), and thinking level (`thinking_level`) via arguments; if omitted, it falls
* back to reusing the current Agent and inheriting the parent session's model and thinking level
* respectively. The spawned child session is managed by `ManagedSubagentSession` (sharing the
* `SubagentSessionManager` injected by Environment with `input_subagent`).
*
* The two-phase semantics mirror `exec_command`: within the `yield_time_ms` window, child-session
* messages are forwarded live (tagged with origin, so the frontend can see the child Agent's tool
* calls and token usage) and the child Agent's text deltas are copied as this tool's output; if
* the child Agent finishes within the window, its terminal state is returned and the child
* session is released; if it's still running once the window expires, it's registered as a
* background session, returning `subagent_id` for subsequent access the same way as
* `input_command` (polling / appending a Prompt, see input-subagent.ts).
*
* Approval: `run_subagent` itself is a read-write tool (`rw`), so its invocation requires Human
* approval; the child session's tool approval requests are forwarded to the same Human within
* the window via the session's approval queue (tagged with origin), and queued for the next
* access while a promoted session runs in the background. A `run_in_background` launch instead
* attaches this call's own approval callback as a standing sink (see the branch below) — the
* child never parks waiting for a poll. An interruption within the startup window kills the
* child session per exec_command semantics; precheck errors such as exceeding the depth limit or
* a nonexistent agent are expressed by the runner as a throw, and collapsed to failed.
* Docs: /docs/tools § "Subagents".
*/
import { partialToolCallOutput, userText } from "../../omnimessage/index.js";
import type { OmniMessage } from "../../omnimessage/index.js";
import { DETACHED_TOOL_NOTE_PREFIX, SUBAGENT_THINKING_LEVELS } from "../../interfaces/index.js";
import type {
EnvironmentServices,
ThinkingLevelName,
ToolDefinitionConfig,
} from "../../interfaces/index.js";
import type { BuiltinTool, ToolExecutionContext, ToolResult } from "./types.js";
import {
DEFAULT_SUBAGENT_YIELD_MS,
ManagedSubagentSession,
resultForSubagentExit,
} from "./subagent/index.js";
import { collectWindow } from "./subagent/collect.js";
import { clampYield, collectUntil, reportLabel, tailForReport } from "./background/index.js";
import { describeArgumentError } from "./tool-arguments.js";
/** Tool name constant (used only within this tool module, never exposed to Environment). */
export const SUBAGENT_NAME = "run_subagent";
/** Pending-approval hint: lets the model know it should poll again to move the child Agent forward. */
export function approvalHint(session: ManagedSubagentSession): string {
const n = session.pendingApprovals;
return n > 0 ? ` [subagent is waiting for approval of ${n} tool call(s); poll to review]` : "";
}
/** Builds run_subagent's BuiltinTool from tool config + injected services. */
export function createSubagentTool(
definition: ToolDefinitionConfig,
services?: EnvironmentServices,
): BuiltinTool {
const runner = services?.subagentRunner;
const manager = services?.subagentSessions;
return {
name: SUBAGENT_NAME,
definition,
detachable: true,
async *execute(
args: Record<string, unknown>,
ctx: ToolExecutionContext,
): AsyncGenerator<OmniMessage, ToolResult | void> {
const { toolCallId, signal, approve, detachSignal } = ctx;
const fail = function* (msg: string): Generator<OmniMessage> {
yield partialToolCallOutput({ eventType: "delta", output: msg, toolCallId });
};
// Missing arguments / unconfigured services both collapse to an explanatory output rather
// than throwing (consistent with other tools).
if (!runner) {
yield* fail("[run_subagent unavailable: no subagent runner configured]");
return { stopReason: "fatal" };
}
if (!manager || manager.isDisposed) {
yield* fail("[run_subagent unavailable: no subagent session manager available]");
return { stopReason: "fatal" };
}
const prompt = typeof args.prompt === "string" ? args.prompt : "";
if (prompt.trim().length === 0) {
yield* fail(
describeArgumentError(definition, args, { argument: "prompt", kind: "missing" }),
);
return { stopReason: "fatal" };
}
const agentId = typeof args.agent_id === "string" ? args.agent_id : undefined;
const modelId = typeof args.model_id === "string" ? args.model_id : undefined;
const provider = typeof args.provider === "string" ? args.provider : undefined;
// A model is referenced by the complete (provider, model_id) pair — never half of one.
// Caught here rather than in createSession so the model is told which half it left out.
if ((modelId === undefined) !== (provider === undefined)) {
yield* fail(
"[run_subagent error: `model_id` and `provider` must be given together (a model reference is the pair), or both omitted to inherit the parent session's model]",
);
return { stopReason: "fatal" };
}
// Thinking-level override: an explicit value must be one of the selectable tiers — a typo
// must fail loudly rather than silently running the child at an inherited level the caller
// did not ask for. JSON `null` counts as omitted (= inherit), like a missing key.
const rawThinkingLevel = args.thinking_level ?? undefined;
if (
rawThinkingLevel !== undefined &&
!(SUBAGENT_THINKING_LEVELS as readonly unknown[]).includes(rawThinkingLevel)
) {
yield* fail(
`[run_subagent error: invalid \`thinking_level\` ${JSON.stringify(rawThinkingLevel)}; ` +
`use one of ${SUBAGENT_THINKING_LEVELS.join(" / ")}, or omit it to inherit the parent session's level]`,
);
return { stopReason: "fatal" };
}
const thinkingLevel = rawThinkingLevel as ThinkingLevelName | undefined;
const background = args.run_in_background === true;
const yieldMs = clampYield(
args.yield_time_ms,
DEFAULT_SUBAGENT_YIELD_MS,
definition.timeoutMs,
);
if (signal?.aborted) return { stopReason: "aborted" };
// Concurrency cap (running child Agents are never evicted): reject spawning if there's no
// room.
if (!manager.makeRoom()) {
yield* fail(
"[run_subagent error: too many background subagents; poll or finish existing ones first]",
);
return { stopReason: "fatal" };
}
// Spawn the child Session (precheck errors such as exceeding the depth limit or a
// nonexistent agent are expressed as a throw).
let session: ManagedSubagentSession;
try {
const handle = await runner.spawn({
...(agentId !== undefined ? { agentId } : {}),
...(modelId !== undefined ? { modelId } : {}),
...(provider !== undefined ? { provider } : {}),
...(thinkingLevel !== undefined ? { thinkingLevel } : {}),
});
session = new ManagedSubagentSession(handle, {
// Spawn-time owner for the revival tombstone (undefined = a self-spawn of this Agent).
...(agentId !== undefined ? { resumeAgentId: agentId } : {}),
});
// Live index from the moment of spawn (before any registration): host paths — the
// subagents panel's steer/abort — reach this child by its session id even while it
// still runs inside this call's foreground collect window.
manager.track(session);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
yield* fail(`[run_subagent error: ${message}]`);
return { stopReason: "fatal" };
}
// run_in_background: no collect window — register immediately, arm the completion
// report (fires at the end of every round until the session is killed), start the run,
// and hand back the subagent_id. The completion reaches the conversation as a harness
// user message; the model can still poll or follow up with input_subagent, or stop it
// input_subagent (abort included). The child's messages stream to the host live through the
// forwarding tap below (its own Trace stays the durable record).
if (background) {
const id = manager.register(session);
armSubagentDoneReport(session, id, prompt, services);
// Decouple the child's lifecycle from this call: a standing approval sink (this
// call's own ctx.approve — without it the child's first read-write tool would park
// at the approval queue forever, since no collect window ever attaches one) and a
// live message tap, so the child streams to the frontend past this turn's end. The
// child's abort signal is its own (ManagedSubagentSession.abortCtrl) — only
// dispose or registry eviction ends it (and a released session can be revived).
if (approve) session.setPersistentApprovalSink(approve);
const forward = services?.backgroundForward;
if (forward) session.setMessageTap(forward);
// Forward the child's session_meta upfront (run skips its own copy): the frontend's
// subagents panel and the server's subagent registry learn of the child at launch,
// not at the first input_subagent access.
const meta = session.takeMeta();
if (meta) yield meta;
session.startRun([userText(prompt, "parent_agent")]);
return {
stopReason: "completed",
note:
`[subagent running in background with subagent_id ${id}; its completion will arrive ` +
`as a user message — no need to poll. Use input_subagent to interact (abort: true stops its current run)]`,
};
}
// An interruption within the startup window kills the child session (consistent with
// exec_command); once switched to background, this listener is removed in `finally`.
// A detach is not on this listener: it leaves the child running, which is the point.
const onAbort = (): void => session.kill();
let registered = false;
signal?.addEventListener("abort", onAbort, { once: true });
const windowSignal = collectUntil(signal, detachSignal);
try {
session.startRun([userText(prompt, "parent_agent")]);
yield* collectWindow(session, {
yieldMs,
toolCallId,
...(windowSignal ? { signal: windowSignal } : {}),
...(approve ? { approve } : {}),
});
if (signal?.aborted) return { stopReason: "aborted" };
if (session.running) {
// Still running: register as a background session, returning subagent_id for
// input_subagent to continue accessing it.
const id = manager.register(session);
registered = true;
if (detachSignal?.aborted) {
// Detached by the user mid-window. The child now outlives this call, so it needs
// everything the collect window was giving it: a standing approval sink (without
// one its next read-write tool parks at the approval queue forever, since no
// window will ever attach another) and a live message tap, so it keeps streaming
// to the frontend past this turn's end. Its completion is reported like a
// run_in_background launch's — nobody is going to poll for it.
armSubagentDoneReport(session, id, prompt, services);
if (approve) session.setPersistentApprovalSink(approve);
const forward = services?.backgroundForward;
if (forward) session.setMessageTap(forward);
// No approval hint here, exactly as on a run_in_background launch: the standing
// sink just attached carries a queued request to the user itself, so "poll to
// review" would send the model after work it is not doing — the deadline
// promotion below keeps the hint because it has no such sink.
return {
stopReason: "completed",
note:
`${DETACHED_TOOL_NOTE_PREFIX} with subagent_id ${id}; leave it running unattended: ` +
`do not poll it or send it input — its completion will arrive on its own as a ` +
`[background_task_done] user message. Move on to other work, or end the turn if ` +
`nothing else is pending; input_subagent with abort: true still stops its current ` +
`run if the user asks]`,
};
}
return {
stopReason: "completed",
note:
`[subagent running with subagent_id ${id}; use input_subagent to poll for progress ` +
`or send a follow-up prompt]` +
approvalHint(session),
};
}
// Finished within the window: report the terminal state; releasing the child session is
// handled uniformly in `finally` (never registered, so no subagent_id).
return resultForSubagentExit(session.exit);
} finally {
signal?.removeEventListener("abort", onAbort);
if (!registered) session.kill();
}
},
};
}
/**
* Arms the completion report of a background-launched subagent: at the end of every
* MODEL-initiated round (the launch itself and input_subagent follow-ups) the report — id,
* terminal status, tail of the yet-undelivered answer text — goes to
* `services.backgroundDone`, which the Session turns into a harness user message. Rounds the
* HOST starts (the panel's message on an idle child) stay silent: they are the user's own
* conversation with the child, not dispatched work awaiting a result (see
* ManagedSubagentSession.startRun's suppressDoneReport), and so does a round ended by an
* explicit abort (input_subagent's `abort` / the panel's stop — the aborter sees the outcome
* directly; see abortRun). A disposed session never fires (see ManagedSubagentSession.onSettled).
*/
export function armSubagentDoneReport(
session: ManagedSubagentSession,
subagentId: string,
prompt: string,
services?: EnvironmentServices,
): void {
const notify = services?.backgroundDone;
if (!notify) return;
session.onSettled(() => {
const exit = session.exit;
// Drain the delta buffer regardless (bounded memory); the report itself carries the
// child's latest complete utterance — the same snapshot input_subagent returns.
session.drainText();
notify({
kind: "subagent",
id: subagentId,
label: reportLabel(prompt),
status: exit?.status ?? "completed",
detail: exit?.note ?? "",
output: tailForReport(session.lastAssistantText ?? ""),
});
});
}