@signalridge/pi-subagents 1.5.0 → 1.7.0

package/src/mention-clone.ts

@@ -0,0 +1,196 @@
+/**
+ * mention-clone.ts — start a mentioned agent through a clone of this
+ * conversation, without putting anything in the chat.
+ *
+ * Claude Code routes `@agent-<type>` through the main model: the mention
+ * becomes a `<system-reminder>` appended to the prompt and the model makes the
+ * tool call (see `agentMentionReminder`). That buys the spawned agent a prompt
+ * written with conversation context, and costs a visible turn — the model's
+ * reasoning and its tool block land in the transcript, for a decision the user
+ * already made when they typed the handle.
+ *
+ * So the turn happens somewhere else. The conversation is cloned into a
+ * throwaway in-memory session — same messages, same system prompt, same model —
+ * and that copy takes the turn off-screen. A literal clone: the session's own
+ * entries, projected by pi's own `sessionEntryToContextMessages`, not
+ * `inherit_context`'s text rendering of them.
+ *
+ * Cloned from memory rather than from the session file, which cannot be relied
+ * on: `SessionManager._persist` withholds every write until the first assistant
+ * message lands, so a fork taken before then reads an empty file and throws.
+ * `buildSessionContext()` has no such timing, and is compaction-aware — it walks
+ * the leaf path and substitutes the summary for entries folded into it, so a
+ * long conversation clones as what the main model is actually working from. A
+ * conversation with nothing in it yet clones to nothing in it yet, which is the
+ * correct answer rather than a failure.
+ *
+ * It is also the oldest of the equivalent Pi APIs — `buildContextEntries` on
+ * ReadonlySessionManager and the `sessionEntryToContextMessages` export both
+ * arrived in 0.80.5 — where this one has been exported unchanged from before
+ * the declared peer floor, and is the same code path (`byId` is only an index
+ * cache, so passing it or not cannot change the result). Keeping the floor
+ * honest costs nothing here: see the `compat-floor-pi` job.
+ *
+ * Its `thinkingLevel` is NOT used, and is the one place the newer API would be
+ * better. `getSessionContextSettings` starts at "off" and moves only on an
+ * explicit `thinking_level_change` entry, so a session where nobody ran
+ * `/think` reports "off" rather than the level it is really using. Omitting the
+ * field instead lets `createAgentSession` resolve it from settings, which is
+ * that real level.
+ *
+ * Three details make the spawn belong to the real session rather than the
+ * clone:
+ *
+ *   - the clone is handed the *registered* `Agent` tool, whose handler closes
+ *     over the main activation, so it spawns top-level: widget, fleet row,
+ *     handle, completion notification, all as if the main model had called it;
+ *   - that tool is re-bound to the main `ExtensionContext`, because the handler
+ *     reads `cwd`, `model` and `sessionManager.getSessionId()` off it to place
+ *     the transcript and the `rootSessionId`. The clone's own context would
+ *     file both under the throwaway fork;
+ *   - it is called with no tool-call id. The clone's turn produces one, but the
+ *     real session never issued it, and a `<tool-use-id>` pointing at nothing
+ *     is exactly the bug the mention-resume path had to fix;
+ *   - and it is forced into the background. A foreground agent returns its
+ *     answer as the tool result and is marked `resultConsumed` so no completion
+ *     notification is sent — correct when the caller is the real conversation,
+ *     silent loss when the caller is a fork about to be discarded. Background
+ *     delivery is the only route from a mention back to the main model.
+ *
+ * The clone gets one tool and one job. It cannot read, write or run anything —
+ * an invisible turn with the full toolset could do invisible work.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import {
+  buildSessionContext,
+  createAgentSession,
+  type ExtensionContext,
+  SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { runInChildSessionContext } from "./child-context.js";
+import { agentMentionReminder } from "./mention.js";
+import type { SubagentType, ThinkingLevel } from "./types.js";
+
+export interface MentionCloneOptions {
+  /** The MAIN session's context — what the spawn is attributed to, and the
+   * source of both the conversation and the live system prompt. */
+  ctx: ExtensionContext;
+  /** Agent type the handle resolved to. */
+  type: SubagentType;
+  /** What the user typed after the handle. */
+  message: string;
+  /** The registered `Agent` tool, reused so the spawn is an ordinary one. */
+  agentTool: ToolDefinition;
+}
+
+export interface MentionCloneResult {
+  /** True once the clone actually called `Agent`. */
+  spawned: boolean;
+  /** Why not, when it didn't. Absent on success. */
+  error?: string;
+}
+
+/**
+ * Fork the conversation, let the copy make the tool call, throw the copy away.
+ * Never rejects: a clone that cannot run is reported so the caller can fall
+ * back to starting the agent directly.
+ */
+export async function runMentionClone(opts: MentionCloneOptions): Promise<MentionCloneResult> {
+  const { ctx, type, message, agentTool } = opts;
+
+  let spawned = false;
+  const cloneAgentTool: ToolDefinition = {
+    ...agentTool,
+    execute: (_cloneToolCallId, params, signal, onUpdate, _cloneCtx) => {
+      // One spawn per mention. The clone has a single tool and every reason to
+      // stop after using it, but a model that decides to "also" launch a second
+      // agent would do it where nobody can see and nobody asked.
+      if (spawned) {
+        return Promise.resolve({
+          content: [{ type: "text" as const, text: "Already started an agent for this mention. Stop here." }],
+          details: undefined,
+          isError: true,
+        });
+      }
+      spawned = true;
+      // undefined tool-call id + the main ctx: see the header. Background is
+      // forced rather than left to the clone: `run_in_background` defaults to
+      // false, and a foreground agent answers through its TOOL RESULT — which
+      // here is delivered into a session that is disposed moments later, so the
+      // agent would run, appear in the widget and the fleet, and reach nobody.
+      return agentTool.execute(
+        undefined as never,
+        { ...(params as Record<string, unknown>), run_in_background: true } as typeof params,
+        signal,
+        onUpdate,
+        ctx,
+      );
+    },
+  };
+
+  let session: Awaited<ReturnType<typeof createAgentSession>>["session"] | undefined;
+  try {
+    // Pi 0.80.8 moved createAgentSession from modelRegistry to modelRuntime;
+    // agent-runner.ts carries the same shim for the same reason — pass both so
+    // the clone keeps the parent's providers across the supported range.
+    const parentModelRuntime = (ctx.modelRegistry as unknown as { runtime?: unknown }).runtime;
+    // The conversation as the main session resolves it: compaction applied,
+    // branch summaries substituted.
+    const conversation = buildSessionContext(
+      ctx.sessionManager.getEntries(),
+      ctx.sessionManager.getLeafId(),
+    );
+    // Pi 0.82.0 added this; below it the field is absent and the clone takes
+    // the settings level instead, which is what a session that never ran
+    // `/think` is on anyway. Same shim shape as `modelRuntime` below.
+    const thinkingLevel = (ctx as { thinkingLevel?: ThinkingLevel }).thinkingLevel;
+    const created = await runInChildSessionContext(() =>
+      createAgentSession({
+        cwd: ctx.cwd,
+        // Nothing about the copy is worth persisting, and an in-memory manager
+        // is also what keeps the real session untouched.
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        model: ctx.model as Model<never> | undefined,
+        ...(thinkingLevel && { thinkingLevel }),
+        modelRegistry: ctx.modelRegistry,
+        ...(parentModelRuntime !== undefined && { modelRuntime: parentModelRuntime as never }),
+        // An allowlist naming exactly the clone's own tool. NOT `noTools:
+        // "all"`, whose doc comment ("start with no tools enabled") reads like
+        // it spares custom tools and does not: it resolves to an EMPTY
+        // allowlist, and `isAllowedTool` then drops every tool from the
+        // registry — the custom one included. The clone would be prompted with
+        // nothing to call, answer in prose, and every mention would fall
+        // through to the direct start with a warning. Same idiom as
+        // agent-runner's `tools: sessionTools` beside its nested `customTools`.
+        tools: [cloneAgentTool.name],
+        customTools: [cloneAgentTool],
+      } as Parameters<typeof createAgentSession>[0]),
+    );
+    session = created.session;
+
+    // The clone rebuilds a system prompt from cwd and agentDir, which is close
+    // but not the live one — extensions contribute to it per turn. Copy the
+    // real thing, so the copy reasons under the instructions the user's model
+    // is actually working under.
+    const systemPrompt = ctx.getSystemPrompt?.();
+    if (systemPrompt) session.agent.state.systemPrompt = systemPrompt;
+
+    // The conversation itself. Pushed rather than assigned so the array the
+    // session was built around stays the one it goes on using.
+    session.agent.state.messages.push(...conversation.messages);
+
+    // User text first, reminder after — the order Claude Code's attachment
+    // renderer produces, where the reminder trails the message it is about.
+    await session.prompt(`${message}\n\n${agentMentionReminder(type)}`);
+  } catch (err) {
+    return { spawned, error: err instanceof Error ? err.message : String(err) };
+  } finally {
+    session?.dispose?.();
+  }
+
+  return spawned
+    ? { spawned: true }
+    : { spawned: false, error: "the conversation clone did not start it" };
+}

