@henryqw/pi-subagent 25.1.1 → 26.0.0

package/CONTEXT.md

@@ -4,7 +4,7 @@
 
 Own Role-configured Pi delegation through one `delegate_task` surface:
 
-- **direct mode** runs read-only compact work in Herdr tabs in Main's workspace and returns a handle before completion;
+- **direct mode** runs authorized compact shared-checkout work in Herdr tabs in Main's workspace and returns a handle before completion;
 - **isolated mode** runs durable checked graphs with Herdr worktrees, exact Git identities, guarded integration, and recovery; and
 - the package root exposes the Role, executor, worktree, evidence, schema, state, and runtime mechanisms used by the extension.
 
@@ -13,7 +13,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 - **Main**: the Pi session and checkout coordinating delegated work.
 - **Role**: package or user Markdown defining responsibility, tools, trusted extension sources, Skills, optional MCP names, instructions, and an optional model-class default. Roles do not select isolation.
 - **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, resolved through `pi-task-models`.
-- **Direct task**: one task using read-only base tools in a Herdr tab in Main's current workspace; trusted extensions and MCP servers are not read-only constrained.
+- **Direct task**: one bounded task using its Role's declared resources in Main's shared checkout; authorized writes take effect immediately without checked integration.
 - **Isolated request**: one durable ID, goal, and checked task graph.
 - **Candidate**: exact clean committed task-worktree identity produced by an isolated changeset worker.
 - **Readiness**: durable proof that one exact live-worker candidate passed its preliminary checks and is sealed for Main's explicit selection; it is not a separate user approval.
@@ -41,7 +41,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 
 ### Direct evidence
 
-- 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.
+- Direct mode admits declared write-capable resources for explicitly authorized scope while preserving read-only Role restrictions. Potential-writer requests serialize tasks and retain Pi checkout admission through exact completion; uncertain outcomes retain admission for manual recovery. Potential-writer answers require an explicit structured `succeeded` outcome; failed, blocked, or malformed completion stops dispatch and retains admission. This is a worker report, not proof of validation, cleanliness, rollback, or checked integration. Direct changesets 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.

package/README.md

@@ -1,11 +1,13 @@
 # `@henryqw/pi-subagent`
 
