rovecode 0.3.2

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,245 @@
+/** 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, ModelRef, SpawnRequest, SpawnResult, RunConfig, StreamFn, PermissionRule, ToolSchema } from "../core/types.ts";
+import { applyModeRules, planModePromptSection } from "./modes.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;
+  /** the tool names of the registry that STARTED this child (a nested start: the spawning child's own, restricted set) —
+   *  the registry factory clamps the child's table to it, so a definition's allow-list is transitive down the chain
+   *  (a restricted agent cannot widen via `main`). Absent for a root start: the root registry's names apply. */
+  parentTools?: ReadonlySet<string>;
+  /** This child's OWN working tree — `iso.dir`, which for an isolated child is its worktree and for a
+   *  plain one is the root. It is here so that what this child starts in turn works where THIS child
+   *  works: an external lane builds its worktree from `dir` and merges its patch back into `dir`, so a
+   *  nested lane's result travels up the same chain of patches as everything else the child did. Left
+   *  unset it defaults to the manager's rootDir, which for an isolated child is the USER'S live tree —
+   *  the lane would then write straight past the isolation its parent was given. */
+  dir?: string;
+}
+
+export interface ChildRunnerDeps {
+  defs: Map<string, AgentDefinition>;
+  stream: StreamFn;
+  registryFactory: (def: AgentDefinition, cwd: string, child?: ChildContext) => ToolRegistry;
+  /** the non-native tool-calling prompt block for `model` over `tools` ("" for a model that calls tools natively) —
+   *  rendered HERE from the child's own restricted registry, never from the root's list (cli/runtime.ts buildDef leaves
+   *  a child definition bare for this reason) */
+  toolPrompt?: (model: ModelRef, tools: ToolSchema[]) => string;
+  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, dir: iso.dir, ...(req.parentTools ? { parentTools: req.parentTools } : {}) });
+    // a plan-mode definition (AgentDefinition.mode, core/agents.ts) runs under the plan rule set — appended to the PARENT's
+    // rules before the child derivation, so last-match-wins denies write/shell/spawn/memory even under a yolo parent (the
+    // TUI's meaning of plan mode) — and gets the plan prompt section; "act"/absent changes nothing
+    const parentRules = applyModeRules(def.mode ?? "act", deps.baseConfig.permissionRules);
+    const cfg: RunConfig = {
+      ...deps.baseConfig,
+      // children get their own permission set derived from parent policy (opencode task.ts:160)
+      permissionRules: deriveChildRules(parentRules, iso.dir, iso.kind !== "none"),
+    };
+    // the child's request carries ITS registry's schemas. Every root surface passes `tools`; runChild never did, so a
+    // native-tool-calling model got a request with no tools and could call nothing, whatever the registry held — the
+    // scripted streams in the tests ignore `tools`, which is why nobody saw it (found porting #62, 2026-09-07)
+    const schemas = registry.list().map((t) => t.schema);
+    // the non-native tool-calling block is rendered from the SAME restricted set (a root-registry block would advertise
+    // tools the child cannot call)
+    const toolBlock = def.model && deps.toolPrompt ? deps.toolPrompt(def.model, schemas) : "";
+    const sections = [def.mode === "plan" ? planModePromptSection() : "", toolBlock ? `# Tool calling\n${toolBlock}` : ""].filter((s) => s !== "");
+    const runDef: AgentDefinition = sections.length > 0
+      ? { ...def, systemPrompt: (v: AgentVars) => [typeof def.systemPrompt === "function" ? def.systemPrompt(v) : def.systemPrompt, ...sections].join("\n\n") }
+      : def;
+    let end: { status: string; summary: string } | undefined;
+    for await (const ev of agentLoop(runDef, 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: schemas,
+      // 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}` : ""}`;
+    // Whether the merge-back LANDED is a fact, and it now travels as one. `git apply` refusing leaves
+    // ok:true, so the marker below was the only trace — and it is appended to a summary that is then
+    // sliced to 4000 chars, which means a child verbose enough to describe its own diff lost the marker
+    // and read as applied. The reader downstream is the collision summary, and the patch git refuses is
+    // usually the SECOND one to touch a file: exactly the task that must not be named as its writer.
+    // Absent when there was no merge-back to attempt, so every existing path keeps its meaning.
+    const applied = ok && patch ? applyPatch(patch, deps.rootDir) : undefined;
+    if (applied === false) summary += `\npatch-apply-failed`;   // kept: human-readable text, no longer load-bearing
+    return { agent: req.agent, ok, summary: summary.slice(0, 4_000), usage: { input, output }, patch, ...(applied !== undefined ? { applied } : {}) };
+  } 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). */
+export 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("/");
+}

