@henryqw/pi-subagent 25.0.2 → 25.1.1

package/CONTEXT.md

@@ -41,7 +41,8 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 
 ### Direct evidence
 
-- Direct mode admits Roles with known read-only base tools. Extensions and MCP servers are trusted without a read-only guarantee; direct changesets and Roles with write-capable base tools require isolated mode.
+- Direct mode admits Roles with known read-only base tools. `codemode` is read-only: its scripts call only the Role's active tools plus trusted extension and MCP tools. Extensions and MCP servers are trusted without a read-only guarantee; direct changesets and Roles with write-capable base tools require isolated mode.
+- Checkout admission in Main serializes write-capable Pi tool calls per checkout by their model-issued root call: a `codemode` script's nested writes share the script's ownership, independent writers wait, and reads never wait.
 - Each direct worker has a recorded Herdr tab and Pi session identity. The first handle returns before completion; subsequent tab identities remain recoverable on the session branch.
 - An exact settled worker with a bounded final Pi answer produces a follow-up to Main. Blocked, unknown, idle-stalled, truncated, or ambiguous outcomes retain actionable recovery identity. Session replacement never delivers to the wrong Main session.
 
@@ -56,13 +57,14 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 - Promotion requires exact unchanged clean Main and a passing combined generation. Durable promotion evidence precedes selected-worker termination and cleanup; recovery never rolls back a proven promotion.
 - Rejected workers and superseded generations stay retained until Main explicitly releases their exact clean, proved-owned resources. At most two unreleased integration checkouts coexist.
 - Failures, ambiguity, interruption, review findings, conflicts, drift, unproved termination, or cleanup failure enter `needs_attention` and preserve evidence.
-- `subagent_status` is read-only. `subagent_resume` accepts only strict `retry`, `verify`, or `finalize` continuations. `subagent_abort` terminates only exact owned workers.
+- `subagent_status` is read-only, callable from `codemode` scripts, and returns the bounded public projection as structured content, never raw run state. `delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only. `subagent_resume` accepts only strict `retry`, `verify`, or `finalize` continuations. `subagent_abort` terminates only exact owned workers.
 - The extension never pushes, opens a pull request, publishes, deploys, stashes, resets, force-cleans, or deletes unproved recoverable work.
 
 ### Resource and launch policy
 
 - Ambient child extensions and Skills stay disabled. Only Role/caller resources plus required internal adapters load.
-- Every Role requires `tools`, `extensions`, and `skills` arrays. `extensions` may name Pi built-in extensions as `builtin:<name>`. `mcps` names servers from the global `~/.pi/agent/mcp.json`; their tools load in the child with direct exposure. Omitted or empty `mcps` denies MCP access. Direct `pi-mcp-adapter` loading is rejected because it bypasses the allowlist.
+- Every Role requires `tools`, `extensions`, and `skills` arrays. `extensions` may name Pi built-in extensions as `builtin:<name>`. A Role activates `codemode` only by naming it in `tools` with `builtin:codemode` loaded; MCP configuration never activates it, and Pi's codemode settings apply unchanged. `mcps` names servers from the global `~/.pi/agent/mcp.json`; their tools keep their configured exposure in a codemode Role and are forced to direct exposure otherwise. Omitted or empty `mcps` denies MCP access. Direct `pi-mcp-adapter` loading is rejected because it bypasses the allowlist.
+- The Role tool policy declares the Role's `tools` and the extension tools Pi would declare on registration; extension tools with `codemode` or `deferred` exposure stay callable from scripts without being declared.
 - Selected extensions are trusted executable bundles, not a sandbox. All tools and lifecycle behavior they register load together.
 - Role Skill names resolve through Main's effective Pi registry. Missing Roles, Skills, tools, MCP servers, routes, models, or thinking levels fail before the first productive turn.
 - Route precedence is call model class, then Role default, then registered Model Task assignment/default. A direct model replaces only the route model and must support its thinking level.

package/README.md

@@ -30,7 +30,7 @@ Commands are for you; tools and the packaged skill are for Main. You do not need
 | `/subagent` | command | Browse work, launch isolated status inspection in a separate Herdr tab with the `fast` model, or send/edit pending instructions. Requires interactive TUI or RPC; inspection also requires a Herdr-managed pane and a read-only `scout` Role. |
 | `/subagent recover` | command | Classify orphaned isolated work in the current canonical repository and send Main one follow-up with request IDs, blockers, and reported next actions. No UI or Herdr pane required. |
 | `delegate_task` | tool | Start read-only direct work or a durable isolated checked graph. |
-| `subagent_status` | tool | Read durable isolated state and the exact allowed continuation without replaying work. |
+| `subagent_status` | tool | Read durable isolated state and the exact allowed continuation without replaying work. Declares an output schema, so `codemode` scripts receive the same bounded public projection as structured content. |
 | `subagent_resume` | tool | Perform the reported `retry`, `verify`, or `finalize` continuation; does not replace staging or integration. |
 | `subagent_stage` | tool | Stage or resolve an exact candidate, or reject/revise it; rejection of a staged candidate freezes that generation. |
 | `subagent_integrate` | tool | Advance staged dependents, refresh after clean Main drift, validate, record one correction, promote, reconcile interrupted promotion, clean up proven promotion, or explicitly release rejected/superseded resources. |
@@ -39,6 +39,8 @@ Commands are for you; tools and the packaged skill are for Main. You do not need
 
 ![Main, its coordinator extension, and a Herdr subagent through checked work, worker failure, and coordinator interruption](./docs/worker-lifecycle.svg)
 
+`delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only: Pi's `codemode` scripts cannot call them, because delegation and guarded state transitions need Main's visible reasoning. `subagent_status` stays callable from scripts. In Main, one model-issued call at a time may write to a checkout through Pi tools; a `codemode` script owns the checkout from its first nested write until the script ends, so its own nested calls pass while an independent writer is blocked with a reason and retries after it settles. Reads never wait.
+
 The coordinator is extension code running in Main's Pi process, not another agent. It persists the request, launches the Herdr subagent, checks its committed work, and reports saved results; Main chooses what to stage and promote. If a worker fails, the coordinator reports attention after the wave settles, not necessarily immediately while siblings work. If Main's Pi process stops, no follow-up is guaranteed: restart and run `/subagent recover` in the canonical repository to classify orphaned interruptions and send Main one recovery report. Main then uses `subagent_status` for exact evidence and deliberate next actions. A stale `running` state does not prove a worker is still active; interrupted or ambiguous actions are never replayed automatically.
 
 In the TUI, the compact widget uses one row per visible agent/task: `D` or `I` marks direct or isolated work, and `[S]` or `[I3]` identifies the Role initial (plus the isolated model class: `1` fast, `2` balanced, `3` frontier, `*` fav). Direct rows show the launched model, thinking level, elapsed time, and measured session tokens (`— tok` until usage is available). Isolated rows show the recorded task state and any retained workspace; an aborted request with visible tasks has its own `request aborted` row and does not change their recorded statuses. A committed worker without a checked candidate can still show attention rather than readiness. Status glyphs use the active TUI theme, while the text still names the status without color. Herdr does not currently provide reliable live model, thinking, or token readings for those rows. Attention appears before ordinary work, with a `… N more` summary when direct rows overflow. A ready isolated candidate is **not promoted** to Main. Choose **Refresh** in `/subagent` to reload both the menu and isolated widget from saved state; it does not recover or change a request. Use `/subagent` or `subagent_status` for exact identities, failures, and recovery.
