@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/core/subagents/dispatcher.js

@@ -1,31 +1,36 @@
 /**
- * Subagent dispatcher (Sprint a5.4 — M1 gap remediation D).
+ * Subagent dispatcher (β2 S1 + S4 —).
  *
  * The dispatcher is the runtime side of the @pugi/sdk subagent contracts.
  * Given a SubagentTask, it:
  *
- *   1. Resolves the role to a Cyber-Zoo persona via the local registry
- *      (apps/pugi-cli/src/core/agents/registry.ts, which itself sources
- *      @pugi/personas).
- *   2. Classifies isolation per the M1 matrix (see isolationForRole).
- *   3. Builds the dispatch-time permission overrides (Vera as reviewer
- *      or verifier loses every edit/write/bash class — see
- *      permissionOverridesForRole).
- *   4. Emits subagent.spawned into the session events log.
- *   5. Runs the dispatch (M1: stub returning shipped immediately so the
- *      contract surface is exercisable; M2+ swaps the body for
- *      worktree-isolated execution backed by runEngineLoop).
- *   6. Emits subagent.completed | blocked | failed into the session
- *      events log.
- *   7. Returns the typed SubagentResult.
+ *  1. Resolves the role to a Cyber-Zoo persona via the local registry
+ *     (apps/pugi-cli/src/core/agents/registry.ts, which itself sources
+ *     @pugi/personas).
+ *  2. Classifies isolation per the matrix (see isolationForRole).
+ *  3. Builds the dispatch-time permission overrides (Vera as reviewer
+ *     or verifier loses every edit/write/bash class — see
+ *     permissionOverridesForRole).
+ *  4. Emits subagent.spawned into the session events log.
+ *  5. Drives the dispatch via one of two backends:
+ *     - REAL (β2 S1): when ctx carries an EngineLoopClient, the child
+ *       runs a genuine `runEngineLoop` against Anvil with a per-child
+ *       tools schema gated by the isolation-matrix capability map
+ *       (β2 S4). See `dispatcher-real.ts::runRealDispatch`.
+ *     - STUB (M1 legacy): when no engine client is supplied, the
+ *       dispatcher returns a `shipped` result with zero metrics so
+ *       the legacy `inMemoryDispatcherContext` test path stays green.
+ *       This is the back-compat door for the M1 spec coverage.
+ *  6. Emits subagent.completed | blocked | failed into the session
+ *     events log (real backend emits richer details; stub emits the
+ *     M1-compatible shape).
+ *  7. Returns the typed SubagentResult.
  *
- * Why a stub at M1: the contract surface itself, the event emission, the
- * isolation classification, and the permission overrides are real
- * load-bearing pieces — the cabinet UI, audit replay, and triple-review
- * gating all read these events. The model-driven loop that actually
- * spawns a separate Anvil session is alpha-5.7 work (REPL-by-default).
- * The stub returns a shipped result with the correct persona slug + role
- * pair so downstream consumers can wire against the real shape.
+ * Why we kept the stub path: the existing M1 spec coverage exercises
+ * the dispatcher's contract surface (role-to-persona, isolation tier,
+ * permission overrides, event ordering) without any HTTP transport.
+ * β2 must not regress that surface — every existing assertion still
+ * holds for in-memory contexts. The real backend is a strict superset.
  *
  * The dispatcher is the only place that knows the isolation matrix and
  * the permission overrides. Both surfaces are exported so engine adapter
@@ -36,10 +41,10 @@ import { randomUUID } from 'node:crypto';
 import { subagentTaskSchema } from '@pugi/sdk';
 import { getPersonaForRole } from '../agents/registry.js';
 /* ------------------------------------------------------------------ */
-/* Isolation matrix                                                   */
+/* Isolation matrix                                                  */
 /* ------------------------------------------------------------------ */
 /**
- * M1 isolation matrix (ADR-0056 Sprint a5.4 acceptance #2).
+ * M1 isolation matrix .
  *
  * The function is pure (same role in, same isolation out) and exported
  * separately so consumers (tests, REPL UI) can introspect without
@@ -62,11 +67,11 @@ export function isolationForRole(role) {
     }
 }
 /* ------------------------------------------------------------------ */
