@ferris1225/pi-subagents 4.3.8 → 4.3.9

package/CHANGELOG.md

@@ -4,6 +4,23 @@ Published versions of `@ferris1225/pi-subagents`. Unpublished numbers
 (`4.2.3`, `4.2.6`, `4.2.9`–`4.2.11`) never shipped on npm; their changes
 landed in the next published release.
 
+## 4.3.9
+
+- Add optional bounded stable `phaseId` and exact declarative write `scope` claims to single
+  and parallel dispatches. Phase identity is immutable across task rewrites and resume; scope
+  is monotonic across retained generations and survives durable v1 restore. Exact task+cwd
+  remains the compatibility fallback.
+- Reject deterministic duplicates and declared writer-scope conflicts before parallel batch
+  allocation. Fresh single and resumed writers also reject normalized absolute scope overlap
+  with active leases, without requiring equal caller cwd. Parallel calls that omit scope remain
+  compatible and explicitly report `independence not verified`; declared claims do not prove
+  natural-language task independence. Scope is conflict metadata, not permissions or a sandbox.
+- Add the advisory-only `subagent_risk` tool. Without a model call it resolves the repository
+  root, reads root-relative tracked and untracked changes from `HEAD`, and applies fixed
+  explainable rules for concurrency, trust-boundary, persistence-compatibility, and
+  failure-cancellation risk. It propagates cancellation, and suggests but never dispatches or
+  requires a Sentinel review.
+
 ## 4.3.8
 
 - Restore `sentinel` as an optional fresh-context reviewer instead of the mandatory

package/README.md

@@ -12,12 +12,13 @@ once and your main agent delegates on its own.
 
 ## What's new
 
-**4.3.8** — `sentinel` is back as an optional fresh-context reviewer. It reads a
-completed diff with no memory of how it was written and returns only evidence-backed
-defects and test gaps; the main agent dispatches it for diffs that touch concurrency,
-trust boundaries, persistence, or failure paths, never as a fixed pre-commit ritual, and
-routes a finding back to the thread that owns the change. Configs written by
-4.3.5–4.3.7 adopt it once; a deliberate disable sticks.
+**4.3.9** — dispatch admission now accepts bounded stable `phaseId` identities and exact
+declarative write `scope` claims. Fresh/resumed writers are checked against active leases;
+parallel batches preflight deterministic duplicates and all declared scope conflicts before
+allocation. Omitted scopes remain compatible; a parallel call that omits `scope` reports
+`independence not verified`. Declared claims do not prove natural-language task independence.
+The no-model-call `subagent_risk` advisory classifies changed tracked and untracked paths
+with fixed, documented rules before main decides whether a Sentinel review is worthwhile.
 
 See [CHANGELOG.md](./CHANGELOG.md).
 
@@ -50,9 +51,10 @@ back — with you. This extension owns them:
   handoff costs. Every brief carries the objective and done condition, exact paths,
   facts already established with citations, boundaries, and the expected output, so a
   child starts from evidence instead of re-deriving it.
-- One normalized task and working directory owns its phase: an exact duplicate of an
-  active run is rejected, and an exact re-run of a finished brief with retained
-  context is rejected in favor of resuming it, so the same work is never bought twice.
+- A stable `phaseId` owns a logical phase in one resolved working directory even if
+  its task wording changes. IDs are 1–80 ASCII letters, numbers, or `._:-`, starting
+  with a letter or number, so lease output stays single-line. Exact normalized task+cwd
+  remains the backward-compatible fallback for old calls.
 - Follow-up work stays on the same thread: `steer` a running phase, `resume` or
   `park` a thread with its retained context, `stop` a phase the evidence made moot.
 - Background completions and stop results arrive at the next parent model boundary;
@@ -122,15 +124,30 @@ what the injected delegation guidance produces when the main agent dispatches fo
 ```ts
 // One task
 subagent({
+  phaseId: "cache-invalidation-fix",
   agent: "artisan",
   task: "Fix the cache invalidation bug in src/cache, add regression tests, run the checks.",
+  scope: {
+    paths: ["src/cache"],
+    symbols: [{ path: "test/cache.test.ts", name: "invalidates stale entries" }],
+  },
 });
 
 // Parallel only when each scope independently justifies a child
 subagent({
   tasks: [
-    { agent: "scout", task: "Research current provider API limits in primary sources and cite URLs." },
-    { agent: "artisan", task: "Fix config validation in src/config.ts and its tests." },
+    {
+      agent: "artisan",
+      phaseId: "provider-docs",
+      task: "Update provider limits documentation from the established API citations.",
+      scope: { paths: ["docs/provider-limits.md"] },
+    },
+    {
+      agent: "artisan",
+      phaseId: "config-validation",
+      task: "Fix config validation in src/config.ts and its tests.",
+      scope: { paths: ["src/config.ts", "test/config.test.ts"] },
+    },
   ],
 });
 ```