-Delegate work to configured Pi Roles with [Herdr](https://herdr.dev/). Read-only direct tasks run in Herdr tabs in your current workspace; checked implementation runs in isolated Herdr worktrees. Both return a handle so Main can continue while they work.
+Delegate work to configured Pi Roles with [Herdr](https://herdr.dev/). Authorized direct tasks run in Herdr tabs in your current workspace; checked implementation runs in isolated Herdr worktrees. Both return a handle so Main can continue while they work.
 
 ![Pi showing six delegated tasks running in parallel](./example.png)
 
 ## Install
 
+Requires Pi 1.0.0 or later. Development and automated checks use Pi 1.0.2. Older Pi releases are no longer supported.
+
 ```bash
 pi install npm:@henryqw/pi-task-models
 pi install npm:@henryqw/pi-subagent
@@ -29,7 +31,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. |
+| `delegate_task` | tool | Start authorized shared-checkout work or a durable isolated checked graph. |
 | `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. |
@@ -51,7 +53,7 @@ Main chooses the mode from your request; you do not need to select one. Words li
 
 | Mode | Request that triggers it | Checkout behavior |
 | --- | --- | --- |
-| `direct` | Read-only research, analysis, or review | Opens non-focused Herdr tabs in Main's current workspace. No worktree is created. |
+| `direct` | Bounded research, review, or explicitly authorized shared-checkout writes and commits | Opens non-focused Herdr tabs in Main's current workspace. No worktree is created. |
 | `isolated` | Implementation or a checked task graph | Runs changesets in owned Herdr worktrees; Main selects, validates, and promotes exact candidates. |
 
 Keep trivial mechanically verifiable work in Main. Keep tightly coupled changes under one owner rather than splitting by file count.
@@ -77,7 +79,11 @@ 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. `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.
+Direct tasks use the selected Role's declared tools, extensions, Skills, and MCP servers, including write-capable resources. Authorization comes from your request and Main's bounded task packet, not the Role's capabilities: name allowed paths/actions and exclusions, preserve unrelated edits and staged changes, and authorize commits or external actions explicitly. For example, a configured Git operator with `bash` can stage named pending files and commit them on the `fast` route. Read-only Roles retain their tool restrictions. Use isolated mode for a checked changeset.
+
+Direct writes affect Main's checkout immediately. No clean-checkout prerequisite, automatic checks, rollback, or isolated integration guarantee applies. Requests containing potential writers (including any extensions or MCP servers) run their tasks serially and hold checkout admission after the initial handle returns; competing Pi writes fail until exact successful completion. Pure read-only parallel requests still run concurrently. A failure in a potential-writer request stops further dispatch; an uncertain worker may still be running. Chains replace each literal `{previous}` with the preceding successful answer and stop on failure. On failure, cancellation, or uncertain launch after tab creation, admission stays held: inspect the exact tabs/session files through `/subagent`, stop any remaining owned workers, inspect and preserve their changes, then restart Pi before new writes. Never blindly retry a commit or delete work to recover.
+
+Potential-writer tasks must return one JSON completion object, such as `{"outcome":"succeeded","answer":"Scoped commit completed."}`. `outcome` must be `succeeded`, `failed`, or `blocked`, and `answer` must be non-empty. A normal final Pi turn is not enough: failure, blocked work, plain text, or malformed completion stops later dispatch and retains admission. Success is the worker's explicit report, not independent validation of its changes.
 
 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.
 
@@ -191,7 +197,7 @@ Checkout admission keeps a script's writer ownership until the script and all it
 
 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.
+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. `oauth.clientRegistration` must be `dcr` or `cimd`; `cimd` requires Pi 1.0.1 or later; Pi 1.0.0 rejects it before child launch. It cannot use `clientId` or `clientName`, and any `callbackUrl` must use localhost or 127.0.0.1 with path `/callback`. Project MCP overrides remain ignored: a project cannot change the Role's global server allowlist or exposure. 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
 
@@ -218,4 +224,4 @@ Durable state is private under `config/pi-subagent/state/`. Isolated worker Pi s
 
 ## Limits and recovery
 
-Role extensions and MCP servers are trusted executable code, not a sandbox. Select the smallest resource set. Direct admission checks only declared base tools; extensions and MCP servers can perform writes, including to Main's checkout. Concurrent changes can make a direct worker's read stale. Retained-work reports identify exact resources for deliberate recovery.
+Role extensions and MCP servers are trusted executable code, not a sandbox. Select the smallest resource set. Direct tasks may use declared write-capable resources in Main's checkout only within the authorized scope. Checkout admission coordinates this Main's Pi calls, not other Pi sessions, trusted extension lifecycle code, or external processes. Concurrent changes can make a direct worker's read stale. Retained-work reports identify exact resources for deliberate recovery.

package/dist/direct-herdr.d.ts

@@ -12,9 +12,9 @@ export interface DirectHandle {
     cancel(): Promise<void>;
 }
 export declare function exactDirectTerminalTurn(jsonl: string, prompt: string): boolean;
-export declare function exactDirectAnswer(jsonl: string, prompt: string, maxBytes?: number): string;
+export declare function exactDirectAnswer(jsonl: string, prompt: string, maxBytes?: number, requireSuccess?: boolean): string;
 export declare function directSessionTokens(jsonl: string, prompt: string): number | undefined;
 export type DirectTab = Pick<DirectHandle, "name" | "tabId" | "paneId" | "sessionFile">;
 export declare function createDirectHerdr(pi: Pick<ExtensionAPI, "exec">, cwd: string, idleMs: number): {
-    start(launch: ResolvedRoleLaunch, name: string, label: string, task: string, signal: AbortSignal, onTab: (tab: DirectTab) => void): Promise<DirectHandle>;
+    start(launch: ResolvedRoleLaunch, name: string, label: string, task: string, signal: AbortSignal, onTab: (tab: DirectTab) => void, requireSuccess?: boolean): Promise<DirectHandle>;
 };

package/dist/direct-herdr.js

@@ -7,6 +7,7 @@ import { createHerdrClient, hasHerdrErrorCode, herdrCommandFailure, startPiAgent
 const OPERATION_MS = 30_000;
 const SESSION_LIMIT = 16 * 1024 * 1024;
 const ANSWER_LIMIT = 50 * 1024;
+const DIRECT_OUTCOMES = ["succeeded", "failed", "blocked"];
 const object = (value, label) => {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error(`Malformed Herdr ${label}.`);
@@ -63,7 +64,7 @@ export function exactDirectTerminalTurn(jsonl, prompt) {
     const reason = exactFinalTurn(jsonl, prompt)?.stopReason;
     return reason === "stop" || reason === "error" || reason === "aborted";
 }
-export function exactDirectAnswer(jsonl, prompt, maxBytes = ANSWER_LIMIT) {
+export function exactDirectAnswer(jsonl, prompt, maxBytes = ANSWER_LIMIT, requireSuccess = false) {
     const final = exactFinalTurn(jsonl, prompt);
     if (!final || final.stopReason !== "stop" || !Array.isArray(final.content)) {
         throw new Error("Pi did not persist an exact successful final answer for this prompt.");
@@ -76,7 +77,23 @@ export function exactDirectAnswer(jsonl, prompt, maxBytes = ANSWER_LIMIT) {
         throw new Error("Pi persisted an empty final answer.");
     if (Buffer.byteLength(text, "utf8") > maxBytes)
         throw new Error(`Pi final answer exceeds the ${maxBytes}-byte workflow limit; read the private session file for recovery.`);
-    return text;
+    if (!requireSuccess)
+        return text;
+    let completion;
+    try {
+        completion = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error("Pi potential-writer final answer must be a JSON completion object.", { cause: error });
+    }
+    if (!completion || typeof completion !== "object" || Array.isArray(completion)
+        || !DIRECT_OUTCOMES.some((outcome) => outcome === completion.outcome)
+        || typeof completion.answer !== "string" || !completion.answer.trim()) {
+        throw new Error("Pi potential-writer completion must have a valid outcome and a non-empty answer.");
+    }
+    if (completion.outcome !== "succeeded")
+        throw new Error(`Direct task reported ${completion.outcome}: ${completion.answer}`);
+    return completion.answer;
 }
 // Ignore a partial trailing JSONL entry while the child is writing it.
 export function directSessionTokens(jsonl, prompt) {
@@ -132,7 +149,7 @@ export function createDirectHerdr(pi, cwd, idleMs) {
         return field(agent.agent_status, "agent state");
     };
     return {
-        async start(launch, name, label, task, signal, onTab) {
+        async start(launch, name, label, task, signal, onTab, requireSuccess = false) {
             const caller = result(await herdr.json(["pane", "current", "--current"], options(signal)), "pane_current");
             const pane = object(caller.pane, "calling pane");
             if (pane.pane_id !== callerPane || pane.workspace_id !== workspaceId)
@@ -170,7 +187,10 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                 // A canceled start may have succeeded server-side; retain its tab but
                 // never submit a new prompt after cancellation.
                 signal.throwIfAborted();
-                const prompt = `${task}\n\nDirect text boundary: inspect only. Do not modify files, the Git index, HEAD, branches, or worktrees.\n\nTurn identity: ${randomBytes(16).toString("hex")}`;
+                const completionInstruction = requireSuccess
+                    ? `\n\nPotential-writer completion: Return exactly one JSON object without Markdown, {"outcome":"succeeded","answer":"summary"}. outcome must be ${DIRECT_OUTCOMES.join(", ")}. Use succeeded only when the entire authorized task, including requested checks and commits, completed successfully; a failed mutation, unresolved partial work, or missing authorization must be failed or blocked, even if your Pi turn ends normally. Describe changes, checks, commit identity, remaining risks, and checkout status in answer.`
+                    : "";
+                const prompt = `${task}\n\nDirect shared-checkout boundary: use only your Role's resources for the explicitly authorized task and scope. Writes and commits affect Main's existing checkout immediately; preserve unrelated files and staged changes. Do not create or manage worktrees, change branches, push, or perform external mutations without explicit task authorization. There is no isolated integration, automatic validation, or rollback. If instructions conflict or authorization is missing, stop and report it. Report changes, commit identity if any, checks, remaining risks, and checkout status; never claim isolated guarantees.${completionInstruction}\n\nTurn identity: ${randomBytes(16).toString("hex")}`;
                 // Native prompt without --wait acknowledges submission, not completion of the turn.
                 const accepted = await herdr.json(["agent", "prompt", name, prompt], options(signal));
                 const state = inspect(accepted, "agent_prompted", name, paneId, tabId);
@@ -195,7 +215,7 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                             const info = await stat(sessionFile);
                             if (info.size > SESSION_LIMIT)
                                 throw new Error(`Pi session in tab ${tabId} exceeds 16 MiB; inspect ${sessionFile} for recovery.`);
-                            return exactDirectAnswer(await readFile(sessionFile, "utf8"), prompt, maxBytes);
+                            return exactDirectAnswer(await readFile(sessionFile, "utf8"), prompt, maxBytes, requireSuccess);
                         };
                         const maybeAnswer = async () => {
                             try {

package/dist/index.js

@@ -97,7 +97,7 @@ const stringList = (value, field, source) => {
     }
     return value.map((item) => item.trim());
 };
-// Pi 0.99 built-in extensions (`builtin:<name>`, see Pi's settings docs); Pi exports no list of them.
+// Pi built-in extensions (`builtin:<name>`, see Pi's settings docs); Pi exports no list of them.
 // `builtin:mcp` is excluded: it connects every server in mcp.json and would bypass the Role `mcps` allowlist.
 const BUILTIN_EXTENSION_NAMES = ["codemode", "tool-search", "llama.cpp"];
 const BUILTIN_EXTENSION_PREFIX = "builtin:";

package/dist/mcp-role.d.ts

@@ -1,4 +1,4 @@
-import type { LoadedMcpConfig } from "@earendil-works/pi-coding-agent";
+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`
@@ -9,4 +9,5 @@ export declare function parseRoleMcpAllowlist(value: unknown): string[];
  */
 export declare function loadRoleMcpConfig(agentDir: string, allowlist: readonly string[], options?: {
     codemode: boolean;
+    piVersion?: string;
 }): LoadedMcpConfig;

package/dist/mcp-role.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { VERSION } from "@earendil-works/pi-coding-agent";
 export function parseRoleMcpAllowlist(value) {
     if (typeof value !== "string")
         throw new Error("The Role MCP policy flag must contain a JSON array of MCP server names.");
@@ -62,6 +63,7 @@ const HTTP_CHECKS = {
         }, "an http URL on localhost, 127.0.0.1, or [::1] without query or fragment, on the \"oauth.callbackPort\" port"],
     "oauth.scope": [isString, "a string"],
     "oauth.clientName": [(value) => typeof value === "string" && value.trim() !== "", "a non-empty string"],
+    "oauth.clientRegistration": [(value) => value === "dcr" || value === "cimd", '"dcr" or "cimd"'],
     "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"],
 };
