@selesai/code 0.13.39 → 0.14.0

package/dist/extensions/pi-subagents/package.json

@@ -1,6 +1,7 @@
 {
   "name": "pi-subagents",
-  "version": "0.66.0",
+  "version": "0.76.1",
+  "private": true,
   "description": "Selesai extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -11,9 +12,11 @@
     "./external-job-provider": "./src/api/external-job-provider.ts",
     "./external-runs": "./src/api/external-runs.ts",
     "./agents": "./src/api/agents.ts",
+    "./inspectors": "./src/api/inspectors.ts",
     "./delegation": "./src/api/delegation.ts",
     "./capability-ceiling": "./src/api/capability-ceiling.ts",
     "./workflow-resources": "./src/api/workflow-resources.ts",
+    "./required-child-extensions": "./src/api/required-child-extensions.ts",
     "./preflight": "./src/api/preflight.ts",
     "./control-channel": "./src/api/control-channel.ts",
     "./intercom-bridge": "./src/api/intercom-bridge.ts",
@@ -33,6 +36,7 @@
     "pi-package",
     "pi",
     "pi-coding-agent",
+    "extension",
     "subagents",
     "ai",
     "agents",
@@ -53,10 +57,13 @@
     "CHANGELOG.md"
   ],
   "scripts": {
+    "build:pkg": "node scripts/build-package.mjs",
+    "pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
     "typecheck": "tsc --noEmit",
     "test": "npm run test:unit",
     "test:unit": "node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
     "test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
+    "test:smoke:tool-activation": "node --experimental-strip-types --test test/smoke/tool-activation.test.ts",
     "test:all": "npm run test:unit && npm run test:integration"
   },
   "pi": {
@@ -72,9 +79,10 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": ">=0.80.0",
+    "@earendil-works/pi-ai": ">=0.86.1",
     "@selesai/code": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-agent-core": {
@@ -88,24 +96,27 @@
     },
     "@earendil-works/pi-tui": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@earendil-works/pi-server": "0.85.0",
+    "@js-temporal/polyfill": "0.5.1",
     "acorn": "8.18.0",
     "jiti": "2.7.0",
-    "typebox": "1.1.38",
-    "undici": "8.10.0",
+    "undici": "8.10.2",
     "yaml": "2.8.3"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.81.0",
-    "@earendil-works/pi-ai": "0.81.0",
-    "@earendil-works/pi-tui": "0.81.0",
+    "@earendil-works/pi-agent-core": "1.1.0",
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
     "@oxlint/plugins": "1.80.0",
     "@types/node": "24.13.3",
     "oxlint": "1.80.0",
     "typescript": "5.9.3",
-    "@selesai/code": "file:./test/fixtures/pi-coding-agent-shim"
+    "@selesai/code": "file:../../..",
+    "typebox": "1.3.27"
   }
-}
+}

package/dist/extensions/pi-subagents/prompts/council.md

@@ -8,8 +8,11 @@ session, are the supervisor. You select the roster, curate cross-advisor packets
 decide which feedback is valid, and write the final memo. Advisors do not talk
 directly or see peer transcripts by default. This is not free-form agent chat.
 
-Before you orchestrate, read `skills/council-mode/SKILL.md` and
-`skills/pi-subagents/references/execution-controls.md`.
+Before you orchestrate, load the council protocol with
+`subagent({ action: "guide", topic: "council" })`. If only `subagents_enable`
+is available, call it first; `subagent` is available on the next request. The
+guide returns the packaged council-mode skill and the references it asks you to
+read, so it also works when Pi runs with `--no-skills`.
 
 Parse the invocation yourself. The flags below are conventions, not runtime
 options. Record a brief with the question, scope, non-goals, evidence targets,
@@ -48,7 +51,7 @@ path if the run is not resumable.
 ## Run the protocol
 
 Use the canonical workflow, structured advisor contracts, aggregate pass receipts,
-and memo requirements in `skills/council-mode/SKILL.md`. Keep the parent as the
+and memo requirements from the council guide. Keep the parent as the
 only synthesizer and decision maker. Do not introduce a chair advisor, peer chat,
 or transcript sharing.
 
@@ -57,4 +60,4 @@ polling, and write its required final memo.
 
 Question and options from the slash command invocation:
 