@@ -140,13 +157,13 @@ independent unit in one `tasks` array. The runtime paces execution instead, runn
 half the machine's cores with a 4–6 child-process bound; wider batches queue and
 start automatically as slots free.
 
-A run leases its normalized task and resolved working directory across agent
-names. Dispatching the same pair again while the run is active is rejected and
-names the existing run id. Once the run has finished in this session and still
-holds its retained session, the same pair is rejected too, pointing at
-`subagent_control resume` — the thread that already did the work continues for a
-fraction of a fresh run — or at restating the brief with what changed. Matching is
-exact, never fuzzy.
+A run leases its stable, single-line `phaseId` in the resolved working directory.
+Rewording the task with the same `phaseId` is rejected and names the existing run.
+The id remains immutable across resume. Calls that omit `phaseId` keep the old exact
+normalized task+cwd behavior; consequently, equal task text with different phase ids is
+still rejected by that fallback. Matching is deterministic, never fuzzy, embedding-based,
+or inferred from natural language. Active leases win over matching settled threads when
+the runtime chooses which owner to report.
 
 Because queueing is pacing rather than refusal, it is always reported as such.
 Dispatch confirmations name each waiting run's real reason — waiting for a free
@@ -190,8 +207,49 @@ paths, or when the checks cannot prove the change. It is never a fixed pre-commi
 ritual. A finding is evidence, not an order: main routes it to the thread that owns
 the change with `subagent_control resume`, or fixes it inline when that is cheaper.
 
+`subagent_risk({})` is an advisory-only, no-model-call check over tracked and untracked
+changes relative to `HEAD`. It resolves the repository root first, so a nested `cwd` still
+returns repository-root-relative paths, including untracked files outside that subdirectory.
+Its fixed case-insensitive path-token rules flag:
+`concurrency` (`thread`, `queue`, `parallel`, `dispatch`, locks/races and related tokens);
+`trust-boundary` (`auth`, credentials, permissions, policy, secrets, sandbox, security, trust, tokens);
+`persistence-compatibility` (durable state, manifests, migrations, restore, schemas,
+serialization/storage); and `failure-cancellation` (abort, cancel, errors/failures, recovery,
+retry, stop, timeout). It returns the changed paths, matched categories, and whether those
+rules suggest Sentinel. If Git or `HEAD` is unavailable, it reports advisory unavailable; an
+aborted tool call propagates cancellation instead of converting it to an advisory result. It
+never blocks, starts a child, or automatically dispatches Sentinel.
+
+This classifier is intentionally conservative and explainable: it only sees path names, so
+it can produce false positives and miss risky behavior hidden behind neutral names. Main
+still decides whether review pays from the actual diff, test evidence, handoff cost, and the
+complete conversation. The runtime can enforce explicit phase/scope admission, but cannot
+safely force the natural-language judgment of whether work is worth delegating.
+
 ## Parallel edits
 
+`scope` is declarative admission metadata for expected writes, not access control. `paths`
+contains exact file or directory paths; `symbols` contains exact `{ path, name }` claims.
+Paths resolve from each task's caller-facing cwd and use case-insensitive comparison on
+Windows. Wildcard `*` and `?` inputs are rejected; other punctuation is treated literally,
+so paths such as `app/[id]/page.tsx` are valid exact claims. A path claim overlaps the same
+path, an ancestor/descendant path, or a symbol under that path; identical path+symbol
+claims overlap, while two different symbols in the same file may run together.
+
+Fresh single dispatches and resumes check a declared writer scope against active, parked,
+resuming, interrupting, or settling writer leases before allocating a generation. Scope
+comparison uses normalized absolute claims rather than requiring equal caller cwd, so a
+repo-root claim still conflicts with the same path claimed from a nested cwd. Settled
+threads do not block a later phase solely because it edits the same scope.
+
+Before allocating any run in a parallel call, the runtime also rejects deterministic phase
+duplicates within the batch or against existing active/retained threads, then compares
+declared writer scopes across the whole batch. A definite conflict rejects the whole batch
+with zero starts. Parallel calls without `scope` remain valid, but their tool result and
+launch receipt say `independence not verified`; that means the contract lacked enough
+metadata, not that overlap was proved safe. Single calls never make a batch-independence
+claim. The existing shared-checkout writer lane remains the final serialization boundary.
+
 - Single tasks use your checkout. Every parallel write-capable agent (`artisan`,
   `steward`, and custom writers) defaults to a detached Git worktree, so
   parallel writers run at the same time. Worktree mode needs a committed `HEAD`;