@@ -75,7 +77,7 @@ Parallel: { mode: "direct", tasks: [{ role, name, task, ... }] }
 Chain:    { mode: "direct", chain: [{ role, name, task, ... }] }
 ```
 
-Only Roles whose declared base tools are known read-only may run direct. Configured extensions and MCP servers are trusted and may provide additional tools; use isolated mode when a task needs write-capable base tools or a checked changeset. Parallel tasks run independently; chains replace each literal `{previous}` with the preceding successful answer and stop on failure.
+Only Roles whose declared base tools are known read-only may run direct. `codemode` counts as read-only because its scripts can only call the tools the Role already activates plus trusted extension and MCP tools. Configured extensions and MCP servers are trusted and may provide additional tools; use isolated mode when a task needs write-capable base tools or a checked changeset. Parallel tasks run independently; chains replace each literal `{previous}` with the preceding successful answer and stop on failure.
 
 The tool returns a task ID and first Herdr tab after launch, not the answer. The extension observes each worker and sends one result to Main when the workflow finishes. If Main is busy, Pi queues it after the current turn; if idle, it starts a turn. A blocked, stalled, unknown, or truncated result is not reported as success. Session switch or shutdown stops observation and preserves tab identities for recovery. Open `/subagent` on the session branch to inspect exact tabs, agents, and Pi session files, including tabs launched after the first. A recorded tab may no longer be running; locally observed work is labelled separately.
 
@@ -175,7 +177,7 @@ Role Markdown lives in `~/.pi/agent/config/pi-subagent/` and requires frontmatte
 | --- | --- |
 | `name`, `description` | Required non-empty text without terminal control characters |
 | `modelClass` | Optional `fast`, `balanced`, `frontier`, or `fav` default |
-| `tools` | Required array of base tool names; `[]` selects none |
+| `tools` | Required array of base tool names; `[]` selects none. Name `codemode` here to activate it (see below) |
 | `extensions` | Required array of trusted absolute paths, supported package sources, or Pi built-in extensions such as `builtin:codemode` |
 | `skills` | Required array of effective Pi Skill names |
 | `mcps` | Optional exact server names from `~/.pi/agent/mcp.json` in Pi's native `mcpServers` format; omitted or `[]` denies MCP access |
@@ -183,7 +185,13 @@ Role Markdown lives in `~/.pi/agent/config/pi-subagent/` and requires frontmatte
 
 Roles describe responsibility and capabilities. They do not choose isolation; each request does. A same-named user Role overrides a built-in Role. The package ships `implementer`, `reviewer`, and `scout`.
 
-Children run with `--no-extensions`, so a Role must list the extension that registers its route model's provider, and only declared resources plus required internal policy adapters load. `builtin:<name>` entries load Pi built-in extensions (`builtin:codemode`, `builtin:tool-search`, `builtin:llama.cpp`) explicitly; `builtin:mcp` is rejected because it would connect every configured server and bypass `mcps`. The servers named in `mcps` come from the global `~/.pi/agent/mcp.json` only; their tools load in the child with direct exposure and are declared to the model as `mcp__<server>__<tool>` once the server connects. Pi replaces `-` in server and tool names with `_` and appends a hash suffix when two tool names collide or a name exceeds 64 characters. Each selected entry is checked against Pi's documented `mcpServers` rules before launch, in Main and again in the child: a disabled, malformed, or unknown-transport entry, an invalid server name, two selected names that differ only in `-` and `_`, `auth.provider` over plain HTTP outside `localhost`, `127.0.0.1`, or `[::1]`, or a non-HTTPS `oauth.authServerMetadataUrl` outside those hosts fails the launch with the file path and field. The file is never modified; fix the entry or choose another server. Valid `auth`, `oauth`, and `description` fields are passed through so Pi's native provider auth and OAuth apply. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work starts. Main-only delegation and recovery tools plus `ask_question` are excluded from children.
+Children run with `--no-extensions`, so a Role must list the extension that registers its route model's provider, and only declared resources plus required internal policy adapters load. `builtin:<name>` entries load Pi built-in extensions (`builtin:codemode`, `builtin:tool-search`, `builtin:llama.cpp`) explicitly; `builtin:mcp` is rejected because it would connect every configured server and bypass `mcps`. Extension tools registered with `codemode` or `deferred` exposure stay callable from scripts but are declared to the model only when `tools` names them.
+
+Checkout admission keeps a script's writer ownership until the script and all its admitted nested writes finish, including writes still settling after cancellation. Independent writers stay blocked during that time; nested writes that have not passed admission before the script ends are rejected.
+
+To let a Role run `codemode` scripts, list `builtin:codemode` in `extensions` and `codemode` in `tools`; both are required, because the built-in registers the tool inactive and the Role tool policy activates it. `codemode` alone in `tools` fails the launch as an unavailable tool. Pi's `codemode.mode` and `codemode.inlineBudget` settings apply in the child unchanged, so the Role never forces codemode-only operation, and MCP configuration never activates `codemode` in a child. Scripts can call only the Role's active tools plus `codemode`/`deferred` extension and MCP tools; inactive base tools such as `bash` stay unreachable.
+
+The servers named in `mcps` come from the global `~/.pi/agent/mcp.json` only. In a Role that activates `codemode`, each selected server keeps its configured `exposure` and `toolExposure` (Pi's default `codemode` exposure makes tools callable from scripts without declaring them, `direct` declares them, `deferred` tools stay reachable from scripts, `hidden` tools stay unreachable), and an invalid exposure value fails the launch. In every other Role, selected servers are forced to `direct` exposure and `toolExposure` is ignored, because that child cannot reach undeclared tools. Declared tools appear to the model as `mcp__<server>__<tool>` once the server connects. Pi replaces `-` in server and tool names with `_` and appends a hash suffix when two tool names collide or a name exceeds 64 characters. Each selected entry is checked against Pi's documented `mcpServers` rules before launch, in Main and again in the child: a disabled, malformed, or unknown-transport entry, an invalid server name, two selected names that differ only in `-` and `_`, `auth.provider` over plain HTTP outside `localhost`, `127.0.0.1`, or `[::1]`, or a non-HTTPS `oauth.authServerMetadataUrl` outside those hosts fails the launch with the file path and field. The file is never modified; fix the entry or choose another server. Valid `auth`, `oauth`, and `description` fields are passed through so Pi's native provider auth and OAuth apply. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work starts. Main-only delegation and recovery tools plus `ask_question` are excluded from children.
 
 ## API
 

package/dist/direct-herdr.js

@@ -243,11 +243,6 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                             const waited = await herdr.exec(args, options(signal));
                             if (waited.code !== 0 || waited.killed) {
                                 if (!waited.killed && hasHerdrErrorCode(waited, "timeout")) {
-                                    if (current === "idle") {
-                                        const answer = await maybeAnswer();
-                                        if (answer !== undefined)
-                                            return answer;
-                                    }
                                     continue;
                                 }
                                 throw new Error(herdrCommandFailure(args, waited));

package/dist/ephemeral.js

@@ -429,9 +429,8 @@ async function runPi(prepared, input, budget, invocation) {
         let spawnError;
         let protocolError;
         let aborted = false;
-        let turnLimited = false;
+        let limit;
         let tokenBudget = "within";
-        const tokenLimited = () => tokenBudget === "limited";
         let startedTurns = 0;
         let lastEventAt = startedAt;
         let deadline = Math.min(startedAt + timeoutPolicy.idleMs, maxDeadline ?? startedAt + timeoutPolicy.idleMs);
@@ -514,15 +513,12 @@ async function runPi(prepared, input, budget, invocation) {
                     : `Subagent timed out after ${formatDuration(timeoutPolicy.idleMs)} without a recognized Pi event.`;
                 reject(new EphemeralSubagentError("timeout", message, new Error(message), accumulatedUsage()));
             }
-            else if (turnLimited) {
-                const summary = `Subagent reached its maximum turn limit of ${budget.maxTurns}.`;
+            else if (limit) {
+                const summary = limit === "turn_limit"
+                    ? `Subagent reached its maximum turn limit of ${budget.maxTurns}.`
+                    : `Subagent reached its maximum token limit of ${budget.maxTokens}.`;
                 const message = output ? capEphemeralSubagentOutput(`${summary}\n\nLast assistant output:\n${output}`) : summary;
-                reject(new EphemeralSubagentError("turn_limit", message, new Error(message), accumulatedUsage(), output));
-            }
-            else if (tokenLimited()) {
-                const summary = `Subagent reached its maximum token limit of ${budget.maxTokens}.`;
-                const message = output ? capEphemeralSubagentOutput(`${summary}\n\nLast assistant output:\n${output}`) : summary;
-                reject(new EphemeralSubagentError("token_limit", message, new Error(message), accumulatedUsage(), output));
+                reject(new EphemeralSubagentError(limit, message, new Error(message), accumulatedUsage(), output));
             }
             else if (protocolError) {
                 reject(new EphemeralSubagentError("protocol", protocolError.message, protocolError, accumulatedUsage()));
@@ -585,7 +581,7 @@ async function runPi(prepared, input, budget, invocation) {
             deadlineTimer.unref();
         };
         const observeEvent = () => {
-            if (callbackFailure || aborted || timedOutAfterMs !== undefined || turnLimited || tokenLimited() || childExited)
+            if (callbackFailure || aborted || timedOutAfterMs !== undefined || limit || childExited)
                 return;
             const now = Date.now();
             if (now >= deadline) {
@@ -609,17 +605,15 @@ async function runPi(prepared, input, budget, invocation) {
                 case "final_turn":
                     if (event === "turn_start") {
                         if (!callbackFailure && !aborted && timedOutAfterMs === undefined)
-                            tokenBudget = "limited";
+                            limit = "token_limit";
                         stop(true);
                         return true;
                     }
                     return false;
-                case "limited":
-                    return true;
             }
         };
         const processLine = (line) => {
-            if (turnLimited || tokenLimited() || !line.trim())
+            if (limit || !line.trim())
                 return;
             let event;
             try {
@@ -637,7 +631,7 @@ async function runPi(prepared, input, budget, invocation) {
             if (record.type === "turn_start") {
                 if (++startedTurns > budget.maxTurns) {
                     if (!callbackFailure && !aborted && timedOutAfterMs === undefined)
-                        turnLimited = true;
+                        limit = "turn_limit";
                     stop(true);
                     return;
                 }
@@ -775,7 +769,7 @@ async function runPi(prepared, input, budget, invocation) {
         };
         onStdoutData = (data) => {
             armPostExitIdleDeadline();
-            if (callbackFailure || protocolError || turnLimited || tokenLimited())
+            if (callbackFailure || protocolError || limit)
                 return;
             let offset = 0;
             while (offset < data.length) {
@@ -816,7 +810,7 @@ async function runPi(prepared, input, budget, invocation) {
                         invokeCallback("onActivity", input.onActivity, activity);
                     }
                 }
-                if (callbackFailure || turnLimited || tokenLimited())
+                if (callbackFailure || limit)
                     return;
                 lineParts = [];
                 lineBytes = 0;
@@ -856,13 +850,13 @@ async function runPi(prepared, input, budget, invocation) {
             killTimer.unref();
         }
         const abort = () => {
-            if (timedOutAfterMs !== undefined || turnLimited || tokenLimited() || childExited)
+            if (timedOutAfterMs !== undefined || limit || childExited)
                 return;
             aborted = true;
             stop();
         };
         function timeout(afterMs, reason) {
-            if (timedOutAfterMs !== undefined || turnLimited || tokenLimited() || childExited)
+            if (timedOutAfterMs !== undefined || limit || childExited)
                 return;
             if (reason === "maximum") {
                 if (!aborted) {

package/dist/git-process.js

@@ -1,17 +1,10 @@
-import { spawnBounded } from "@henryqw/pi-process";
+import { runProcess } from "./process.js";
 const GIT_TIMEOUT_MS = 30_000;
-const GIT_OUTPUT_LIMIT_BYTES = 1 * 1024 * 1024;
 const GIT_DIAGNOSTIC_LIMIT = 200;
 /** Run one ordinary Git command with bounded output; transport failures never throw. */
 export const runGit = async (args, cwd, signal) => {
     try {
-        const result = await spawnBounded("git", ["--no-pager", ...args], {
-            cwd,
-            signal,
-            timeoutMs: GIT_TIMEOUT_MS,
-            stdoutLimitBytes: GIT_OUTPUT_LIMIT_BYTES,
-            stderrLimitBytes: GIT_OUTPUT_LIMIT_BYTES,
-        });
+        const result = await runProcess("git", ["--no-pager", ...args], { cwd, signal, timeoutMs: GIT_TIMEOUT_MS });
         if (result.killed) {
             return {
                 code: -1,

package/dist/index.d.ts

@@ -7,9 +7,18 @@ export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectW
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";
 export declare const PI_SUBAGENT_PROCESS_LEASE = "PI_SUBAGENT_PROCESS_LEASE";
 export declare const ROLE_MCP_POLICY_FLAG = "pi-subagent-role-mcps";
+export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
 /** Read child MCP policy before Pi binds registered extension flag values. */
 export declare function roleMcpAllowlistFromArgv(args: readonly string[]): string[];
-export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+/** Parse the Role tool policy flag value: JSON tool names. */
+export declare function parseRoleToolPolicy(value: unknown): string[];
+/** Read child tool policy before Pi binds registered extension flag values. */
+export declare function roleToolPolicyFromArgv(args: readonly string[]): string[];
+/**
+ * Whether a tool policy activates `codemode` in the child, so scripts can reach tools with
+ * `codemode` or `deferred` exposure. Loading `builtin:codemode` alone registers the tool inactive.
+ */
+export declare function roleActivatesCodemode(tools: readonly string[]): boolean;
 export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "ask_question", "subagent_status", "subagent_resume", "subagent_stage", "subagent_abort"];
 export declare const DELEGATE_TASK: {
     readonly id: "pi-subagent/delegateTask";

package/dist/index.js

@@ -17,15 +17,46 @@ const ROLE_MCP_EXTENSION = fileURLToPath(new URL("../extensions/role-mcp.ts", im
 const ROLE_TOOLS_EXTENSION = fileURLToPath(new URL("../extensions/role-tools.ts", import.meta.url));
 export const PI_SUBAGENT_PROCESS_LEASE = "PI_SUBAGENT_PROCESS_LEASE";
 export const ROLE_MCP_POLICY_FLAG = "pi-subagent-role-mcps";
-/** Read child MCP policy before Pi binds registered extension flag values. */
-export function roleMcpAllowlistFromArgv(args) {
-    const flag = `--${ROLE_MCP_POLICY_FLAG}`;
+export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+const CODEMODE_TOOL = "codemode";
+/** The value after a flag that must appear exactly once in a child's argv. */
+function flagValueFromArgv(args, flag) {
     const indexes = args.flatMap((arg, index) => arg === flag ? [index] : []);
     if (indexes.length !== 1)
         throw new Error(`${flag} must appear exactly once.`);
-    return parseRoleMcpAllowlist(args[indexes[0] + 1]);
+    return args[indexes[0] + 1];
+}
+/** Read child MCP policy before Pi binds registered extension flag values. */
+export function roleMcpAllowlistFromArgv(args) {
+    return parseRoleMcpAllowlist(flagValueFromArgv(args, `--${ROLE_MCP_POLICY_FLAG}`));
+}
+/** Parse the Role tool policy flag value: JSON tool names. */
+export function parseRoleToolPolicy(value) {
+    if (typeof value !== "string")
+        throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+    }
+    if (!Array.isArray(parsed) || parsed.some((name) => typeof name !== "string" || !name.trim() || name.includes("\0"))) {
+        throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+    }
+    return [...new Set(parsed.map((name) => name.trim()))];
+}
+/** Read child tool policy before Pi binds registered extension flag values. */
+export function roleToolPolicyFromArgv(args) {
+    return parseRoleToolPolicy(flagValueFromArgv(args, `--${ROLE_TOOL_POLICY_FLAG}`));
+}
+/**
+ * Whether a tool policy activates `codemode` in the child, so scripts can reach tools with
+ * `codemode` or `deferred` exposure. Loading `builtin:codemode` alone registers the tool inactive.
+ */
+export function roleActivatesCodemode(tools) {
+    return tools.includes(CODEMODE_TOOL);
 }
-export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
 export const CHILD_EXCLUDED_TOOL_NAMES = [
     "delegate_task",
     "ask_question",
@@ -333,8 +364,9 @@ export function prepareRoleLaunch(pi, ctx, input) {
         : prepareResolvedRoleLaunch(pi, ctx, input);
     assertNoMissingRoleSkills(input.role, prepared);
     // Validate the mcp.json the child reads: its environment inherits Main's, with launch overrides on top.
-    if (input.role.mcps?.length)
-        loadRoleMcpConfig(prepared.env.PI_CODING_AGENT_DIR ?? getAgentDir(), input.role.mcps);
+    if (input.role.mcps?.length) {
+        loadRoleMcpConfig(prepared.env.PI_CODING_AGENT_DIR ?? getAgentDir(), input.role.mcps, { codemode: roleActivatesCodemode(prepared.tools) });
+    }
     return { ...prepared, role };
 }
 /** Resolve and prepare a configured Role with its package-owned resources. */
@@ -342,12 +374,11 @@ export async function resolveConfiguredRoleLaunch(pi, ctx, input) {
     const roleName = parseRoleName(input.role);
     if (input.modelClass === undefined)
         throw new Error("Configured Role launch requires an explicit modelClass.");
-    const matches = loadRoles().filter((role) => role.name === roleName);
-    if (matches.length !== 1)
+    const role = loadRoles().find((role) => role.name === roleName);
+    if (!role)
         throw new Error(`Required configured Role ${roleName} is missing or ambiguous.`);
-    const role = matches[0];
     if (role.mcps?.length)
-        loadRoleMcpConfig(getAgentDir(), role.mcps);
+        loadRoleMcpConfig(getAgentDir(), role.mcps, { codemode: roleActivatesCodemode(role.tools) });
     const resources = await resolveRolePackageResources(role, ctx);
     const effectiveRole = { ...role, extensions: resources.extensions };
     const namedSkills = resolveRoleSkills(pi, effectiveRole);

package/dist/launch-runtime.js

@@ -125,11 +125,7 @@ export class RoleLaunchRuntime {
     }
     async prepareLaunch(role, modelClass, context) {
         abortIfNeeded(context.signal);
-        const input = { role, modelClass, task: ISOLATED_MODEL_TASK };
-        const prepared = await resolveConfiguredRoleLaunch(this.options.pi, this.options.context(), input);
-        if (prepared.missingSkills.length) {
-            throw new Error(`Role ${role} requires missing Skills: ${prepared.missingSkills.join(", ")}.`);
-        }
+        const prepared = await resolveConfiguredRoleLaunch(this.options.pi, this.options.context(), { role, modelClass });
         return Object.freeze({
             launch: Object.freeze({
                 role: prepared.role,

package/dist/mcp-role.d.ts

@@ -2,7 +2,11 @@ import type { LoadedMcpConfig } from "@earendil-works/pi-coding-agent";
 export declare function parseRoleMcpAllowlist(value: unknown): string[];
 /**
  * Select the Role's allowlisted servers from the global `mcp.json` in Pi's native `mcpServers`
- * shape; the project `.pi/mcp.json` is ignored. A `--no-extensions` child has no codemode tool, so
- * every selected server is forced to direct exposure and codemode is never activated.
+ * shape; the project `.pi/mcp.json` is ignored. A child that activates `codemode` keeps each
+ * server's configured exposure, so scripts reach `codemode` and `deferred` tools. Any other child
+ * cannot reach undeclared tools, so every selected server is forced to direct exposure. Codemode is
+ * never activated by MCP configuration: the Role tool policy owns the active set.
  */
-export declare function loadRoleMcpConfig(agentDir: string, allowlist: readonly string[]): LoadedMcpConfig;
+export declare function loadRoleMcpConfig(agentDir: string, allowlist: readonly string[], options?: {
+    codemode: boolean;
+}): LoadedMcpConfig;

package/dist/mcp-role.js

@@ -31,6 +31,11 @@ const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
 const isHttpsOrLoopback = (url) => url !== undefined && (url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname)));
 /** Tool namespace `mcp__<server>` replaces `-` with `_`, so names differing only there collide. */
 const mcpNamespace = (name) => name.replace(/-/g, "_");
+// Pi's exposure names and the alias it still accepts (core/mcp-servers.ts); the native loader is bypassed, so resolve it here.
+const MCP_EXPOSURES = ["codemode", "deferred", "direct", "hidden"];
+const MCP_EXPOSURE_ALIASES = { "codemode-deferred": "codemode" };
+const resolveExposure = (value) => MCP_EXPOSURE_ALIASES[value] ?? value;
+const isExposure = (value) => typeof value === "string" && MCP_EXPOSURES.includes(resolveExposure(value));
 /** Documented `mcpServers` fields (Pi's docs/mcp.md) and their shapes, by transport; dotted keys are nested. */
 const COMMON_CHECKS = {
     enabled: [(value) => typeof value === "boolean", "a boolean"],
@@ -60,8 +65,12 @@ const HTTP_CHECKS = {
     "oauth.authServerMetadataUrl": [(value) => isHttpsOrLoopback(parseUrl(value)), "an https URL, or http on localhost, 127.0.0.1, or [::1]"],
     auth: [(value) => isRecord(value) && typeof value.provider === "string" && value.provider !== "", "an object with a non-empty \"provider\" string"],
 };
+const EXPOSURE_CHECKS = {
+    exposure: [isExposure, `one of ${MCP_EXPOSURES.map((exposure) => `"${exposure}"`).join(", ")}`],
+    toolExposure: [(value) => isRecord(value) && Object.values(value).every(isExposure), "an object mapping tool names to exposures"],
+};
 /** Validate one selected server against Pi's documented `mcpServers` rules; the native loader is bypassed by `loadConfig`. */
-function validateRoleMcpServer(path, name, value) {
+function validateRoleMcpServer(path, name, value, codemode) {
     const fail = (message) => { throw new Error(`${path}: MCP server "${name}" ${message}`); };
     if (!SERVER_NAME.test(name))
         fail("has an invalid name (use letters, digits, \"_\" and \"-\").");
@@ -73,7 +82,7 @@ function validateRoleMcpServer(path, name, value) {
     const http = typeof value.url === "string" && value.url.trim() !== "" && (value.type === undefined || value.type === "http" || value.type === "streamable-http");
     if (stdio === http)
         fail("needs either a \"command\" (stdio) or a \"url\" (http or streamable-http).");
-    for (const [field, [valid, shape]] of Object.entries({ ...COMMON_CHECKS, ...(stdio ? STDIO_CHECKS : HTTP_CHECKS) })) {
+    for (const [field, [valid, shape]] of Object.entries({ ...COMMON_CHECKS, ...(stdio ? STDIO_CHECKS : HTTP_CHECKS), ...(codemode ? EXPOSURE_CHECKS : {}) })) {
         const fieldValue = field.split(".").reduce((parent, key) => (isRecord(parent) ? parent[key] : undefined), value);
         if (fieldValue !== undefined && !valid(fieldValue, value))
             fail(`field "${field}" must be ${shape}.`);
@@ -82,15 +91,25 @@ function validateRoleMcpServer(path, name, value) {
     if (value.auth !== undefined && !isHttpsOrLoopback(parseUrl(value.url))) {
         fail("field \"auth\" requires \"url\" to use https, or http on localhost, 127.0.0.1, or [::1].");
     }
+    if (codemode) {
+        const { exposure, toolExposure } = value;
+        return {
+            ...value,
+            ...(typeof exposure === "string" ? { exposure: resolveExposure(exposure) } : {}),
+            ...(isRecord(toolExposure) ? { toolExposure: Object.fromEntries(Object.entries(toolExposure).map(([tool, entry]) => [tool, resolveExposure(entry)])) } : {}),
+        };
+    }
     const { toolExposure: _toolExposure, ...config } = value;
     return { ...config, exposure: "direct" };
 }
 /**
  * Select the Role's allowlisted servers from the global `mcp.json` in Pi's native `mcpServers`
- * shape; the project `.pi/mcp.json` is ignored. A `--no-extensions` child has no codemode tool, so
- * every selected server is forced to direct exposure and codemode is never activated.
+ * shape; the project `.pi/mcp.json` is ignored. A child that activates `codemode` keeps each
+ * server's configured exposure, so scripts reach `codemode` and `deferred` tools. Any other child
+ * cannot reach undeclared tools, so every selected server is forced to direct exposure. Codemode is
+ * never activated by MCP configuration: the Role tool policy owns the active set.
  */
-export function loadRoleMcpConfig(agentDir, allowlist) {
+export function loadRoleMcpConfig(agentDir, allowlist, options = { codemode: false }) {
     const path = join(agentDir, "mcp.json");
     let parsed = {};
     try {
@@ -114,7 +133,7 @@ export function loadRoleMcpConfig(agentDir, allowlist) {
         if (clash)
             throw new Error(`${path}: Role MCP server "${name}" conflicts with "${clash}": names that differ only in "-" and "_" share one tool namespace.`);
         namespaces.set(mcpNamespace(name), name);
-        return { name, config: validateRoleMcpServer(path, name, configured[name]), source: path, scope: "global" };
+        return { name, config: validateRoleMcpServer(path, name, configured[name], options.codemode), source: path, scope: "global" };
     });
     return { servers, autoEnableCodemode: false, errors: [] };
 }

package/dist/process.d.ts

@@ -1,6 +1,6 @@
 type ProcessOptions = {
     cwd: string;
-    signal: AbortSignal;
+    signal?: AbortSignal;
     timeoutMs?: number;
     stdin?: string;
 };

package/dist/runner.js

@@ -131,12 +131,12 @@ class FollowupControl {
         if (this.queue.length >= MAX_QUEUED_FOLLOWUPS)
             throw new Error(`A task may queue at most ${MAX_QUEUED_FOLLOWUPS} follow-ups.`);
         this.validateFollowup(instruction);
-        this.queue.push({ kind: "followup", instruction });
+        this.queue.push(instruction);
     }
     drainPending() {
         if (this.sealed)
             throw new Error("This task candidate is already sealed for integration.");
-        return this.queue.splice(0).map(({ instruction }) => instruction);
+        return this.queue.splice(0);
     }
     takeQueuedFollowup() {
         if (this.sealed)
@@ -578,7 +578,7 @@ export class IsolatedRunner {
     }
     drainFollowups(root, requestId, taskId) {
         const active = this.activeControl(realpathSync.native(root), requestId, taskId);
-        if (!active || !this.canFollowup(root, requestId, taskId)) {
+        if (!active || active.task.status !== "working" || active.control.isSealed) {
             throw new Error(`Task ${taskId} is not an active unsealed changeset.`);
         }
         return active.control.drainPending();
@@ -589,7 +589,7 @@ export class IsolatedRunner {
             throw new Error("Follow-up instruction must be non-empty exact text of at most 32000 characters.");
         }
         const active = this.activeControl(realpathSync.native(root), requestId, taskId);
-        if (!active || !this.canFollowup(realpathSync.native(root), requestId, taskId)) {
+        if (!active || active.task.status !== "working" || active.control.isSealed) {
             throw new Error(`Task ${taskId} is not an active unsealed changeset.`);
         }
         if (latestAttempt(active.task).prompts.length + active.control.pendingFollowups >= MAX_WORKER_PROMPTS) {
@@ -1093,7 +1093,8 @@ export class IsolatedRunner {
         return await this.withProductiveRun(root, async (lifecycle) => {
             const handle = await this.store.withLock(root, async () => await this.store.load(root, action.id), { productiveRunLease: lifecycle.lease });
             const state = handle.state;
-            const request = parseExecuteRequest(state.request);
+            // Loading state has already normalized optional request fields, including finalChecks.
+            const request = state.request;
             const generation = state.integration.generations.at(-1);
             if (action.action === "release") {
                 const scope = new ProductiveScope(outerSignal);
@@ -2300,7 +2301,7 @@ export class IsolatedRunner {
                     const queuedFollowup = control.takeQueuedFollowupOrSeal();
                     if (queuedFollowup) {
                         kind = "followup";
-                        instruction = queuedFollowup.instruction;
+                        instruction = queuedFollowup;
                         task.status = "working";
                         continue;
                     }
@@ -2336,7 +2337,7 @@ export class IsolatedRunner {
             const queuedFollowup = control.takeQueuedFollowup();
             if (queuedFollowup) {
                 kind = "followup";
-                instruction = queuedFollowup.instruction;
+                instruction = queuedFollowup;
                 task.status = "working";
                 continue;
             }

package/dist/schema.d.ts

@@ -2320,6 +2320,116 @@ declare const RunStateSchema: Type.TObject<{
     createdAt: Type.TInteger;
     updatedAt: Type.TInteger;
 }>;
+/**
+ * `subagent_status` structured output: the bounded public projection that Main reads, never raw
+ * run state. Objects stay open so bounded evidence fields pass; the identities and statuses that
+ * drive stage, integrate, resume, and release decisions are typed.
+ */
+export declare const StatusOutputSchema: Type.TObject<{
+    state: Type.TObject<{
+        version: Type.TLiteral<5>;
+        id: Type.TString;
+        status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"needs_attention">, Type.TLiteral<"completed">, Type.TLiteral<"final_failed">, Type.TLiteral<"superseded">, Type.TLiteral<"aborted">]>;
+        accepted: Type.TBoolean;
+        main: Type.TObject<{
+            branch: Type.TString;
+            head: Type.TString;
+            index: Type.TString;
+            tree: Type.TString;
+        }>;
+        tasks: Type.TArray<Type.TObject<{
+            taskId: Type.TString;
+            status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"allocating">, Type.TLiteral<"working">, Type.TLiteral<"ready_to_integrate">, Type.TLiteral<"integrating">, Type.TLiteral<"cleanup">, Type.TLiteral<"completed">, Type.TLiteral<"rejected">, Type.TLiteral<"needs_attention">, Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"completed">, Type.TLiteral<"needs_attention">]>;
+        }>>;
+        final: Type.TObject<{
+            status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"interrupted">, Type.TLiteral<"passed">, Type.TLiteral<"final_failed">, Type.TLiteral<"superseded">]>;
+        }>;
+        integration: Type.TObject<{
+            candidates: Type.TArray<Type.TObject<{
+                taskId: Type.TString;
+                attempt: Type.TInteger;
+                base: Type.TObject<{
+                    branch: Type.TString;
+                    head: Type.TString;
+                    index: Type.TString;
+                    tree: Type.TString;
+                }>;
+                tip: Type.TObject<{
+                    branch: Type.TString;
+                    head: Type.TString;
+                    index: Type.TString;
+                    tree: Type.TString;
+                }>;
+                checked: Type.TBoolean;
+                worker: Type.TUnion<[Type.TLiteral<"retained">, Type.TLiteral<"release_pending">, Type.TLiteral<"released">]>;
+                decision: Type.TOptional<Type.TLiteral<"rejected">>;
+            }>>;
+            generations: Type.TArray<Type.TObject<{
+                number: Type.TInteger;
+                status: Type.TUnion<[Type.TLiteral<"staging">, Type.TLiteral<"conflict">, Type.TLiteral<"validating">, Type.TLiteral<"validation_failed">, Type.TLiteral<"ready">, Type.TLiteral<"promoting">, Type.TLiteral<"promoted">, Type.TLiteral<"promotion_unknown">, Type.TLiteral<"promotion_failed">, Type.TLiteral<"superseded">]>;
+                integrationBase: Type.TObject<{
+                    branch: Type.TString;
+                    head: Type.TString;
+                    index: Type.TString;
+                    tree: Type.TString;
+                }>;
+                combinedTip: Type.TOptional<Type.TObject<{
+                    branch: Type.TString;
+                    head: Type.TString;
+                    index: Type.TString;
+                    tree: Type.TString;
+                }>>;
+                retainedWorktree: Type.TOptional<Type.TObject<{
+                    path: Type.TString;
+                    branch: Type.TString;
+                }>>;
+            }>>;
+        }>;
+        needsAttention: Type.TOptional<Type.TObject<{
+            scope: Type.TUnion<[Type.TLiteral<"task">, Type.TLiteral<"final">, Type.TLiteral<"request">]>;
+            taskId: Type.TOptional<Type.TString>;
+            failure: Type.TOptional<Type.TString>;
+        }>>;
+        createdAt: Type.TInteger;
+        updatedAt: Type.TInteger;
+    }>;
+    main: Type.TOptional<Type.TUnion<[Type.TObject<{
+        status: Type.TUnion<[Type.TLiteral<"current">, Type.TLiteral<"drifted">]>;
+        expected: Type.TObject<{
+            branch: Type.TString;
+            head: Type.TString;
+            index: Type.TString;
+            tree: Type.TString;
+        }>;
+        actual: Type.TObject<{
+            branch: Type.TString;
+            head: Type.TString;
+            index: Type.TString;
+            tree: Type.TString;
+        }>;
+    }>, Type.TObject<{
+        status: Type.TLiteral<"unavailable">;
+        expected: Type.TObject<{
+            branch: Type.TString;
+            head: Type.TString;
+            index: Type.TString;
+            tree: Type.TString;
+        }>;
+        failure: Type.TString;
+    }>]>>;
+    continuation: Type.TOptional<Type.TUnion<[Type.TObject<{
+        id: Type.TString;
+        action: Type.TLiteral<"retry">;
+        taskId: Type.TString;
+    }>, Type.TObject<{
+        id: Type.TString;
+        action: Type.TLiteral<"verify">;
+        taskId: Type.TString;
+    }>, Type.TObject<{
+        id: Type.TString;
+        action: Type.TLiteral<"finalize">;
+    }>]>>;
+}>;
 export declare function taskDependencies(task: TaskRequest): string[];
 export declare function validateGraph(tasks: readonly TaskRequest[]): void;
 export declare function parseExecuteRequest(value: unknown): ExecuteRequest;

package/dist/schema.js

@@ -427,6 +427,55 @@ const RunStateSchema = Type.Object({
     createdAt: TimestampSchema,
     updatedAt: TimestampSchema,
 }, { additionalProperties: false });
+/**
+ * `subagent_status` structured output: the bounded public projection that Main reads, never raw
+ * run state. Objects stay open so bounded evidence fields pass; the identities and statuses that
+ * drive stage, integrate, resume, and release decisions are typed.
+ */
+export const StatusOutputSchema = Type.Object({
+    state: Type.Object({
+        version: RunStateSchema.properties.version,
+        id: IdSchema,
+        status: RunStateSchema.properties.status,
+        accepted: Type.Boolean(),
+        main: WorkspaceSchema,
+        tasks: Type.Array(Type.Object({
+            taskId: IdSchema,
+            status: Type.Union([...ChangesetTaskStateSchema.properties.status.anyOf, ...TextTaskStateSchema.properties.status.anyOf]),
+        })),
+        final: Type.Object({ status: FinalGateSchema.properties.status }),
+        integration: Type.Object({
+            candidates: Type.Array(Type.Object({
+                taskId: IdSchema,
+                attempt: IntegrationCandidateSchema.properties.attempt,
+                base: WorkspaceSchema,
+                tip: WorkspaceSchema,
+                checked: Type.Boolean(),
+                worker: IntegrationCandidateSchema.properties.worker,
+                decision: Type.Optional(IntegrationCandidateSchema.properties.decision),
+            })),
+            generations: Type.Array(Type.Object({
+                number: IntegrationGenerationSchema.properties.number,
+                status: IntegrationGenerationSchema.properties.status,
+                integrationBase: WorkspaceSchema,
+                combinedTip: Type.Optional(WorkspaceSchema),
+                retainedWorktree: Type.Optional(Type.Object({ path: Type.String(), branch: Type.String() })),
+            })),
+        }),
+        needsAttention: Type.Optional(Type.Object({
+            scope: Type.Union([Type.Literal("task"), Type.Literal("final"), Type.Literal("request")]),
+            taskId: Type.Optional(IdSchema),
+            failure: Type.Optional(Type.String()),
+        })),
+        createdAt: TimestampSchema,
+        updatedAt: TimestampSchema,
+    }),
+    main: Type.Optional(Type.Union([
+        Type.Object({ status: Type.Union([Type.Literal("current"), Type.Literal("drifted")]), expected: WorkspaceSchema, actual: WorkspaceSchema }),
+        Type.Object({ status: Type.Literal("unavailable"), expected: WorkspaceSchema, failure: Type.String() }),
+    ])),
+    continuation: Type.Optional(ResumeRequestSchema),
+});
 function normalizeCheck(check, field) {
     return {
         command: normalizeText(check.command, `${field}.command`),

package/dist/store.js

@@ -61,7 +61,7 @@ async function canonicalPlannedPath(path) {
     }
 }
 function serialize(state, maxBytes = STATE_MAX_BYTES) {
-    const validated = parseRunState(structuredClone(state));
+    const validated = parseRunState(state);
     const contents = `${JSON.stringify(validated, null, 2)}\n`;
     if (Buffer.byteLength(contents, "utf8") > maxBytes) {
         throw new Error(`pi-subagent state exceeds ${maxBytes} bytes.`);

package/docs/orchestration.md

@@ -139,7 +139,7 @@ Every child launch:
 5. excludes Main-only delegation/recovery tools and `ask_question`; and
 6. prepends the delegated-subagent identity contract.
 
-An empty `tools` list adds no base tools, though selected extension tools can still activate. Children run with `--no-extensions`, so a Role must list the extension that registers its route model's provider; `builtin:<name>` entries load Pi built-in extensions. `mcps` names servers from the global `~/.pi/agent/mcp.json` in Pi's native format, and their tools load in the child with direct exposure. Omitted or empty `mcps` denies MCP access. Loading `pi-mcp-adapter` directly is rejected because it bypasses the allowlist.
+An empty `tools` list adds no base tools, though selected extension tools can still activate; extension tools with `codemode` or `deferred` exposure stay callable from scripts and are declared only when `tools` names them. Children run with `--no-extensions`, so a Role must list the extension that registers its route model's provider; `builtin:<name>` entries load Pi built-in extensions. A Role activates `codemode` by listing `builtin:codemode` in `extensions` and `codemode` in `tools`. `mcps` names servers from the global `~/.pi/agent/mcp.json` in Pi's native format; their tools keep their configured exposure in a codemode Role and load with direct exposure otherwise. Omitted or empty `mcps` denies MCP access. Loading `pi-mcp-adapter` directly is rejected because it bypasses the allowlist.
 
 Isolated Herdr Role launches receive the same turn, token, and child-runtime budget metadata as ephemeral launches. Retained workers therefore keep one non-refilling session budget across follow-ups rather than receiving a new request budget.
 

package/extensions/admission.ts

@@ -2,8 +2,10 @@ import { realpath } from "node:fs/promises";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Role } from "../dist/index.js";
 
+// `codemode` mutates nothing itself: its sandbox reaches a checkout only through nested tool calls,
+// which are admitted by their own names here and limited to the Role's active tools in children.
 const READ_ONLY_TOOLS = new Set([
-	"read", "grep", "find", "ffgrep", "fffind", "ls", "codegraph_explore", "subagent_status",
+	"read", "grep", "find", "ffgrep", "fffind", "ls", "codegraph_explore", "subagent_status", "codemode",
 ]);
 
 export function roleCanWrite(role: Role): boolean {
@@ -26,37 +28,62 @@ async function checkoutKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<str
 /**
  * Coordinate Pi-owned calls that can mutate one checkout. This is admission,
  * not an OS sandbox: external processes and trusted extension lifecycle code
- * remain outside interception.
+ * remain outside interception. A model-issued call owns the checkout for the
+ * calls it makes through `ctx.executeTool()` (codemode scripts), so its nested
+ * writes pass while independent writers wait until it settles.
  */
 export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (input: unknown) => boolean): void {
 	const ownerByCheckout = new Map<string, string>();
-	const checkoutByCall = new Map<string, string>();
+	const checkoutByRoot = new Map<string, string>();
+	const writersByRoot = new Map<string, Set<string>>();
+	/** Model-issued ancestor of each in-flight call; Pi names nested calls `<parent id>/<n>`. */
+	const rootByCall = new Map<string, string>();
 	const release = (toolCallId: string) => {
-		const key = checkoutByCall.get(toolCallId);
+		const root = rootByCall.get(toolCallId);
+		if (root === undefined) return;
+		rootByCall.delete(toolCallId);
+		const writers = writersByRoot.get(root);
+		writers?.delete(toolCallId);
+		if (rootByCall.has(root) || writers?.size) return;
+		writersByRoot.delete(root);
+		const key = checkoutByRoot.get(root);
 		if (!key) return;
-		checkoutByCall.delete(toolCallId);
-		if (ownerByCheckout.get(key) === toolCallId) ownerByCheckout.delete(key);
+		checkoutByRoot.delete(root);
+		if (ownerByCheckout.get(key) === root) ownerByCheckout.delete(key);
 	};
 	pi.on("tool_call", async (event, ctx) => {
+		const root = event.parentToolCallId === undefined
+			? event.toolCallId
+			: rootByCall.get(event.parentToolCallId) ?? event.parentToolCallId;
+		rootByCall.set(event.toolCallId, root);
 		const potentiallyWriting = event.toolName === "delegate_task"
 			? directCanWrite(event.input)
 			: !READ_ONLY_TOOLS.has(event.toolName);
 		if (!potentiallyWriting) return;
 		const key = await checkoutKey(pi, ctx);
+		// A codemode result can settle while an unawaited nested call is still resolving its checkout.
+		if (root !== event.toolCallId && !rootByCall.has(root)) {
+			return { block: true, reason: `Parent call ${root} already settled; ${event.toolCallId} is not admitted.` };
+		}
 		const owner = ownerByCheckout.get(key);
-		if (owner && owner !== event.toolCallId) {
+		if (owner && owner !== root) {
 			return {
 				block: true,
 				reason: `Checkout ${key} already has an admitted Pi writer (${owner}); retry after it settles.`,
 			};
 		}
-		ownerByCheckout.set(key, event.toolCallId);
-		checkoutByCall.set(event.toolCallId, key);
+		ownerByCheckout.set(key, root);
+		checkoutByRoot.set(root, key);
+		const writers = writersByRoot.get(root) ?? new Set<string>();
+		writers.add(event.toolCallId);
+		writersByRoot.set(root, writers);
 	});
 	pi.on("tool_result", (event) => release(event.toolCallId));
 	pi.on("tool_execution_end", (event) => release(event.toolCallId));
 	pi.on("session_shutdown", () => {
 		ownerByCheckout.clear();
-		checkoutByCall.clear();
+		checkoutByRoot.clear();
+		writersByRoot.clear();
+		rootByCall.clear();
 	});
 }

package/extensions/isolated.ts

@@ -1,3 +1,4 @@
+import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { EphemeralSubagentExecutor } from "../dist/ephemeral.js";
@@ -22,11 +23,12 @@ import {
 	IntegrationActionParameters,
 	parseIntegrationAction,
 	parseStageRequest,
-	parseExecuteRequest,
 	parseIdOnly,
 	parseResumeRequest,
 	sameIdentity,
+	StatusOutputSchema,
 	type CheckBatchEvidence,
+	type ExecuteRequest,
 	type ModelClass,
 	type ReviewEvidence,
 	type RunState,
@@ -410,7 +412,7 @@ function toolResult(response: RunResponse, ctx: ExtensionContext, rowsByRequest:
 }
 
 export interface IsolatedSurface {
-	execute(params: unknown, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof toolResult>>;
+	execute(request: ExecuteRequest, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof toolResult>>;
 	inventory(cwd: string, current?: () => boolean): Promise<IsolatedInventory>;
 	recover(cwd: string): Promise<string>;
 	inspect(root: string, requestId: string): Promise<readonly string[]>;
@@ -616,16 +618,22 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		return toolResult({ text: `Pi Subagent ${id}: durable request accepted; productive work continues. Use subagent_status to inspect progress.`, state }, ctx, workspaceRowsByRequest);
 	};
 
+	// Status stays callable from codemode scripts and hands them the same bounded public projection
+	// the model reads; every mutating tool below is model-only because its guarded transitions need
+	// Main's visible reasoning.
 	pi.registerTool({
 		name: "subagent_status",
 		label: "Subagent status",
 		description: "Read one durable isolated request without reconciling or changing resources.",
 		parameters: IdOnlySchema,
 		prepareArguments: parseIdOnly,
+		outputSchema: StatusOutputSchema,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
 			const root = await lookupRoot(ctx.cwd, signal);
-			return toolResult(await getComponents().runner.status(params.id, root, signal), ctx, workspaceRowsByRequest);
+			const result = toolResult(await getComponents().runner.status(params.id, root, signal), ctx, workspaceRowsByRequest);
+			// The projection is plain JSON; its conditional fields are typed optional rather than absent.
+			return { ...result, structuredContent: result.details as JsonValue };
 		},
 	});
 	pi.registerTool({
@@ -634,6 +642,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		description: "Resume one unfinished isolated request without resetting its recorded policy or correction count.",
 		parameters: ResumeRequestParameters,
 		prepareArguments: parseResumeRequest,
+		exposure: "model-only",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
 			const root = await lookupRoot(ctx.cwd, signal);
@@ -649,6 +658,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		description: "Main stages/resolves an exact candidate, or rejects/revises one. Rejection of a staged candidate freezes the old generation; explicitly restage chosen candidates in a new generation. Never writes Main.",
 		parameters: StageRequestSchema,
 		prepareArguments: parseStageRequest,
+		exposure: "model-only",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
 			const root = await lookupRoot(ctx.cwd, signal);
@@ -661,6 +671,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		description: "Main advances staged dependents, refreshes after clean Main drift, validates, corrects, promotes, reconciles an interrupted promotion, cleans up promoted resources, or explicitly releases rejected/superseded owned resources. Never replays an uncertain mutation.",
 		parameters: IntegrationActionParameters,
 		prepareArguments: parseIntegrationAction,
+		exposure: "model-only",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
 			const root = await lookupRoot(ctx.cwd, signal);
@@ -679,6 +690,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		description: "Abort an isolated request; reject and release retained candidates and integration checkouts first. Terminate only exact owned workers. Repeat abort to reconcile cleanup of unchanged no-candidate allocations; preserve dirty or committed work.",
 		parameters: IdOnlySchema,
 		prepareArguments: parseIdOnly,
+		exposure: "model-only",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			latestCtx = ctx;
 			const root = await lookupRoot(ctx.cwd, signal);
@@ -755,10 +767,9 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			requireCurrent(current);
 			return getComponents().runner.drainFollowups(root, requestId, taskId);
 		},
-		async execute(params, signal, ctx) {
+		async execute(request, signal, ctx) {
 			latestCtx = ctx;
 			latestContext();
-			const request = parseExecuteRequest(params);
 			const root = await lookupRoot(ctx.cwd, signal);
 			return await startInSession(request.id, root, signal, ctx,
 				(state) => state.status === "pending" && state.createdAt === state.updatedAt

package/extensions/role-mcp.ts

@@ -1,5 +1,5 @@
 import { createMcpExtension, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadRoleMcpConfig, roleMcpAllowlistFromArgv, ROLE_MCP_POLICY_FLAG } from "@henryqw/pi-subagent";
+import { loadRoleMcpConfig, roleActivatesCodemode, roleMcpAllowlistFromArgv, ROLE_MCP_POLICY_FLAG, roleToolPolicyFromArgv } from "@henryqw/pi-subagent";
 
 export default function roleMcp(pi: ExtensionAPI): void | Promise<void> {
 	pi.registerFlag(ROLE_MCP_POLICY_FLAG, {
@@ -7,6 +7,8 @@ export default function roleMcp(pi: ExtensionAPI): void | Promise<void> {
 		type: "string",
 	});
 	// Pi binds extension flag values after factories load. Throwing here exits the child non-zero.
-	const config = loadRoleMcpConfig(getAgentDir(), roleMcpAllowlistFromArgv(process.argv));
+	const config = loadRoleMcpConfig(getAgentDir(), roleMcpAllowlistFromArgv(process.argv), {
+		codemode: roleActivatesCodemode(roleToolPolicyFromArgv(process.argv)),
+	});
 	return createMcpExtension({ loadConfig: () => config })(pi);
 }

package/extensions/role-tools.ts

@@ -4,12 +4,16 @@ import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-codin
 import {
 	CHILD_EXCLUDED_TOOL_NAMES,
 	EXECUTION_BUDGET_ENV,
+	parseRoleToolPolicy,
 	PI_SUBAGENT_PROCESS_LEASE,
 	ROLE_TOOL_POLICY_FLAG,
 	type EphemeralSubagentExecutionBudget,
 } from "@henryqw/pi-subagent";
 
 const childExcludedTools: ReadonlySet<string> = new Set(CHILD_EXCLUDED_TOOL_NAMES);
+// Pi does not declare these exposures on registration: `codemode`/`deferred` tools stay callable from
+// scripts, `hidden` ones are unreachable. The Role policy declares them only when `tools` names them.
+const undeclaredExposures: ReadonlySet<string> = new Set(["codemode", "deferred", "hidden"]);
 const WARNING_RATIO = 0.8;
 const WARNING_MESSAGE_TYPE = "pi-subagent-execution-budget";
 const PROCESS_LEASE_ERROR = `${PI_SUBAGENT_PROCESS_LEASE} must be a nonempty NUL/newline-free absolute path naming a regular non-symlink file owned by the current uid with mode 0600.`;
@@ -33,20 +37,6 @@ function validateProcessLease(path: string): void {
 	}
 }
 
-function configuredTools(value: unknown): string[] {
-	if (typeof value !== "string") throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(value);
-	} catch {
-		throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
-	}
-	if (!Array.isArray(parsed) || parsed.some((name) => typeof name !== "string" || !name.trim() || name.includes("\0"))) {
-		throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
-	}
-	return [...new Set(parsed.map((name) => name.trim()))];
-}
-
 function executionBudget(value: string | undefined): EphemeralSubagentExecutionBudget | undefined {
 	if (value === undefined) return;
 	let parsed: unknown;
@@ -107,11 +97,11 @@ export default function roleTools(pi: ExtensionAPI): void {
 	const budget = executionBudget(process.env[EXECUTION_BUDGET_ENV]);
 	let handoffSent = false;
 	pi.on("session_start", () => {
-		const selected = configuredTools(pi.getFlag(ROLE_TOOL_POLICY_FLAG));
+		const selected = parseRoleToolPolicy(pi.getFlag(ROLE_TOOL_POLICY_FLAG));
 		const allTools = pi.getAllTools();
 		const registeredTools = new Set(allTools.map((tool) => tool.name));
 		const extensionTools = allTools
-			.filter((tool) => !["builtin", "sdk", "inline"].includes(tool.sourceInfo.source))
+			.filter((tool) => !["builtin", "sdk", "inline"].includes(tool.sourceInfo.source) && !undeclaredExposures.has(tool.exposure))
 			.map((tool) => tool.name);
 		pi.setActiveTools([...new Set([...selected, ...extensionTools])].filter((name) => !childExcludedTools.has(name)));
 		const activeTools = new Set(pi.getActiveTools().filter((name) => registeredTools.has(name) && !childExcludedTools.has(name)));

package/extensions/subagent.ts

@@ -461,6 +461,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			`For delegate_task, ${MODEL_CLASS_GUIDANCE} A direct model replaces only the selected route's model; its thinking level stays unchanged.`,
 		],
 		parameters: DelegateTaskParameters,