-$@
+$@

package/dist/extensions/pi-subagents/prompts/parallel-review.md

@@ -28,7 +28,7 @@ Choose or adapt angles when the work calls for it:
 
 Prefer three strong reviewers over many vague reviewers.
 
-Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete, current, caused or made reachable by the target diff, and supported by source proof, a test or repro, or a contract contradiction. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
+Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete and current within the named review target, and supported by source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
 
 Do not default first-pass reviews to `blockers only`. That phrase is valid only for final pre-merge re-checks after P1/P2 findings are already inventoried, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred.
 
@@ -55,4 +55,4 @@ Additional review target or focus from the slash command invocation:
 
 $@
 
-If the invocation provides a URL, issue link, file path, plan path, or freeform focus, treat it as the primary review scope. Read or fetch that target before assigning reviewer angles, and pass the target explicitly into each reviewer task.
+If the invocation provides a URL, issue link, file path, plan path, or freeform focus, treat it as the primary review scope. Read or fetch that target before assigning reviewer angles, and pass the target explicitly into each reviewer task.

package/dist/extensions/pi-subagents/prompts/review-loop.md

@@ -8,7 +8,7 @@ Use the `subagent` tool. Keep the parent session as the loop controller and fina
 
 Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a worker pass. Stop early when reviewers find no P0 findings, no P1 fixes worth doing now, and no approved P2 notes that should be handled in this loop.
 