@@ -230,7 +288,7 @@ Every dispatch returns a stable `#id`, which is the handle for the thread tools:
 
 | Tool               | What it does |
 | ------------------ | ------------ |
-| `subagent_control` | `steer` a running RPC attempt with additional evidence/guidance, continuing the same thread with it when the thread has settled or is parked; `resume` a parked/settled thread with an optional appended `objective`; `park` a running thread at a stable checkpoint, keeping its session and worktree for a later resume. |
+| `subagent_control` | `steer` a running RPC attempt with additional evidence/guidance, continuing the same thread with it when the thread has settled or is parked; `resume` a parked/settled thread with an optional appended `objective` and additive `scope`; `park` a running thread at a stable checkpoint, keeping its session and worktree for a later resume. |
 | `subagent_stop`    | Destructively cancel, deliver partial output, and retire the thread. Steering and follow-up messages still queued in the child are dropped so nothing can revive it later. |
 
 ```ts
@@ -239,6 +297,13 @@ subagent_control({ action: "park", id: 7 });
 subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
 ```
 
+A fresh dispatch stores `phaseId` and normalized `scope` on its stable thread and durable
+v1 record. `resume` always keeps the thread's phase id. An optional resume `scope` adds
+normalized claims to the retained scope; it cannot shrink or clear prior claims, so edits
+already present in a retained worktree stay covered by admission. Resume also rechecks the
+unioned scope against other active writer leases before starting a generation. Existing v1
+manifests without these optional fields remain readable.
+
 `steer` requires a nonblank `objective`. While the child RPC is running, it adds
 guidance to the current phase without replacing the original task. If the thread has
 already reached `completed`, `failed`, or `parked` — including a generation that settles

package/index.ts

@@ -24,6 +24,7 @@ import { getConfigPath, loadConfig } from "./src/configuration/config.ts";
 import { runSetup } from "./src/configuration/setup.ts";
 import { discoverAgents } from "./src/delegation/agents.ts";
 import { registerSubagentTool } from "./src/delegation/dispatch.ts";
+import { registerSubagentRiskTool } from "./src/delegation/risk.ts";
 import { buildDelegationDirective } from "./src/delegation/prompt.ts";
 import { currentSubagentDepth } from "./src/execution/spawn.ts";
 import { createRuntime } from "./src/lifecycle/runtime.ts";
@@ -69,6 +70,7 @@ export default function (pi: ExtensionAPI): void {
 	});
 
 	registerSubagentTool(pi, runtime);