@@ -70,7 +72,7 @@ const EXPOSURE_CHECKS = {
     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, codemode) {
+function validateRoleMcpServer(path, name, value, codemode, piVersion) {
     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 \"-\").");
@@ -87,6 +89,17 @@ function validateRoleMcpServer(path, name, value, codemode) {
         if (fieldValue !== undefined && !valid(fieldValue, value))
             fail(`field "${field}" must be ${shape}.`);
     }
+    if (http && isRecord(value.oauth) && value.oauth.clientRegistration === "cimd") {
+        if (piVersion === "1.0.0")
+            fail('field "oauth.clientRegistration" "cimd" requires Pi 1.0.1 or later; current Pi is 1.0.0.');
+        if (value.oauth.clientId !== undefined || value.oauth.clientName !== undefined) {
+            fail('field "oauth.clientRegistration" "cimd" cannot be combined with "oauth.clientId" or "oauth.clientName".');
+        }
+        const callback = parseUrl(value.oauth.callbackUrl);
+        if (callback && (callback.hostname === "[::1]" || callback.pathname !== "/callback")) {
+            fail('field "oauth.clientRegistration" "cimd" requires "oauth.callbackUrl" on localhost or 127.0.0.1 with path /callback.');
+        }
+    }
     // The native transport sends the provider's token to `url`, so Pi only allows it over https or loopback.
     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].");
