@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.10

package/src/plan-mode-children.ts

@@ -0,0 +1,176 @@
+/**
+ * plan-mode-children.ts -- keeps a child started while the parent plans in Plan
+ * mode (#437), as Claude Code keeps a subagent spawned in plan mode in plan mode.
+ *
+ * pi-plan-mode gates only its own session's tool calls, and a child is a separate
+ * session on a separate event bus. So right before a child runs, the manager asks
+ * the parent's pi-plan-mode, synchronously on the parent's `pi.events`, whether it
+ * is planning; when it is, the answer carries the Plan tool policy, and this
+ * module applies it to every call the child makes. No answer means pi-plan-mode is
+ * not installed, and nothing changes.
+ *
+ * The contract mirrors `packages/plan-mode/src/child-policy.ts`, repeated rather
+ * than imported because either package installs without the other.
+ */
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { AgentRecord } from "./types.js";
+
+export const PLAN_MODE_STATE_QUERY = "pi-plan-mode:state-query";
+/** pi-plan-mode asks here whether a compatible gate is installed; answering is the handshake. */
+export const PLAN_MODE_GATE_QUERY = "pi-plan-mode:gate-query";
+const PLAN_MODE_STATE_VERSION = 1;
+
+/** Buses on which pi-plan-mode has shown itself by asking {@link PLAN_MODE_GATE_QUERY}. */
+const planModeSeen = new WeakSet<object>();
+
+/**
+ * Answer pi-plan-mode's gate query, so Plan admits `Agent` and friends, and remember that Plan
+ * mode is installed on this bus: from then on a state query nobody answers fails closed.
+ */
+export function answerPlanGateQueries(events: { on(channel: string, handler: (data: unknown) => void): unknown }): void {
+  events.on(PLAN_MODE_GATE_QUERY, (data) => {
+    planModeSeen.add(events);
+    const reply = (data as { reply?: unknown } | undefined)?.reply;
+    if (typeof reply === "function") reply({ version: PLAN_MODE_STATE_VERSION, gate: "@nredd/pi-subagents" });
+  });
+}
+
+/** Thrown when pi-plan-mode is installed but did not answer whether it is planning. */
+export const PLAN_MODE_SILENT_ERROR =
+  "Plan mode is installed but did not answer whether it is planning, so this subagent was not started. Reload Pi, or update @nredd/pi-plan-mode and @nredd/pi-subagents together.";
+
+/** One tool call inside a child session. */
+interface PlanModeChildToolCall {
+  toolName: string;
+  input: unknown;
+  cwd: string;
+  tool: ToolInfo | undefined;
+}
+
+/** Why Plan mode refuses a child's tool call, or `undefined` when it may run. */
+export type PlanToolPolicy = (call: PlanModeChildToolCall) => string | undefined;
+
+/**
+ * The Plan restriction one child run is under. Mutable on purpose: it is decided
+ * per run (a spawn, then each resume) while the hooks reading it are installed
+ * once, on the child's session.
+ */
+export interface PlanGate {
+  policy?: PlanToolPolicy;
+}
+
+/** Tools a child keeps without asking: safe built-ins only. */
+const FAIL_CLOSED_TOOLS: ReadonlySet<string> = new Set(["read", "grep", "find", "ls"]);
+
+/**
+ * For a planner that says it is active but sent no policy this host understands:
+ * nothing beyond the safe built-ins, so a contract mismatch can never run a child
+ * unrestricted.
+ */
+const failClosedPolicy: PlanToolPolicy = ({ toolName }) =>
+  FAIL_CLOSED_TOOLS.has(toolName)
+    ? undefined
+    : `Plan mode is active and sent no tool policy this subagent understands, so '${toolName}' is blocked.`;
+
+/**
+ * Ask the parent's pi-plan-mode whether a child started now must plan. Returns
+ * the policy to run it under, or `undefined` when nobody is planning. Several
+ * answers (two Plan extensions) combine fail-closed: any active one restricts.
+ * A malformed answer (not version 1 with a boolean `active`) restricts like an unusable one.
+ * When Plan mode is installed but nothing answers, a new child is refused
+ * (`silent: "refuse"`, which throws) and a resumed one runs fail-closed.
+ */
+export function queryPlanPolicy(
+  events: { emit(channel: string, data: unknown): void } | undefined,
+  silent: "refuse" | "restrict" = "refuse",
+): PlanToolPolicy | undefined {
+  // Hosts without an event bus (bare programmatic callers) cannot run pi-plan-mode either.
+  if (!events) return undefined;
+  const policies: PlanToolPolicy[] = [];
+  let answered = false;
+  events.emit(PLAN_MODE_STATE_QUERY, {
+    version: PLAN_MODE_STATE_VERSION,
+    reply: (state: unknown) => {
+      const answer = state as { version?: unknown; active?: unknown; evaluate?: unknown } | undefined;
+      // Only a well-formed answer says whether Plan is on; anything else restricts, never frees.
+      if (answer?.version !== PLAN_MODE_STATE_VERSION || typeof answer.active !== "boolean") {
+        policies.push(failClosedPolicy);
+        return;
+      }
+      answered = true;
+      if (!answer.active) return;
+      policies.push(typeof answer.evaluate === "function" ? (answer.evaluate as PlanToolPolicy) : failClosedPolicy);
+    },
+  });
+  if (!answered && policies.length === 0 && planModeSeen.has(events)) {
+    if (silent === "refuse") throw new Error(PLAN_MODE_SILENT_ERROR);
+    return failClosedPolicy;
+  }
+  if (policies.length === 0) return undefined;
+  return (call) => {
+    for (const policy of policies) {
+      const reason = policy(call);
+      if (reason !== undefined) return reason;
+    }
+    return undefined;
+  };
+}
+
+/**
+ * Whether a Plan policy is active on `events` now, failing closed: an installed Plan mode that
+ * answers badly or not at all counts as planning. For work that would otherwise outlive Plan
+ * unrestricted (a schedule, a quota-parked dispatch, steering an unrestricted child).
+ */
+export function planningNow(events: { emit(channel: string, data: unknown): void } | undefined): boolean {
+  return queryPlanPolicy(events, "restrict") !== undefined;
+}
+
+/**
+ * Whether a steer must be refused: the agent is running or queued under no Plan policy (it started
+ * before Plan) while Plan is active, so the steer would drive it with its full surface. The one
+ * predicate for `steer_subagent` and `subagents:rpc:steer`.
+ */
+export function planSteerBlocked(
+  record: Pick<AgentRecord, "status" | "planGate">,
+  events: { emit(channel: string, data: unknown): void } | undefined,
+): boolean {
+  return (record.status === "running" || record.status === "queued") && !record.planGate?.policy && planningNow(events);
+}
+
+/** Plan's model must not steer a child that runs without Plan's restrictions. */
+export function planSteerRefusal(id: string): string {
+  return (
+    `Cannot steer agent "${id}" while Plan mode is active: it started before Plan and runs without Plan's restrictions, so a steer could make it edit. ` +
+    "Wait for it to finish and steer it then (that resumes it read-only), stop it with stop_subagent, or leave Plan mode (/plan exit) first."
+  );
+}
+
+/** A scheduled agent fires as a fresh spawn, after Plan, with nothing restricting it. */
+export const PLAN_SCHEDULE_REFUSAL =
+  "Cannot schedule an agent while Plan mode is active: it would start later, after Plan, without Plan's restrictions. Start it now, or leave Plan mode first.";
+
+/** A quota-parked dispatch is a scheduled job too. */
+export const PLAN_PARK_REFUSAL =
+  "The agent was not started or parked: Plan mode is active, and a parked agent would start after Plan without Plan's restrictions. Retry after the reset, or leave Plan mode first.";
+
+/**
+ * The refusal for one child tool call, or `undefined`. Tools this extension
+ * injects (nested delegation, whose children inherit the gate; StructuredOutput;
+ * the workflow refusal) are exempt: Plan's policy has no entry for them.
+ */
+export function planGateReason(
+  gate: PlanGate | undefined,
+  call: { toolName: string; input: unknown; cwd: string },
+  tools: () => ToolInfo[],
+  exempt: ReadonlySet<string>,
+): string | undefined {
+  const policy = gate?.policy;
+  if (!policy || exempt.has(call.toolName)) return undefined;
+  return policy({ ...call, tool: tools().find((tool) => tool.name === call.toolName) });
+}
+
+/** Told to a child started while planning, so a refused write is not a surprise. */
+export const PLAN_MODE_CHILD_PROMPT = `<plan_mode>
+Your parent is in Plan mode, so you are too: investigate and report, do not change anything.
+edit and write are blocked, bash runs only reviewed read-only commands, and other tools run only when Plan mode admits them.
+</plan_mode>`;