package/src/mention.ts

@@ -0,0 +1,141 @@
+/**
+ * mention.ts — the `@handle` grammar for messaging a subagent from the prompt.
+ *
+ * Claude Code lets you type `@code-review take another look` at the prompt and
+ * routes the message to that agent instead of the main model. Its grammar is
+ * reproduced here so the two behave identically:
+ *
+ *   - suggestions fire on `@` at the start of the input or after whitespace,
+ *     followed by `[\w-]*` (so `@src/foo.ts` is a file, never an agent);
+ *   - a send is recognized only at the START of the input, and only with a
+ *     non-empty message after the handle. That is why a bare `@code-review`
+ *     goes to the main model rather than anywhere near the agent.
+ *
+ * A record's own identity is a UUID plus a deliberately non-unique description,
+ * neither of which is typeable, so the handle is derived from the agent type.
+ * Colliding handles are numbered (`explore`, `explore-2`), which is also what
+ * Claude Code's `allocateName` does — it recycles a name only once the task
+ * behind it is gone. Its SendMessage prompt describes the *registry* as
+ * latest-wins, which is a different thing and not how names are allocated.
+ */
+
+/**
+ * Suggestion trigger: `@` at a token boundary plus the partial handle typed so
+ * far. Ported from Claude Code, including the CJK sentence-ending punctuation
+ * it accepts as a boundary.
+ */
+export const MENTION_TRIGGER = /(^|[\s。、？！])@([\w-]*)$/;
+
+/** Send grammar: leading `@handle`, then a non-empty message. */
+const MENTION_SEND = /^@([\w-]+)\s+([\s\S]+)$/;
+
+/**
+ * Upper bound on a handle, matching Claude Code's `dSS`. Nothing here generates
+ * a name this long, but an agent type or a model-supplied name can be arbitrary
+ * text, and an unbounded handle would wrap the suggestion popup.
+ */
+const MAX_HANDLE_LENGTH = 64;
+
+/**
+ * Handles that address something other than a subagent, and so can never be
+ * allocated to one. Claude Code reserves exactly this name (`Vq = "main"`),
+ * refusing it at spawn and routing it to the main conversation instead.
+ */
+const RESERVED_HANDLES: ReadonlySet<string> = new Set(["main"]);
+
+/** Whether `@handle` names the main conversation rather than any subagent. */
+export function isReservedHandle(handle: string): boolean {
+  return RESERVED_HANDLES.has(handle.toLowerCase());
+}
+
+/** Slug of an agent type or name, restricted to the `[\w-]` the grammar allows. */
+export function handleBase(type: string): string {
+  const slug = type.toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_HANDLE_LENGTH)
+    // The slice can land mid-run and leave the trailing hyphen back.
+    .replace(/-+$/, "");
+  return slug || "agent";
+}
+
+/**
+ * `base`, else `base-2`, `base-3`, … — the first form that is neither `taken`
+ * nor reserved. Callers pass one shared `taken` set covering type-derived
+ * handles and model-supplied aliases alike, so the two can never collide.
+ */
+export function assignHandle(base: string, taken: ReadonlySet<string>): string {
+  let candidate = base;
+  let n = 1;
+  while (taken.has(candidate) || RESERVED_HANDLES.has(candidate)) {
+    n++;
+    candidate = `${base}-${n}`;
+  }
+  return candidate;
+}
+
+/**
+ * Map a typed handle back to a registered agent type, so `@explore fix it`
+ * reaches the Explore agent even when no instance has ever run. `handleBase` is
+ * the single source of truth in both directions, so a type is addressable by
+ * exactly the handle its instances would be given.
+ */
+export function resolveHandleToType(handle: string, types: readonly string[]): string | undefined {
+  const wanted = handle.toLowerCase();
+  // A type slugging to a reserved name is unaddressable rather than shadowing
+  // it — `assignHandle` refuses that name too, so its instances never hold one.
+  if (RESERVED_HANDLES.has(wanted)) return undefined;
+  return types.find(type => handleBase(type) === wanted);
+}
+
+/**
+ * Claude Code documents `@agent-<name>` as the form you type by hand when the
+ * picker isn't involved. Accepted here as an exact synonym: the caller tries the
+ * handle as written first, so an agent genuinely called `agent-foo` still wins
+ * over `@agent-` + `foo`, and only falls back to this when that finds nothing.
+ * Returns undefined when the prefix is absent or is the whole handle.
+ */
+export function stripAgentPrefix(handle: string): string | undefined {
+  const rest = /^agent-(.+)$/i.exec(handle)?.[1];
+  return rest || undefined;
+}
+
+/**
+ * A spawn needs the short description every agent surface renders. A mention
+ * carries no separate label, so the message itself becomes one: first line,
+ * whitespace collapsed, clipped to roughly the 3-5 words the Agent tool asks of
+ * the model.
+ */
+export function describeMention(message: string): string {
+  const oneLine = message.split("\n", 1)[0].replace(/\s+/g, " ").trim();
+  return oneLine.length > 40 ? `${oneLine.slice(0, 39).trimEnd()}…` : oneLine;
+}
+
+/**
+ * What Claude Code sends the main model when a mention names an agent it could
+ * start. Its `@agent-<type>` mention is not a spawn at all: it becomes an
+ * `agent_mention` attachment, which renders to a synthetic `isMeta` user
+ * message placed after the user's own untouched text — no tool forcing, no
+ * allowed-tools narrowing, and the Task tool is not even named. The model reads
+ * this and calls the tool itself.
+ *
+ * Ported verbatim from the 2.1.233 bundle's attachment renderer, trailing space
+ * before the closing newline included, so the wording the model was trained
+ * against is the wording it gets. The one substitution is ours: pi's equivalent
+ * of Task is the `Agent` tool, and the agent listing that teaches valid
+ * `subagent_type` values is the tool spec rather than a separate attachment.
+ */
+export function agentMentionReminder(type: string): string {
+  return `<system-reminder>\nThe user has expressed a desire to invoke the agent "${type}". Please invoke the agent appropriately, passing in the required context to it. \n</system-reminder>`;
+}
+
+/**
+ * Split `@handle message` into its parts, or null when the text isn't a send —
+ * a bare handle, a leading file path, or a mention that isn't at the start.
+ */
+export function parseMention(text: string): { handle: string; message: string } | null {
+  const match = MENTION_SEND.exec(text);
+  if (!match) return null;
+  const message = match[2].trim();
+  return message ? { handle: match[1], message } : null;
+}