-/* Permission overrides                                               */
+/* Permission overrides                                              */
 /* ------------------------------------------------------------------ */
 /**
  * Per-role permission overrides applied at dispatch time. The dominant
- * case is Vera's dual-role rule (ADR-0056 Sprint a5.4 acceptance #4):
+ * case is Vera's dual-role rule :
  * when dispatched as verifier OR reviewer, Vera gets edit: deny (which
  * we generalize to deny edit + write + bash, the three classes that can
  * mutate the workspace) so a review pass cannot accidentally patch what
@@ -81,7 +86,7 @@ export function isolationForRole(role) {
  * Write-capable roles (coder, release, devops, design_qa) get no
  * override; they inherit the workspace permission settings as-is.
  *
- * orchestrator also gets no override; Mira runs inside the parent
+ * orchestrator also gets no override; Pugi runs inside the parent
  * context, so the parent's permission settings already govern her.
  */
 export function permissionOverridesForRole(role) {
@@ -104,17 +109,17 @@ const DENY_ALL_WRITES_VERA = Object.freeze([
     {
         toolClass: 'edit',
         allowedPaths: Object.freeze([]),
-        reason: 'Vera dispatched as verifier/reviewer (ADR-0056 section a5.4 acceptance #4)',
+        reason: 'Vera dispatched as verifier/reviewer ',
     },
     {
         toolClass: 'write',
         allowedPaths: Object.freeze([]),
-        reason: 'Vera dispatched as verifier/reviewer (ADR-0056 section a5.4 acceptance #4)',
+        reason: 'Vera dispatched as verifier/reviewer ',
     },
     {
         toolClass: 'bash',
         allowedPaths: Object.freeze([]),
-        reason: 'Vera dispatched as verifier/reviewer (ADR-0056 section a5.4 acceptance #4)',
+        reason: 'Vera dispatched as verifier/reviewer ',
     },
 ]);
 const DENY_ALL_WRITES_READONLY = Object.freeze([
@@ -135,18 +140,23 @@ const DENY_ALL_WRITES_READONLY = Object.freeze([
     },
 ]);
 /* ------------------------------------------------------------------ */
-/* Default budgets                                                    */
+/* Default budgets                                                   */
 /* ------------------------------------------------------------------ */
+// CEO escalation 2026-06-05: 120K coder budget exhausted mid-React-
+// build (120214 > 120000). Match the engine-level `code` task bump
+// (apps/pugi-cli/src/core/engine/budgets.ts:149 — 400K). Subagent
+// dispatches inherit the upstream caller's headroom, so this needs
+// to track the engine envelope.
 const DEFAULT_BUDGETS = Object.freeze({
-    orchestrator: { tokens: 200_000, dollars: 5, wallClockMs: 600_000 },
-    architect: { tokens: 80_000, dollars: 2, wallClockMs: 300_000 },
-    coder: { tokens: 120_000, dollars: 3, wallClockMs: 600_000 },
-    verifier: { tokens: 60_000, dollars: 2, wallClockMs: 300_000 },
-    reviewer: { tokens: 80_000, dollars: 2, wallClockMs: 300_000 },
-    researcher: { tokens: 60_000, dollars: 1.5, wallClockMs: 300_000 },
-    release: { tokens: 40_000, dollars: 1, wallClockMs: 180_000 },
-    devops: { tokens: 60_000, dollars: 2, wallClockMs: 300_000 },
-    design_qa: { tokens: 60_000, dollars: 1.5, wallClockMs: 300_000 },
+    orchestrator: { tokens: 400_000, dollars: 8, wallClockMs: 900_000 },
+    architect: { tokens: 200_000, dollars: 4, wallClockMs: 600_000 },
+    coder: { tokens: 400_000, dollars: 8, wallClockMs: 900_000 },
+    verifier: { tokens: 150_000, dollars: 3, wallClockMs: 600_000 },
+    reviewer: { tokens: 200_000, dollars: 4, wallClockMs: 600_000 },
+    researcher: { tokens: 150_000, dollars: 3, wallClockMs: 600_000 },
+    release: { tokens: 80_000, dollars: 2, wallClockMs: 300_000 },
+    devops: { tokens: 150_000, dollars: 3, wallClockMs: 600_000 },
+    design_qa: { tokens: 150_000, dollars: 3, wallClockMs: 600_000 },
 });
 /**
  * Resolve the effective budget for a dispatch by merging task overrides
@@ -164,19 +174,51 @@ export function budgetForRole(role, override) {
     };
 }
 /* ------------------------------------------------------------------ */
-/* Dispatch                                                           */
+/* Real-backend lazy import (memoized)                               */
 /* ------------------------------------------------------------------ */
 /**
- * Spawn a subagent. M1 implementation is a stub that synchronously
- * returns a shipped result so the contract surface is exercised by
- * tests and the cabinet UI. M2+ replaces the body with an Anvil-side
- * dispatch over a per-task worktree (ADR-0057, deferred).
+ * β2a r1 (Backend Architect P1): cached lazy-import of
+ * the real dispatch backend. Hoisting the dynamic import to
+ * module scope (instead of running it on every dispatch call) means
+ * the first agent spawn does not pay 50-200ms cold-start latency.
  *
- * The function still emits real subagent.spawned and subagent.completed
- * events; downstream consumers (audit replay, cabinet activity feed,
- * eval harness) cannot tell the stub apart from a real dispatch on the
- * event surface alone, which is the property we want for forward-
- * compatibility testing.
+ * The cache is a Promise so concurrent first-callers share one
+ * import; ESM's own module cache also dedups but the Promise wrapper
+ * lets `prewarmRealDispatch` kick off the import without awaiting.
+ */
+let realDispatchPromise = null;
+function ensureRealDispatch() {
+    if (!realDispatchPromise) {
+        realDispatchPromise = import('./dispatcher-real.js');
+    }
+    return realDispatchPromise;
+}
+/**
+ * β2a r1: pre-warm the real dispatcher's module graph. Called by the
+ * engine adapter (`NativePugiEngineAdapter`) at construction time
+ * when an engine client is wired, so the first `dispatch()` call
+ * with `ctx.engineClient` set returns instantly. Safe to call
+ * multiple times — subsequent calls hit the cached promise.
+ */
+export function prewarmRealDispatch() {
+    return ensureRealDispatch();
+}
+/**
+ * Spawn a subagent. Two backends:
+ *
+ *  - REAL (β2 S1): when `ctx.engineClient` is set, the dispatcher
+ *    spawns a genuine child engine loop. See `dispatcher-real.ts`.
+ *    The child's tool surface is filtered by the isolation matrix
+ *    (β2 S4) so a `researcher` role cannot see `write`/`edit`/`bash`
+ *    in its tools schema and the executor refuses if the model
+ *    fabricates a call.
+ *
+ *  - STUB (M1 legacy): when no engine client is supplied, the
+ *    dispatcher returns a `shipped` result with zero metrics. This
+ *    is the back-compat door for the M1 spec coverage and for
+ *    in-memory consumers that only want to assert the dispatcher's
+ *    CONTRACT surface (role-to-persona, isolation tier, permission
+ *    overrides, event ordering) without standing up Anvil.
  *
  * The function rejects with ZodError when the task fails schema
  * validation. Throwing rather than returning a failed result is the
@@ -186,6 +228,58 @@ export function budgetForRole(role, override) {
  */
 export async function dispatch(task, ctx) {
     const validated = subagentTaskSchema.parse(task);
+    if (ctx.engineClient) {
+        // β2a r1 (Backend Architect P1): the lazy import
+        // chain (worktree + engine SDK graph) cost 50-200ms on the FIRST
+        // dispatch call. `ensureRealDispatch` memoizes the promise so the
+        // import happens at most once per process; subsequent dispatches
+        // hit the cached promise instantly. Production callers should
+        // prewarm via `prewarmRealDispatch()` at engine adapter init so
+        // the operator never pays cold-start on the first agent call.
+        const { runRealDispatch } = await ensureRealDispatch();
+        const outcome = await runRealDispatch(validated, {
+            sessionId: ctx.sessionId,
+            workspaceRoot: ctx.workspaceRoot,
+            appendEvent: ctx.appendEvent,
+            ...(ctx.now ? { now: ctx.now } : {}),
+            engineClient: ctx.engineClient,
+            ...(ctx.commandKind ? { commandKind: ctx.commandKind } : {}),
+            ...(ctx.useWorktreeIsolation !== undefined
+                ? { useWorktreeIsolation: ctx.useWorktreeIsolation }
+                : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+        return outcome.result;
+    }
+    return runStubDispatch(validated, ctx);
+}
+/**
+ * Real-backend variant that also surfaces the optional worktree
+ * handle. Callers that need to promote/drop the scratch worktree
+ * (e.g. the REPL `/agent` surface, or the Agent tool dispatcher) use
+ * this entry point.
+ */
+export async function dispatchWithOutcome(task, ctx) {
+    const validated = subagentTaskSchema.parse(task);
+    if (ctx.engineClient) {
+        const { runRealDispatch } = await ensureRealDispatch();
+        return runRealDispatch(validated, {
+            sessionId: ctx.sessionId,
+            workspaceRoot: ctx.workspaceRoot,
+            appendEvent: ctx.appendEvent,
+            ...(ctx.now ? { now: ctx.now } : {}),
+            engineClient: ctx.engineClient,
+            ...(ctx.commandKind ? { commandKind: ctx.commandKind } : {}),
+            ...(ctx.useWorktreeIsolation !== undefined
+                ? { useWorktreeIsolation: ctx.useWorktreeIsolation }
+                : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+    }
+    const result = await runStubDispatch(validated, ctx);
+    return { result };
+}
+async function runStubDispatch(validated, ctx) {
     const persona = getPersonaForRole(validated.role);
     const isolation = isolationForRole(validated.role);
     void budgetForRole(validated.role, validated.budget);
@@ -233,13 +327,13 @@ export async function dispatch(task, ctx) {
     return result;
 }
 function stubSummaryFor(role, personaName) {
-    return `${personaName} (${role}) dispatched: stub returning shipped (M1 contract surface only; real dispatch in alpha-5.7)`;
+    return `${personaName} (${role}) dispatched: in-memory stub backend (no engine client supplied; production callers should pass DispatcherContext.engineClient)`;
 }
 function defaultNow() {
     return new Date().toISOString();
 }
 /* ------------------------------------------------------------------ */
-/* Convenience helpers                                                */
+/* Convenience helpers                                               */
 /* ------------------------------------------------------------------ */
 /**
  * Build a dispatch context tied to an in-memory event sink. Useful for

package/dist/core/subagents/index.js

@@ -6,7 +6,7 @@
  * engine adapter code, the REPL, and tests can pull in everything they
  * need with one import statement:
  *
- *   import { dispatch, isolationForRole, ... } from '../core/subagents/index.js';
+ *  import { dispatch, isolationForRole, ... } from '../core/subagents/index.js';
  *
  * The submodule index does not re-export persona types — those live in
  * @pugi/personas and are pulled in by core/agents/registry.ts. Mixing
@@ -14,13 +14,26 @@
  * would invite the kind of accidental drift the persona-registry
  * extraction was designed to prevent.
  */
-export { budgetForRole, dispatch, inMemoryDispatcherContext, isolationForRole, permissionOverridesForRole, } from './dispatcher.js';
+export { budgetForRole, dispatch, dispatchWithOutcome, inMemoryDispatcherContext, isolationForRole, permissionOverridesForRole, } from './dispatcher.js';
+/**
+ * β2 S4: per-role capability matrix. Surfaced via the barrel so
+ * engine adapter code, the Agent tool, and tests can introspect a
+ * role's allowed tool set without importing the matrix module
+ * directly.
+ */
+export { allowedToolsForRole, capabilitiesForRole, roleHasToolAccess, ROLE_CAPABILITIES, } from './isolation-matrix.js';
+/**
+ * β2 S1: real-backend entry point. Exposed for callers that want to
+ * drive the dispatch with the worktree handle in scope (e.g. the
+ * Agent tool, the REPL `/agent` surface). Most callers should prefer
+ * the `dispatch()` / `dispatchWithOutcome()` helpers above which
+ * route to this module when ctx.engineClient is set.
+ */
+export { runRealDispatch } from './dispatcher-real.js';
 /**
  * Spawn a subagent from inside the engine adapter loop. Re-exported via
  * the barrel so engine code does not have to import the dispatcher
- * module directly. The actual task_dispatch tool that the model uses
- * to invoke a subagent lands in alpha-5.7 (REPL); for now the helper
- * exists so adapter code has a single seam to wire against.
+ * module directly.
  */
-export { spawnSubagent } from './spawn.js';
+export { spawnSubagent, spawnSubagentWithOutcome } from './spawn.js';
 //# sourceMappingURL=index.js.map

package/dist/core/subagents/isolation-matrix.js

@@ -0,0 +1,213 @@
+const CAP_READ_ONLY = new Set([
+    'read',
+    'task',
+    'skill',
+]);
+const CAP_VERIFIER = new Set([
+    'read',
+    'task',
+    'skill',
+    // β2a r1 (Codex P1): verifier previously got the FULL
+    // `bash` capability. The class-aware bash tool defaults to
+    // permission mode `auto`, which permits `write_workspace` class
+    // commands (e.g. `echo x > src/file.ts`, `sed -i`, `rm`). That
+    // silently bypassed the no-edit/no-write contract — a verifier
+    // could mutate the workspace it was meant to read.
+    //
+    // The fix splits bash into two capabilities:
+    //  - `bash`         → full bash (writers only)
+    //  - `bash_read_only` → bash gate that forces read-only classifier
+    //                       mode regardless of operator settings
+    // verifier needs the read-only flavor so test commands (pnpm test,
+    // jest --listFiles, typecheck) still work but a fabricated
+    // `echo x > file.ts` is refused at the executor layer.
+    'bash_read_only',
+]);
+const CAP_WRITER = new Set([
+    'read',
+    'write',
+    'bash',
+    'task',
+    'skill',
+    'ask_user',
+]);
+const CAP_FULL = new Set([
+    'read',
+    'write',
+    'bash',
+    'task',
+    'skill',
+    'ask_user',
+    'web_fetch',
+    'agent',
+]);
+/**
+ * Per-role capability map. Add a new role only when the matching
+ * isolation tier classification in dispatcher.ts agrees with the
+ * capability set here — drift would let a `coder` role get write
+ * privileges with `shared_fs_readonly` isolation, which would mean
+ * the dispatcher emits readonly-isolation events while the child
+ * actually writes. Always touch both files together.
+ */
+export const ROLE_CAPABILITIES = new Map([
+    [
+        'orchestrator',
+        {
+            role: 'orchestrator',
+            capabilities: CAP_FULL,
+            rationale: 'orchestrator (Pugi/Pugi) runs in parent context with full toolset; '
+                + 'parent permissions still gate any actual mutation',
+        },
+    ],
+    [
+        'architect',
+        {
+            role: 'architect',
+            capabilities: CAP_READ_ONLY,
+            rationale: 'architect role is read-only by design (analysis + planning, no mutations)',
+        },
+    ],
+    [
+        'coder',
+        {
+            role: 'coder',
+            capabilities: CAP_WRITER,
+            rationale: 'coder role mutates the workspace via write + edit + bash',
+        },
+    ],
+    [
+        'verifier',
+        {
+            role: 'verifier',
+            capabilities: CAP_VERIFIER,
+            rationale: 'verifier role reads workspace + executes verification commands (tests, typecheck) '
+                + 'but never edits the code it is verifying',
+        },
+    ],
+    [
+        'reviewer',
+        {
+            role: 'reviewer',
+            capabilities: CAP_READ_ONLY,
+            rationale: 'reviewer role is read-only by policy (no edits to code under review); '
+                + 'shell is denied because reviewer should not be re-running tests',
+        },
+    ],
+    [
+        'researcher',
+        {
+            role: 'researcher',
+            capabilities: CAP_READ_ONLY,
+            rationale: 'researcher role is read-only (corpus search + summarization)',
+        },
+    ],
+    [
+        'release',
+        {
+            role: 'release',
+            capabilities: CAP_WRITER,
+            rationale: 'release role needs write + bash for changelog edits + version bumps',
+        },
+    ],
+    [
+        'devops',
+        {
+            role: 'devops',
+            capabilities: CAP_WRITER,
+            rationale: 'devops role needs write + bash for infra config + deploy scripts',
+        },
+    ],
+    [
+        'design_qa',
+        {
+            role: 'design_qa',
+            capabilities: CAP_WRITER,
+            rationale: 'design_qa role needs write + bash for UI tweaks + screenshot scripts',
+        },
+    ],
+]);
+/**
+ * Resolve the capability set for a role. Throws when the role is not
+ * registered — the closed SubagentRole union prevents that at compile
+ * time for typed callers, but the runtime guard catches dynamic dispatch
+ * paths (e.g. a tag parsed off Pugi's reply text).
+ */
+export function capabilitiesForRole(role) {
+    const entry = ROLE_CAPABILITIES.get(role);
+    if (!entry) {
+        throw new Error(`capabilitiesForRole: unknown role '${role}'`);
+    }
+    return entry;
+}
+/**
+ * Map capability classes → concrete tool names (matches tool-bridge.ts
+ * WIRED_TOOLS). This is the bridge between the policy layer (this file)
+ * and the schema-shaping layer (tool-bridge buildToolsSchema). Keep in
+ * lockstep with WIRED_TOOLS — a new tool added to the bridge should
+ * be classified here so subagents see (or do not see) it consistently.
+ */
+const CAPABILITY_TO_TOOLS = {
+    read: ['read', 'grep', 'glob'],
+    write: ['write', 'edit'],
+    bash: ['bash'],
+    // β2a r1 : `bash_read_only` maps to the same `bash`
+    // tool name so the model sees only one tool surface. The
+    // dispatcher-real executor wraps the verifier's bash calls with a
+    // forced read-only classifier mode (see `gatedExecutor` in
+    // dispatcher-real.ts) so a `write_workspace`-class command is
+    // rejected before the tool runs even though the capability set
+    // appears to advertise `bash`.
+    bash_read_only: ['bash'],
+    task: ['task_create', 'task_get', 'task_list', 'task_update'],
+    skill: ['skill', 'skills_list'],
+    ask_user: ['ask_user_question'],
+    web_fetch: ['web_fetch'],
+    // Agent tool is the subagent spawn primitive itself (S3). Only the
+    // orchestrator role gets it — child agents cannot recursively spawn
+    // grand-children, which keeps the spawn depth bounded at 1 and the
+    // budget rollup tractable.
+    agent: ['agent'],
+};
+/**
+ * Return the set of tool names a role is allowed to call. Used by the
+ * per-child tool-bridge to shape the OpenAI tools schema AND by the
+ * executor refusal gate.
+ *
+ * The function is pure — same role in, same set out — so the schema
+ * builder can call it from inside `buildToolsSchema`.
+ */
+export function allowedToolsForRole(role) {
+    const caps = capabilitiesForRole(role);
+    const out = new Set();
+    for (const cap of caps.capabilities) {
+        for (const name of CAPABILITY_TO_TOOLS[cap]) {
+            out.add(name);
+        }
+    }
+    return out;
+}
+/**
+ * Predicate: is a tool name reachable by a role under the capability
+ * matrix? Used by the executor's pre-dispatch refusal gate.
+ *
+ * Returns true for orchestrator/full-capability roles and for every
+ * specific tool the role's capability set unlocks; false otherwise.
+ */
+export function roleHasToolAccess(role, toolName) {
+    return allowedToolsForRole(role).has(toolName);
+}
+/**
+ * β2a r1 (Codex P1): predicate identifying roles whose
+ * bash access is restricted to read-only classifier mode. Used by
+ * dispatcher-real.ts's gatedExecutor to force-flag bash dispatches as
+ * read-only regardless of the workspace's permission settings.
+ *
+ * A role qualifies when it holds `bash_read_only` but NOT the
+ * full-power `bash` capability — orchestrators (which inherit both
+ * via CAP_FULL) keep full bash access through the regular path.
+ */
+export function bashIsReadOnlyForRole(role) {
+    const caps = capabilitiesForRole(role).capabilities;
+    return caps.has('bash_read_only') && !caps.has('bash');
+}
+//# sourceMappingURL=isolation-matrix.js.map

package/dist/core/subagents/spawn.js

@@ -1,5 +1,5 @@
 import { recordSubagentBlocked, recordSubagentCompleted, recordSubagentFailed, recordSubagentSpawned, recordSubagentToolCall, } from '../session.js';
-import { dispatch } from './dispatcher.js';
+import { dispatch, dispatchWithOutcome, } from './dispatcher.js';
 /**
  * Spawn a subagent under an existing PugiSession. Events are routed
  * through the session module's recorder functions; if the session is
@@ -7,13 +7,28 @@ import { dispatch } from './dispatcher.js';
  * dispatch still runs — the contract is "dispatch always works, audit
  * is best-effort".
  */
-export async function spawnSubagent(task, session) {
-    const ctx = {
+export async function spawnSubagent(task, session, options = {}) {
+    return dispatch(task, buildContext(session, options));
+}
+/**
+ * β2 S1: spawnSubagent variant that surfaces the optional worktree
+ * handle so the caller can wire promote/drop follow-ups.
+ */
+export async function spawnSubagentWithOutcome(task, session, options = {}) {
+    return dispatchWithOutcome(task, buildContext(session, options));
+}
+function buildContext(session, options) {
+    return {
         sessionId: session.id,
         workspaceRoot: session.root,
         appendEvent: (event) => routeEvent(event, session),
+        ...(options.engineClient ? { engineClient: options.engineClient } : {}),
+        ...(options.commandKind ? { commandKind: options.commandKind } : {}),
+        ...(options.useWorktreeIsolation !== undefined
+            ? { useWorktreeIsolation: options.useWorktreeIsolation }
+            : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
     };
-    return dispatch(task, ctx);
 }
 function routeEvent(event, session) {
     if (!isRecord(event))