package/src/process-budget.ts

@@ -0,0 +1,346 @@
+/**
+ * process-budget.ts -- one ceiling on running subagents for the whole pi process.
+ *
+ * `maxConcurrent` and `maxConcurrentForeground` are per `AgentManager`, and
+ * there can be more than one manager per process: `/new`, `/resume`, `/fork`
+ * and `/reload` activate a fresh one and leave the previous manager alive until
+ * its background agents finish. (Subagent sessions do not activate this
+ * extension; nested children run in the parent's manager.) Those pools also
+ * exempt nested children, workflow children, scheduled jobs and resumes. The budget is the one count all of them share, kept on `globalThis`
+ * under `Symbol.for` so every manager and every module instance (a `/reload`
+ * loads a fresh copy of this file) sees the same state.
+ *
+ * Scope is the PROCESS, not the machine: two pi processes each get their own
+ * budget. It bounds running agents, not CPU, memory or commands.
+ *
+ * Every run holds one lease from the moment it is admitted until it actually
+ * settles. A parent keeps its lease while it waits on a child: releasing it
+ * around a nested call would be wrong, because pi runs a turn's tool calls in
+ * parallel and the parent's other tools are still executing.
+ *
+ * Holding parent leases is what makes a plain cap deadlock: twelve parents
+ * each waiting on a child that can never start. The reserve prevents it. With
+ * `L` the policy's `maxDepth` (one value for the whole process, NOT a branch's
+ * own cap) and `limit(j) = maxActive - nestedReserve * (L - j)`, a run at depth
+ * `d` is admitted only while, for EVERY level `j` from `d` to `L`,
+ *
+ *   active at depth <= j      < limit(j)
+ *
+ * (`j = L` is the plain `active < maxActive`). So with `maxActive: 12,
+ * nestedReserve: 2, L: 2`, at most ten top-level runs hold slots at once, and
+ * the last two only ever go to depth-2 children. Every admission keeps
+ * `count(<= j) <= limit(j)` for all `j`, releases only lower counts, and
+ * policy changes that could break it wait for an idle process (see
+ * `setBudgetPolicy`). Suppose every holder is a parent blocked on a child and
+ * `k < L` is the deepest level holding any: then `active = count(<= k) <=
+ * limit(k) < limit(k + 1) <= maxActive`, so a depth-`k+1` child fits at every
+ * level. Leaves (depth `L`) never wait on anyone, so they finish. That needs
+ * `limit` strictly increasing and `limit(1) >= 1` -- `isCoherent` -- and a run
+ * deeper than `L` refused outright (`assertWithinBudgetDepth`), since nothing
+ * reserves a slot for it. Top-level, workflow and scheduled runs all count as
+ * depth 1.
+ *
+ * Waiters are served first-come-first-served among the ELIGIBLE: a deeper
+ * waiter may pass a shallower one whose threshold is not met, which is what the
+ * reserve is for. Without that, a root at the head of the line would block the
+ * child that its own siblings are waiting on.
+ */
+
+const BUDGET_KEY = Symbol.for("pi-subagents:process-budget");
+
+/** Bumped on any incompatible change to `BudgetState`'s shape. */
+const BUDGET_VERSION = 2;
+
+/**
+ * Queued starts the budget will hold while it is enabled. Only a bound on
+ * memory and on runaway fan-out -- a full queue fails the spawn with
+ * `BUDGET_QUEUE_FULL_ERROR` instead of parking work nobody will see start.
+ */
+export const MAX_PENDING_SUBAGENTS = 128;
+
+export const DEFAULT_BUDGET_POLICY: Readonly<BudgetPolicy> = {
+  maxActive: 0,
+  nestedReserve: 2,
+  maxDepth: 2,
+};
+
+export interface BudgetPolicy {
+  /** Process-wide ceiling on running subagents. `0` = off (counted, never enforced). */
+  maxActive: number;
+  /** Slots held back per nesting level below a run, so children can always start. */
+  nestedReserve: number;
+  /**
+   * The deepest level the reserve covers: the GLOBAL `maxSubagentDepth`, so a
+   * project file cannot reshape a process-wide policy. A deeper run is refused.
+   */
+  maxDepth: number;
+}
+
+/** One admitted run. Released exactly once; later releases are no-ops. */
+export interface BudgetLease {
+  readonly depth: number;
+  released: boolean;
+}
+
+/** A start waiting for admission. */
+export interface BudgetWaiter {
+  /** Nesting depth of the run: top-level = 1. */
+  depth: number;
+  /** Local conditions the owner also needs (its own pool limits). */
+  ready: () => boolean;
+  /** Takes ownership of the lease. Must not throw; a throw is swallowed and the lease released. */
+  grant: (lease: BudgetLease) => void;
+}
+
+interface BudgetState {
+  version: number;
+  policy: BudgetPolicy;
+  /** A tightening change, applied once no lease is active (`setBudgetPolicy`). */
+  pendingPolicy: BudgetPolicy | undefined;
+  active: Set<BudgetLease>;
+  waiters: BudgetWaiter[];
+  pumping: boolean;
+  repump: boolean;
+}
+
+export const BUDGET_QUEUE_FULL_ERROR =
+  `Subagent queue is full (${MAX_PENDING_SUBAGENTS} waiting for the process-wide maxActiveSubagents limit). `
+  + "Wait for running agents to finish, or do the work directly.";
+
+function freshState(): BudgetState {
+  return {
+    version: BUDGET_VERSION,
+    policy: { ...DEFAULT_BUDGET_POLICY },
+    pendingPolicy: undefined,
+    active: new Set(),
+    waiters: [],
+    pumping: false,
+    repump: false,
+  };
+}
+
+/**
+ * The process's budget state. An incompatible version (a `/reload` onto a
+ * build that changed the shape) refuses budget operations until pi restarts.
+ * Never fork the state: two private counts could each admit the whole cap.
+ */
+function state(): BudgetState {
+  const g = globalThis as Record<symbol, unknown>;
+  const existing = g[BUDGET_KEY] as BudgetState | undefined;
+  if (existing === undefined) {
+    const created = freshState();
+    g[BUDGET_KEY] = created;
+    return created;
+  }
+  if (existing.version === BUDGET_VERSION) return existing;
+  throw new Error(
+    `[pi-subagents] Incompatible process budget v${String(existing.version)} already loaded (this build uses v${String(BUDGET_VERSION)}). `
+    + "Restart pi before starting more subagents; no private budget will be created.",
+  );
+}
+
+/** The deepest level `policy` reserves for; nesting off still means one level. */
+const topLevel = (policy: BudgetPolicy): number => Math.max(1, policy.maxDepth);
+
+/**
+ * How many runs at depth <= `level` may hold leases before a run at `level` or
+ * shallower has to wait. No floor: `isCoherent` keeps it at least one.
+ */
+export function admissionLimit(policy: BudgetPolicy, level: number): number {
+  if (policy.maxActive <= 0) return Number.POSITIVE_INFINITY;
+  return policy.maxActive - policy.nestedReserve * (topLevel(policy) - level);
+}
+
+/**
+ * Whether `policy` is deadlock-free: off, or `limit` strictly increasing from
+ * at least one at depth 1 -- a reserve of one or more, and room for one
+ * top-level run after reserving for every level below it.
+ */
+export function isCoherent(policy: BudgetPolicy): boolean {
+  if (policy.maxActive <= 0 || topLevel(policy) === 1) return true;
+  return policy.nestedReserve >= 1 && admissionLimit(policy, 1) >= 1;
+}
+
+/** Every level's limit is at least what it was, so no held lease can block a child that fit before. */
+function relaxes(from: BudgetPolicy, to: BudgetPolicy): boolean {
+  if (to.maxActive <= 0) return true;
+  if (from.maxActive <= 0 || topLevel(from) !== topLevel(to)) return false;
+  for (let level = 1; level <= topLevel(to); level++) {
+    if (admissionLimit(to, level) < admissionLimit(from, level)) return false;
+  }
+  return true;
+}
+
+export function getBudgetPolicy(): BudgetPolicy {
+  return { ...state().policy };
+}
+
+/**
+ * Replace the policy. Last writer wins: every activation in the process
+ * shares it. An incoherent policy is refused with a warning. A change that
+ * could strand a waiting child -- turning the budget on, lowering a limit,
+ * changing `maxDepth` -- is held until no lease is active, since running
+ * parents were admitted under the old limits; turning it off or raising
+ * limits applies at once.
+ */
+export function setBudgetPolicy(next: BudgetPolicy): void {
+  const policy: BudgetPolicy = {
+    maxActive: Math.max(0, Math.floor(next.maxActive)),
+    nestedReserve: Math.max(0, Math.floor(next.nestedReserve)),
+    maxDepth: Math.max(0, Math.floor(next.maxDepth)),
+  };
+  if (!isCoherent(policy)) {
+    console.warn(
+      `[pi-subagents] Ignoring maxActiveSubagents ${String(policy.maxActive)} with nestedSubagentReserve ${String(policy.nestedReserve)} `
+      + `at maxSubagentDepth ${String(policy.maxDepth)}: it could deadlock. Nesting needs a reserve of at least 1 and `
+      + "maxActiveSubagents >= nestedSubagentReserve * (maxSubagentDepth - 1) + 1.",
+    );
+    return;
+  }
+  const s = state();
+  if (s.active.size === 0 || relaxes(s.policy, policy)) {
+    s.policy = policy;
+    s.pendingPolicy = undefined;
+    pumpBudget();
+  } else {
+    s.pendingPolicy = policy;
+    console.warn(
+      `[pi-subagents] Process budget change deferred until all running subagents settle: `
+      + `maxActiveSubagents=${String(policy.maxActive)}, nestedSubagentReserve=${String(policy.nestedReserve)}, `
+      + `maxSubagentDepth=${String(policy.maxDepth)}. The previous policy remains in force; continuous work can delay this indefinitely.`,
+    );
+  }
+}
+
+/** The policy waiting for the process to go idle, if any. For diagnostics and tests. */
+export function getPendingBudgetPolicy(): BudgetPolicy | undefined {
+  const pending = state().pendingPolicy;
+  return pending === undefined ? undefined : { ...pending };
+}
+
+/**
+ * Throw when the budget is on and a run at `depth` is deeper than its policy
+ * reserves for: it could wait forever behind its own ancestors. Pass/fail is
+ * fixed for the run's life, since `maxDepth` changes only while idle.
+ */
+export function assertWithinBudgetDepth(depth: number): void {
+  const { policy } = state();
+  if (policy.maxActive > 0 && depth > topLevel(policy)) {
+    throw new Error(
+      `Nested subagent at depth ${String(depth)} exceeds the process budget's depth ${String(topLevel(policy))} `
+      + "(global maxSubagentDepth). Complete the task directly.",
+    );
+  }
+}
+
+/** Running leases and waiting starts, for diagnostics and tests. */
+export function budgetUsage(): { active: number; pending: number; maxActive: number } {
+  const s = state();
+  return { active: s.active.size, pending: s.waiters.length, maxActive: s.policy.maxActive };
+}
+
+function admits(s: BudgetState, depth: number): boolean {
+  const { policy } = s;
+  if (policy.maxActive <= 0) return true;
+  const top = topLevel(policy);
+  const level = Math.max(1, depth);
+  if (level > top) return false;
+  // Leases deeper than `top` cannot exist while it is on; clamp so they still count in the total.
+  const atDepth = new Array<number>(top + 1).fill(0);
+  for (const lease of s.active) {
+    const index = Math.min(top, Math.max(1, lease.depth));
+    atDepth[index] = atDepth[index]! + 1;
+  }
+  let atOrAbove = 0;
+  for (let j = 1; j <= top; j++) {
+    atOrAbove += atDepth[j]!;
+    if (j >= level && atOrAbove >= admissionLimit(policy, j)) return false;
+  }
+  return true;
+}
+
+function newLease(s: BudgetState, depth: number): BudgetLease {
+  const lease: BudgetLease = { depth, released: false };
+  s.active.add(lease);
+  return lease;
+}
+
+/**
+ * Take a lease now, or undefined when this depth is at its limit or an earlier
+ * eligible waiter has first claim. Completion listeners can spawn synchronously
+ * between release and drain; re-entrant grant callbacks can do the same.
+ */
+export function tryAcquireBudget(depth: number): BudgetLease | undefined {
+  const s = state();
+  if (!admits(s, depth) || s.waiters.some(waiter => admits(s, waiter.depth) && waiter.ready())) return undefined;
+  return newLease(s, depth);
+}
+
+/** Whether another waiter fits. Always true while the budget is off. */
+export function budgetHasPendingRoom(): boolean {
+  const s = state();
+  return s.policy.maxActive <= 0 || s.waiters.length < MAX_PENDING_SUBAGENTS;
+}
+
+/** Join the queue. Returns a cancel function; cancelling a granted waiter is a no-op. */
+export function enqueueBudget(waiter: BudgetWaiter): () => void {
+  state().waiters.push(waiter);
+  return () => {
+    const s = state();
+    const i = s.waiters.indexOf(waiter);
+    if (i !== -1) s.waiters.splice(i, 1);
+  };
+}
+
+/**
+ * Give a lease back. Idempotent; does not pump, so callers keep their own
+ * ordering. The last release applies a held policy change.
+ */
+export function releaseBudget(lease: BudgetLease | undefined): void {
+  if (lease === undefined || lease.released) return;
+  lease.released = true;
+  const s = state();
+  s.active.delete(lease);
+  if (s.active.size === 0 && s.pendingPolicy !== undefined) {
+    s.policy = s.pendingPolicy;
+    s.pendingPolicy = undefined;
+  }
+}
+
+/**
+ * Admit every waiter that fits, earliest first, re-scanning after each grant
+ * because a grant changes the counts (`ready()` reads the owner's pools).
+ * Re-entrant calls from inside a grant are folded into the running loop.
+ */
+export function pumpBudget(): void {
+  const s = state();
+  if (s.pumping) {
+    s.repump = true;
+    return;
+  }
+  s.pumping = true;
+  try {
+    do {
+      s.repump = false;
+      for (;;) {
+        const i = s.waiters.findIndex(w => admits(s, w.depth) && w.ready());
+        if (i === -1) break;
+        const waiter = s.waiters.splice(i, 1)[0]!;
+        const lease = newLease(s, waiter.depth);
+        try {
+          waiter.grant(lease);
+        } catch {
+          releaseBudget(lease);
+        }
+      }
+    } while (s.repump);
+  } finally {
+    s.pumping = false;
+  }
+}
+
+/** Test-only: forget all leases and waiters and restore the default policy. */
+export function resetBudgetForTests(): void {
+  const g = globalThis as Record<symbol, unknown>;
+  g[BUDGET_KEY] = freshState();
+}

