rovecode 0.4.0-beta.3 → 0.4.0

package/src/core/modes.ts

@@ -0,0 +1,372 @@
+/**
+ * Plan/Act agent modes with per-mode model config — ported from cline
+ * (snapshot: research/source_snapshots/cline-cline @ 8eb5f3d).
+ * Citations are snapshot-relative path:line.
+ *
+ * Ported behavior:
+ *  - Two modes, "plan" | "act", default "act"
+ *    (apps/vscode/src/shared/storage/state-keys.ts:281  mode: { default: "act" }).
+ *  - Plan mode is the read-only exploration mode: editor/patch tools are
+ *    disabled (sdk/packages/core/src/extensions/tools/presets.ts:45-57), and
+ *    the model cannot switch modes itself — the user flips the toggle
+ *    (apps/vscode/src/sdk/sdk-session-config-builder.ts:12-18,
+ *     sdk/packages/shared/src/prompt/cline.ts:52-59).
+ *  - Per-mode provider+model slots (state-keys.ts:150,196,245-252
+ *    planModeApiModelId / actModeApiModelId / planModeApiProvider /
+ *    actModeApiProvider): each mode reads ITS OWN slot at run-build time
+ *    (apps/vscode/src/sdk/cline-session-factory.ts:552-558 resolveModelId;
+ *     :799-800 provider per mode), while `planActSeparateModels` (default
+ *    false — state-keys.ts:272) gates WRITE-time sync only: with the flag
+ *    off, setting a model in one mode mirrors it to the other
+ *    (apps/vscode/src/core/controller/models/updateApiConfiguration.ts:104-131).
+ *  - Toggling to the mode you are already in is a no-op
+ *    (apps/vscode/src/sdk/sdk-mode-coordinator.ts:131-135).
+ *  - A user-initiated switch stamps a <mode_notice> onto the next outbound
+ *    message, and a round trip (plan→act→plan before sending) cancels out
+ *    (sdk/packages/shared/src/prompt/format.ts:41-80, tracker semantics
+ *     :61-80; per-session scoping of pending notices:
+ *     apps/vscode/src/sdk/sdk-mode-coordinator.ts:79-81,101-112).
+ *  - Plan-mode behavioral contract for the system prompt adapted from
+ *    sdk/packages/shared/src/prompt/cline.ts:34-45 (base) + :52-59 (the
+ *    no-self-switch tail used by hosts without a switch_to_act_mode tool).
+ *
+ * Deliberate deviations (rovecode-specific, per ADR-005 deny-default policy):
+ *  - Enforcement rides the EXISTING permission pipeline: plan mode is a rule
+ *    set appended to RunConfig.permissionRules and evaluated by the one
+ *    evaluatePermissions ladder (src/core/tools.ts:17-27, last match wins).
+ *    No second enforcement path.
+ *  - Upstream plan mode keeps shell access with a file-editing command
+ *    blacklist (presets.ts:48, sdk/packages/core/src/extensions/tools/
+ *    command-guard.ts:1-74, runtime-builder.ts:477-489). rovecode plan mode
+ *    denies shell.exec outright — the task bar mandates a read/grep-class
+ *    toolset, and a blacklist is a weaker guarantee than a deny rule.
+ *  - Upstream plan mode allows spawning sub-agents (presets.ts:55); rovecode
+ *    denies spawn in plan mode because children could write.
+ *  - memory.write is denied in plan mode EXCEPT `todo_write` (port #32): the
+ *    todo list is the plan's own artifact (agent-private session metadata,
+ *    never workspace state), so planning may record it; memory_edit stays denied.
+ *  - The mode switch is preserved durably as a session entry (a system-role
+ *    Message carrying the upstream notice text) instead of a prefix on the
+ *    next user message — rovecode sessions are an append-only tree, so the entry
+ *    lands exactly where the switch happened. Round-trip cancellation is
+ *    kept: a cancelled switch never becomes an entry.
+ *
+ * Scope: modes are a TUI feature — only src/tui consumes this module;
+ * `rovecode run`/acp/serve ignore .rovecode/modes.json (incl. defaultMode) and own
+ * their RunConfig outright (R2 #20 LOW-4 decision: documented, not wired).
+ */
+
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Message, PermissionRule } from "./types.ts";
+
+// ---------- Mode ----------
+
+export type AgentMode = "plan" | "act";
+
+/** Upstream default mode (state-keys.ts:281). */
+export const DEFAULT_MODE: AgentMode = "act";
+
+function isMode(v: unknown): v is AgentMode {
+  return v === "plan" || v === "act";
+}
+
+// ---------- Per-mode model config (.rovecode/modes.json) ----------
+
+/** One mode's provider/model selection (upstream planMode… / actMode… fields). */
+export interface ModeModelSelection {
+  provider?: string;
+  model?: string;
+}
+
+export interface ModesConfig {
+  /** Starting mode; default "act" (state-keys.ts:281). Read by the TUI only —
+   *  headless entrypoints (run/acp/serve) never load modes.json (LOW-4). */
+  defaultMode?: AgentMode;
+  /** Write-time sync gate; default false (planActSeparateModelsSetting,
+   *  state-keys.ts:272): false = setting a model in one mode mirrors it to
+   *  the other (updateApiConfiguration.ts:119-131). */
+  planActSeparateModels?: boolean;
+  plan?: ModeModelSelection;
+  act?: ModeModelSelection;
+}
+
+function asSelection(v: unknown): ModeModelSelection | undefined {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return undefined;
+  const o = v as Record<string, unknown>;
+  const provider = typeof o.provider === "string" && o.provider.trim() !== "" ? o.provider.trim() : undefined;
+  const model = typeof o.model === "string" && o.model.trim() !== "" ? o.model.trim() : undefined;
+  if (provider === undefined && model === undefined) return undefined;
+  return { provider, model };
+}
+
+/** Load `<cwd>/.rovecode/modes.json`. Missing, unreadable, or malformed files and
+ *  junk fields all degrade to defaults — config can never crash startup
+ *  (house pattern: src/core/config.ts tryReadFile / src/mcp config). */
+export function loadModesConfig(cwd: string): ModesConfig {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(join(cwd, ".rovecode", "modes.json"), "utf8"));
+  } catch {
+    return {};
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const o = raw as Record<string, unknown>;
+  const out: ModesConfig = {};
+  if (isMode(o.defaultMode)) out.defaultMode = o.defaultMode;
+  if (typeof o.planActSeparateModels === "boolean") out.planActSeparateModels = o.planActSeparateModels;
+  const plan = asSelection(o.plan);
+  const act = asSelection(o.act);
+  if (plan) out.plan = plan;
+  if (act) out.act = act;
+  return out;
+}
+
+// ---------- Plan-mode policy rule set (rides the existing pipeline) ----------
+
+/**
+ * Deny rules appended AFTER the base rules; evaluatePermissions is
+ * last-match-wins (src/core/tools.ts:17-27), so these override any earlier
+ * allow/prompt — including yolo's `* * allow`. Action names are the ones
+ * actionFor() emits (src/core/tools.ts:145-154).
+ *
+ * Upstream basis: ToolPresets.plan disables editing (presets.ts:50-51); the
+ * shell/spawn/memory denies are the rovecode deviations documented above.
+ */
+export function planModeRules(allowTools: readonly string[] = []): PermissionRule[] {
+  const rules: PermissionRule[] = [
+    // plan is the exploration mode: reads are guaranteed, whatever the base
+    // rules said (ToolPresets.plan enableReadFiles/enableSearch, presets.ts:46-47)
+    { action: "file.read", resource: "*", effect: "allow" },
+    { action: "file.write", resource: "*", effect: "deny" },
+    { action: "shell.exec", resource: "*", effect: "deny" },
+    { action: "spawn", resource: "*", effect: "deny" },
+    { action: "memory.write", resource: "*", effect: "deny" },
+    // port #32: the session todo list IS the plan — todo_write (kind memory; its policy resource
+    // is the tool name, tools/todo.ts) is re-allowed right after the memory deny, so plan mode can
+    // record its plan while memory_edit and every other memory.write stay denied (one ladder)
+    { action: "memory.write", resource: "todo_write", effect: "allow" },
+    // blanket deny for custom tools (e.g. mcp_call) — MCP calls can mutate
+    { action: "tool.*", resource: "*", effect: "deny" },
+  ];
+  // read-only custom tools a caller vouches for, re-allowed after the blanket
+  // deny (last match wins)
+  for (const name of allowTools) {
+    rules.push({ action: `tool.${name}`, resource: "*", effect: "allow" });
+  }
+  return rules;
+}
+
+/** Mode-aware rule transform: act passes the base rules through untouched;
+ *  plan appends the read-only rule set. Pure — never mutates `base`. */
+export function applyModeRules(
+  mode: AgentMode,
+  base: readonly PermissionRule[],
+  allowTools: readonly string[] = [],
+): PermissionRule[] {
+  if (mode !== "plan") return [...base];
+  return [...base, ...planModeRules(allowTools)];
+}
+
+// ---------- Plan-mode system prompt section ----------
+
+/**
+ * Behavioral contract appended to the system prompt in plan mode. Adapted
+ * from PLAN_MODE_INSTRUCTIONS_BASE (sdk/packages/shared/src/prompt/
+ * cline.ts:34-45) with the no-self-switch tail (:52-59). The upstream
+ * run_commands paragraph is replaced: rovecode plan mode has no shell at all.
+ */
+export function planModePromptSection(): string {
+  return `# Plan Mode
+
+You are in Plan mode. Your role is to explore, analyze, and plan -- not to execute.
+- Read files and search the codebase to understand the task
+- Present your plan as a structured outline with clear steps
+- Editing tools, shell commands, and sub-agents are unavailable in plan mode: attempts are denied by policy. If the task requires a mutation, put it in the plan; it happens only after the user switches to act mode.
+
+Once you have presented your plan, end your turn and wait for the user's response. You do NOT have the ability to switch to act mode yourself -- the user must do it manually with the Plan/Act toggle once they are satisfied with the plan. If the task requires tools that are only available in act mode, ask the user to "toggle to Act mode" (use those words).`;
+}
+
+// ---------- Mode-switch notice (format.ts:41-80, ported) ----------
+
+export interface ModeSwitch {
+  from: AgentMode;
+  to: AgentMode;
+}
+
+/** Ports formatModeSwitchNotice (format.ts:41-46) verbatim. */
+export function formatModeSwitchNotice(from: AgentMode, to: AgentMode): string {
+  return `<mode_notice>The user switched from ${from} mode to ${to} mode before sending this message.</mode_notice>`;
+}
+
+/**
+ * Ports createModeSwitchNoticeTracker (format.ts:61-80): tracks a
+ * user-initiated switch so the next outbound turn can carry a notice. A
+ * round trip (plan→act→plan before sending anything) cancels out, since the
+ * mode the model last saw never effectively changed (:64-73).
+ */
+export function createModeSwitchNoticeTracker(): {
+  record(from: AgentMode, to: AgentMode): void;
+  consume(): ModeSwitch | null;
+} {
+  let pending: ModeSwitch | null = null;
+  return {
+    record(from: AgentMode, to: AgentMode): void {
+      if (from === to) return;
+      if (pending) {
+        pending = pending.from === to ? null : { from: pending.from, to };
+        return;
+      }
+      pending = { from, to };
+    },
+    consume(): ModeSwitch | null {
+      const notice = pending;
+      pending = null;
+      return notice;
+    },
+  };
+}
+
+// ---------- Session entry (durable mode-switch record) ----------
+
+/**
+ * Mode switches persist as system-role Messages so the existing SessionStore
+ * Entry union (src/core/session.ts:10) accepts them unchanged: `modeSwitch`
+ * is an extra field that rides the JSONL round trip; replay renders the
+ * notice text as a system note; the provider seam sees a system message
+ * placed exactly where the switch happened.
+ */
+export interface ModeChangeEntry extends Message {
+  role: "system";
+  modeSwitch: ModeSwitch;
+}
+
+export function buildModeChangeEntry(sw: ModeSwitch, parentId: string | null): ModeChangeEntry {
+  return {
+    id: randomUUID(),
+    role: "system",
+    parts: [{ kind: "text", text: formatModeSwitchNotice(sw.from, sw.to) }],
+    parentId,
+    createdAt: Date.now(),
+    modeSwitch: { from: sw.from, to: sw.to },
+  };
+}
+
+/** The ModeSwitch a session entry carries, or null for anything else (plain
+ *  system notes, junk fields). Lets replay render a switch as a human line
+ *  ("mode → plan") instead of the raw <mode_notice> XML (R2 #20 LOW-3). */
+export function modeSwitchOf(entry: unknown): ModeSwitch | null {
+  if (!entry || typeof entry !== "object") return null;
+  const e = entry as { role?: unknown; modeSwitch?: unknown };
+  if (e.role !== "system") return null;
+  const sw = e.modeSwitch as { from?: unknown; to?: unknown } | undefined;
+  if (!sw || typeof sw !== "object") return null;
+  return isMode(sw.from) && isMode(sw.to) ? { from: sw.from, to: sw.to } : null;
+}
+
+/** Mode a resumed session should restore to: the LAST mode-change entry on
+ *  the active path wins; null when the session never switched. */
+export function modeFromEntries(entries: readonly unknown[]): AgentMode | null {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const sw = modeSwitchOf(entries[i]);
+    if (sw) return sw.to;
+  }
+  return null;
+}
+
+// ---------- ModeManager (session-scoped mode + per-mode model slots) ----------
+
+interface Slots {
+  plan: ModeModelSelection;
+  act: ModeModelSelection;
+}
+
+/**
+ * Holds the current mode plus one provider/model slot per mode.
+ *
+ * Model resolution precedence per field (highest wins), tested:
+ *   1. runtime writes via setModel() to that mode's slot (latest wins —
+ *      upstream: the settings UI writes the current mode's field,
+ *      updateApiConfiguration.ts:108-117)
+ *   2. `.rovecode/modes.json` per-mode entry (seeds the slot — upstream reads
+ *      planMode… / actMode… fields per mode, cline-session-factory.ts:552-558)
+ *   3. constructor fallback (session default provider/model)
+ *
+ * With planActSeparateModels=false (the default, state-keys.ts:272),
+ * setModel() mirrors the write into BOTH slots (updateApiConfiguration.ts:
+ * 119-131); config seeds still resolve per mode, matching upstream's
+ * read-side behavior which never consults the flag.
+ */
+export class ModeManager {
+  private currentMode: AgentMode;
+  private readonly slots: Slots;
+  private readonly fallback: ModeModelSelection;
+  private readonly separateModels: boolean;
+  private readonly tracker = createModeSwitchNoticeTracker();
+
+  constructor(cfg: ModesConfig = {}, fallback: ModeModelSelection = {}) {
+    this.currentMode = cfg.defaultMode ?? DEFAULT_MODE;
+    this.separateModels = cfg.planActSeparateModels ?? false;
+    this.fallback = { provider: fallback.provider, model: fallback.model };
+    this.slots = {
+      plan: { provider: cfg.plan?.provider, model: cfg.plan?.model },
+      act: { provider: cfg.act?.provider, model: cfg.act?.model },
+    };
+  }
+
+  get mode(): AgentMode {
+    return this.currentMode;
+  }
+
+  get separate(): boolean {
+    return this.separateModels;
+  }
+
+  /** Switch modes. Already in `to` → null, nothing recorded
+   *  (sdk-mode-coordinator.ts:131-135). Otherwise records the pending notice
+   *  (round trips cancel, format.ts:64-73) and returns the switch. */
+  toggle(to: AgentMode): ModeSwitch | null {
+    if (to === this.currentMode) return null;
+    const sw: ModeSwitch = { from: this.currentMode, to };
+    this.currentMode = to;
+    this.tracker.record(sw.from, sw.to);
+    return sw;
+  }
+
+  /** Restore a mode on session resume WITHOUT recording a notice: a pending
+   *  notice must not leak across sessions (sdk-mode-coordinator.ts:79-81,
+   *  101-112 scope notices to the session they were recorded for). */
+  restore(mode: AgentMode): void {
+    this.currentMode = mode;
+    this.tracker.consume();
+  }
+
+  /** Pending user-initiated switch for the NEXT outbound turn, cleared on
+   *  read (format.ts:74-78). Null after a cancelled round trip. */
+  consumeSwitchNotice(): ModeSwitch | null {
+    return this.tracker.consume();
+  }
+
+  /** Provider+model the given (default: current) mode runs with. */
+  modelFor(mode: AgentMode = this.currentMode): { provider: string; model: string } {
+    const slot = this.slots[mode];
+    return {
+      provider: slot.provider ?? this.fallback.provider ?? "",
+      model: slot.model ?? this.fallback.model ?? "",
+    };
+  }
+
+  /** Write the current mode's slot; with separate models OFF the write is
+   *  mirrored into the other mode's slot (updateApiConfiguration.ts:119-131).
+   *  Only fields present in `sel` are written. */
+  setModel(sel: ModeModelSelection): void {
+    const targets: AgentMode[] = this.separateModels
+      ? [this.currentMode]
+      : ["plan", "act"];
+    for (const m of targets) {
+      if (sel.provider !== undefined) this.slots[m].provider = sel.provider;
+      if (sel.model !== undefined) this.slots[m].model = sel.model;
+    }
+  }
+}