package/src/output-file.ts

@@ -68,6 +68,22 @@ export function writeInitialEntry(path: string, agentId: string, prompt: string,
   writeFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
 }
 
+/**
+ * Ensure a transcript file exists without disturbing what is already in it.
+ *
+ * A resume reuses the agent's existing transcript (same deterministic path), so
+ * it must never call `writeInitialEntry` — that truncates, discarding turns the
+ * completion notification still points the user at, and any history the session
+ * has since compacted away is gone for good (#145). Appending nothing creates
+ * the file when this is the agent's first transcript and is a no-op when it is
+ * not.
+ */
+export function ensureOutputFile(path: string): void {
+  try {
+    appendFileSync(path, "", "utf-8");
+  } catch { /* ignore — streaming writes are best-effort too */ }
+}
+
 /**
  * Subscribe to session events and flush new messages to the output file on each turn_end.
  * Returns a cleanup function that does a final flush and unsubscribes.
@@ -77,8 +93,14 @@ export function streamToOutputFile(
   path: string,
   agentId: string,
   cwd: string,
+  startIndex?: number,
 ): () => void {
-  let writtenCount = 1; // initial user prompt already written
+  // Index of the first message this stream is responsible for. A spawn writes
+  // messages[0] as the initial prompt entry, so it starts at 1. A resume hands
+  // in the session's length as of just before the run: the session already
+  // holds every prior turn, and re-emitting those would duplicate history that
+  // is already in the file.
+  let writtenCount = startIndex ?? 1;
 
   const flush = () => {
     const messages = session.messages;

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";
 
@@ -109,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`.
@@ -182,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`
@@ -189,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
@@ -204,15 +269,25 @@ 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;
@@ -223,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;
@@ -268,6 +347,14 @@ 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);
@@ -427,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 &&
@@ -434,6 +528,23 @@ 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();
   }
@@ -461,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
@@ -471,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;
@@ -799,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;
@@ -811,8 +952,20 @@ 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);
@@ -824,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.