@jerryan/pi-subagent-tools 0.1.1 → 0.3.0

package/agents.ts

@@ -0,0 +1,878 @@
+/**
+ * Agent manager — in-process subagent sessions with follow-up support.
+ *
+ * Each subagent is an AgentSession created via the pi SDK, running in the
+ * parent's process. Sessions are in-memory (SessionManager.inMemory) — no
+ * backing files, the in-process equivalent of --no-session.
+ *
+ * Lifetime
+ * ────────
+ * Agents live in a registry keyed by id ("delegate-1", "review-2", ...).
+ * Cleanup is recency-based, not count-based:
+ *
+ *   - The owning session's turn counter advances on every turn_end.
+ *   - An agent records lastActiveTurn at spawn and when each run completes.
+ *   - A sweep at turn_end disposes agents idle for more than
+ *     PROTECTION_TURNS turns. There is no cap — any number of recently
+ *     active agents survive.
+ *   - Running agents (session.isStreaming) are never disposed. With
+ *     turn-scoped execution this is structural — a turn cannot end while
+ *     its tool calls are still running — but the guard also covers a
+ *     future background mode.
+ *   - All agents are disposed when the owning session shuts down.
+ *
+ * Ownership
+ * ─────────
+ * A delegate child gets its own manager (own id namespace, own turn
+ * tracking), stored on the spawning entry. Disposing an entry cascades to
+ * its child manager, so no session in the tree outlives its owner.
+ *
+ * Recursion
+ * ─────────
+ * Structural, not env-based. Review/explore children are created with
+ * noExtensions: true — they get exactly the tools injected here (read +
+ * sandboxed bash) and are leaves. Delegate children discover user/project
+ * extensions like a fresh pi (guard extensions included), minus this
+ * extension itself — self-exclusion is the recursion guard — and get
+ * review/explore/follow_up via an inline extension factory; their
+ * delegate tool is registered but rejects.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Type, type TObject } from "@sinclair/typebox";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+  CONFIG_DIR_NAME,
+  type AgentSession,
+  type AgentToolResult,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { createUIBridge } from "./ui-bridge.ts";
+import { sandboxBashTool } from "./sandbox-bash.ts";
+import { renderSubagentCall, renderSubagentResult } from "./render.ts";
+import { shortenPath, truncate, TOOL_LINE_PREFIX, type UsageStats } from "./tui.ts";
+
+const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PROMPTS_DIR = path.resolve(EXTENSION_DIR, "prompts");
+
+// ---------------------------------------------------------------------------
+// Roles — everything that distinguishes delegate/review/explore children
+// ---------------------------------------------------------------------------
+
+export type AgentRole = "delegate" | "review" | "explore";
+
+/**
+ * Tool allowlist for read-only child roles. "bash" here denotes the
+ * sandboxed read-only shell injected via customTools (custom tools shadow
+ * builtins of the same name — fail-closed).
+ */
+export const READONLY_TOOLS = ["read", "bash"];
+
+interface RoleConfig {
+  promptFile: string;
+  /** Built-in tool allowlist. Undefined = pi defaults (full access). */
+  tools?: string[];
+  customTools?: ToolDefinition<any>[];
+  /** Whether children of this role get the (guarded) subagent tool surface. */
+  childExtension: boolean;
+  /**
+   * Whether the child discovers and loads user/project extensions like a
+   * fresh pi would. True for delegate (a worker needs the parent's full
+   * environment — tools, guards); false for read-only leaf agents (minimal
+   * surface is the point).
+   */
+  discoverExtensions: boolean;
+}
+
+const ROLES: Record<AgentRole, RoleConfig> = {
+  delegate: {
+    promptFile: path.join(PROMPTS_DIR, "delegate.md"),
+    childExtension: true,
+    discoverExtensions: true,
+  },
+  review: {
+    promptFile: path.join(PROMPTS_DIR, "review.md"),
+    tools: READONLY_TOOLS,
+    customTools: [sandboxBashTool],
+    childExtension: false,
+    discoverExtensions: false,
+  },
+  explore: {
+    promptFile: path.join(PROMPTS_DIR, "explore.md"),
+    tools: READONLY_TOOLS,
+    customTools: [sandboxBashTool],
+    childExtension: false,
+    discoverExtensions: false,
+  },
+};
+
+/** Agents idle for more than this many owning-session turns are disposed. */
+export const PROTECTION_TURNS = 10;
+
+// ---------------------------------------------------------------------------
+// Parameter schemas
+// ---------------------------------------------------------------------------
+
+const TaskParam = Type.String({
+  description: "Task to delegate to the subagent",
+});
+
+const SkillsParam = Type.Optional(
+  Type.Array(Type.String(), {
+    description: "Optional startup skills to load (paths, like --skill)",
+  }),
+);
+
+const CwdParam = Type.Optional(
+  Type.String({
+    description:
+      "Working directory for the subagent. Defaults to the parent's cwd.",
+  }),
+);
+
+export const ReviewParams = Type.Object({
+  task: TaskParam,
+  skills: SkillsParam,
+});
+
+export const ExploreParams = Type.Object({
+  task: TaskParam,
+  cwd: Type.String({
+    description:
+      "Working directory for the explorer. Required — the explorer runs in the target project to pick up its settings, skills, and context files.",
+  }),
+  skills: SkillsParam,
+});
+
+export const DelegateParams = Type.Object({
+  task: TaskParam,
+  cwd: CwdParam,
+  skills: SkillsParam,
+});
+
+export const FollowUpParams = Type.Object({
+  agent: Type.String({
+    description:
+      'Agent id from a previous spawn or follow_up result (e.g. "delegate-1"). The agent continues its session with full context and retains its original role, tools, and working directory.',
+  }),
+  task: Type.String({
+    description: "Follow-up task or question for the agent",
+  }),
+});
+
+/** Shared shape of all spawn-tool parameters (each schema is a subset). */
+interface SpawnToolParams {
+  task: string;
+  cwd?: string;
+  skills?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface AgentEntry {
+  id: string;
+  session: AgentSession;
+  bridge: ProgressBridge;
+  childManager?: AgentManager;
+  lastActiveTurn: number;
+}
+
+export interface SpawnAgentOptions {
+  role: AgentRole;
+  task: string;
+  cwd: string;
+  skills?: string[];
+  ctx: ExtensionContext;
+  signal?: AbortSignal;
+  onUpdate?: (result: AgentToolResult<any>) => void;
+}
+
+/**
+ * Everything needed to create a child session. One named type shared by the
+ * production default and the test seam — with two separate signatures the
+ * two sides could drift apart; with one params type, drift is a compile
+ * error.
+ */
+export interface SpawnSessionParams {
+  opts: SpawnAgentOptions;
+  id: string;
+  runtime: () => Promise<ModelRuntime>;
+  childManager: AgentManager | undefined;
+}
+
+export interface FollowUpOptions {
+  agent: string;
+  task: string;
+  signal?: AbortSignal;
+  onUpdate?: (result: AgentToolResult<any>) => void;
+}
+
+export interface AgentManagerDeps {
+  /** Shared model runtime. Defaults to a process-wide lazy singleton. */
+  runtime?: () => Promise<ModelRuntime>;
+  /** Test seam: override session creation. */
+  spawnSession?: (params: SpawnSessionParams) => Promise<AgentSession>;
+}
+
+let sharedRuntime: Promise<ModelRuntime> | undefined;
+
+function defaultRuntime(): Promise<ModelRuntime> {
+  if (!sharedRuntime) sharedRuntime = ModelRuntime.create();
+  return sharedRuntime;
+}
+
+// ---------------------------------------------------------------------------
+// Throttle (leading + trailing)
+// ---------------------------------------------------------------------------
+
+function createThrottle(fn: () => void, interval: number) {
+  let last = 0;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return {
+    trigger() {
+      const now = Date.now();
+      if (now - last >= interval) {
+        last = now;
+        fn();
+      } else if (!timer) {
+        timer = setTimeout(() => {
+          timer = null;
+          last = Date.now();
+          fn();
+        }, interval - (now - last));
+      }
+    },
+    cancel() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Progress bridge — translates session events into tool progress updates
+// ---------------------------------------------------------------------------
+
+const MAX_PREV_LINES = 20;
+const UPDATE_INTERVAL = 200;
+
+export class ProgressBridge {
+  private previousTurnsText = "";
+  private streamText = "";
+  private turnCount = 0;
+  private tokens = { input: 0, output: 0 };
+  private startTime = Date.now();
+  private onUpdate?: (result: AgentToolResult<any>) => void;
+  private throttle = createThrottle(() => this.doUpdate(), UPDATE_INTERVAL);
+
+  reset(onUpdate?: (result: AgentToolResult<any>) => void) {
+    this.throttle.cancel();
+    this.previousTurnsText = "";
+    this.streamText = "";
+    this.turnCount = 0;
+    this.tokens = { input: 0, output: 0 };
+    this.startTime = Date.now();
+    this.onUpdate = onUpdate;
+  }
+
+  usage(): UsageStats {
+    return {
+      turns: this.turnCount,
+      input: this.tokens.input,
+      output: this.tokens.output,
+      durationMs: Date.now() - this.startTime,
+    };
+  }
+
+  private displayText() {
+    return (
+      this.previousTurnsText +
+      (this.previousTurnsText && this.streamText ? "\n" : "") +
+      this.streamText
+    );
+  }
+
+  private pushPrev(text: string) {
+    if (!text) return;
+    this.previousTurnsText = this.previousTurnsText
+      ? this.previousTurnsText + "\n" + text
+      : text;
+    const lines = this.previousTurnsText.split("\n");
+    if (lines.length > MAX_PREV_LINES) {
+      this.previousTurnsText = lines.slice(-MAX_PREV_LINES).join("\n");
+    }
+  }
+
+  private doUpdate() {
+    if (!this.onUpdate) return;
+    this.onUpdate({
+      content: [{ type: "text", text: this.displayText() }],
+      details: { usage: this.usage() },
+    });
+  }
+
+  /** Feed a session event. */
+  handle(event: any) {
+    if (event.type === "message_update" && event.assistantMessageEvent) {
+      const delta = event.assistantMessageEvent;
+      if (delta.type === "text_delta" || delta.type === "thinking_delta") {
+        this.streamText += delta.delta;
+        this.throttle.trigger();
+      }
+      return;
+    }
+
+    if (event.type === "message_end" && event.message) {
+      const msg = event.message;
+      if (msg.role !== "assistant") return;
+      this.turnCount++;
+      if (msg.usage) {
+        this.tokens.input += msg.usage.input || 0;
+        this.tokens.output += msg.usage.output || 0;
+      }
+      this.pushPrev(this.streamText);
+      this.streamText = "";
+      this.throttle.trigger();
+      return;
+    }
+
+    if (event.type === "tool_execution_start") {
+      this.pushPrev(formatToolCallLine(event.toolName, event.args));
+      this.throttle.trigger();
+    }
+  }
+}
+
+/** One-line summary of a tool call: "▸ name k=v k=v", capped at 80 chars. */
+function formatToolCallLine(name: string, args: unknown): string {
+  const parts = [`${TOOL_LINE_PREFIX} ${name}`];
+  if (args && typeof args === "object" && !Array.isArray(args)) {
+    const entries = Object.entries(args);
+    const capPerParam = entries.length > 1;
+    for (const [k, v] of entries) {
+      const val = typeof v === "string" ? v : JSON.stringify(v);
+      parts.push(`${k}=${capPerParam ? truncate(val, 40) : val}`);
+    }
+  }
+  return truncate(parts.join(" "), 80);
+}
+
+// ---------------------------------------------------------------------------
+// Result extraction
+// ---------------------------------------------------------------------------
+
+function extractResult(messages: Array<any>): { output: string; isError: boolean } {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role !== "assistant") continue;
+    if (msg.stopReason === "error") {
+      return {
+        output: `Subagent failed: ${msg.errorMessage || "unknown error"}`,
+        isError: true,
+      };
+    }
+    if (msg.stopReason === "aborted") {
+      return { output: "Subagent was aborted", isError: true };
+    }
+    const text = (msg.content ?? [])
+      .filter((c: any) => c.type === "text")
+      .map((c: any) => c.text)
+      .join("");
+    if (text) return { output: text, isError: false };
+  }
+  return { output: "(no output)", isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// Error helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Signal a tool error. In current pi, errors are reported by throwing — the
+ * agent loop catches and marks the tool result as an error with this message.
+ * (Returning isError in the result object is no longer supported.)
+ */
+function fail(text: string): never {
+  throw new Error(text);
+}
+
+function assertCwd(cwd: string | undefined): asserts cwd is string {
+  if (!cwd) fail("Cannot spawn subagent: cwd is required.");
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(cwd);
+  } catch (err: any) {
+    fail(
+      `Cannot spawn subagent: cwd "${cwd}" does not exist or is not accessible (${err.message}).`,
+    );
+  }
+  if (!stat.isDirectory()) {
+    fail(`Cannot spawn subagent: "${cwd}" is not a directory.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Agent manager
+// ---------------------------------------------------------------------------
+
+export class AgentManager {
+  private entries = new Map<string, AgentEntry>();
+  private counters = new Map<string, number>();
+  private turn = 0;
+  private runtime: () => Promise<ModelRuntime>;
+  private spawnSession?: AgentManagerDeps["spawnSession"];
+
+  constructor(deps: AgentManagerDeps = {}) {
+    this.runtime = deps.runtime ?? defaultRuntime;
+    this.spawnSession = deps.spawnSession;
+  }
+
+  /** Ids of live agents, in spawn order. */
+  liveIds(): string[] {
+    return [...this.entries.keys()];
+  }
+
+  /** Advance the owning session's turn counter and sweep stale agents. */
+  noteTurnEnd() {
+    this.turn++;
+    for (const [id, entry] of this.entries) {
+      if (entry.session.isStreaming) continue;
+      if (this.turn - entry.lastActiveTurn > PROTECTION_TURNS) {
+        this.disposeEntry(id, entry);
+      }
+    }
+  }
+
+  /** Dispose all agents (owning session shutdown/replacement). */
+  disposeAll() {
+    for (const [id, entry] of this.entries) {
+      this.disposeEntry(id, entry);
+    }
+  }
+
+  private disposeEntry(id: string, entry: AgentEntry) {
+    this.entries.delete(id);
+    // Cascade before disposing the session: no grandchild outlives its owner.
+    entry.childManager?.disposeAll();
+    try {
+      entry.session.dispose();
+    } catch {
+      // Dispose is best-effort cleanup; a broken session must not jam the sweep.
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Spawn
+  // -------------------------------------------------------------------------
+
+  async spawn(opts: SpawnAgentOptions): Promise<AgentToolResult<any>> {
+    assertCwd(opts.cwd);
+
+    const role = ROLES[opts.role];
+    const next = (this.counters.get(opts.role) ?? 0) + 1;
+    this.counters.set(opts.role, next);
+    const id = `${opts.role}-${next}`;
+    const childManager = role.childExtension
+      ? new AgentManager({ runtime: this.runtime })
+      : undefined;
+
+    let session: AgentSession;
+    try {
+      session = await (this.spawnSession ?? defaultSpawnSession)({
+        opts,
+        id,
+        runtime: this.runtime,
+        childManager,
+      });
+    } catch (err: any) {
+      fail(`Failed to start subagent: ${err.message || String(err)}`);
+    }
+
+    const entry: AgentEntry = {
+      id,
+      session,
+      bridge: new ProgressBridge(),
+      childManager,
+      lastActiveTurn: this.turn,
+    };
+    session.subscribe((event) => entry.bridge.handle(event));
+    this.entries.set(id, entry);
+
+    return this.run(entry, opts.task, opts.signal, opts.onUpdate);
+  }
+
+  // -------------------------------------------------------------------------
+  // Follow-up
+  // -------------------------------------------------------------------------
+
+  async followUp(opts: FollowUpOptions): Promise<AgentToolResult<any>> {
+    const entry = this.entries.get(opts.agent);
+    if (!entry) {
+      const live = this.liveIds();
+      const hint = live.length > 0 ? ` Live agents: ${live.join(", ")}.` : " No live agents.";
+      fail(
+        `Agent "${opts.agent}" not found (expired or never existed).${hint} Spawn a fresh agent instead.`,
+      );
+    }
+    return this.run(entry, opts.task, opts.signal, opts.onUpdate);
+  }
+
+  // -------------------------------------------------------------------------
+  // Run one prompt against an agent's session
+  // -------------------------------------------------------------------------
+
+  private async run(
+    entry: AgentEntry,
+    task: string,
+    signal: AbortSignal | undefined,
+    onUpdate: ((result: AgentToolResult<any>) => void) | undefined,
+  ): Promise<AgentToolResult<any>> {
+    // Any engagement — even an aborted or failed run — marks the agent active.
+    entry.lastActiveTurn = this.turn;
+    entry.bridge.reset(onUpdate);
+
+    const onAbort = () => {
+      void entry.session.abort();
+    };
+    if (signal?.aborted) fail("Subagent was aborted");
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+
+    try {
+      await entry.session.prompt(task, { expandPromptTemplates: false });
+    } catch (err: any) {
+      fail(`Subagent failed: ${err.message || String(err)}`);
+    } finally {
+      if (signal) signal.removeEventListener("abort", onAbort);
+    }
+
+    const { output, isError } = extractResult(entry.session.messages as any[]);
+    const text = `${output}\n\n---\nagent: ${entry.id}`;
+    if (isError) fail(text);
+    return {
+      content: [{ type: "text" as const, text }],
+      details: { usage: entry.bridge.usage(), final: true },
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Extension discovery filter (delegate children)
+// ---------------------------------------------------------------------------
+
+export interface ChildExtensionFilterOptions {
+  /** Directory containing this extension's own files (dev/local installs). */
+  selfDir: string;
+  /** The child session's working directory. */
+  childCwd: string;
+  /** Whether the parent session treats its project as trusted. */
+  projectTrusted: boolean;
+}
+
+/**
+ * Filter the discovered extension set for a delegate child session.
+ * Pure and exported for tests.
+ *
+ * Two exclusions:
+ *   1. Self — the discovered copy of THIS extension would register the full
+ *      parent tool surface (an unguarded delegate) and conflict with the
+ *      inline factory's guarded tools. Self-exclusion IS the recursion
+ *      guard (it replaces the subprocess era's env-var role signal).
+ *   2. Project-local extensions when the project is untrusted — mirrors
+ *      pi's trust model, which the raw SDK path does not enforce.
+ */
+export function filterChildExtensions<T extends { path: string; resolvedPath?: string }>(
+  extensions: T[],
+  opts: ChildExtensionFilterOptions,
+): T[] {
+  const selfDir = path.resolve(opts.selfDir);
+  const projectExtDir = path.resolve(opts.childCwd, CONFIG_DIR_NAME);
+  return extensions.filter((ext) => {
+    for (const p of [ext.path, ext.resolvedPath]) {
+      if (!p) continue;
+      // Skip pseudo-paths (e.g. "<inline:name>") — they are not filesystem
+      // locations and must not be resolved against directory prefixes.
+      if (p.startsWith("<")) continue;
+      const normalized = p.replace(/\\/g, "/");
+      if (normalized.includes("node_modules/@jerryan/pi-subagent-tools/")) return false;
+      const resolved = path.resolve(p);
+      if (resolved === selfDir || resolved.startsWith(selfDir + path.sep)) return false;
+      if (
+        !opts.projectTrusted &&
+        (resolved === projectExtDir || resolved.startsWith(projectExtDir + path.sep))
+      ) {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Default session creation (the in-process equivalent of buildSpawnArgs)
+// ---------------------------------------------------------------------------
+
+async function defaultSpawnSession(
+  params: SpawnSessionParams,
+): Promise<AgentSession> {
+  const { opts, id, runtime, childManager } = params;
+  const modelRuntime = await runtime();
+  const role = ROLES[opts.role];
+  const agentDir = getAgentDir();
+  const settingsManager = SettingsManager.create(opts.cwd, agentDir, {
+    projectTrusted: opts.ctx.isProjectTrusted(),
+  });
+
+  const loader = new DefaultResourceLoader({
+    cwd: opts.cwd,
+    agentDir,
+    settingsManager,
+    noExtensions: !role.discoverExtensions,
+    extensionsOverride: role.discoverExtensions
+      ? (base) => ({
+          ...base,
+          extensions: filterChildExtensions(base.extensions, {
+            selfDir: EXTENSION_DIR,
+            childCwd: opts.cwd,
+            projectTrusted: opts.ctx.isProjectTrusted(),
+          }),
+        })
+      : undefined,
+    additionalSkillPaths: opts.skills ?? [],
+    appendSystemPrompt: [role.promptFile],
+    extensionFactories: childManager
+      ? [
+          {
+            name: "pi-subagent-tools",
+            factory: (pi: ExtensionAPI) =>
+              registerChildAgentTools(pi, childManager),
+          },
+        ]
+      : [],
+  });
+  await loader.reload();
+
+  const { session } = await createAgentSession({
+    cwd: opts.cwd,
+    model: opts.ctx.model,
+    thinkingLevel: opts.ctx.thinkingLevel,
+    modelRuntime,
+    tools: role.tools ? [...role.tools] : undefined,
+    customTools: role.customTools,
+    resourceLoader: loader,
+    sessionManager: SessionManager.inMemory(opts.cwd),
+    settingsManager,
+  });
+
+  await session.bindExtensions({
+    uiContext: createUIBridge(opts.ctx.ui, { label: id }),
+    mode: "rpc",
+  });
+
+  return session;
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+interface SpawnToolConfig {
+  role: AgentRole;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TObject<any>;
+  resolveCwd: (params: SpawnToolParams, ctx: ExtensionContext) => string;
+  hint?: (params: SpawnToolParams) => string | undefined;
+}
+
+const DELEGATE_TOOL: SpawnToolConfig = {
+  role: "delegate",
+  label: "Delegate",
+  description:
+    "Delegate a task to a subagent. " +
+    "For general-purpose work that doesn't fit the review or explore tools. " +
+    "The result includes an agent id — use follow_up to continue working with the same agent.",
+  promptSnippet: "Delegate a task to a worker subagent",
+  promptGuidelines: [
+    "Use the delegate tool for non-trivial, self-contained implementation tasks — it has full tool access unlike the read-only review and explore tools.",
+    "Use follow_up with the agent id from the result to refine a subagent's work or recover from an incomplete result, instead of spawning a fresh agent.",
+  ],
+  parameters: DelegateParams,
+  resolveCwd: (params, ctx) => params.cwd ?? ctx.cwd,
+  hint: (params) => (params.cwd ? shortenPath(params.cwd) : undefined),
+};
+
+const REVIEW_TOOL: SpawnToolConfig = {
+  role: "review",
+  label: "Review",
+  description:
+    "Review code changes or files in the current project. " +
+    "The reviewer is always read-only and runs in the parent's working directory. " +
+    "Use for code review, diff inspection, issue analysis, and quality checks. " +
+    "The result includes an agent id — use follow_up to ask the reviewer more questions.",
+  promptSnippet: "Review code or files with a read-only subagent",
+  promptGuidelines: [
+    "Use the review tool for code review, diff inspection, and quality checks — it is read-only and cannot modify files.",
+  ],
+  parameters: ReviewParams,
+  resolveCwd: (_params, ctx) => ctx.cwd,
+};
+
+const EXPLORE_TOOL: SpawnToolConfig = {
+  role: "explore",
+  label: "Explore",
+  description:
+    "Explore a project directory to understand its structure, patterns, and key files. " +
+    "The explorer is always read-only and runs in the specified working directory. " +
+    "Use for mapping codebases, scouting dependencies, or understanding unfamiliar projects. " +
+    "The result includes an agent id — use follow_up to dig deeper with the same explorer.",
+  promptSnippet: "Explore a project directory with a read-only subagent",
+  promptGuidelines: [
+    "Use the explore tool to map unfamiliar codebases or scout dependencies — it runs read-only in the specified directory.",
+  ],
+  parameters: ExploreParams,
+  resolveCwd: (params) => params.cwd!,
+  hint: (params) => shortenPath(params.cwd!),
+};
+
+/**
+ * Build a spawn tool's definition. Everything is derived from the role
+ * config except `execute` — so the parent's real tool and the delegate
+ * child's rejecting guard differ by exactly one function.
+ */
+function spawnToolDefinition(
+  config: SpawnToolConfig,
+  execute: (
+    params: SpawnToolParams,
+    signal: AbortSignal | undefined,
+    onUpdate: ((result: AgentToolResult<any>) => void) | undefined,
+    ctx: ExtensionContext,
+  ) => Promise<AgentToolResult<any>>,
+) {
+  return {
+    name: config.role,
+    label: config.label,
+    description: config.description,
+    promptSnippet: config.promptSnippet,
+    promptGuidelines: config.promptGuidelines,
+    parameters: config.parameters,
+    execute: (
+      _toolCallId: string,
+      params: SpawnToolParams,
+      signal: AbortSignal | undefined,
+      onUpdate: ((result: AgentToolResult<any>) => void) | undefined,
+      ctx: ExtensionContext,
+    ) => execute(params, signal, onUpdate, ctx),
+    renderCall: (args: SpawnToolParams, theme: any) =>
+      renderSubagentCall(
+        `${config.role} `,
+        { task: args.task, hint: config.hint?.(args) },
+        theme,
+      ),
+    renderResult: (result: any, options: any, theme: any, context: any) =>
+      renderSubagentResult(result, options, theme, context),
+  };
+}
+
+function registerSpawnTool(
+  pi: ExtensionAPI,
+  manager: AgentManager,
+  config: SpawnToolConfig,
+): void {
+  pi.registerTool(
+    spawnToolDefinition(config, (params, signal, onUpdate, ctx) =>
+      manager.spawn({
+        role: config.role,
+        task: params.task,
+        cwd: config.resolveCwd(params, ctx),
+        skills: params.skills,
+        ctx,
+        signal,
+        onUpdate,
+      }),
+    ) as any,
+  );
+}
+
+/** The rejecting delegate tool registered in delegate children. */
+function registerRejectingDelegateTool(pi: ExtensionAPI): void {
+  pi.registerTool(
+    spawnToolDefinition(DELEGATE_TOOL, () =>
+      fail(
+        "Delegation not available in delegate subagents. Use review or explore instead.",
+      ),
+    ) as any,
+  );
+}
+
+function registerFollowUpTool(pi: ExtensionAPI, manager: AgentManager): void {
+  pi.registerTool({
+    name: "follow_up",
+    label: "Follow Up",
+    description:
+      "Send a follow-up task to a previously spawned subagent, continuing its session with full context. " +
+      "The agent retains its original role, tools, and working directory. " +
+      "Errors if the agent id is unknown or expired — spawn a fresh agent instead.",
+    promptSnippet: "Continue working with an existing subagent",
+    promptGuidelines: [
+      "Use follow_up to refine a subagent's work, ask questions about its findings, or recover from an incomplete or failed result — the agent keeps its full context.",
+    ],
+    parameters: FollowUpParams,
+    async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+      return manager.followUp({
+        agent: params.agent,
+        task: params.task,
+        signal,
+        onUpdate,
+      });
+    },
+    renderCall: (args, theme) =>
+      renderSubagentCall("follow_up ", { task: args.task, hint: args.agent }, theme),
+    renderResult: (result, options, theme, context) =>
+      renderSubagentResult(result as any, options, theme, context),
+  });
+}
+
+
+function wireLifecycle(pi: ExtensionAPI, manager: AgentManager): void {
+  pi.on("turn_end", () => manager.noteTurnEnd());
+  pi.on("session_shutdown", () => manager.disposeAll());
+}
+
+/** Full tool surface for the parent session. */
+export function registerAgentTools(pi: ExtensionAPI, manager: AgentManager): void {
+  wireLifecycle(pi, manager);
+  registerSpawnTool(pi, manager, DELEGATE_TOOL);
+  registerSpawnTool(pi, manager, REVIEW_TOOL);
+  registerSpawnTool(pi, manager, EXPLORE_TOOL);
+  registerFollowUpTool(pi, manager);
+}
+
+/**
+ * Guarded tool surface for delegate children: review/explore/follow_up are
+ * active; delegate is registered but rejects — the structural recursion guard.
+ */
+export function registerChildAgentTools(
+  pi: ExtensionAPI,
+  manager: AgentManager,
+): void {
+  wireLifecycle(pi, manager);
+  registerRejectingDelegateTool(pi);
+  registerSpawnTool(pi, manager, REVIEW_TOOL);
+  registerSpawnTool(pi, manager, EXPLORE_TOOL);
+  registerFollowUpTool(pi, manager);
+}