+	registerSubagentRiskTool(pi);
 	registerLookupTools(pi, runtime);
 
 	pi.registerCommand("subagents-setup", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.3.8",
+  "version": "4.3.9",
   "description": "A managed sub-agent team for pi: scout, artisan, steward, and sentinel roles, durable threads, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

package/src/delegation/agents.ts

@@ -54,6 +54,7 @@ export const SUBAGENT_TOOL_NAMES = [
 	"subagent",
 	"subagent_control",
 	"subagent_stop",
+	"subagent_risk",
 ] as const;
 const SUBAGENT_TOOL_NAME_SET = new Set<string>(SUBAGENT_TOOL_NAMES);
 

package/src/delegation/dispatch.ts

@@ -7,10 +7,11 @@
  */
 
 import { StringEnum, type Usage } from "@earendil-works/pi-ai";
+import { resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { discoverAgents } from "./agents.ts";
+import { discoverAgents, isWriteCapableAgent, type AgentConfig } from "./agents.ts";
 import { loadConfig } from "../configuration/config.ts";
 import { formatCompletionBlock, formatUsage } from "../presentation/format.ts";
 import {
@@ -22,7 +23,17 @@ import {
 	sumUsage,
 	type RunWaitReason,
 } from "../presentation/monitor.ts";
-import { formatPhaseLeaseReceipt } from "./prompt.ts";
+import { findDuplicateDispatch, formatParallelScopeAdmissionNote, formatPhaseLeaseReceipt } from "./prompt.ts";
+import {
+	findPhaseScopeOverlap,
+	findWriterLeaseScopeOverlap,
+	normalizePhaseId,
+	normalizePhaseScope,
+	PHASE_ID_MAX_LENGTH,
+	PHASE_ID_PATTERN_SOURCE,
+	type PhaseScope,
+	type PhaseScopeInput,
+} from "./phase-scope.ts";
 import type { SubagentRuntime, SubagentThread } from "../lifecycle/runtime.ts";
 import { createBackgroundDispatcher } from "../lifecycle/thread-lifecycle.ts";
 import {
@@ -53,6 +64,23 @@ const IsolationSchema = Type.Optional(
 	StringEnum(["shared", "worktree"] as const, { description: ISOLATION_DESCRIPTION }),
 );
 
+const PhaseIdSchema = Type.Optional(Type.String({
+	minLength: 1,
+	maxLength: PHASE_ID_MAX_LENGTH,
+	pattern: PHASE_ID_PATTERN_SOURCE,
+	description: "Stable logical phase id: 1-80 ASCII letters, numbers, or ._:- characters, starting with a letter or number. Reuse it when task wording changes so duplicate fresh dispatches are rejected.",
+}));
+const ScopeSchema = Type.Optional(Type.Object({
+	paths: Type.Optional(Type.Array(Type.String({
+		...NON_BLANK_TASK_OPTIONS,
+		description: "Exact file or directory write claim resolved from the caller-facing cwd; wildcard * and ? are rejected, while other punctuation is literal.",
+	}))),
+	symbols: Type.Optional(Type.Array(Type.Object({
+		path: Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Exact file path resolved from the caller-facing cwd." }),
+		name: Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Exact symbol name claimed for writing." }),
+	}))),
+}, { description: "Declarative write-conflict metadata for admission, not filesystem permissions or a sandbox. If present, at least one valid claim is required." }));
+
 const WaitSchema = Type.Optional(
 	Type.Boolean({
 		description:
@@ -69,6 +97,8 @@ const TaskItem = Type.Object({
 		...NON_BLANK_TASK_OPTIONS,
 		description: TASK_BRIEF_DESCRIPTION,
 	}),
+	phaseId: PhaseIdSchema,
+	scope: ScopeSchema,
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	isolation: IsolationSchema,
 });
@@ -78,6 +108,8 @@ const SubagentParams = Type.Object({
 	task: Type.Optional(
 		Type.String({ ...NON_BLANK_TASK_OPTIONS, description: `${TASK_BRIEF_DESCRIPTION} (single mode)` }),
 	),
+	phaseId: PhaseIdSchema,
+	scope: ScopeSchema,
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Independently justified, disjoint phases for parallel execution" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 	isolation: IsolationSchema,
@@ -109,6 +141,91 @@ export function defaultIsolationMode(
 	return mode === "parallel" && writeCapable ? "worktree" : "shared";
 }
 
+interface PreparedDispatchTask {
+	index: number;
+	agent: string;
+	task: string;
+	cwd: string;
+	phaseId?: string;
+	scope?: PhaseScope;
+	isolation?: IsolationMode;
+	writeCapable: boolean;
+}
+
+function prepareDispatchTasks(
+	tasks: ReadonlyArray<{ agent: string; task: string; cwd?: string; phaseId?: string; scope?: PhaseScopeInput; isolation?: IsolationMode }>,
+	callerCwd: string,
+	agents: readonly AgentConfig[],
+): PreparedDispatchTask[] {
+	return tasks.map((item, index) => {
+		const cwd = resolve(callerCwd, item.cwd ?? ".");
+		const agent = agents.find((candidate) => candidate.name === item.agent);
+		return {
+			index,
+			agent: item.agent,
+			task: item.task,
+			cwd,
+			phaseId: normalizePhaseId(item.phaseId),
+			scope: normalizePhaseScope(item.scope, cwd),
+			isolation: item.isolation,
+			writeCapable: agent ? isWriteCapableAgent(agent) : true,
+		};
+	});
+}
+
+function parallelAdmissionConflict(
+	tasks: readonly PreparedDispatchTask[],
+	threads: Iterable<SubagentThread>,
+): string | undefined {
+	for (let leftIndex = 0; leftIndex < tasks.length; leftIndex++) {
+		for (let rightIndex = leftIndex + 1; rightIndex < tasks.length; rightIndex++) {
+			const left = tasks[leftIndex]!;
+			const right = tasks[rightIndex]!;
+			const duplicate = findDuplicateDispatch([{
+				id: left.index,
+				agentName: left.agent,
+				task: left.task,
+				phaseId: left.phaseId,
+				cwd: left.cwd,
+				state: "queued",
+			}], right.task, right.cwd, right.phaseId);
+			if (duplicate) {
+				return `deterministic duplicate between tasks[${left.index}] and tasks[${right.index}]`;
+			}
+		}
+	}
+	const leases = [...threads];
+	for (const task of tasks) {
+		const duplicate = findDuplicateDispatch(leases, task.task, task.cwd, task.phaseId);
+		if (duplicate?.kind === "active") {
+			return `tasks[${task.index}] duplicates active run #${duplicate.source.id} (${duplicate.source.agentName})`;
+		}
+		if (duplicate?.kind === "settled") {
+			return `tasks[${task.index}] duplicates settled run #${duplicate.source.id} (${duplicate.source.agentName}); resume that retained thread instead`;
+		}
+	}
+	const writers = tasks.filter(
+		(task): task is PreparedDispatchTask & { scope: PhaseScope } => task.writeCapable && task.scope !== undefined,
+	);
+	for (let leftIndex = 0; leftIndex < writers.length; leftIndex++) {
+		for (let rightIndex = leftIndex + 1; rightIndex < writers.length; rightIndex++) {
+			const left = writers[leftIndex]!;
+			const right = writers[rightIndex]!;
+			const overlap = findPhaseScopeOverlap(left.scope, right.scope);
+			if (overlap) {
+				return `tasks[${left.index}] scope ${overlap.left} overlaps tasks[${right.index}] scope ${overlap.right}`;
+			}
+		}
+	}
+	for (const task of writers) {
+		const conflict = findWriterLeaseScopeOverlap(task.scope, leases);
+		if (conflict) {
+			return `tasks[${task.index}] scope ${conflict.overlap.left} overlaps run #${conflict.lease.id} scope ${conflict.overlap.right}`;
+		}
+	}
+	return undefined;
+}
+
 /** Map the child's own usage tally onto pi's tool-result `Usage`, so sub-agent
  * token spend lands in the parent's footer, /session, and RPC session totals
  * instead of being invisible. Only the total cost is known here: a child
@@ -325,11 +442,15 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		(mode: "single" | "parallel", background = false) =>
 		(results: SingleResult[]): SubagentDetails => ({ mode, results, background });
 
-	const phaseLeaseReceipt = (runIds: number[]): string =>
+	const phaseLeaseReceipt = (
+		runIds: number[],
+		options: { mode: "single" } | { mode: "parallel"; declaredScopesComplete: boolean },
+	): string =>
 		formatPhaseLeaseReceipt(
 			runIds
 				.map((runId) => runtime.threads.get(runId))
 				.filter((thread): thread is SubagentThread => thread !== undefined),
+			options,
 		);
 
 	/** Pacing note appended to dispatch confirmations whenever runs are actually
@@ -378,7 +499,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 	pi.registerTool({
 		name: "subagent",
 		label: "Subagent",
-		description: "Start paid leaf runs for broad reconnaissance or substantial self-contained work. Each normalized task+cwd owns its phase: an exact duplicate of an active run is rejected, and one of a finished run with retained context is rejected in favor of subagent_control resume. Batch scopes must be independent. wait:true returns results in-turn; otherwise completions wake main. Parallel writers default to detached Git worktrees; isolation:'shared' serializes same-repository writes.",
+		description: "Start paid leaf runs for substantial self-contained work. phaseId is a stable single-line logical identity; exact task+cwd remains the compatibility fallback. scope declares exact write-conflict metadata (not permissions or sandboxing). Fresh single and resumed writer scopes are checked against active leases; parallel batches also preflight deterministic duplicates and all declared scope overlaps before allocation. A parallel batch that omits scope reports `independence not verified`; declared claims do not prove natural-language task independence. wait:true returns results in-turn; otherwise completions wake main.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -452,10 +573,21 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			// each delegated phase. The queue paces child processes without changing
 			// phase ownership or requiring a per-call task cap.
 			if (params.tasks && params.tasks.length > 0) {
-				// Admission is synchronous and ordered; slow worktree preparation belongs
-				// to the bounded queue. Promise.all preserves caller result order while no
-				// item waits for a sibling's filesystem setup.
-				const results = await Promise.all(params.tasks.map((item) => {
+				let prepared: PreparedDispatchTask[];
+				try {
+					prepared = prepareDispatchTasks(params.tasks, ctx.cwd, agents);
+				} catch (error) {
+					throw new Error(`Parallel admission rejected: ${error instanceof Error ? error.message : String(error)} No background tasks were started.`);
+				}
+				const conflict = parallelAdmissionConflict(prepared, runtime.threads.values());
+				if (conflict) {
+					throw new Error(`Parallel admission rejected: ${conflict}. No background tasks were started.`);
+				}
+				const declaredScopesComplete = prepared.every((item) => item.scope !== undefined);
+				const admissionNote = formatParallelScopeAdmissionNote(declaredScopesComplete);
+				// Duplicate and scope admission completes for the whole batch before any
+				// startBackground call can allocate a run. Worktree preparation stays queued.
+				const results = await Promise.all(prepared.map((item) => {
 					const catalogAgent = agents.find((candidate) => candidate.name === item.agent);
 					return startBackground(
 						item.agent,
@@ -464,11 +596,16 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						defaultIsolationMode(
 							"parallel",
 							item.agent,
-							item.isolation as IsolationMode | undefined,
+							item.isolation,
 							catalogAgent ? isWorktreeCapableAgent(catalogAgent) : undefined,
 							catalogAgent?.isolation,
 						),
-						{ deliveryRoute: params.wait ? "await" : "background" },
+						{
+							deliveryRoute: params.wait ? "await" : "background",
+							phaseId: item.phaseId,
+							scope: item.scope,
+							writeCapable: item.writeCapable,
+						},
 					);
 				}));
 				const startedRuns = results.filter((result) => result.exitCode === -1);
@@ -492,9 +629,10 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					const blocks = await awaitRunResults(runtime, startedIds, signal, config.maxResultLines, ctx.cwd, makeProgress(makeDetails("parallel", true)(results)));
 					if (signal?.aborted) runtime.fallbackAwaitDelivery(startedIds);
 					else runtime.completeAwaitDelivery(startedIds);
-					const text = failureLines.length > 0
+					const resultText = failureLines.length > 0
 						? `${blocks}\n\nLaunch failures:\n${failureLines.join("\n")}`
 						: blocks;
+					const text = `${resultText}\n\n${admissionNote}`;
 					return {
 						content: [{ type: "text", text }],
 						details: makeDetails("parallel", true)(results),
@@ -502,7 +640,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					};
 				}
 				const text = [
-					phaseLeaseReceipt(startedIds),
+					phaseLeaseReceipt(startedIds, { mode: "parallel", declaredScopesComplete }),
 					...(failureLines.length > 0 ? ["Launch failures:", ...failureLines] : []),
 				].join("\n") + queuePacingNote();
 				return {
@@ -511,19 +649,37 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				};
 			}
 
-			const singleCatalogAgent = agents.find((candidate) => candidate.name === params.agent);
+			let single: PreparedDispatchTask;
+			try {
+				single = prepareDispatchTasks([{
+					agent: params.agent as string,
+					task: params.task as string,
+					cwd: params.cwd,
+					phaseId: params.phaseId,
+					scope: params.scope,
+					isolation: params.isolation as IsolationMode | undefined,
+				}], ctx.cwd, agents)[0]!;
+			} catch (error) {
+				throw new Error(`Dispatch admission rejected: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			const singleCatalogAgent = agents.find((candidate) => candidate.name === single.agent);
 			const result = await startBackground(
-				params.agent as string,
-				params.task as string,
-				params.cwd,
+				single.agent,
+				single.task,
+				single.cwd,
 				defaultIsolationMode(
 					"single",
-					params.agent as string,
-					params.isolation as IsolationMode | undefined,
+					single.agent,
+					single.isolation,
 					singleCatalogAgent ? isWorktreeCapableAgent(singleCatalogAgent) : undefined,
 					singleCatalogAgent?.isolation,
 				),
-				{ deliveryRoute: params.wait ? "await" : "background" },
+				{
+					deliveryRoute: params.wait ? "await" : "background",
+					phaseId: single.phaseId,
+					scope: single.scope,
+					writeCapable: single.writeCapable,
+				},
 			);
 			if (result.exitCode !== -1) {
 				throw new Error(getResultOutput(result));
@@ -541,7 +697,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			return {
 				content: [{
 					type: "text",
-					text: phaseLeaseReceipt(result.runId === undefined ? [] : [result.runId]) + queuePacingNote(),
+					text: phaseLeaseReceipt(result.runId === undefined ? [] : [result.runId], { mode: "single" }) + queuePacingNote(),
 				}],
 				details: makeDetails("single", true)([result]),
 			};