package/src/core/proc-group.ts

@@ -0,0 +1,48 @@
+/** POSIX process GROUPS: the two calls that make a spawned child killable as a tree on a platform that
+ *  has no Job Object. Ported from the aion harness (port #67) together with the external lanes, which
+ *  are the first thing here that spawns a process it does not itself wait on.
+ *
+ *  Why a module of its own. Windows already has one answer (core/win-job.ts: membership is recorded at
+ *  CreateProcess time and TerminateJobObject reaches every descendant). POSIX has a different one, and
+ *  it is only two lines — but both spawn sites need the SAME two lines or the platforms drift: a child
+ *  spawned `detached` gets its own session and process group whose pgid equals its pid, and `kill(-pid)`
+ *  then addresses shell, grandchildren and backgrounded `&` members alike. Measured in the harness this
+ *  came from: without it, `sleep` inside a compound command, inside `bash -c` and behind `&` survived
+ *  the kill 3/3 and held stdout open, so the runner hung waiting on a pipe nobody would ever close.
+ *
+ *  NOTE: rovecode's own executor (core/executor.ts) does NOT use these yet — its POSIX abort still hands
+ *  the signal to Bun.spawn, which reaches the direct child only. That is the same leak, one seam over.
+ *  It is deliberately not changed in the commit that lands the lanes: it is a behaviour change to the
+ *  path every bash tool call takes, and it deserves its own commit and its own measurement. */
+
+/** The extra spawn options that put a POSIX child in its own process group (`detached` → setsid, pgid =
+ *  pid); EMPTY on win32, so Windows spawn options stay byte-identical to what they were. */
+export function groupSpawnOptions(platform: NodeJS.Platform): { detached: true } | Record<never, never> {
+  return platform === "win32" ? {} : { detached: true };
+}
+
+/** `kill(pid, signal)` — injectable so tests never signal a real process. */
+export type KillFn = (pid: number, signal: NodeJS.Signals) => void;
+
+const defaultKill: KillFn = (pid, signal) => { process.kill(pid, signal); };
+
+/** Signal the child's whole process group (pgid = pid under a detached spawn): `kill(-pid, signal)`.
+ *  Best effort — false when the group is already gone (ESRCH) or the pid is not usable; the caller then
+ *  falls back to signalling the launcher itself. Never called on win32: there are no process groups
+ *  there, and the Job Object is the tree. */
+export function killGroup(pid: number, signal: NodeJS.Signals, kill: KillFn = defaultKill): boolean {
+  if (!(pid > 0)) return false;
+  try { kill(-pid, signal); return true; } catch { return false; }
+}
+
+/** The parts of a Bun subprocess the lane runner touches. Structural on purpose: the production spawn is
+ *  `Bun.spawn`, a test's is an object literal, and neither needs to name Bun's type. */
+export interface SpawnedProc {
+  readonly pid: number;
+  readonly stdout: ReadableStream<Uint8Array>;
+  readonly stderr: ReadableStream<Uint8Array>;
+  readonly exited: Promise<number>;
+  /** null while the child is still running — the lane runner reads it to tell "exited 0" from "not done" */
+  readonly exitCode: number | null;
+  kill(signal?: NodeJS.Signals | number): void;
+}