-If the invocation includes an implementation request, first launch one async `worker` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front with `workflowScript` when it is already clear, or continued as follow-up single-agent runs after each async completion. For an initial workflowScript, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
+If the invocation includes an implementation request, first launch one async `worker` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front as a workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true })`) when it is already clear, or continued as follow-up single-agent runs after each async completion. For an initial workflow script, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
 
 As a conservative orchestration policy, do not set a hard `toolBudget` or tight `usageBudget` on implementation or fix workers. A default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model, so count or usage limits still do not measure delivery safety. Give each writer a narrow delivery slice and an outer elapsed deadline with enough margin. Before that deadline, request a checkpoint after the current tool returns with changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be the checkpoint trigger.
 
@@ -44,4 +44,4 @@ On completion, inspect the final diff yourself, run or confirm focused validatio
 
 Additional target, implementation request, max-iteration cap, or review focus from the slash command invocation:
 
-$@
+$@

package/dist/extensions/pi-subagents/runner-peer-loader.mjs

@@ -0,0 +1,21 @@
+import { pathToFileURL } from "node:url";
+
+let aliases = {};
+let nativeRunner = false;
+const redirected = new Set([
+	"@earendil-works/pi-tui",
+]);
+
+export function initialize(data) {
+	aliases = data?.aliases ?? {};
+	nativeRunner = data?.nativeRunner === true;
+}
+
+export function resolve(specifier, context, nextResolve) {
+	const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
+	if (alias) {
+		const target = pathToFileURL(alias).href;
+		return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
+	}
+	return nextResolve(specifier, context);
+}

package/dist/extensions/pi-subagents/runner-peer-preload.mjs

@@ -0,0 +1,30 @@
+import * as nodeModule from "node:module";
+import { pathToFileURL } from "node:url";
+
+const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
+const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
+const redirected = new Set([
+	"@earendil-works/pi-tui",
+]);
+
+if (typeof nodeModule.registerHooks === "function") {
+	nodeModule.registerHooks({
+		resolve(specifier, context, nextResolve) {
+			const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
+			if (alias) {
+				const target = pathToFileURL(alias).href;
+				return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
+			}
+			try {
+				return nextResolve(specifier, context);
+			} catch (error) {
+				if (nativeRunner && specifier.endsWith(".js")) return nextResolve(`${specifier.slice(0, -3)}.ts`, context);
+				throw error;
+			}
+		},
+	});
+} else {
+	nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
+		data: { aliases, nativeRunner },
+	});
+}

package/dist/extensions/pi-subagents/scripts/build-package.mjs

@@ -0,0 +1,79 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const output = path.join(root, "dist-pkg");
+const expectedRootModules = [
+	"install.mjs",
+	"runner-peer-preload.mjs",
+	"runner-peer-loader.mjs",
+	"inspector-runner.mjs",
+	"async-retention-discovery-worker.mjs",
+];
+const staticFiles = [
+	"README.md",
+	"CHANGELOG.md",
+	"LICENSE",
+];
+const expectedDirectories = ["agents", "skills", "prompts", "docs"];
+
+for (const relativePath of [
+	...expectedRootModules,
+	...staticFiles,
+	...expectedDirectories,
+	"index.ts",
+	"src",
+	"package.json",
+	"tsconfig.json",
+	"tsconfig.build.json",
+]) {
+	if (!fs.existsSync(path.join(root, relativePath))) throw new Error(`Missing package input: ${relativePath}`);
+}
+
+fs.rmSync(output, { recursive: true, force: true });
+const tsc = path.join(root, "node_modules", "typescript", "bin", "tsc");
+if (!fs.existsSync(tsc)) throw new Error("Missing TypeScript compiler; run npm install first");
+execFileSync(process.execPath, [tsc, "-p", path.join(root, "tsconfig.build.json")], { cwd: root, stdio: "inherit" });
+
+const runnerBootstrap = fs.readFileSync(path.join(output, "src/runs/background/subagent-runner-bootstrap.js"), "utf8");
+if (!runnerBootstrap.includes('import("./subagent-runner.js")')) {
+	throw new Error("Compiled runner bootstrap must dynamically import the heavy execution module");
+}
+if (/^import\s+.*["']\.\/subagent-runner\.js["'];?$/m.test(runnerBootstrap)) {
+	throw new Error("Compiled runner bootstrap must not statically import the heavy execution module");
+}
+
+const rootModules = fs.readdirSync(root).filter((name) => name.endsWith(".mjs"));
+for (const relativePath of [...rootModules, ...staticFiles]) {
+	fs.copyFileSync(path.join(root, relativePath), path.join(output, relativePath));
+}
+for (const relativePath of expectedDirectories) {
+	fs.cpSync(path.join(root, relativePath), path.join(output, relativePath), { recursive: true });
+}
+
+const sourcePackage = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+if (sourcePackage.private !== true) throw new Error("The source package must remain private; publish only ./dist-pkg");
+const copyFields = [
+	"name", "version", "description", "author", "license", "repository", "homepage", "bugs",
+	"bin", "dependencies", "peerDependencies", "peerDependenciesMeta", "engines", "keywords",
+];
+const publishedPackage = { type: sourcePackage.type };
+for (const field of copyFields) {
+	if (sourcePackage[field] !== undefined) publishedPackage[field] = sourcePackage[field];
+}
+publishedPackage.types = "./index.d.ts";
+publishedPackage.exports = Object.fromEntries(Object.entries(sourcePackage.exports).map(([name, target]) => {
+	if (typeof target !== "string" || !target.endsWith(".ts")) throw new Error(`Unsupported package export ${name}: ${String(target)}`);
+	const base = target.slice(0, -3);
+	for (const extension of [".js", ".d.ts"]) {
+		if (!fs.existsSync(path.join(output, `${base.slice(2)}${extension}`))) throw new Error(`Missing compiled package export: ${base}${extension}`);
+	}
+	return [name, { types: `${base}.d.ts`, default: `${base}.js` }];
+}));
+publishedPackage.pi = {
+	...sourcePackage.pi,
+	extensions: ["./index.js"],
+};
+fs.writeFileSync(path.join(output, "package.json"), `${JSON.stringify(publishedPackage, null, 2)}\n`);

package/dist/extensions/pi-subagents/skills/council-mode/SKILL.md

@@ -32,7 +32,7 @@ Pass 1 is independent reports. Pass 2 is one cross-exam. Run Pass 3 only when `-
 
 1. Write the council brief: question, scope, non-goals, evidence targets, roster, known advisor context modes, and pass cap.
 2. Tell the user the roster, context modes, and pass cap.