@@ -133,7 +146,7 @@ export function loadRoleMcpConfig(agentDir, allowlist, options = { codemode: fal
         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], options.codemode), source: path, scope: "global" };
+        return { name, config: validateRoleMcpServer(path, name, configured[name], options.codemode, options.piVersion ?? VERSION), source: path, scope: "global" };
     });
     return { servers, autoEnableCodemode: false, errors: [] };
 }

package/docs/orchestration.md

@@ -3,7 +3,7 @@
 `pi-subagent` owns both delegation paths behind `delegate_task`:
 
 ```text
-                         ┌─ direct ─── read-only Herdr tab in Main's workspace
+                         ┌─ direct ─── authorized shared-checkout Herdr tab
 request + Role + route ──┤
                          └─ isolated ─ Herdr worktree, checked candidate, durable state
 ```
@@ -62,7 +62,9 @@ Each entry has:
 
 An explicit model must support the route's thinking level. A launched child is never retried automatically after provider or process failure.
 
-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 or write to Main's checkout. A direct `changeset` or Role with write-capable base tools is rejected; use isolated mode for implementation. Parallel tasks run concurrently and report in request order. A chain substitutes only the preceding successful output and stops at its first failure.
+Direct tasks use their Role's declared resources, including write tools, within explicit task authorization. Read-only Role restrictions, resource/trust validation, and recursive-delegation exclusions still apply. A direct `changeset` is rejected; use isolated mode for checked integration. Tasks in any potential-writer request run serially and reserve checkout admission until exact successful completion; pure read-only parallel tasks run concurrently. Results stay in request order. A chain substitutes only the preceding successful output and stops at its first failure.
+
+Writes and commits immediately change the shared checkout; there is no automatic validation, rollback, or isolated promotion. A potential-writer final answer must be a JSON object with `outcome` (`succeeded`, `failed`, or `blocked`) and a non-empty `answer`; only explicit worker-reported success permits later dispatch or admission release, not merely a normally settled Pi turn. Preserve unrelated files and index entries, require explicit commit/external-action scope, and report checkout status. Uncertain launch after tab creation, failure, or cancellation retains admission and exact recovery identities. Inspect `/subagent`, stop remaining owned workers, inspect and preserve changes, then restart Pi before new writes. Admission covers this Main's Pi calls, not other sessions or external processes.
 
 The tool returns a handle after the first exact Herdr tab is launched. The remaining tabs are launched asynchronously; their identities are recorded on the session branch. A session-owned observer awaits each exact agent's lifecycle and retrieves its final answer from its Pi session file, not its possibly truncated screen. Idle, blocked, unknown, malformed, or oversized answers fail with recoverable tab/session identity; no whole-run deadline is imposed. `/subagent` shows exact recorded tabs on this session branch, distinguishing locally observed work from unobserved records. A session switch stops observation and carries tab identity into the new branch.
 

