tau-all-agent 0.2.0 → 0.3.0

package/extensions/sandbox/permissions/unsandboxed.ts

@@ -1,22 +1,3 @@
-import { homedir } from "node:os";
-import {
-  DynamicBorder,
-  type ExtensionContext,
-  type KeybindingsManager,
-  type Theme,
-} from "@earendil-works/pi-coding-agent";
-import {
-  CURSOR_MARKER,
-  Text,
-  TUI_KEYBINDINGS,
-  visibleWidth,
-  type Component,
-  type Focusable,
-  type TUI,
-  type TuiMouseEvent,
-  type TuiMouseEventResult,
-} from "@earendil-works/pi-tui";
-
 export const UNSANDBOXED_APPROVAL_CHOICES = ["Deny", "Run once outside sandbox"] as const;
 
 export function isUnsandboxedApproval(choices: readonly string[]): boolean {
@@ -26,237 +7,17 @@ export function isUnsandboxedApproval(choices: readonly string[]): boolean {
   );
 }
 
-/** Use Pi's editor-area dialog. RPC presentation belongs to its human client. */
-export async function showUnsandboxedApproval(
-  ctx: ExtensionContext,
-  title: string,
-  signal?: AbortSignal,
-): Promise<string | undefined> {
-  if (!ctx.hasUI || ctx.mode !== "tui" || signal?.aborted) return undefined;
-  let cancel: (() => void) | undefined;
-  try {
-    const result = await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
-      cancel = () => done(undefined);
-      signal?.addEventListener("abort", cancel, { once: true });
-      if (signal?.aborted) cancel();
-      return new UnsandboxedApproval(title, tui, theme, keybindings, (choice) =>
-        done(signal?.aborted ? undefined : choice),
-      );
-    });
-    return signal?.aborted ? undefined : result;
-  } catch {
-    return undefined;
-  } finally {
-    if (cancel) signal?.removeEventListener("abort", cancel);
-  }
-}
-
 /** Shell-style details for both the local dialog and forwarded RPC approvals. */