-3. Launch one async `workflowScript` with `runs.all` for Pass 1. Use stable keys, `phase: "Council pass 1"`, concise labels, and `output: false` unless separate artifacts are useful. Set `context` only when the profile context is known or a fallback rule requires it.
+3. Launch one async workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true, async: true })`) with `runs.all` for Pass 1. Use stable keys, `phase: "Council pass 1"`, concise labels, and `output: false` unless separate artifacts are useful. Set `context` only when the profile context is known or a fallback rule requires it.
 4. Return one aggregate Pass 1 receipt. On completion, tell the user completion count, agreement count, dispute count, and whether Pass 2 is needed.
 5. Synthesize the claim matrix in the parent: agreements, disputed claims, missing proof, owner decisions, and at most five material relay claims per advisor.
 6. For Pass 2, tell the user which claims are relayed and why they matter. Resume each advisor with a curated challenge packet. A resume needs a retained run id and task; it excludes `agent` and rejects `gate`. Record each new run id; Pass 3 resumes those latest ids with new stable keys.
@@ -56,4 +56,4 @@ The memo states:
 - confidence and what would change the decision
 - roster, passes, fallbacks, and known advisor context modes
 
-Identify advisors by profile name. State when fallback `oracle` was forked and context-aware. Escalate to a writer only after the memo and only when the user requests it.
+Identify advisors by profile name. State when fallback `oracle` was forked and context-aware. Escalate to a writer only after the memo and only when the user requests it.

package/dist/extensions/pi-subagents/skills/pi-subagents/SKILL.md

@@ -1,28 +1,25 @@
 ---
 name: pi-subagents
 description: |
-  Delegate to builtin or custom subagents for single-agent handoffs, parallel
-  review, scripted chaining, async work, forked context, and coordinated
-  workflows. Use when one parent agent should stay in control while children
-  supply focused context, planning, review, or execution.
+  Technical guidance for operator-requested delegation to builtin or custom
+  subagents: bounded handoffs, parallel review, scripted workflows, async work,
+  forked context, isolation, and coordinated execution.
 ---
 
 # Pi Subagents
 
-Choose a mode:
-
-- **Direct mode:** For tiny or focused work, the parent handles the task
-  directly; a single bounded child handoff is fine. Skip workflow ceremony.
-- **Orchestrator mode:** For substantial or delegated work, the parent is the
-  supervisor, arbiter, and authority holder—not the routine primary doer.
-  Subagents may own planning/design, scouting, implementation,
-  simplification/challenge, validation, and review as useful. The parent keeps
-  user intent, constraints, authority, routing, arbitration, final acceptance,
-  and publication.
-- A useful loop for substantial work is **writer → challenge/simplify → review**;
-  the parent arbitrates between steps, and tiny tasks can skip it.
-- Direct parent edits during orchestrator mode should be intentional, small
-  interventions with a brief reason.
+The parent works directly by default. Invoke subagents only when the operator
+requested delegation in the current request or through applicable user/project
+instructions. Task size, complexity, risk, tool-call count, recipe fit, or an
+available specialist does not independently authorize delegation.
+
+Once authorized, choose the smallest bounded shape that earns its token and
+elapsed-time overhead through concrete evidence, independent review,
+specialization, useful parallelism, or needed isolation. A single child is
+valid; writer, challenge, and review stages must each earn their overhead rather
+than becoming default ceremony. The parent keeps user intent, constraints,
+routing, arbitration, decisions, final acceptance, and publication authority,
+and may perform the work directly where it is the most efficient owner.
 
 Children do not spawn subagents unless the parent explicitly delegated fanout
 and their resolved `tools` allow `subagent`.
@@ -32,24 +29,43 @@ and their resolved `tools` allow `subagent`.
 | Need | Use |
 | --- | --- |
 | One bounded task for one child | direct `{ agent, task }` |
-| JavaScript control flow or data-dependent branching; sequence, fanout, retry, rolling fanout, or aggregation | `workflowScript` with `runs.run(...)` / `runs.all(...)` |
-| A broad plan split into visible narrow stages per lane | `workflowScript` with `runs.lanes([{ key, stages: [...] }])` |
+| JavaScript control flow or data-dependent branching; sequence, fanout, retry, rolling fanout, or aggregation | a workflow script with `runs.run(...)` / `runs.all(...)` |
+| A broad plan split into visible narrow stages per lane | a workflow script with `runs.lanes([{ key, stages: [...] }])` |
 | Independent worktree or repository lanes | `references/multi-lane-orchestration.md` |
 | Council of advisors | `../council-mode/SKILL.md` |
 | Management, status, steering, authoring, or inspection | `action` |
 
-`workflowScript` is code-driven: `runs.run(...)` for keyed steps,
+To launch a workflow script, write it as one ```` ```js workflow ```` fenced
+block in your reply, then call `subagent({ workflow: true, ... })` in the same
+reply. Use `workflow: "./path/to/script.js"` for a script file and
+`workflow: "<name>"` for a named resource.
+
+A workflow script is code-driven: `runs.run(...)` for keyed steps,
 `runs.all([...])` for fanout, plain JavaScript for branching and aggregation.
 Keep scripts portable: use top-level `await`, plain helpers, or explicit Promise
 chains, not nested async helpers. Legacy top-level `chain` / `tasks` inputs and