package/src/prompts.ts

@@ -0,0 +1,161 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+
+import { PLAN_MODE_CHILD_PROMPT } from "./plan-mode-children.js";
+import type { AgentConfig, EnvInfo } from "./types.js";
+
+/** Extra sections to inject into the system prompt (memory, skills, etc.). */
+export interface PromptExtras {
+  /** Persistent memory content to inject (first 200 lines of MEMORY.md + instructions). */
+  memoryBlock?: string;
+  /** Preloaded skill contents to inject. */
+  skillBlocks?: { name: string; content: string }[];
+  /**
+   * Parent directory the worktree copy was created from. Set only for
+   * `isolation: "worktree"` spawns — triggers the block that tells the agent
+   * to stay in the copy.
+   */
+  worktreeBase?: string;
+  /** Set when the parent was planning at spawn: the child is told it plans too (#437). */
+  planMode?: boolean;
+  /**
+   * Set only for a workflow's own children, and only when they have no
+   * `StructuredOutput` tool to answer through.
+   *
+   * A workflow child's final text is not read by a human — it is the value
+   * `agent()` resolves to, and the script interpolates it straight into the
+   * next stage's prompt. Without this, children answer the way every other
+   * subagent does (a report addressed to a reader), and the padding becomes
+   * input tokens for the stage downstream. Claude Code's `Workflow` tool
+   * documents this contract to the script-writing model; this is the end of it
+   * that makes the documentation true.
+   *
+   * Deliberately NOT applied to every subagent. In pi an ordinary agent's
+   * output IS read by a human — through FleetView, the conversation viewer and
+   * `get_subagent_result` — so terse raw data would be the wrong answer there.
+   */
+  workflowChild?: boolean;
+  /**
+   * Set when the agent lists `allowed_subagents` but got no `Agent` tool (depth
+   * cap, isolation, `disallowed_tools`). Without the line it reads the missing tool as a fault and
+   * emulates one, e.g. by shelling out to `claude -p`, which escapes the depth
+   * cap, quota admission and usage reporting.
+   */
+  nestingDisabled?: boolean;
+}
+
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
+ * - "append" with empty systemPrompt: pure parent clone
+ *
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
+ */
+export function buildAgentPrompt(
+  config: AgentConfig,
+  cwd: string,
+  env: EnvInfo,
+  parentSystemPrompt?: string,
+  extras?: PromptExtras,
+): string {
+  const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
+
+  const envBlock = `# Environment
+Working directory: ${cwd}
+${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
+Platform: ${env.platform}`;
+
+  // A worktree agent is told its cwd twice: by the env block above (the copy)
+  // and by whatever names the main checkout — the inherited parent prompt in
+  // append mode, or the task prompt in either mode. It follows the latter and
+  // works in the shared tree (#187), so resolve the contradiction explicitly.
+  const worktreeBlock = extras?.worktreeBase
+    ? `\n\n<worktree_isolation>
+Your working directory is an isolated git worktree copy of ${extras.worktreeBase}.
+Work only inside it — never in ${extras.worktreeBase}, even if other instructions name that path as your working directory.
+</worktree_isolation>`
+    : "";
+
+  // The script, not a person, reads what this child returns — see
+  // `PromptExtras.workflowChild` for why only workflow children get this.
+  const workflowBlock = extras?.workflowChild
+    ? `\n\n<workflow_child>
+Your final message IS the return value of this task. A workflow script captures it and passes it to the next stage; no person reads it.
+Return only the answer, in exactly the shape the prompt asks for — no preamble, no summary of what you did, no offer to continue.
+</workflow_child>`
+    : "";
+
+  const planModeBlock = extras?.planMode ? `\n\n${PLAN_MODE_CHILD_PROMPT}` : "";
+
+  const nestingBlock = extras?.nestingDisabled
+    ? `\n\n<nesting_disabled>
+Nested subagents are disabled for this session, so you have no Agent tool. Do the work yourself, inline.
+Do not emulate subagents by running another agent CLI (e.g. \`claude -p\`) from bash.
+</nesting_disabled>`
+    : "";
+
+  // Build optional extras suffix
+  const extraSections: string[] = [];
+  if (extras?.memoryBlock) {
+    extraSections.push(extras.memoryBlock);
+  }
+  if (extras?.skillBlocks?.length) {
+    for (const skill of extras.skillBlocks) {
+      extraSections.push(`\n# Preloaded Skill: ${skill.name}\n${skill.content}`);
+    }
+  }
+  const extrasSuffix = extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
+
+  if (config.promptMode === "append") {
+    const identity = parentSystemPrompt || genericBase;
+
+    const bridge = `<sub_agent_context>
+You are operating as a sub-agent invoked to handle a specific task.
+- Use the read tool instead of cat/head/tail
+- Use the edit tool instead of sed/awk
+- Use the write tool instead of echo/heredoc
+- Use the find tool instead of bash find/ls for file search
+- Use the grep tool instead of bash grep/rg for content search
+- Make independent tool calls in parallel
+- Use absolute file paths
+- Do not use emojis
+- Be concise but complete
+</sub_agent_context>`;
+
+    const customSection = config.systemPrompt?.trim()
+      ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
+      : "";
+
+    // Place shared/stable content first so the LLM's KV cache can reuse the
+    // inherited prefix across all subagent invocations. The parent prompt is
+    // placed verbatim (no wrapper tag) so it forms an identical byte prefix
+    // with the parent session, maximising KV cache hits. The <active_agent>
+    // tag and env block vary per call and are placed after the cached prefix.
+    return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + worktreeBlock + planModeBlock + workflowBlock + nestingBlock + customSection + extrasSuffix;
+  }
+
+  // "replace" mode — env header + the config's full system prompt
+  const replaceHeader = `You are a pi coding agent sub-agent.
+You have been invoked to handle a specific task autonomously.
+
+${envBlock}`;
+
+  return activeAgentTag + replaceHeader + worktreeBlock + planModeBlock + workflowBlock + nestingBlock + "\n\n" + config.systemPrompt + extrasSuffix;
+}
+
+/** Fallback base prompt when parent system prompt is unavailable in append mode. */
+const genericBase = `# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.`;