package/src/core/orchestrator.ts

@@ -0,0 +1,207 @@
+/** Subagent orchestration (ADR-009): child sessions, depth caps, spawn policy,
+ *  git-worktree isolation with delta patch merge-back (omp structured-subagent + worktree pattern). */
+
+import { randomUUID } from "node:crypto";
+import { cpSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentDefinition, AgentVars, SpawnRequest, SpawnResult, RunConfig, StreamFn, PermissionRule } from "../core/types.ts";
+import { ToolRegistry, type ExtensionHooks } from "../core/tools.ts";
+import { ToolGuard } from "../core/guardrails.ts";
+import { SessionStore } from "../core/session.ts";
+import { agentLoop, SteeringQueue } from "../core/loop.ts";
+
+export const DEFAULT_MAX_DEPTH = 3;
+
+export interface SpawnContext {
+  depth: number;          // 0 = root
+  maxDepth: number;
+  parentSessionId: string;
+}
+
+/** Preflight (omp structured-subagent.ts:220-237): depth, spawn policy, recursion block. */
+export function preflightSpawn(def: AgentDefinition, ctx: SpawnContext): { ok: boolean; reason?: string } {
+  const policy = def.spawns ?? "subtasks";
+  if (policy === "none") return { ok: false, reason: `agent '${def.name}' spawn policy is 'none'` };
+  if (ctx.depth >= ctx.maxDepth) return { ok: false, reason: `depth cap ${ctx.maxDepth} reached (current ${ctx.depth})` };
+  return { ok: true };
+}
+
+export interface IsolationWorkspace {
+  dir: string;
+  kind: "worktree" | "copy" | "none";
+  /** produce a git-compatible patch of changes vs baseline */
+  diff(): Promise<string>;
+  cleanup(): Promise<void>;
+}
+
+function git(args: string[], cwd: string, stdin?: string): { code: number; out: string } {
+  const p = Bun.spawnSync(["git", ...args], { cwd, stdin: stdin === undefined ? "ignore" : new Blob([stdin]), stdout: "pipe", stderr: "pipe" });
+  return { code: p.exitCode ?? -1, out: p.stdout.toString() };
+}
+
+/** COW-ish isolation: prefer `git worktree`, fall back to plain copy (omp pi-iso ladder).
+ *  Windows-safe: git for worktree/diff, node fs.cpSync/rmSync for copy/cleanup (no POSIX cp/rm/diff). */
+export async function createIsolation(rootDir: string, opts: { prefer: "worktree" | "copy" | "none" }): Promise<IsolationWorkspace> {
+  if (opts.prefer === "none") {
+    return { dir: rootDir, kind: "none", diff: async () => "", cleanup: async () => {} };
+  }
+  const id = randomUUID().slice(0, 8);
+  if (opts.prefer === "worktree") {
+    const dir = join(rootDir, ".rovecode", "worktrees", id);
+    // --detach (fix-wave L3): `-b rovecode/task/<id>` left one branch per isolated task behind in
+    // the root repo after `worktree remove`; a detached checkout at HEAD leaves only the
+    // worktree, which cleanup removes
+    if (git(["worktree", "add", "--detach", dir], rootDir).code === 0) {
+      return {
+        dir, kind: "worktree",
+        // intent-to-add first: `git diff HEAD` never shows UNTRACKED files, so a child's
+        // new files would silently miss the merge-back (port #26 isolation fix)
+        diff: async () => { git(["add", "-A", "-N"], dir); return git(["diff", "HEAD"], dir).out; },
+        cleanup: async () => { git(["worktree", "remove", "--force", dir], rootDir); },
+      };
+    }
+  }
+  // copy fallback: work/ is the live copy the child mutates; baseline/ is the pristine snapshot
+  // (node fs.cpSync/fs.rmSync — POSIX `cp -r`/`rm -rf` don't exist on Windows)
+  const dir = mkdtempSync(join(tmpdir(), "rovecode-iso-"));
+  try {
+    mkdirSync(join(dir, "baseline"));
+    cpSync(rootDir, join(dir, "baseline"), { recursive: true });
+    cpSync(rootDir, join(dir, "work"), { recursive: true });
+  } catch {
+    rmSync(dir, { recursive: true, force: true });
+    return { dir: rootDir, kind: "none", diff: async () => "", cleanup: async () => {} };
+  }
+  return {
+    dir: join(dir, "work"), kind: "copy",
+    // git diff --no-index (POSIX `diff -ru` doesn't exist on Windows and isn't a git patch);
+    // strip the baseline//work/ path roots so the patch applies at repo-relative paths.
+    // The header names EITHER root on either side (modify: a/baseline b/work; create:
+    // a/work b/work; delete: a/baseline b/baseline) — strip both, or `git apply` rejects
+    // creations with "inconsistent new filename" (port #26 isolation fix).
+    diff: async () => {
+      const d = git(["diff", "--no-index", "baseline", "work"], dir);
+      return d.code <= 1 ? d.out.replace(/^([-+]{3} [ab]\/)(baseline|work)\//gm, "$1").replace(/^(diff --git a\/)(?:baseline|work)\/(\S+ b\/)(?:baseline|work)\/(\S+)/gm, "$1$2$3") : "";
+    },
+    cleanup: async () => { rmSync(dir, { recursive: true, force: true }); },
+  };
+}
+
+/** Per-child context handed to registryFactory (port #26): a child's registry can
+ *  bind nested tools (the `task` tool) to THIS child's depth, its own steering
+ *  queue (nested completion notes land in the child's next turn, not the root's)
+ *  and its run signal. `taskId` is set by TaskManager when the child IS a
+ *  background task (enables slot lending); plain runChild callers leave it unset. */
+export interface ChildContext {
+  depth: number;
+  steering: SteeringQueue;
+  signal?: AbortSignal;
+  taskId?: string;
+}
+
+export interface ChildRunnerDeps {
+  defs: Map<string, AgentDefinition>;
+  stream: StreamFn;
+  registryFactory: (def: AgentDefinition, cwd: string, child?: ChildContext) => ToolRegistry;
+  rootDir: string;
+  sessionsDir: string;
+  baseConfig: RunConfig;
+  /** port #29: the parent runtime's hook set — a child runs under the same hooks (pre_tool vetoes,
+   *  post_tool, pre_run/post_run/on_event via the observer), so delegation cannot dodge a hook */
+  hooks?: ExtensionHooks;
+}
+
+/** Runs a child agent in its own session (+ optional isolation), returns summary + patch.
+ *  `depth` = this child's depth (root spawn = 0); grandchildren receive depth + 1 via agentLoop.
+ *  `signal` (port #26): aborting it cancels the child's run — agentLoop's own controller
+ *  follows deps.signal (port #21), so the in-flight fetch and tool subprocesses die.
+ *  ok = the child's run ended "done"; error/budget/stopped runs return ok:false with
+ *  the run_end summary (a background job needs a truthful failed status). An isolated
+ *  child's patch is merged back ONLY when ok — a cancelled or errored child's
+ *  half-done edits never land in the parent tree (the patch is still returned). */
+export async function runChild(deps: ChildRunnerDeps, req: SpawnRequest, depth = 0, signal?: AbortSignal): Promise<SpawnResult> {
+  const fail = (summary: string): SpawnResult => ({ agent: req.agent, ok: false, summary, usage: { input: 0, output: 0 } });
+  const def = deps.defs.get(req.agent);
+  if (!def) return fail(`unknown agent '${req.agent}'`);
+  const gate = preflightSpawn(def, { depth, maxDepth: DEFAULT_MAX_DEPTH, parentSessionId: "" });
+  if (!gate.ok) return fail(gate.reason ?? "spawn refused");
+
+  const iso = req.isolated ? await createIsolation(deps.rootDir, { prefer: "worktree" }) : await createIsolation(deps.rootDir, { prefer: "none" });
+  try {
+    const store = new SessionStore(deps.sessionsDir, randomUUID());
+    const steering = new SteeringQueue();
+    const registry = deps.registryFactory(def, iso.dir, { depth, steering, signal });
+    const cfg: RunConfig = {
+      ...deps.baseConfig,
+      // children get their own permission set derived from parent policy (opencode task.ts:160)
+      permissionRules: deriveChildRules(deps.baseConfig.permissionRules, iso.dir, iso.kind !== "none"),
+    };
+    let end: { status: string; summary: string } | undefined;
+    for await (const ev of agentLoop(def, req.goal, req.vars ?? {}, cfg, {
+      // port #4: children get their own loop guard — subagents loop too
+      stream: deps.stream, registry, store, guard: new ToolGuard(),
+      // tools resolve relative paths / run shells in the ISOLATION dir, not the process cwd
+      cwd: iso.dir,
+      signal,
+      hooks: deps.hooks, // port #29: the parent's hooks govern the child too
+    }, steering, depth + 1)) {
+      if (ev.type === "run_end") end = { status: ev.status, summary: ev.summary };
+    }
+    let input = 0, output = 0;
+    for (const m of store.messages()) {
+      if (m.usage) { input += m.usage.input; output += m.usage.output; }
+    }
+    const patch = iso.kind === "none" ? undefined : await iso.diff();
+    const ok = end?.status === "done";
+    const text = lastText(store);
+    let summary = ok
+      ? (text || "(no output)")
+      : `${end?.summary ?? "child run ended without run_end"}${text ? `\nlast output: ${text}` : ""}`;
+    if (ok && patch && !applyPatch(patch, deps.rootDir)) summary += `\npatch-apply-failed`;
+    return { agent: req.agent, ok, summary: summary.slice(0, 4_000), usage: { input, output }, patch };
+  } finally {
+    await iso.cleanup();
+  }
+}
+
+function lastText(store: SessionStore): string {
+  const last = [...store.messages()].reverse().find((m) => m.role === "assistant");
+  return last ? last.parts.filter((p) => p.kind === "text").map((p) => (p as { text: string }).text).join("") : "";
+}
+
+/** Best-effort merge-back into the parent tree (omp worktree → git apply). */
+function applyPatch(patch: string, parentDir: string): boolean {
+  if (!patch.trim()) return true; // nothing changed
+  // -c core.autocrlf=false: apply the patch byte-exact — Git for Windows' system-level autocrlf=true
+  // would rewrite every patched file to CRLF, even in a non-repo parent dir (measured on the copy rung)
+  return git(["-c", "core.autocrlf=false", "apply", "--whitespace=nowarn", "-"], parentDir, patch).code === 0;
+}
+
+/** Children never exceed parent grants:
+ *  - "prompt" rules become "deny": children are non-interactive, nobody can answer a prompt
+ *  - isolated children: path-glob allow resources are re-rooted under the isolation dir
+ *  - non-isolated children keep allow breadth unchanged (resources are action-shaped globs like
+ *    "src/**" or "rm *"; prefixing them with an absolute path would break shell-command matching)
+ *  - deny-rest DEFAULT, placed FIRST: evaluatePermissions is LAST-match-wins
+ *    (tools.ts), so the catch-all must sit at the lowest priority for the
+ *    parent-derived rules after it to override — an unlisted action falls
+ *    through to it and is denied. Appending it LAST was bug FW2-P: the
+ *    catch-all matched everything as the final word and overrode every
+ *    parent allow, denying ALL child tool calls even under an allow-all parent.
+ */
+export function deriveChildRules(rules: PermissionRule[], isoDir?: string, isolated = false): PermissionRule[] {
+  const out: PermissionRule[] = [{ action: "*", resource: "*", effect: "deny" }];
+  for (const r of rules) {
+    if (r.effect === "prompt") out.push({ ...r, effect: "deny" });
+    else if (isolated && isoDir && r.effect === "allow" && isPathResource(r)) out.push({ ...r, resource: join(isoDir, r.resource) });
+    else out.push({ ...r });
+  }
+  return out;
+}
+
+/** Path-shaped resources ("src/**", "**\/*.ts"); "rm *" (space-separated) is a command resource. */
+function isPathResource(r: PermissionRule): boolean {
+  if (r.resource === "*" || r.resource.includes(" ")) return false;
+  return r.action.startsWith("file.") || r.resource.includes("/");
+}