-durable `.chain.md` execution are inspection or migration material only.
+durable `.chain.md` execution are inspection or migration material only, except
+that `disabledFeatures: ["workflow-scripts"]` replaces scripts with top-level
+`chain` and `tasks` (see [configuration](../../docs/configuration.md#chain-and-tasks-without-workflow-scripts)).
 
-Use `runs.lanes(...)` only inside a `workflowScript`, not as a top-level mode,
+Use `runs.lanes(...)` only inside a workflow script, not as a top-level mode,
 when a broad, predeclared plan benefits from visible per-lane stages; otherwise
 use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
 example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
 bounded, but do not add stages or ceremony just to satisfy this skill.
 
+When composing `runs.run(...)`, `runs.all(...)`, or `runs.lanes(...)`, always
+supply a short verb + behavior display `label` derived from the task, unless
+the user supplied an explicit label; preserve that label. Keep the stable
+machine `key` independent (for example, `issue2011-writer` with
+`label: "Fix workflow steering"`). For `runs.lanes`, put labels on stage
+items, not lane objects. Use stage-appropriate labels for reviews and retained-child
+follow-ups too (for example, `Review workflow steering`). Generate labels in
+the orchestrator while composing the launch—no extra model call, runtime
+generator, or schema change. Native direct `{ agent, task }` calls have no
+top-level `label` parameter; do not invent one or wrap a tiny single task in
+a workflow just to label it.
+
 Use async/background by default. Set `async:false` only when the parent must
 block. Final reviews, validation gates, oracle checks, and publication checks
 stay async.
@@ -71,6 +87,8 @@ that runner explicitly supports the option.
 
 ## Read the reference for the branch
 
+For exact API fields and worked examples, call `subagent({action:"guide",topic:"tool-reference"})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
+
 | Branch | Read |
 | --- | --- |
 | Delegate or choose roles, prompts, models, or slash commands | `references/prompting-and-roles.md` |
@@ -80,9 +98,9 @@ that runner explicitly supports the option.
 | List, create, edit, disable, eject, or expose agents/RPC | `references/management-authoring-rpc.md` |
 | Check safety constraints, recipes, or error handling | `references/constraints-and-recipes.md` |
 
-For complex work, read `prompting-and-roles.md` and `execution-controls.md`, then
-load `review-and-validation.md` and `constraints-and-recipes.md` before launch or
-review.
+For an authorized complex delegated workflow, read `prompting-and-roles.md` and
+`execution-controls.md`, then load `review-and-validation.md` and
+`constraints-and-recipes.md` before launch or review.
 
 ## Operating rules
 
@@ -90,6 +108,7 @@ review.
 - Keep the parent on the ordinary strong default model. Route workers/scouts to a fast capable tier, serious reviews to a strong tier, and top reasoning to bounded read-only critique.
 - Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
 - Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
+- Before launching a writer for substantial mutation work, classify it as single-seam or multi-seam and partition multi-seam work across exclusive component owners, gates, and durable handoffs before an integration-only owner. See `references/multi-lane-orchestration.md`.
 - For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. See `references/multi-lane-orchestration.md` for lane mechanics.
 - Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
 - Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
@@ -101,4 +120,4 @@ review.
 - Preserve parent authority and escalate unresolved choices.
 - Treat receipts, CI, review bots, and external-run records as evidence, not authority.
 - For backlog maintenance, releases, merge queues, or other public-repo mutation policy, load the matching user/project skill. This package defines delegation primitives, not private policy.
-- As a conservative orchestration policy, do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
+- As a conservative orchestration policy, do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.

package/dist/extensions/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md

@@ -6,10 +6,13 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
 
 - **Explicit forking requires a persisted parent session.** If the current session
   does not have a persisted session file or current leaf, explicit `context: "fork"`
-  fails. An agent-level `defaultContext: fork` is a preference: packaged `worker`,
-  `oracle`, and `advisor` fall back to `fresh` when those fork preconditions are not
+  fails. An agent-level `defaultContext: fork` is a preference: packaged `oracle`
+  and `advisor` fall back to `fresh` when those fork preconditions are not
   met yet. Use `context: "fresh"` when you do not want a fork even after the parent
   session exists.
+- **Packaged workers start fresh.** `worker` defaults to fresh context so its brief,
+  not the parent's unfinished agenda, controls the implementation. Pass explicit
+  `context: "fork"` when inherited conversation history is required.
 - **Forked runs inherit parent history.** They are branched threads, not fresh
   filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
 - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
@@ -31,8 +34,8 @@ For durable evidence, copy only the final summary to session memory, a PR body/c
 
 ## Best Practices
 
-- Run subagents asynchronously by default; direct one-child execution is enough for one bounded task, while `workflowScript` is the composition surface for JavaScript control flow and data-dependent branching. Use `async: false` only when the parent must block. See `references/execution-controls.md` → Async/background for wait semantics.
-- For a predeclared broad plan split into visible narrow stages, use `runs.lanes([...])` inside `workflowScript`; use raw `runs.run(...)`/`runs.all(...)` for conditional or rolling flows. See [`execution-controls.md`](execution-controls.md#parallel-sequential-lanes).
+- Run subagents asynchronously by default; direct one-child execution is enough for one bounded task, while a workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true })`) is the composition surface for JavaScript control flow and data-dependent branching. Use `async: false` only when the parent must block. See `references/execution-controls.md` → Async/background for wait semantics.
+- For a predeclared broad plan split into visible narrow stages, use `runs.lanes([...])` inside a workflow script; use raw `runs.run(...)`/`runs.all(...)` for conditional or rolling flows. See [`execution-controls.md`](execution-controls.md#parallel-sequential-lanes).
 - Keep one writer per cwd/worktree. Parallelize reading, review, and validation; concurrent writers need isolated worktrees. Give every child a cold-start packet with its goal, target/ref, authority, context, success criteria, validation, output, and stop rules.
 - Keep tasks narrow and standalone; do not rely on issue numbers, broad globs, or supervisor round-trips to supply missing context.
 - Keep authority with the parent. Escalate unapproved product, scope, architecture, merge, credential, or release decisions; checks, receipts, and review bots are evidence, not authority.
@@ -52,15 +55,16 @@ This reference keeps cross-cutting policy and failure handling. Load the matchin
 | Independent lanes, repositories, worktrees, and handoffs | [`references/multi-lane-orchestration.md`](multi-lane-orchestration.md) |
 | Agent management, file authoring, prompt integration, or RPC | [`references/management-authoring-rpc.md`](management-authoring-rpc.md) |
 
-Choose the smallest recipe that fits:
+After delegation is operator-authorized, choose the smallest recipe that earns
+its overhead. Recipes select a shape; they do not authorize delegation:
 
 - **Recon → plan → implement:** run one focused `scout`, then one `worker` that consumes its findings.
-- **Non-trivial implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, scout load-bearing code, plan when useful, use one writer, run fresh review/validation, apply only accepted fixes with one writer, then inspect direct evidence and the final diff before parent acceptance. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
+- **Implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, and use a bounded scout, writer, or fresh reviewer only where the requested delegation benefits from that stage. Keep one writer, inspect direct evidence, and require every added stage to earn its overhead. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
 - **Parallel analysis:** fan out only independent read/review/validation work, or isolate each writer in its own worktree. Never run concurrent writers in one checkout.
 
 ## Error Handling
 
-- **Unknown agent:** run `subagent({ action: "list" })`; check scope/precedence and author new orchestration with `workflowScript`, not legacy chains.
+- **Unknown agent:** run `subagent({ action: "list" })`; check scope/precedence and author new orchestration as a workflow script, not legacy chains.
 - **Setup, discovery, or intercom confusion:** run `subagent({ action: "doctor" })`.
 - **Max subagent depth exceeded:** flatten the workflow or raise `maxSubagentDepth` in config.
 - **Missing session file for a fork:** persist the parent session before using `context: "fork"`.