-export function formatUnsandboxedApproval(command: string, cwd: string): string {
-  const home = homedir();
-  const homePrefix = home.endsWith("/") ? home : `${home}/`;
-  const directory =
-    cwd === home ? "~" : cwd.startsWith(homePrefix) ? `~/${cwd.slice(homePrefix.length)}` : cwd;
+export function formatUnsandboxedApproval(command: string): string {
   return [
     "Run once outside sandbox?",
     "",
-    escapeControls(directory).replaceAll("\n", "\\u000a"),
     `$ ${escapeControls(command)}`,
     "",
     "This command and its descendants get host filesystem and network access.",
   ].join("\n");
 }
 
-/** The cursor keeps the focused review line or choice visible when Pi shrinks its editor dock. */
-class UnsandboxedApproval implements Component, Focusable {
-  focused = false;
-  private readonly content = new Text("", 0, 0);
-  private readonly titleLines: string[];
-  private readonly directoryLine: number;
-  private selected = 0;
-  private reviewLine: number | undefined;
-  private scrollTop = 0;
-  private contentLines: string[] = [];
-  private viewportHeight = 0;
-  private renderedWidth = 0;
-  private renderedHeight = 0;
-  private canApprove = false;
-
-  constructor(
-    title: string,
-    private readonly tui: TUI,
-    private readonly theme: Theme,
-    private readonly keybindings: KeybindingsManager,
-    private readonly done: (choice: string | undefined) => void,
-  ) {
-    this.titleLines = escapeControls(title).split("\n");
-    this.directoryLine = this.titleLines.findIndex((line) => line.startsWith("$ ")) - 1;
-  }
-
-  render(width: number): string[] {
-    const rows = this.tui.terminal.rows;
-    const height = Math.min(16, Math.max(0, rows - 2));
-    if (width !== this.renderedWidth || rows !== this.renderedHeight) this.selected = 0;
-    this.renderedWidth = width;
-    this.renderedHeight = rows;
-    this.canApprove = false;
-    // Fullscreen owns unmodified PageUp/PageDown and Home/End before dialog input.
-    // Advertise the configured editor aliases that can actually reach this dialog.
-    const viewportKeys = new Set(
-      this.tui.mode === "fullscreen"
-        ? Object.keys(TUI_KEYBINDINGS)
-            .filter((action) => action.startsWith("tui.altScreen."))
-            .flatMap((action) => this.keybindings.getKeys(action as keyof typeof TUI_KEYBINDINGS))
-        : [],
-    );
-    const key = (action: Parameters<KeybindingsManager["getKeys"]>[0]) =>
-      this.keybindings
-        .getKeys(action)
-        .find((binding) => !action.startsWith("tui.editor.") || !viewportKeys.has(binding)) ??
-      "unbound";
-    const border = new DynamicBorder((line) => this.theme.fg("border", line)).render(width);
-    const gap = height >= 14 ? [""] : [];
-    this.content.setText(
-      this.titleLines
-        .map((line, index) =>
-          index === this.directoryLine
-            ? this.theme.fg("dim", line)
-            : line.startsWith("$ ")
-              ? this.theme.fg("text", line)
-              : line,
-        )
-        .join("\n"),
-    );
-    this.contentLines = this.content.render(Math.max(1, width - 2));
-    const choices = UNSANDBOXED_APPROVAL_CHOICES.flatMap((choice, index) =>
-      new Text(
-        this.theme.fg(
-          index === this.selected ? "accent" : "text",
-          `${this.focused && this.reviewLine === undefined && index === this.selected ? CURSOR_MARKER : ""}${index === this.selected ? "→" : " "} ${choice}`,
-        ),
-        1,
-        0,
-      ).render(width),
-    );
-    const navigation =
-      key("tui.select.up") === "up" && key("tui.select.down") === "down"
-        ? "↑↓"
-        : `${key("tui.select.up")}/${key("tui.select.down")}`;
-    const hint = (binding: string, description: string) =>
-      this.theme.fg("dim", binding) + this.theme.fg("muted", ` ${description}`);
-    const hints = new Text(
-      `${hint(navigation, "navigate")}  ${hint(key("tui.select.confirm"), "select")}  ${hint(key("tui.select.cancel"), "cancel")}`,
-      1,
-      0,
-    ).render(width);
-    this.viewportHeight =
-      height - border.length * 2 - gap.length * 4 - choices.length - hints.length;
-    const reviewHints =
-      this.contentLines.length > this.viewportHeight || this.reviewLine !== undefined
-        ? new Text(
-            this.theme.fg(
-              "dim",
-              `${key("tui.editor.pageUp")}/${key("tui.editor.pageDown")} review lines · ${key("tui.editor.cursorLineStart")}/${key("tui.editor.cursorLineEnd")} top/end`,
-            ),
-            1,
-            0,
-          ).render(width)
-        : [];
-    this.viewportHeight -= reviewHints.length;
-    if (width < 3 || this.viewportHeight < 1) {
-      return new Text("Resize to review. Escape denies.", 0, 0)
-        .render(Math.max(1, width))
-        .slice(0, Math.max(0, height));
-    }
-    this.viewportHeight = Math.min(this.viewportHeight, this.contentLines.length);
-    if (this.reviewLine !== undefined) {
-      this.reviewLine = Math.min(this.reviewLine, this.contentLines.length - 1);
-      this.scrollTop = Math.max(0, this.reviewLine - this.viewportHeight + 1);
-    }
-    this.scrollTop = Math.min(
-      this.scrollTop,
-      Math.max(0, this.contentLines.length - this.viewportHeight),
-    );
-    this.canApprove =
-      this.focused &&
-      this.reviewLine === undefined &&
-      this.selected === 1 &&
-      width >= visibleWidth(` → ${UNSANDBOXED_APPROVAL_CHOICES[1]} `);
-    const visible = Array.from({ length: this.viewportHeight }, (_, index) => {
-      const row = this.scrollTop + index;
-      const line = this.contentLines[row] ?? "";
-      const cursor = this.focused && row === this.reviewLine ? CURSOR_MARKER : "";
-      const text = row === 0 ? this.theme.fg("accent", this.theme.bold(line)) : line;
-      return ` ${cursor}${text}`;
-    });
-    return [
-      ...border,
-      ...gap,
-      ...visible,
-      ...gap,
-      ...choices,
-      ...gap,
-      ...hints,
-      ...reviewHints,
-      ...gap,
-      ...border,
-    ];
-  }
-
-  handleInput(data: string): void {
-    const kb = this.keybindings;
-    if (kb.matches(data, "tui.select.cancel")) {
-      this.done(undefined);
-      return;
-    }
-    if (
-      this.renderedWidth !== this.tui.terminal.columns ||
-      this.renderedHeight !== this.tui.terminal.rows
-    ) {
-      this.canApprove = false;
-      this.selected = 0;
-      this.tui.requestRender();
-      return;
-    }
-    if (kb.matches(data, "tui.select.confirm")) {
-      if (this.selected === 0) this.done("Deny");
-      else if (this.canApprove) this.done("Run once outside sandbox");
-      return;
-    }
-    if (kb.matches(data, "tui.select.up") || kb.matches(data, "tui.select.down")) {
-      this.selected = kb.matches(data, "tui.select.down") && this.viewportHeight > 0 ? 1 : 0;
-      this.reviewLine = undefined;
-      this.canApprove = false;
-    }
-    // Pi does not expose the editor dock's height. Advance one review line so its
-    // cursor can reveal every line even when only part of this component fits.
-    else if (kb.matches(data, "tui.editor.pageUp")) this.scroll(-1);
-    else if (kb.matches(data, "tui.editor.pageDown")) this.scroll(1);
-    else if (kb.matches(data, "tui.editor.cursorLineStart")) this.scroll(-this.contentLines.length);
-    else if (kb.matches(data, "tui.editor.cursorLineEnd")) this.scroll(this.contentLines.length);
-    this.tui.requestRender();
-  }
-
-  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
-    if (event.type !== "wheel") return undefined;
-    this.scroll(event.wheelDelta ?? 0);
-    return { handled: true, render: true };
-  }
-
-  invalidate(): void {
-    this.content.invalidate();
-  }
-
-  private scroll(lines: number): void {
-    this.selected = 0;
-    this.canApprove = false;
-    this.reviewLine = Math.max(
-      0,
-      Math.min(this.contentLines.length - 1, (this.reviewLine ?? 0) + lines),
-    );
-  }
-}
-
 /** Preserve layout newlines while making untrusted terminal and Unicode controls inert. */
 function escapeControls(text: string): string {
   return text.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, (character) =>

package/extensions/sandbox/runtime.ts

@@ -1,4 +1,8 @@
-import { SandboxManager, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import {
+  SandboxManager,
+  type SandboxAskCallback,
+  type SandboxRuntimeConfig,
+} from "@anthropic-ai/sandbox-runtime";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import {
@@ -16,7 +20,6 @@ import {
   type SandboxConfigPath,
 } from "./config.js";
 import { createNetworkPermissions } from "./permissions/network.js";
-import { isUnsandboxedApproval, showUnsandboxedApproval } from "./permissions/unsandboxed.js";
 
 const STATUS_KEY = "sandbox";
 const SANDBOX_EVENT_LIMIT = 50;
@@ -70,11 +73,11 @@ export interface SandboxRuntime {
   readonly configPaths: SandboxConfigPath[];
   readonly events: SandboxEvent[];
   getRuntimeConfig(): SandboxRuntimeConfig | null;
-  captureContext(ctx: ExtensionContext): void;
-  withPermissionContext<T>(
-    ctx: ExtensionContext,
+  withBashContext<T>(ctx: ExtensionContext, signal: AbortSignal, run: () => Promise<T>): Promise<T>;
+  withPermissionContext<C extends ExtensionContext, T>(
+    ctx: C,
     signal: AbortSignal | undefined,
-    run: (ctx: ExtensionContext, signal: AbortSignal) => Promise<T>,
+    run: (ctx: C, signal: AbortSignal) => Promise<T>,
   ): Promise<T>;
   start(ctx: ExtensionContext): Promise<void>;
   shutdown(ctx: ExtensionContext): Promise<void>;
@@ -230,6 +233,7 @@ export function createSandboxRuntime(pi: ExtensionAPI): SandboxRuntime {
   const warnedSkippedProjectConfigPaths = new Set<string>();
   let permissionLifetime = new AbortController();
   const permissionInvocations = new Set<Promise<unknown>>();
+  let networkInvocation: { signal: AbortSignal; pending: Set<Promise<boolean>> } | undefined;
 
   function recordSandboxEvent(event: SandboxEvent): void {
     sandboxEvents.push(event);
@@ -298,6 +302,19 @@ export function createSandboxRuntime(pi: ExtensionAPI): SandboxRuntime {
     notify,
   });
 
+  const askNetworkPermission: SandboxAskCallback = async (request) => {
+    const owner = networkInvocation;
+    if (!owner || owner.signal.aborted) return false;
+
+    const decision = networkPermissions.ask(request, owner.signal);
+    owner.pending.add(decision);
+    try {
+      return await decision;
+    } finally {
+      owner.pending.delete(decision);
+    }
+  };
+
   async function initializeSandboxRuntime(
     ctx: ExtensionContext,
     config: SandboxConfig,
@@ -326,7 +343,7 @@ export function createSandboxRuntime(pi: ExtensionAPI): SandboxRuntime {
     const runtimeConfig = toRuntimeConfig(config);
 
     try {
-      await SandboxManager.initialize(runtimeConfig, networkPermissions.ask, true);
+      await SandboxManager.initialize(runtimeConfig, askNetworkPermission, true);
       const activeConfig = cloneRuntimeConfig(runtimeConfig);
       sandboxState = { status: "active", runtimeConfig: activeConfig };
       return activeConfig;
@@ -491,11 +508,33 @@ export function createSandboxRuntime(pi: ExtensionAPI): SandboxRuntime {
     }
   }
 
-  /** Own invocation-local permission work until its dialog or command has settled. */
-  function withPermissionContext<T>(
+  /** Hold the Bash lane until asynchronous proxy approvals have been revoked and joined. */
+  async function withBashContext<T>(
     ctx: ExtensionContext,
+    signal: AbortSignal,
+    run: () => Promise<T>,
+  ): Promise<T> {
+    const completion = new AbortController();
+    const permissionSignal = AbortSignal.any([signal, completion.signal]);
+    const owner = { signal: permissionSignal, pending: new Set<Promise<boolean>>() };
+    const previousContext = sessionContext;
+    sessionContext = permissionContext(ctx, permissionSignal);
+    networkInvocation = owner;
+    try {
+      return await run();
+    } finally {
+      completion.abort();
+      while (owner.pending.size) await Promise.allSettled(owner.pending);
+      networkInvocation = undefined;
+      sessionContext = previousContext;
+    }
+  }
+
+  /** Own invocation-local permission work until its dialog or command has settled. */
+  function withPermissionContext<C extends ExtensionContext, T>(
+    ctx: C,
     signal: AbortSignal | undefined,
-    run: (ctx: ExtensionContext, signal: AbortSignal) => Promise<T>,
+    run: (ctx: C, signal: AbortSignal) => Promise<T>,
   ): Promise<T> {
     const signals = [permissionLifetime.signal, ctx.signal, signal].filter(
       (value): value is AbortSignal => value !== undefined,
@@ -515,7 +554,7 @@ export function createSandboxRuntime(pi: ExtensionAPI): SandboxRuntime {
     await Promise.allSettled(permissionInvocations);
   }
 
-  function permissionContext(ctx: ExtensionContext, contextSignal = ctx.signal): ExtensionContext {
+  function permissionContext<C extends ExtensionContext>(ctx: C, contextSignal = ctx.signal): C {
     function queued<T>(
       run: (signal?: AbortSignal) => Promise<T>,
       cancelled: T,
@@ -545,10 +584,7 @@ export function createSandboxRuntime(pi: ExtensionAPI): SandboxRuntime {
     const overrides: Pick<ExtensionContext["ui"], "select" | "confirm"> = {
       select: (title, options, opts) =>
         queued(
-          (signal) =>
-            isUnsandboxedApproval(options) && ctx.mode === "tui"
-              ? showUnsandboxedApproval(ctx, title, signal)
-              : ctx.ui.select(title, options, { ...opts, signal }),
+          (signal) => ctx.ui.select(title, options, { ...opts, signal }),
           undefined,
           opts?.signal,
         ),
@@ -578,7 +614,7 @@ export function createSandboxRuntime(pi: ExtensionAPI): SandboxRuntime {
           },
         },
       },
-    ) as ExtensionContext;
+    ) as C;
   }
 
   return {
@@ -601,9 +637,7 @@ export function createSandboxRuntime(pi: ExtensionAPI): SandboxRuntime {
       return sandboxEvents;
     },
     getRuntimeConfig: () => getStateRuntimeConfig(sandboxState),
-    captureContext(ctx) {
-      sessionContext = permissionContext(ctx);
-    },
+    withBashContext,
     withPermissionContext,
     start,
     shutdown,

package/extensions/subagent/README.md

@@ -23,7 +23,7 @@ The model and thinking level default to the parent's settings when the child sta
 
 Match model capability to the task. Favor faster, less capable models for mechanical work and well-defined, bounded tasks. Favor more capable models for complex, ambiguous, or high-stakes work. Override the parent's model in either direction when there is a clear benefit. Choose model and thinking level independently. If no suitable alternative is known to be available, omit `model` to inherit.
 
-The thinking-level guidance favors inheritance. Override the thinking level only when the task clearly warrants more or less reasoning. When choosing an override:
+The built-in model and thinking-level guidance favors inheritance. Choose a different model or thinking level only when the task clearly benefits from different model capabilities or reasoning effort. The built-in [customizable recommendations](#selection-recommendations) suggest these thinking levels:
 
 - **Low:** mechanical searches and extraction.
 - **Medium:** bounded edits or tests with a well-defined approach.
@@ -34,6 +34,59 @@ These are recommendations, not fixed tiers. There is no automatic upgrade or dow
 
 `steer` is cooperative: a running child receives the message after its current tool batch, before its next model call. It does not interrupt an in-flight shell command. An idle child starts another turn with its existing history.
 
+## Selection recommendations
+
+Override or extend the task guidance in `<agent-dir>/subagent.json`, normally `~/.pi/agent/subagent.json`. This is an optional, agent-global file. There are no project overrides or configuration commands. Run `/reload` after editing it.
+
+The file is an array of overrides and additions, **not a replacement for the built-in recommendations**. All four built-ins (`low`, `medium`, `high`, `xhigh`) are enabled by default. A missing file or `[]` leaves the defaults unchanged.
+
+For example, using illustrative model IDs:
+
+```json
+[
+  {
+    "id": "low",
+    "model": "provider/fast-model"
+  },
+  {
+    "id": "medium",
+    "model": "provider/coding-model",
+    "thinking": "inherit"
+  },
+  {
+    "id": "high",
+    "model": "inherit",
+    "thinking": "high"
+  },
+  {
+    "id": "xhigh",
+    "model": "provider/strong-model"
+  },
+  {
+    "id": "security-review",
+    "when": "Reviewing authentication, authorization, or trust boundaries.",
+    "model": "provider/strong-model",
+    "thinking": "high"
+  }
+]
+```
+
+| Field      | Meaning                                                                                                              |
+| ---------- | -------------------------------------------------------------------------------------------------------------------- |
+| `id`       | Required stable identifier. An existing ID merges supplied fields into that default. A new ID adds a recommendation. |
+| `when`     | Task guidance for the parent. Omit it to keep the built-in description. Required for a new recommendation.           |
+| `model`    | Exact `provider/model` ID, or `"inherit"` to recommend the parent's model.                                           |
+| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `"inherit"`.                                           |
+| `enabled`  | Optional boolean. Set `false` to exclude a recommendation from the guidance. Defaults to enabled.                    |
+
+A new recommendation requires `when` and at least one of `model` or `thinking`, even if disabled. Built-in IDs are labels, not inferred thinking levels: `"id": "medium"` can recommend `"thinking": "inherit"` or any supported level. Strings are trimmed, duplicate IDs and unknown fields are errors, and invalid configuration reports its path and prevents the parent extension from loading rather than silently using defaults.
+
+Only supplied fields override defaults. In the example, `low` keeps its built-in task description and `low` thinking recommendation while gaining a preferred model. `high` explicitly recommends inheriting the parent's model. Unchanged fields continue receiving improvements to the built-ins. Existing recommendations retain their order; new ones are appended in file order. Order is not routing priority.
+
+These settings change **advice**, not execution defaults or allowed choices. The effective recommendations appear in the tool description and parent instructions. The parent still decides which advice applies and chooses model and thinking independently. Omitting a field in the file keeps its built-in recommendation; `"inherit"` explicitly recommends omitting that tool argument. Do not pass the literal string `inherit` to the tool.
+
+Model IDs are checked for `provider/model` syntax, not availability at configuration load. A model must be known and usable when actually selected, and an explicit thinking level must be supported by it. Explicit selection failures remain errors, with no silent substitution. Disabling a recommendation does not prohibit its model or thinking level.
+
 ## Display and cancellation
 
 A compact running count appears only while children are active. With Tool Display Mode and an embedding-capable editor, it joins the composer's working indicator, including when only children are running. Otherwise it appears above the composer. Pi's tool-expansion shortcut, normally **Ctrl+O**, reveals rows above the composer with each child's status, goal, model, and thinking level. There is no separate shortcut or transcript viewer.
@@ -46,6 +99,8 @@ Ghostty's title spinner stays active while children are working, even when the p
 
 While children or Review tasks are active, Escape asks **“Cancel all ongoing work?”**. **Enter** confirms cancellation of the parent and all active background work. Escape again or **No** dismisses the confirmation without stopping anything. Existing dialogs keep their own Escape handling, and idle children do not require confirmation. `stop` still cancels one child directly without affecting others.
 
+Whole-run parent cancellation also stops active children during tool execution or retry backoff. An independently aborted child run is reported as `aborted`, retaining its available partial answer, and can still be continued with `steer`. This differs from `stop`, which closes the child process. Pi's retry-only cancellation (`abortRetry()`, including native retry Escape) does not currently report whole-run cancellation.
+
 Idle conversations remain available until stopped or the parent session closes. Reload, session replacement, and exit stop children and join their processes, pipes, pending startup, and approval requests. Navigating to another conversation branch also stops children so their answers cannot arrive on the wrong branch. Shutdown clears queued directions and requests a native abort before sending SIGTERM. Startup or unresponsive requests cannot block this indefinitely; SIGKILL is the final fallback.
 
 Children are marked with `TAU_SUBAGENT_CHILD=1`. They do not get the delegation tool or Telegram integration themselves. The parent also sets `TAU_SUBAGENT_UNSANDBOXED_APPROVAL=1` to advertise support for forwarding sandbox approval requests. These are internal launch markers, not user configuration or permission grants.
@@ -56,6 +111,8 @@ Children load normal Pi configuration, authentication, and extensions from the p
 
 When Tau's Sandbox is loaded, it explicitly passes its **current session policy** to the child, including temporary changes. A blocked or uninitialized parent sandbox prevents starting a child. A child still needs its own working sandbox prerequisites. Permissions subsequently granted to one child do not automatically grant access to its siblings or parent.
 
+This policy applies to the child's Bash tool, including nested calls through codemode. It does not sandbox the Pi process, other tools, or MCP servers. MCP subprocesses run with the child's host permissions.
+
 Standard child selection, confirmation, and text-input requests appear in the parent UI, labelled with the child's ID and goal. A single queue handles these requests and the parent's Sandbox approvals. Cancelling a queued child removes its request without dismissing another child's dialog. No agent message counts as permission; only the user's actual response is returned to the child. Non-interactive sandbox policy remains non-interactive, and requests without a parent UI are denied.
 
 Pi does not queue arbitrary extension dialogs. This integration waits for an already-open Pi prompt, but unrelated extensions can still open their own dialogs without joining the approval queue. RPC also cannot display custom TUI components; multiline editor requests are cancelled because Pi does not provide cancellable forwarding for them.

package/extensions/subagent/config.ts

@@ -0,0 +1,118 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+interface Recommendation {
+  id: string;
+  when: string;
+  model?: string;
+  thinking?: string;
+  enabled?: boolean;
+}
+
+const DEFAULT_RECOMMENDATIONS: readonly Recommendation[] = [
+  {
+    id: "low",
+    when: "mechanical searches and extraction",
+    thinking: "low",
+  },
+  {
+    id: "medium",
+    when: "bounded edits or tests with a well-defined approach",
+    thinking: "medium",
+  },
+  {
+    id: "high",
+    when: "non-trivial implementation tasks, cross-cutting changes, and security or concurrency review with a reasonably understood problem and direction",
+    thinking: "high",
+  },
+  {
+    id: "xhigh",
+    when: "difficult, open-ended reasoning that requires resolving substantial uncertainty or evaluating competing explanations and approaches. Ambiguous debugging and difficult investigations are examples",
+    thinking: "xhigh",
+  },
+];
+const FIELDS = new Set(["id", "when", "model", "thinking", "enabled"]);
+const THINKING = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max", "inherit"]);
+
+export function loadRecommendations(): string[] {
+  const configPath = path.join(getAgentDir(), "subagent.json");
+  try {
+    let overrides: unknown = [];
+    try {
+      overrides = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    const recommendations = mergeRecommendations(overrides);
+    const enabled = recommendations.filter((recommendation) => recommendation.enabled !== false);
+    if (!enabled.length) return [];
+    return [
+      "Use these task-specific subagent recommendations when applicable, in preference to general selection guidance. They are advice, not fixed tiers or automatic routing. Choose model and thinking independently; a recommendation may suggest either or both. Inherit by omitting the corresponding tool argument, not by passing the literal string inherit.",
+      ...enabled.map(describeRecommendation),
+    ];
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid subagent config at ${configPath}: ${message}`);
+  }
+}
+
+function mergeRecommendations(value: unknown): Recommendation[] {
+  if (!Array.isArray(value)) throw new Error("Expected an array of recommendation overrides");
+  const recommendations = new Map(DEFAULT_RECOMMENDATIONS.map((item) => [item.id, item]));
+  const seen = new Set<string>();
+  for (const [index, item] of value.entries()) {
+    const entry = `Entry ${index + 1}`;
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      throw new Error(`${entry} must be an object`);
+    const raw = item as Record<string, unknown>;
+    for (const key of Object.keys(raw)) {
+      if (!FIELDS.has(key)) throw new Error(`${entry}: unknown field ${JSON.stringify(key)}`);
+    }
+    const id = readString(raw.id, `${entry}.id`);
+    if (seen.has(id)) throw new Error(`${entry}: duplicate id ${JSON.stringify(id)}`);
+    seen.add(id);
+    const label = `${entry} (${JSON.stringify(id)})`;
+    const override: Partial<Recommendation> = { id };
+    if (raw.when !== undefined) override.when = readString(raw.when, `${label}.when`);
+    if (raw.model !== undefined) {
+      const model = readString(raw.model, `${label}.model`);
+      if (model !== "inherit" && !/^[^\s/]+\/[^\s]+$/.test(model))
+        throw new Error(`${label}.model must be inherit or an exact provider/model ID`);
+      override.model = model;
+    }
+    if (raw.thinking !== undefined) {
+      const thinking = readString(raw.thinking, `${label}.thinking`);
+      if (!THINKING.has(thinking))
+        throw new Error(`${label}.thinking must be one of ${[...THINKING].join(", ")}`);
+      override.thinking = thinking;
+    }
+    if (raw.enabled !== undefined) {
+      if (typeof raw.enabled !== "boolean") throw new Error(`${label}.enabled must be a boolean`);
+      override.enabled = raw.enabled;
+    }
+    const merged = { ...recommendations.get(id), ...override, id };
+    if (!merged.when) throw new Error(`${label}: a new recommendation requires when`);
+    if (merged.model === undefined && merged.thinking === undefined)
+      throw new Error(`${label}: a new recommendation requires model or thinking`);
+    recommendations.set(id, { ...merged, when: merged.when });
+  }
+  return [...recommendations.values()];
+}
+
+function readString(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`${label} must be a nonblank string`);
+  return value.trim();
+}
+
+function describeRecommendation(recommendation: Recommendation): string {
+  const settings = (["model", "thinking"] as const).flatMap((field) => {
+    const value = recommendation[field];
+    if (value === undefined) return [];
+    return value === "inherit"
+      ? [`omit ${field} to inherit the parent's ${field === "model" ? "model" : "thinking level"}`]
+      : [`prefer ${field}=${JSON.stringify(value)}`];
+  });
+  return `Subagent recommendation ${JSON.stringify(recommendation.id)} (${recommendation.when}): ${settings.join("; ")}.`;
+}