@signalridge/pi-subagents 1.4.0 → 1.6.1

package/src/settings.ts

@@ -2,13 +2,23 @@
 // - Global:  ~/.pi/agent/subagents.json (via getAgentDir()) — manual defaults, never written here
 // - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { WorkflowTier } from "@signalridge/pi-subagents-protocol";
+// Imported only for the applySettings fallback so a persisted defaultToolTimeoutMs
+// takes effect even before the host wires the new applier — avoids needing to
+// edit index.ts in the same change.
+import { setDefaultToolTimeoutMs } from "./agent-runner.js";
 import { NO_FALLBACK } from "./agent-types.js";
 import type { JoinMode, ThinkingLevel } from "./types.js";
 
+/** How a `@handle message` mention is dispatched. See `agentMentions`. */
+export const AGENT_MENTION_MODES = ["model", "direct", "off"] as const;
+export type AgentMentionMode = (typeof AGENT_MENTION_MODES)[number];
+const VALID_AGENT_MENTION_MODES: ReadonlySet<string> = new Set(AGENT_MENTION_MODES);
+
 /** A tier's thinking value: a level, or `inherit` to keep the parent's. */
 export type TierThinking = ThinkingLevel | "inherit";
 
@@ -82,6 +92,25 @@ export interface SubagentsSettings {
    * these. See `agent-tiers.ts` for resolution and precedence.
    */
   agentTiers?: AgentTiersSettings;
+  /**
+   * The model a subagent runs when nothing else chose one — no tier applied and
+   * no programmatic override. It takes the place of the parent session's model
+   * as the last step of resolution, so a workspace can say "subagents run on the
+   * cheap model" without first defining a tier catalogue.
+   *
+   * A `provider/model` reference, or the literal `"inherit"` to follow the
+   * parent. `"inherit"` is spellable rather than merely omittable because a
+   * project needs a way to undo a global default; omitting the key inherits
+   * whatever global set.
+   *
+   * Deliberately weaker than a tier: a tier naming an unavailable model fails
+   * the spawn, because someone asked for that policy by name, while an
+   * unresolvable default model falls back to the parent. Failing every spawn on
+   * a machine that happens to lack one provider is the wrong trade for a value
+   * nobody named at the call site — the `/agents → Settings` row shows the
+   * fallback instead.
+   */
+  defaultModel?: string;
   maxConcurrent?: number;
   /**
    * 0 = unlimited — the extension's single source of truth for that convention:
@@ -90,6 +119,19 @@ export interface SubagentsSettings {
    */
   defaultMaxTurns?: number;
   graceTurns?: number;
+  /**
+   * Token budget for one subagent run. `0` (default) = unlimited, matching
+   * `defaultMaxTurns`. A wrap-up steer is sent at 80% and the run is aborted at
+   * 100%. Bounds what one agent can spend, which a turn count cannot — a single
+   * turn can burn an arbitrary number of tokens. Frontmatter `max_tokens` wins.
+   */
+  defaultMaxTokens?: number;
+  /**
+   * Tool-call budget for one subagent run. `0` (default) = unlimited, with the
+   * same 80%/100% shape as `defaultMaxTokens`. Frontmatter `max_tool_calls`
+   * wins.
+   */
+  defaultMaxToolCalls?: number;
   defaultJoinMode?: JoinMode;
   /**
    * Master switch for the schedule subagent feature. Defaults to `true`.
@@ -163,6 +205,32 @@ export interface SubagentsSettings {
    * (`isolation: worktree`), or memory files.
    */
   outputTranscript?: boolean;
+  /**
+   * Whether evicted agent records stay addressable as resumable entries
+   * (`@handle` reopen). Defaults to true. When false, a cleaned-up record is
+   * forgotten entirely.
+   */
+  rememberAgents?: boolean;
+  /**
+   * How `@handle message` typed at the prompt is dispatched.
+   *
+   *  - `"model"` (default) — a mention that names an agent TYPE takes its turn
+   *    in an off-screen clone of the conversation, so the started agent gets a
+   *    prompt written with context instead of only the words after the handle.
+   *    Messaging and resuming an existing agent stay direct either way.
+   *  - `"direct"` — start the agent straight from the typed text, no clone.
+   *  - `"off"` — the text goes to the main model verbatim, exactly as it did
+   *    before mentions existed.
+   *
+   * A boolean is still accepted and read as `"model"`/`"off"`.
+   */
+  agentMentions?: AgentMentionMode;
+  /**
+   * Whether subagents may interrupt with `contact_supervisor` to ask their
+   * human a question. Defaults to true. The tool is only ever injected where
+   * there is a UI to ask through, so this turns it off where there is one.
+   */
+  supervisorQuestions?: boolean;
   /**
    * Hard ceiling on nested subagent delegation, counted from the main session:
    * main = 0, its subagents = 1, their children = 2. Defaults to `2`; `0` or `1`
@@ -170,6 +238,22 @@ export interface SubagentsSettings {
    * change applies to agents started after it.
    */
   maxSubagentDepth?: number;
+  /**
+   * Cumulative descendants any one top-level agent may start, over its whole
+   * life. Defaults to `64`. The depth cap bounds how DEEP nesting goes and
+   * nothing about how WIDE it gets — this is the horizontal bound. Minimum 1;
+   * turn nesting off with `maxSubagentDepth` instead.
+   */
+  maxSubagentSpawnsPerBranch?: number;
+  /**
+   * Default per-tool timeout in milliseconds. `0` = disabled (no timeout). When
+   * set, any tool call that does not settle within this window is aborted with
+   * a timeout error, preventing a hung `bash` or MCP tool from stalling the
+   * subagent forever. `0` when unset, matching tintinweb (no per-tool timeout
+   * by default; hung tools are reclaimed via abort/quiescence). Frontmatter does
+   * not override.
+   */
+  defaultToolTimeoutMs?: number;
   /**
    * Agent type substituted when a caller-supplied `subagent_type` doesn't
    * resolve to exactly one enabled agent (unknown, disabled, or ambiguous by
@@ -185,16 +269,28 @@ export interface SubagentsSettings {
    * meaning one thing here and another in the resolver.
    */
   fallbackSubagent?: string;
+  /**
+   * Project-wide switch for worktree isolation (upstream #184). When false,
+   * no caller can create a worktree regardless of isolation param. Defaults to
+   * true (unchanged behaviour). Routed through worktree.ts singleton.
+   */
+  worktreeIsolation?: boolean;
 }
 
 export type ToolDescriptionMode = "full" | "compact" | "custom";
 
 /** Setter hooks used by applySettings to wire persisted values into in-memory state. */
 export interface SettingsAppliers {
+  setWorktreeIsolation?: (enabled: boolean) => void;
   setMaxConcurrent: (n: number) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
+  setDefaultMaxTokens: (n: number) => void;
+  setDefaultMaxToolCalls: (n: number) => void;
+  setDefaultToolTimeout?: (ms: number) => void;
   setDefaultJoinMode: (mode: JoinMode) => void;
+  /** `undefined` and `"inherit"` both mean "follow the parent session". */
+  setDefaultModel: (ref: string | undefined) => void;
   setSchedulingEnabled: (b: boolean) => void;
   setScopeModels: (enabled: boolean) => void;
   setStrictAgentFiles: (b: boolean) => void;
@@ -202,7 +298,11 @@ export interface SettingsAppliers {
   setToolDescriptionMode: (mode: ToolDescriptionMode) => void;
   setFleetView: (b: boolean) => void;
   setOutputTranscript: (b: boolean) => void;
+  setRememberAgents: (b: boolean) => void;
+  setAgentMentions: (mode: AgentMentionMode) => void;
+  setSupervisorQuestions: (b: boolean) => void;
   setMaxSubagentDepth: (n: number) => void;
+  setMaxSubagentSpawnsPerBranch: (n: number) => void;
   setFallbackSubagent: (v: string | undefined) => void;
   /** Optional because non-runtime settings tests and consumers need not apply workflow state. */
   setWorkflow?: (settings: WorkflowSettings) => void;
@@ -215,15 +315,23 @@ export type SettingsEmit = (event: string, payload: unknown) => void;
 
 const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>(["async", "group", "smart"]);
 const VALID_TOOL_DESCRIPTION_MODES: ReadonlySet<string> = new Set<ToolDescriptionMode>(["full", "compact", "custom"]);
-const VALID_THINKING_LEVELS: ReadonlySet<string> = new Set([
+/**
+ * Thinking values a tier profile accepts, `inherit` first and then ascending.
+ *
+ * Ordered because the `/agents → Model tiers` editor offers them in this order;
+ * note `off` is absent — a profile that wants no thinking says so through the
+ * model it names, and `clampThinkingLevel` handles a model that supports none.
+ */
+export const TIER_THINKING_LEVELS: readonly TierThinking[] = [
+  "inherit",
   "minimal",
   "low",
   "medium",
   "high",
   "xhigh",
   "max",
-  "inherit",
-]);
+];
+const VALID_THINKING_LEVELS: ReadonlySet<string> = new Set(TIER_THINKING_LEVELS);
 const WORKFLOW_TIER_NAMES: readonly WorkflowTier[] = ["small", "medium", "large"];
 const MAX_MODEL_REFERENCE_LENGTH = 512;
 /** Mirrors MAX_AGENT_TIER_KEY_LENGTH in agent-tiers.ts; duplicated to keep settings dependency-free. */
@@ -239,12 +347,28 @@ const MAX_CONCURRENT_CEILING = 1024;
 const MAX_TURNS_CEILING = 10_000;
 const GRACE_TURNS_CEILING = 1_000;
 const SUBAGENT_DEPTH_CEILING = 16;
+/**
+ * Upper bound on the branch spawn budget. A configured value this high is
+ * already far past the point where a fan-out is intentional; the ceiling exists
+ * so a typo cannot turn the horizontal bound off by writing a huge number.
+ */
+const SUBAGENT_SPAWNS_PER_BRANCH_CEILING = 4_096;
+/** Per-tool timeout ceiling: 10 minutes, matching gate timeout. */
+const TOOL_TIMEOUT_CEILING_MS = 600_000;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function validWorkflowModelReference(value: unknown): value is string {
+/**
+ * `inherit`, or a bounded whitespace-free `provider/model` reference.
+ *
+ * Exported so the `/agents` menus can reject a typed reference at the prompt.
+ * Without that they would hand an invalid value to `saveSettings`, which drops
+ * unrecognized fields silently — a success toast for a setting that never
+ * persisted.
+ */
+export function isModelReference(value: unknown): value is string {
   if (typeof value !== "string") return false;
   const model = value.trim();
   if (model === "inherit") return true;
@@ -267,7 +391,7 @@ function sanitizeWorkflowProfile(raw: unknown): WorkflowTierProfile | undefined
   const keys = Object.keys(raw);
   if (keys.some((key) => key !== "model" && key !== "thinking")) return undefined;
   if (!Object.hasOwn(raw, "model") || !Object.hasOwn(raw, "thinking")) return undefined;
-  if (!validWorkflowModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
+  if (!isModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
   return { model: raw.model.trim(), thinking: raw.thinking };
 }
 
@@ -318,7 +442,7 @@ function sanitizeAgentTierProfile(raw: unknown): AgentTierProfile | undefined {
   const keys = Object.keys(raw);
   if (keys.some((key) => key !== "model" && key !== "thinking" && key !== "description")) return undefined;
   if (!Object.hasOwn(raw, "model") || !Object.hasOwn(raw, "thinking")) return undefined;
-  if (!validWorkflowModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
+  if (!isModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
   if (
     Object.hasOwn(raw, "description") &&
     (typeof raw.description !== "string" ||
@@ -390,6 +514,13 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.graceTurns = r.graceTurns as number;
   }
+  // `0` is accepted and means unlimited, matching `defaultMaxTurns`.
+  if (Number.isInteger(r.defaultMaxTokens) && (r.defaultMaxTokens as number) >= 0) {
+    out.defaultMaxTokens = r.defaultMaxTokens as number;
+  }
+  if (Number.isInteger(r.defaultMaxToolCalls) && (r.defaultMaxToolCalls as number) >= 0) {
+    out.defaultMaxToolCalls = r.defaultMaxToolCalls as number;
+  }
   if (
     Number.isInteger(r.maxSubagentDepth) &&
     (r.maxSubagentDepth as number) >= 0 &&
@@ -397,6 +528,26 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.maxSubagentDepth = r.maxSubagentDepth as number;
   }
+  // Minimum 1, not 0: zero reads as a limit, and silently meaning "unlimited"
+  // is how a safety valve gets disabled by accident. Nesting is turned off with
+  // `maxSubagentDepth`, which says so.
+  if (
+    Number.isInteger(r.maxSubagentSpawnsPerBranch) &&
+    (r.maxSubagentSpawnsPerBranch as number) >= 1 &&
+    (r.maxSubagentSpawnsPerBranch as number) <= SUBAGENT_SPAWNS_PER_BRANCH_CEILING
+  ) {
+    out.maxSubagentSpawnsPerBranch = r.maxSubagentSpawnsPerBranch as number;
+  }
+  if (
+    Number.isInteger(r.defaultToolTimeoutMs) &&
+    (r.defaultToolTimeoutMs as number) >= 0 &&
+    (r.defaultToolTimeoutMs as number) <= TOOL_TIMEOUT_CEILING_MS
+  ) {
+    out.defaultToolTimeoutMs = r.defaultToolTimeoutMs as number;
+  }
+  if (isModelReference(r.defaultModel)) {
+    out.defaultModel = r.defaultModel.trim();
+  }
   if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
     out.defaultJoinMode = r.defaultJoinMode as JoinMode;
   }
@@ -421,6 +572,17 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.outputTranscript === "boolean") {
     out.outputTranscript = r.outputTranscript;
   }
+  if (typeof r.rememberAgents === "boolean") {
+    out.rememberAgents = r.rememberAgents;
+  }
+  if (typeof r.agentMentions === "boolean") {
+    out.agentMentions = r.agentMentions ? "model" : "off";
+  } else if (typeof r.agentMentions === "string" && VALID_AGENT_MENTION_MODES.has(r.agentMentions)) {
+    out.agentMentions = r.agentMentions as AgentMentionMode;
+  }
+  if (typeof r.supervisorQuestions === "boolean") {
+    out.supervisorQuestions = r.supervisorQuestions;
+  }
   if (r.fallbackSubagent === false) {
     // The only non-string spelling worth accepting: a boolean would otherwise be
     // dropped, silently leaving the PERMISSIVE default in place. Every string is
@@ -431,6 +593,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   } else if (typeof r.fallbackSubagent === "string" && r.fallbackSubagent.trim()) {
     out.fallbackSubagent = r.fallbackSubagent.trim();
   }
+  if (typeof r.worktreeIsolation === "boolean") {
+    out.worktreeIsolation = r.worktreeIsolation;
+  }
 
   const workflow = sanitizeWorkflow(r.workflow);
   if (workflow) out.workflow = workflow;
@@ -759,7 +924,23 @@ export function saveSettings(s: SubagentsSettings, cwd: string = process.cwd()):
   const path = projectPath(cwd);
   try {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(sanitize(s), null, 2), "utf-8");
+    // Atomic write: settings are written on every /agents mutation, and a torn
+    // write (crash, kill, disk full between truncate and flush) would silently
+    // discard the project's entire configuration. Write to a unique temp file
+    // in the same directory, then rename over the target — rename is atomic on
+    // POSIX and Windows. Same pattern as packages/pi-goal/src/settings.ts.
+    const document = `${JSON.stringify(sanitize(s), null, 2)}\n`;
+    const temporaryPath = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temporaryPath, document, { encoding: "utf8", flag: "wx" });
+      renameSync(temporaryPath, path);
+    } finally {
+      try {
+        rmSync(temporaryPath, { force: true });
+      } catch {
+        // Best-effort cleanup must not replace the save result.
+      }
+    }
     return true;
   } catch {
     return false;
@@ -771,8 +952,23 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.maxConcurrent === "number") appliers.setMaxConcurrent(s.maxConcurrent);
   if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
+  if (typeof s.defaultMaxTokens === "number") appliers.setDefaultMaxTokens(s.defaultMaxTokens);
+  if (typeof s.defaultMaxToolCalls === "number") appliers.setDefaultMaxToolCalls(s.defaultMaxToolCalls);
   if (typeof s.maxSubagentDepth === "number") appliers.setMaxSubagentDepth(s.maxSubagentDepth);
+  if (typeof s.maxSubagentSpawnsPerBranch === "number")
+    appliers.setMaxSubagentSpawnsPerBranch(s.maxSubagentSpawnsPerBranch);
+  if (typeof s.defaultToolTimeoutMs === "number") {
+    appliers.setDefaultToolTimeout?.(s.defaultToolTimeoutMs);
+    // Fallback for hosts that have not yet wired the new applier (and for tests
+    // that call applySettings with a minimal appliers object): ensure the
+    // in-memory timeout still follows the persisted value.
+    setDefaultToolTimeoutMs(s.defaultToolTimeoutMs);
+  }
   if (typeof s.fallbackSubagent === "string") appliers.setFallbackSubagent(s.fallbackSubagent);
+  if (typeof s.worktreeIsolation === "boolean") appliers.setWorktreeIsolation?.(s.worktreeIsolation);
+  // Applied whenever the key is present, `"inherit"` included: that spelling is
+  // how a project cancels a global default model, so it has to reach the setter.
+  if (typeof s.defaultModel === "string") appliers.setDefaultModel(s.defaultModel);
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
   if (typeof s.schedulingEnabled === "boolean") appliers.setSchedulingEnabled(s.schedulingEnabled);
   if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels);
@@ -781,6 +977,9 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (s.toolDescriptionMode) appliers.setToolDescriptionMode(s.toolDescriptionMode);
   if (typeof s.fleetView === "boolean") appliers.setFleetView(s.fleetView);
   if (typeof s.outputTranscript === "boolean") appliers.setOutputTranscript(s.outputTranscript);
+  if (typeof s.rememberAgents === "boolean") appliers.setRememberAgents(s.rememberAgents);
+  if (s.agentMentions) appliers.setAgentMentions(s.agentMentions);
+  if (typeof s.supervisorQuestions === "boolean") appliers.setSupervisorQuestions(s.supervisorQuestions);
   if (s.workflow) appliers.setWorkflow?.(s.workflow);
   // Applied unconditionally so a session that had tiers and no longer does gets
   // the empty catalogue rather than keeping the previous one.

package/src/supervisor.ts

@@ -0,0 +1,115 @@
+/**
+ * supervisor.ts — `contact_supervisor`, the child→parent direction.
+ *
+ * `steer_subagent` sends guidance downward. Nothing sent anything upward: a
+ * subagent that hit a genuine fork in the road could only guess, finish wrong,
+ * and have the guess discovered later in its result.
+ *
+ * The answer comes from the HUMAN, not from a supervising model. Our subagents
+ * share the parent's `ExtensionContext`, so the parent's UI is directly
+ * reachable — asking the person who is sitting there is both cheaper and more
+ * correct than delegating the judgement to another model, and it is the same
+ * reason this package has no LLM arbitrator anywhere else.
+ *
+ * That reachability is also why this is ~80 lines rather than a filesystem
+ * channel with a poller on each end: in-process, the question is one promise.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { sanitizeDisplayText, truncateCodePoints } from "./ui/safe-text.js";
+
+/** Longest question a child may put to the parent, in characters. */
+const MAX_QUESTION = 2_000;
+/** Longest option label offered in a choice prompt. */
+const MAX_OPTION = 200;
+/** Most options a child may offer, so the picker stays usable. */
+const MAX_OPTIONS = 8;
+
+export interface SupervisorAsk {
+  /** Prompt the human with a free-text question; undefined = dismissed. */
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+  /** Prompt the human to pick one option; undefined = dismissed. */
+  select(title: string, options: string[]): Promise<string | undefined>;
+}
+
+export interface SupervisorToolContext {
+  /** The parent's UI. Omitted when there is no human to ask. */
+  ask?: SupervisorAsk;
+  /** Display name of the asking agent, for the prompt title. */
+  agentLabel: string;
+}
+
+function textResult(text: string, isError = false) {
+  return { content: [{ type: "text" as const, text }], isError, details: {} };
+}
+
+/**
+ * Build the `contact_supervisor` tool, or nothing when no human can answer.
+ *
+ * Returning an empty array rather than a tool that always fails is deliberate,
+ * and matches how nested tools are handled: injecting a tool whose every call
+ * is an error spends context to teach the model an affordance it does not have.
+ * Headless and RPC sessions therefore see no such tool at all.
+ */
+export function createSupervisorTool(context: SupervisorToolContext) {
+  if (!context.ask) return [];
+  const ask = context.ask;
+
+  return [
+    defineTool({
+      name: "contact_supervisor",
+      label: "Ask Supervisor",
+      description:
+        "Ask the human who started you a question and wait for their answer. Use ONLY for a decision you cannot make yourself and cannot defer: an ambiguous requirement where the readings lead to materially different work, a destructive step that needs confirmation, or missing information nothing available to you can supply. It interrupts a person, so prefer stating an assumption and continuing. Returns their answer, or tells you they declined — in which case proceed on your best judgement and say what you assumed.",
+      parameters: Type.Object({
+        question: Type.String({
+          description: "The question, self-contained. The human cannot see your conversation.",
+          maxLength: MAX_QUESTION,
+        }),
+        options: Type.Optional(
+          Type.Array(Type.String({ maxLength: MAX_OPTION }), {
+            description: `Offer up to ${MAX_OPTIONS} concrete choices instead of free text. Prefer this when the answers are known.`,
+            maxItems: MAX_OPTIONS,
+          }),
+        ),
+      }),
+      execute: async (_toolCallId, params) => {
+        // Both the question and any option labels are model-authored text about
+        // to be drawn into the user's terminal, so they are sanitized and
+        // bounded here — the same treatment any other child-supplied string
+        // gets before it reaches a UI surface.
+        const question = truncateCodePoints(sanitizeDisplayText(params.question), MAX_QUESTION, "…").trim();
+        if (!question) return textResult("Ask a non-empty question.", true);
+
+        const title = `${context.agentLabel} asks`;
+        const options = (params.options ?? [])
+          .map((option) => truncateCodePoints(sanitizeDisplayText(option), MAX_OPTION, "…").trim())
+          .filter((option) => option.length > 0)
+          .slice(0, MAX_OPTIONS);
+
+        let answer: string | undefined;
+        try {
+          answer =
+            options.length > 0
+              ? await ask.select(`${title}: ${question}`, options)
+              : await ask.input(title, question);
+        } catch (error: unknown) {
+          // A dialog that cannot open must not fail the child's whole run; it
+          // is told nobody answered and carries on under its own judgement.
+          return textResult(
+            `Could not reach the supervisor (${error instanceof Error ? error.message : String(error)}). Proceed on your best judgement and state the assumption you made.`,
+          );
+        }
+
+        const reply = answer?.trim();
+        if (!reply) {
+          return textResult(
+            "The supervisor did not answer. Proceed on your best judgement and state the assumption you made.",
+          );
+        }
+        return textResult(`Supervisor answered: ${reply}`);
+      },
+    }),
+  ];
+}

package/src/types.ts

@@ -30,13 +30,32 @@ export const DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as con
 /** Memory scope for persistent agent memory. */
 export type MemoryScope = "user" | "project" | "local";
 
-/** Isolation mode for agent execution. */
-export type IsolationMode = "worktree";
+/** Isolation mode for agent execution. "off" explicitly opts out of worktree isolation. */
+export type IsolationMode = "worktree" | "off";
 
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig {
   name: string;
   displayName?: string;
+  /**
+   * Badge colour for this agent, as a Claude Code palette name or `#RRGGBB`.
+   * Anything else renders without a badge rather than failing the load — a
+   * colour typo must not cost the user their agent.
+   */
+  color?: string;
+  /**
+   * Tools whose every call needs the user to agree first (`ask_tools:`). The
+   * third answer between `tools:` and `disallowed_tools:`, for tools that are
+   * usually fine and occasionally not. Approval comes from the human, never
+   * from a model — see `ask-tools.ts`.
+   */
+  askTools?: string[];
+  /**
+   * Shell command run by the HOST after this agent finishes, whose pass/fail is
+   * appended to its result (`gate:`). The one acceptance signal the agent
+   * cannot author — see `gate.ts`.
+   */
+  gate?: string;
   description: string;
   builtinToolNames?: string[];
   /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
@@ -69,6 +88,14 @@ export interface AgentConfig {
   /** Programmatic-only, for the same reason as `model` above. */
   thinking?: ThinkingLevel;
   maxTurns?: number;
+  /**
+   * Token budget for one run of this agent (`max_tokens`). `0`/omitted =
+   * unlimited, matching `maxTurns`. Bounds what a single turn can spend, which
+   * a turn count cannot: one turn can burn an arbitrary number of tokens.
+   */
+  maxTokens?: number;
+  /** Tool-call budget for one run of this agent (`max_tool_calls`). `0`/omitted = unlimited. */
+  maxToolCalls?: number;
   /** Persist this subagent as a normal pi session instead of keeping it in memory only. */
   persistSession?: boolean;
   /** Write the subagent's .output transcript. Defaults to true; false suppresses only that transcript. */
@@ -133,6 +160,17 @@ export interface AgentRecord {
   outputFile?: string;
   /** Cleanup function for the output file stream subscription. */
   outputCleanup?: () => void;
+  /**
+   * Session file path when the agent's conversation is persisted to disk
+   * (session_file in the agent definition or pi's session persistence). Set at
+   * spawn so an evicted record can be reopened as a resumable entry.
+   */
+  sessionFile?: string;
+  /**
+   * Resumable mention handle, when the agent was addressable by `@handle`.
+   * Only top-level agents carry one.
+   */
+  handle?: string;
   /**
    * Lifetime usage breakdown, accumulated via `message_end` events. Survives
    * compaction. Total = input + output + cacheWrite (cacheRead deliberately
@@ -179,6 +217,25 @@ export interface AgentRecord {
   detached?: boolean;
 }
 
+/**
+ * What survives a record's eviction so `@handle` keeps working. The live record
+ * is discarded after the cleanup timer, but the pi session it wrote is still on
+ * disk, and this is the little that is needed to find and describe it again.
+ *
+ * Named `ResumableAgentEntry` (not "tombstone") because this codebase already
+ * uses `ManagedSpawnTombstone` for the managed-spawn idempotency record — two
+ * different concepts must not share a name.
+ */
+export interface ResumableAgentEntry {
+  handle: string;
+  id: string;
+  type: SubagentType;
+  description: string;
+  /** Always set — a record with no session file is never indexed. */
+  sessionFile: string;
+  completedAt: number;
+}
+
 export interface AgentInvocation {
   /** Short display name, e.g. "haiku" — only set when different from parent. */
   modelName?: string;