+		// Delegation needs Main's visible reasoning; codemode scripts cannot start it.
+		exposure: "model-only",
 		prepareArguments(args) {
 			try {
 				const parsed = parseDelegateTask(args);

package/extensions/workflow.ts

@@ -42,8 +42,7 @@ export const DirectWorkflowSchema = Type.Object({
 	chain: Type.Optional(Type.Array(DelegationSchema, { minItems: 1, maxItems: MAX_WORKFLOW_ENTRIES })),
 }, { additionalProperties: false, description: "Direct mode: exactly one compact single, tasks, or chain workflow" });
 
-export const DelegateTaskSchema = Type.Union([DirectWorkflowSchema, ExecuteRequestSchema]);
-// Keep the strict mode union for parsing; expose a plain object root to tool providers.
+// Parse each mode with its strict schema; expose a plain object root to tool providers.
 export const DelegateTaskParameters = Type.Object({
 	...DirectWorkflowSchema.properties,
 	mode: Type.Union([DirectWorkflowSchema.properties.mode, ExecuteRequestSchema.properties.mode]),
@@ -56,7 +55,6 @@ export const DelegateTaskParameters = Type.Object({
 	finalChecks: ExecuteRequestSchema.properties.finalChecks,
 	finalJudgment: ExecuteRequestSchema.properties.finalJudgment,
 }, { additionalProperties: false });
-export const WorkflowSchema = DirectWorkflowSchema;
 
 export type Delegation = Static<typeof DelegationSchema> & { kind: "text" };
 export type WorkflowMode = "single" | "parallel" | "chain";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "25.0.2",
+  "version": "25.1.1",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",