package/examples/roles/implementer.md

@@ -20,6 +20,6 @@ Run focused checks required by the task. Before reporting, remove only task-crea
 
 Access credentials or the network, create extra artifacts, or broaden scope only when the task requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-Follow the task's commit policy. Direct delegation leaves changes uncommitted; isolated delegation commits completed scoped changes. Do not create or manage another worktree. Leave the assigned checkout and branch intact. Never push or open a pull request without explicit authorization.
+Follow the task's commit policy. Direct delegation may write or commit only within Main's explicitly authorized scope; otherwise leave changes uncommitted. Isolated delegation commits completed scoped changes. Do not create or manage another worktree. Leave the assigned checkout and branch intact. Never push or open a pull request without explicit authorization.
 
 Report briefly: outcome, commit, checks, and remaining risks.

package/extensions/admission.ts

@@ -9,7 +9,7 @@ const READ_ONLY_TOOLS = new Set([
 ]);
 
 export function roleCanWrite(role: Role): boolean {
-	return role.tools.some((tool) => !READ_ONLY_TOOLS.has(tool));
+	return role.tools.some((tool) => !READ_ONLY_TOOLS.has(tool)) || role.extensions.length > 0 || Boolean(role.mcps?.length);
 }
 
 export function roleIsReadOnlyScout(role: Role): boolean {
@@ -32,13 +32,15 @@ async function checkoutKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<str
  * 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 {
+export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (input: unknown) => boolean): (toolCallId: string) => () => void {
+	const heldCalls = new Set<string>();
 	const ownerByCheckout = 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) => {
+		if (heldCalls.has(toolCallId)) return;
 		const root = rootByCall.get(toolCallId);
 		if (root === undefined) return;
 		rootByCall.delete(toolCallId);
@@ -85,5 +87,16 @@ export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (inp
 		checkoutByRoot.clear();
 		writersByRoot.clear();
 		rootByCall.clear();
+		heldCalls.clear();
 	});
+	// A direct handle settles the tool call before the worker settles. Keep its
+	// admission until exact completion; uncertain workers require manual recovery.
+	return (toolCallId) => {
+		const root = rootByCall.get(toolCallId);
+		if (root === undefined || !writersByRoot.get(root)?.has(toolCallId)) {
+			throw new Error(`Direct call ${toolCallId} was not admitted as a checkout writer; delegate again with the current Role resources.`);
+		}
+		heldCalls.add(toolCallId);
+		return () => { heldCalls.delete(toolCallId); release(toolCallId); };
+	};
 }

package/extensions/subagent.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, Text, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { availableTaskModels, loadTaskModelsConfig, modelReference, registerModelTask, resolveAvailableModel, type ResolvedTaskRoute, taskThinkingLevels } from "@henryqw/pi-task-models";
-import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, DELEGATE_TASK, formatDuration, loadRoles, prepareRoleLaunch, ROLE_TOOL_POLICY_FLAG, type Role } from "@henryqw/pi-subagent";
+import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, DELEGATE_TASK, formatDuration, loadRoles, prepareRoleLaunch, resolveRolePackageResources, ROLE_TOOL_POLICY_FLAG, type Role } from "@henryqw/pi-subagent";
 import { readSubagentConfig, resolveExecutionPolicy, type EffectiveExecutionPolicy } from "./config.ts";
 import { registerCheckoutAdmission, roleCanWrite, roleIsReadOnlyScout } from "./admission.ts";
 import { registerIsolatedExtension } from "./isolated.ts";
@@ -181,7 +181,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			return true;
 		}
 	};
-	registerCheckoutAdmission(pi, canWrite);
+	const holdAdmission = registerCheckoutAdmission(pi, canWrite);
 	const isolatedSurface = registerIsolatedExtension(pi, {
 		executor,
 		policy: initialPolicy,
@@ -452,10 +452,10 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "delegate_task",
 		label: "Subagent",
-		description: `Delegate read-only direct work in Herdr or a durable checked isolated graph to Pi Roles. Roles: ${roleSummary()}.`,
-		promptSnippet: "Delegate read-only direct work or a checked isolated task graph",
+		description: `Delegate explicitly authorized direct work in the shared checkout or a durable checked isolated graph to Pi Roles. Roles: ${roleSummary()}.`,
+		promptSnippet: "Delegate authorized shared-checkout work or a checked isolated task graph",
 		promptGuidelines: [
-			"Keep trivial mechanically verifiable work in Main. Use mode direct only for read-only research, analysis, or review in the current workspace. Use mode isolated for any implementation, write-capable Role, or checked changeset; explicit mode never falls back.",
+			"Keep trivial mechanically verifiable work in Main. Use mode direct for bounded, explicitly authorized work with the Role's declared resources in the shared checkout, including writes or commits. Specify allowed scope and exclusions; preserve unrelated changes. Direct work has no isolated checks, rollback, or integration guarantees. Use mode isolated for checked changesets; explicit mode never falls back.",
 			"Direct requests use one compact role/name/task packet, tasks for independent packets, or chain with {previous}. Direct work returns a Herdr handle after launch; results arrive as one follow-up message.",
 			"Isolation uses typed tasks and dependencies. Keep tightly coupled changes with one owner; do not split by file count. Failures, ambiguity, limits, and conflicts retain work and never waive checks or identity guards.",
 			`For delegate_task, ${MODEL_CLASS_GUIDANCE} A direct model replaces only the selected route's model; its thinking level stays unchanged.`,
@@ -482,8 +482,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			for (const delegation of workflow.delegations) {
 				const role = roles.get(delegation.role);
 				if (!role) throw boundedError(new Error(`Unknown Subagent role: ${delegation.role}. Available roles: ${[...roles.keys()].join(", ") || "none"}.`));
-				if (roleCanWrite(role)) throw new Error(`Role ${role.name} exposes write-capable or unverified resources. Use mode isolated for this Role; direct is read-only.`);
 			}
+			const writes = workflow.delegations.some((delegation) => roleCanWrite(roles.get(delegation.role)!));
 			const policy = currentPolicy();
 			const herdr = createDirectHerdr(pi, ctx.cwd, policy.childIdleMs);
 			const entries = identifyWorkflowEntries(toolCallId, workflow);
@@ -500,17 +500,25 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			const settled = new Promise<void>((resolve) => { resolveSettled = resolve; });
 			// Register before Herdr can create a tab: session switches must await this
 			// launch, including its identity callback, before copying recovery records.
+			const releaseAdmission = writes ? holdAdmission(toolCallId) : () => {};
 			directTasks.set(taskId, { controller, settled, handles, tabs });
 			const launch = async (entry: WorkflowEntry, activeSignal: AbortSignal) => {
 				activeSignal.throwIfAborted();
 				const role = loadRoles().find((candidate) => candidate.name === entry.delegation.role);
-				if (!role || roleCanWrite(role)) throw new Error(`Role ${entry.delegation.role} disappeared or became write-capable; use mode isolated.`);
+				if (!role) throw new Error(`Role ${entry.delegation.role} disappeared.`);
+				if (!writes && roleCanWrite(role)) throw new Error(`Role ${role.name} became write-capable after admission; delegate again with its current resources.`);
 				const context = latestCtx ?? ctx;
-				const route = prepareRoleLaunch(pi, context, { role, task: DELEGATE_TASK,
+				const resources = await resolveRolePackageResources(role, context);
+				const effectiveRole = { ...role, extensions: resources.extensions };
+				const route = prepareRoleLaunch(pi, context, { role: effectiveRole, task: DELEGATE_TASK,
 					...(entry.delegation.modelClass === undefined ? {} : { modelClass: entry.delegation.modelClass }) });
 				const prepared = entry.delegation.model === undefined ? route : prepareRoleLaunch(pi, context, {
-					role, route: replaceRouteModel(context, entry.delegation.model, route),
+					role: effectiveRole, route: replaceRouteModel(context, entry.delegation.model, route),
 				});
+				prepared.args.push("--no-prompt-templates", "--no-themes",
+					...resources.skills.flatMap((path) => ["--skill", path]),
+					...resources.prompts.flatMap((path) => ["--prompt-template", path]),
+					...resources.themes.flatMap((path) => ["--theme", path]));
 				states.set(entry.id, { ...states.get(entry.id)!, model: modelReference(prepared.model), thinkingLevel: prepared.thinkingLevel, status: "running", assistantOutput: "" });
 				startWidgetItem(entry.id, taskId, role.name, prepared.model.id, prepared.thinkingLevel, entry.delegation.name, ctx);
 				const transient = await materializeTransientLaunch({ launch: prepared, prompt: prepared.systemPrompt,
@@ -524,7 +532,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 							pi.appendEntry(DIRECT_TAB_TYPE, record);
 							tabs.push(record);
 							tabByEntry.set(entry.id, record);
-						});
+						}, writes);
 				} catch (error) {
 					// A failed start can still be in flight. Keep its private prompt for recovery.
 					throw new Error(`${error instanceof Error ? error.message : String(error)}. Direct Role prompt retained at ${transient.launch.args[prepared.promptArgIndex + 1]} after uncertain start.`, { cause: error });
@@ -552,15 +560,17 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				finishWidgetItem(entries[0]!.id, "failure");
 				directTasks.delete(taskId);
 				resolveSettled();
+				if (!tabs.length) releaseAdmission();
 				throw boundedError(error);
 			} finally { signal?.removeEventListener("abort", abortLaunch); }
 			void (async () => {
 				try {
 					await new Promise<void>((resolve) => setImmediate(resolve));
 					let active = 0;
+					let writerFailed = false;
 					const queue: Array<() => void> = [];
 					const permit = async () => {
-						if (active >= policy.maxSubagents) await new Promise<void>((resolve) => queue.push(resolve));
+						if (active >= (writes ? 1 : policy.maxSubagents)) await new Promise<void>((resolve) => queue.push(resolve));
 						active++;
 						return () => { active--; queue.shift()?.(); };
 					};
@@ -568,6 +578,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 						const release = await permit();
 						try {
 							controller.signal.throwIfAborted();
+							if (writerFailed) throw new Error("Previous direct task did not complete exactly; inspect recorded tabs before new shared-checkout work.");
 							const handle = entry.index === 0 ? first : await launch(entry, controller.signal);
 							const answer = await handle.answer(Math.floor(40 * 1024 / entries.length));
 							try {
@@ -578,6 +589,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 							finishWidgetItem(entry.id, "success");
 							return answer;
 						} catch (error) {
+							if (writes) writerFailed = true;
 							const { assistantOutput: _partial, ...base } = states.get(entry.id)!;
 							states.set(entry.id, { ...base, status: "rejected", failure: `${tabByEntry.has(entry.id) ? `recover from Herdr tab ${tabByEntry.get(entry.id)!.tabId}, agent ${tabByEntry.get(entry.id)!.name}, session ${tabByEntry.get(entry.id)!.sessionFile}: ` : ""}${capOutput(error instanceof Error ? error.message : String(error))}` });
 							finishWidgetItem(entry.id, "failure");
@@ -596,13 +608,14 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 							status: "skipped",
 						});
 					}
+					if ([...states.values()].every(({ status }) => status === "succeeded")) releaseAdmission();
 					if (!controller.signal.aborted) reportDirect(launchEpoch, taskId, workflow.mode, [...states.values()], tabs);
 					directTasks.delete(taskId);
 					resolveSettled();
 				}
 			})();
 			return {
-				content: [{ type: "text" as const, text: capOutput(`Direct delegation started · ${taskId}\nHerdr tab: ${first.tabId} · pane: ${first.paneId} · agent: ${first.name}\nExact session: ${first.sessionFile}\nAll launched tabs: /subagent (on this session branch).\n${entries.length} task(s); result will arrive in one follow-up message.`) }],
+				content: [{ type: "text" as const, text: capOutput(`Direct delegation started · ${taskId}\nHerdr tab: ${first.tabId} · pane: ${first.paneId} · agent: ${first.name}\nExact session: ${first.sessionFile}\nAll launched tabs: /subagent (on this session branch).\n${entries.length} task(s); result will arrive in one follow-up message. Direct work shares this checkout; completion is an exact answer, not checked integration. ${writes ? "Potential writers run serially; competing Pi writes stay blocked until exact completion. On failure or cancellation, inspect owned tabs before restarting Pi; changes are not rolled back." : "Concurrent changes may make reads stale."}`) }],
 				details: { taskId, mode: workflow.mode, tabId: first.tabId, sessionFile: first.sessionFile,
 					entries: entries.map(({ id, index, delegation }) => ({ id, index, name: delegation.name, role: delegation.role })) },
 			};

package/extensions/workflow.ts

@@ -107,7 +107,7 @@ export function parseWorkflow(value: unknown): ParsedWorkflow {
 	const mode = workflowMode(value);
 	if (!Check(DirectWorkflowSchema, value)) {
 		const issue = Errors(DirectWorkflowSchema, value)[0];
-		throw new Error(`direct workflow must match the declared tool schema${issue ? ` at ${issue.instancePath || "/"}: ${issue.message}` : ""}. Direct mode is read-only; use mode isolated for changesets.`);
+		throw new Error(`direct workflow must match the declared tool schema${issue ? ` at ${issue.instancePath || "/"}: ${issue.message}` : ""}. Direct mode returns task answers without checked integration; use mode isolated for changesets.`);
 	}
 	if (!mode) throw new Error("direct workflow must select exactly one of single, tasks, or chain.");
 	const input = value as DirectInput;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "25.1.1",
+  "version": "26.0.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -40,9 +40,9 @@
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.99.1 <0.100.0 || ^1.0.0",
-    "@earendil-works/pi-coding-agent": ">=0.99.1 <0.100.0 || ^1.0.0",
-    "@earendil-works/pi-tui": ">=0.99.1 <0.100.0 || ^1.0.0",
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "^1.3.15"
   },
   "repository": {
@@ -74,9 +74,9 @@
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.0.0",
-    "@earendil-works/pi-coding-agent": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0",
+    "@earendil-works/pi-ai": "1.0.2",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@earendil-works/pi-tui": "1.0.2",
     "@types/proper-lockfile": "^4.1.4"
   }
 }

package/skills/pi-subagent/SKILL.md

@@ -11,8 +11,8 @@ Record the requested outcome, allowed scope and exclusions, local delegation/che
 
 Keep trivial, mechanically verifiable work in Main. Choose the user-requested mode when one is explicit. Otherwise:
 
-- Use `mode: direct` for bounded read-only research, analysis, and review with known read-only Roles.
-- Use `mode: isolated` for implementation and other writing tasks, independently checked changes, or an exploratory or discardable candidate. A single isolated task is valid.
+- Use `mode: direct` for bounded research, analysis, review, or explicitly authorized shared-checkout writes and commits using the selected Role's resources.
+- Use `mode: isolated` for independently checked changes, or an exploratory or discardable candidate. A single isolated task is valid.
 - Keep one implementation owner for tightly coupled work. Size alone does not justify splitting it.
 - Never silently fall back from isolated to direct. Scope growth requires a checkpoint and replan, not migration of dirty work.
 
@@ -22,7 +22,7 @@ After delegation acknowledges a handle or durable request, do other work or end
 
 # Direct requests
 
-Use one compact `role`/`name`/`task` packet, `tasks` for independent packets, or `chain` for dependent packets. Only text tasks are accepted; a write-capable Role, `kind: changeset`, checks, and judgment require isolated mode. The tool returns a handle after launching Herdr tabs in the current workspace. Main receives the verified result as a follow-up after the workflow finishes, without interrupting an active turn. If observation stops, open `/subagent` to inspect exact recorded tabs and session files on this session branch; recorded does not prove still running.
+Use one compact `role`/`name`/`task` packet, `tasks` for independent packets, or `chain` for dependent packets. Only answer-returning tasks (`kind: text`) are accepted; writes and commits are allowed within explicit task authorization, but `kind: changeset`, structured checks, and judgment require isolated mode. State scope, exclusions, commit policy, and external-action permission; preserve unrelated files and staged changes. Direct writes take effect immediately with no automatic validation, rollback, or isolated integration guarantees. Requests with potential writers run serially and block competing Pi writes until exact completion. Main may read or do work elsewhere while waiting, not mutate the reserved checkout. On failure/cancellation or an uncertain launched tab, inspect `/subagent` identities, stop remaining owned workers, preserve and inspect changes, then restart Pi before writing or retrying. A failed commit may already have happened; never replay it blindly. The tool returns a handle after launching Herdr tabs in the current workspace. Main receives the verified result as a follow-up after the workflow finishes, without interrupting an active turn. If observation stops, open `/subagent` to inspect exact recorded tabs and session files on this session branch; recorded does not prove still running.
 
 # Isolated requests