@ferris1225/pi-subagents 4.3.7 → 4.3.9

package/src/delegation/risk.ts

@@ -0,0 +1,168 @@
+import { resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { runCommand } from "../isolation/git-command.ts";
+
+export type SubagentRiskCategory =
+	| "concurrency"
+	| "trust-boundary"
+	| "persistence-compatibility"
+	| "failure-cancellation";
+
+export type GitRiskRunner = (
+	cwd: string,
+	args: readonly string[],
+	signal?: AbortSignal,
+) => Promise<string>;
+
+export interface SubagentRiskAdvisory {
+	available: boolean;
+	changedPaths: string[];
+	categories: SubagentRiskCategory[];
+	matches: Partial<Record<SubagentRiskCategory, string[]>>;
+	recommendSentinel: boolean;
+	unavailableReason?: string;
+}
+
+const CATEGORY_RULES: ReadonlyArray<{
+	category: SubagentRiskCategory;
+	pattern: RegExp;
+}> = [
+	{
+		category: "concurrency",
+		pattern: /(?:^|[/_.-])(?:concurr(?:ency|ent)?|parallel|queues?|workers?|threads?|locks?|mutex|semaphore|dispatch|background|races?|lane)(?:[/_.-]|$)/u,
+	},
+	{
+		category: "trust-boundary",
+		pattern: /(?:^|[/_.-])(?:auth|credentials?|permissions?|policy|privilege|secrets?|security|sandbox|trust|tokens?)(?:[/_.-]|$)/u,
+	},
+	{
+		category: "persistence-compatibility",
+		pattern: /(?:^|[/_.-])(?:compat(?:ibility)?|durable|manifests?|migrations?|persist(?:ence|ent)?|restore|schemas?|serializ(?:e|ation)|storage)(?:[/_.-]|$)/u,
+	},
+	{
+		category: "failure-cancellation",
+		pattern: /(?:^|[/_.-])(?:abort(?:ed|ion|s)?|cancel(?:ed|lation|led)?|errors?|fail(?:ed|ures?)?|recovery|retries|retry|stop|timeout)(?:[/_.-]|$)/u,
+	},
+];
+
+function normalizedGitPath(path: string): string {
+	return path.replaceAll("\\", "/").replace(/^\.\//u, "");
+}
+
+export function classifyRiskPaths(paths: readonly string[]): Pick<
+	SubagentRiskAdvisory,
+	"categories" | "matches" | "recommendSentinel"
+> {
+	const normalized = [...new Set(paths.map(normalizedGitPath).filter(Boolean))].sort();
+	const matches: Partial<Record<SubagentRiskCategory, string[]>> = {};
+	const categories: SubagentRiskCategory[] = [];
+	for (const rule of CATEGORY_RULES) {
+		const matching = normalized.filter((path) => rule.pattern.test(path.toLowerCase()));
+		if (matching.length === 0) continue;
+		categories.push(rule.category);
+		matches[rule.category] = matching;
+	}
+	return { categories, matches, recommendSentinel: categories.length > 0 };
+}
+
+const RISK_GIT_TIMEOUT_MS = 30_000;
+const RISK_GIT_OUTPUT_MAX_BYTES = 4 * 1024 * 1024;
+
+const defaultGitRunner: GitRiskRunner = async (cwd, args, signal) => {
+	const result = await runCommand("git", args, {
+		cwd,
+		signal,
+		timeoutMs: RISK_GIT_TIMEOUT_MS,
+		maxOutputBytes: RISK_GIT_OUTPUT_MAX_BYTES,
+	});
+	if (result.code !== 0) {
+		const detail = result.stderr.toString("utf8").trim();
+		throw new Error(detail || `git ${args[0] ?? "command"} exited with code ${result.code}`);
+	}
+	return result.stdout.toString("utf8");
+};
+
+function isCancellation(error: unknown, signal?: AbortSignal): boolean {
+	return signal?.aborted === true || (error instanceof Error && error.name === "AbortError");
+}
+
+function nulPaths(output: string): string[] {
+	return output.split("\0").map(normalizedGitPath).filter(Boolean);
+}
+
+/** Inspect repository-root-relative tracked and untracked changes without a model call.
+ * Non-cancellation Git failures are advisory-unavailable and never block work. */
+export async function analyzeSubagentRisk(
+	cwd: string,
+	runGit: GitRiskRunner = defaultGitRunner,
+	signal?: AbortSignal,
+): Promise<SubagentRiskAdvisory> {
+	signal?.throwIfAborted();
+	const resolvedCwd = resolve(cwd);
+	try {
+		const topLevel = (await runGit(resolvedCwd, ["rev-parse", "--show-toplevel"], signal)).trim();
+		signal?.throwIfAborted();
+		if (!topLevel) throw new Error("Git returned an empty repository top-level path.");
+		const repositoryRoot = resolve(topLevel);
+		const [tracked, untracked] = await Promise.all([
+			runGit(repositoryRoot, ["diff", "--name-only", "-z", "HEAD"], signal),
+			runGit(repositoryRoot, ["ls-files", "--others", "--exclude-standard", "-z"], signal),
+		]);
+		signal?.throwIfAborted();
+		const changedPaths = [...new Set([...nulPaths(tracked), ...nulPaths(untracked)])].sort();
+		const classification = classifyRiskPaths(changedPaths);
+		return { available: true, changedPaths, ...classification };
+	} catch (error) {
+		if (isCancellation(error, signal)) throw error;
+		return {
+			available: false,
+			changedPaths: [],
+			categories: [],
+			matches: {},
+			recommendSentinel: false,
+			unavailableReason: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+export function registerSubagentRiskTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "subagent_risk",
+		label: "Subagent Risk",
+		description: "Advisory-only, no-model-call inspection of repository-root-relative tracked and untracked changes from HEAD, even when called from a nested cwd. Applies fixed path rules for concurrency, trust-boundary, persistence-compatibility, and failure-cancellation risk, and reports whether a fresh Sentinel review is suggested. It never dispatches a child or blocks work.",
+		parameters: Type.Object({
+			cwd: Type.Optional(Type.String({ description: "Repository working directory; defaults to the current caller cwd." })),
+		}),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const advisory = await analyzeSubagentRisk(
+				resolve(ctx.cwd, params.cwd ?? "."),
+				defaultGitRunner,
+				signal,
+			);
+			if (!advisory.available) {
+				return {
+					content: [{
+						type: "text",
+						text: `Sentinel risk advisory unavailable: ${advisory.unavailableReason ?? "Git could not inspect the working tree"}. Advisory only; no child was dispatched and work was not blocked.`,
+					}],
+					details: advisory,
+				};
+			}
+			const changed = advisory.changedPaths.length > 0
+				? advisory.changedPaths.map((path) => `- ${path}`).join("\n")
+				: "- (none)";
+			const categories = advisory.categories.length > 0 ? advisory.categories.join(", ") : "none";
+			const recommendation = advisory.recommendSentinel
+				? "Sentinel suggested by fixed path rules. Dispatch remains the main agent's decision."
+				: "Sentinel not suggested by fixed path rules.";
+			return {
+				content: [{
+					type: "text",
+					text: `Changed paths relative to HEAD:\n${changed}\nRisk categories: ${categories}\n${recommendation} Advisory only; no child was dispatched and work was not blocked.`,
+				}],
+				details: advisory,
+			};
+		},
+	});
+}

package/src/lifecycle/durable.ts

@@ -19,6 +19,7 @@ import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promis
 import { uptime } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import type { UsageStats } from "../execution/rpc-control.ts";
+import { normalizePhaseId, normalizePhaseScope, type PhaseScope } from "../delegation/phase-scope.ts";
 import type { SubagentThread } from "./runtime.ts";
 import { getResultOutput, isFailedResult, getProjectRoot, getSubagentsRoot, type SingleResult } from "../execution/spawn.ts";
 import { isManagedSessionDir, isManagedWorktreeLayout, samePath } from "../isolation/managed-paths.ts";
@@ -76,6 +77,9 @@ export interface ThreadRecord {
 	generation: number;
 	agentName: string;
 	task: string;
+	phaseId?: string;
+	scope?: PhaseScope;
+	writeCapable?: boolean;
 	cwd: string;
 	executionCwd: string;
 	/** Resolved (clamped) level of the last generation. */
@@ -166,6 +170,14 @@ function normalizeRecord(value: unknown): ThreadRecord | undefined {
 	if (raw.state !== "parked" && raw.state !== "completed" && raw.state !== "failed") return undefined;
 	const worktree = raw.worktree === undefined ? undefined : normalizeWorktreeSnapshot(raw.worktree);
 	if (worktree === null) return undefined;
+	let phaseId: string | undefined;
+	let scope: PhaseScope | undefined;
+	try {
+		phaseId = normalizePhaseId(raw.phaseId as string | undefined);
+		scope = normalizePhaseScope(raw.scope as Parameters<typeof normalizePhaseScope>[0], raw.cwd);
+	} catch {
+		return undefined;
+	}
 	return {
 		runId: raw.runId,
 		createdAt: raw.createdAt,
@@ -173,6 +185,9 @@ function normalizeRecord(value: unknown): ThreadRecord | undefined {
 		generation: typeof raw.generation === "number" && Number.isInteger(raw.generation) && raw.generation >= 0 ? raw.generation : 0,
 		agentName: raw.agentName,
 		task: raw.task,
+		...(phaseId ? { phaseId } : {}),
+		...(scope ? { scope } : {}),
+		...(typeof raw.writeCapable === "boolean" ? { writeCapable: raw.writeCapable } : {}),
 		cwd: raw.cwd,
 		executionCwd: typeof raw.executionCwd === "string" && raw.executionCwd ? raw.executionCwd : raw.cwd,
 		...(typeof raw.thinkingLevel === "string" && raw.thinkingLevel ? { thinkingLevel: raw.thinkingLevel } : {}),
@@ -375,6 +390,9 @@ export function threadRecordFromThread(
 		generation: thread.generation,
 		agentName: thread.agentName,
 		task: thread.task,
+		...(thread.phaseId ? { phaseId: thread.phaseId } : {}),
+		...(thread.scope ? { scope: thread.scope } : {}),
+		...(thread.writeCapable !== undefined ? { writeCapable: thread.writeCapable } : {}),
 		cwd: thread.cwd,
 		executionCwd: thread.executionCwd,
 		...(thread.thinkingLevel ? { thinkingLevel: thread.thinkingLevel } : {}),

package/src/lifecycle/runtime.ts

@@ -9,6 +9,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PhaseScope, PhaseScopeInput } from "../delegation/phase-scope.ts";
 import { rmSync } from "node:fs";
 import { resolveSubagentConcurrency, BackgroundTaskQueue } from "../execution/background.ts";
 import {
@@ -43,6 +44,12 @@ export interface SubagentThread {
 	generation: number;
 	agentName: string;
 	task: string;
+	phaseId?: string;
+	scope?: PhaseScope;
+	/** Monotonic continuation scope visible while resume preflight is in flight. */
+	admissionScope?: PhaseScope;
+	/** Capability snapshot used by declared-scope admission, including after restore. */
+	writeCapable?: boolean;
 	/** Caller-facing cwd in the original worktree. */
 	cwd: string;
 	/** Actual child cwd (the equivalent path inside an isolated worktree). */
@@ -77,7 +84,11 @@ export interface SubagentThread {
 	retireOnSettle?: boolean;
 	retired?: boolean;
 	/** Installed by dispatch so the control tool can restart the same logical id. */
-	resume: (objective?: string, ctx?: ExtensionContext) => Promise<SingleResult>;
+	resume: (
+		objective?: string,
+		ctx?: ExtensionContext,
+		metadata?: { scope?: PhaseScopeInput },
+	) => Promise<SingleResult>;
 	/** Dispatch-owned, generation-guarded worktree settlement hook. Its apply
 	 * runs under the canonical original-repository lane. */
 	finalizeIsolation: (generation: number, result?: SingleResult) => Promise<WorktreeFinalization | undefined>;

package/src/lifecycle/thread-lifecycle.ts

@@ -28,6 +28,12 @@ import {
 } from "../presentation/format.ts";
 import { monitor } from "../presentation/monitor.ts";
 import { findDuplicateDispatch } from "../delegation/prompt.ts";
+import {
+	findWriterLeaseScopeOverlap,
+	mergePhaseScopes,
+	normalizePhaseId,
+	normalizePhaseScope,
+} from "../delegation/phase-scope.ts";
 import { persistRecoveryRecords, recoveryRecordFromFinalization } from "../isolation/recovery.ts";
 import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts";
 import { forkRetainedSession } from "../execution/session-fork.ts";
@@ -105,6 +111,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		startOptions: StartBackgroundOptions = {},
 	): Promise<SingleResult> => {
 		const {
+			phaseId: requestedPhaseId,
+			scope: requestedScope,
+			writeCapable: requestedWriteCapable,
 			existingThread,
 			appendedObjectiveOnResume = false,
 			environment,
@@ -127,16 +136,30 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		const resolveLiveAgentTools = (candidate: AgentConfig): AgentConfig =>
 			resolveAgentTools({ ...candidate, tools: discoveredAgent.tools }, runtime.getActiveTools());
 		const agent = resolveLiveAgentTools(discoveredAgent);
+
+		const originalCwd = resolve(cwd ?? runCtx.cwd);
+		let phaseId: string | undefined;
+		let scope: ReturnType<typeof normalizePhaseScope>;
+		try {
+			phaseId = normalizePhaseId(existingThread ? existingThread.phaseId : requestedPhaseId);
+			const requested = normalizePhaseScope(requestedScope, originalCwd);
+			scope = existingThread ? mergePhaseScopes(existingThread.scope, requested) : requested;
+		} catch (error) {
+			return failedStartResult(agentName, task, error instanceof Error ? error.message : String(error));
+		}
+		const currentWriteCapable = isWriteCapableAgent(agent);
+		const priorWriteCapable = existingThread
+			? (existingThread.writeCapable ?? existingThread.agentName !== "scout")
+			: Boolean(requestedWriteCapable);
+		const writeCapable = priorWriteCapable || currentWriteCapable;
 		if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
 			return {
 				...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as artisan.`),
 				isolation,
 			};
 		}
-
-		const originalCwd = resolve(cwd ?? runCtx.cwd);
 		if (!existingThread) {
-			const duplicate = findDuplicateDispatch(runtime.threads.values(), task, originalCwd);
+			const duplicate = findDuplicateDispatch(runtime.threads.values(), task, originalCwd, phaseId);
 			if (duplicate?.kind === "active") {
 				return failedStartResult(
 					agentName,
@@ -150,7 +173,17 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				return failedStartResult(
 					agentName,
 					task,
-					`Run #${duplicate.source.id} (${duplicate.source.agentName}) already ${duplicate.source.state} this exact brief and kept its context; its result was delivered. Resume #${duplicate.source.id} with an appended objective instead of paying for a second run, or restate the brief with what changed.`,
+					`Run #${duplicate.source.id} (${duplicate.source.agentName}) already ${duplicate.source.state} this logical phase and kept its context; its result was delivered. Resume #${duplicate.source.id} with an appended objective instead of paying for a second run${phaseId ? "; keep using the same phaseId on that thread" : ", or restate the brief with what changed"}.`,
+				);
+			}
+		}
+		if (writeCapable && scope) {
+			const conflict = findWriterLeaseScopeOverlap(scope, runtime.threads.values(), existingThread?.id);
+			if (conflict) {
+				return failedStartResult(
+					agentName,
+					task,
+					`Declared writer scope ${conflict.overlap.left} overlaps active run #${conflict.lease.id} scope ${conflict.overlap.right}; no new generation was started.`,
 				);
 			}
 		}
@@ -230,6 +263,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			thread.generation = generation;
 			thread.agentName = agent.name;
 			thread.task = task;
+			thread.phaseId = phaseId;
+			thread.scope = scope;
+			thread.writeCapable = writeCapable;
 			thread.cwd = originalCwd;
 			thread.executionCwd = executionCwd;
 			thread.thinkingLevel = thinkingLevel;
@@ -253,6 +289,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				generation,
 				agentName: agent.name,
 				task,
+				phaseId,
+				scope,
+				writeCapable,
 				cwd: originalCwd,
 				executionCwd,
 				thinkingLevel,
@@ -281,7 +320,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		// Shared write-capable runs serialize on the repository lane so their
 		// edits cannot race; the lane wait releases the process slot because it
 		// is write serialization, not pool pacing.
-		const reserveManagedLane = isolation === "shared" && isWriteCapableAgent(agent);
+		const reserveManagedLane = isolation === "shared" && writeCapable;
 		const runGeneration = async (backgroundSignal: AbortSignal, controller: AbortController): Promise<void> => {
 				if (runtime.threads.get(runId)?.generation !== generation) return;
 				if (isolation === "worktree" && !worktree) {
@@ -718,7 +757,11 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 		});
 	};
 
-	thread.resume = async (objective?: string, resumeCtx?: ExtensionContext): Promise<SingleResult> => {
+	thread.resume = async (
+		objective?: string,
+		resumeCtx?: ExtensionContext,
+		metadata?: { scope?: Parameters<typeof normalizePhaseScope>[0] },
+	): Promise<SingleResult> => {
 		const requestedObjective = objective?.trim();
 		if (!runtime.sessionActive || runtime.threads.get(runId) !== thread) {
 			return failedStartResult(thread.agentName, thread.task, `Run #${runId} belongs to a parent session that has shut down.`);
@@ -726,6 +769,14 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 		if (objective !== undefined && !requestedObjective) {
 			return failedStartResult(thread.agentName, thread.task, "resume objective must be non-blank when provided.");
 		}
+		const continuationPhaseId = thread.phaseId;
+		let continuationScope: ReturnType<typeof normalizePhaseScope>;
+		try {
+			const additionalScope = normalizePhaseScope(metadata?.scope, thread.cwd);
+			continuationScope = mergePhaseScopes(thread.scope, additionalScope);
+		} catch (error) {
+			return failedStartResult(thread.agentName, thread.task, error instanceof Error ? error.message : String(error));
+		}
 		if (thread.retired) return failedStartResult(thread.agentName, thread.task, `Run #${runId} was retired by subagent_stop.`);
 		if (thread.resumeUnavailableReason) {
 			return failedStartResult(thread.agentName, thread.task, thread.resumeUnavailableReason);
@@ -750,6 +801,7 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 			sessionId: previousSessionId,
 			sessionDir: previousSessionDir,
 		};
+		thread.admissionScope = continuationScope;
 		thread.lifecycleOperation = "resume";
 		thread.state = "resuming";
 		const finishPreflight = beginRuntimePreflight(runtime);
@@ -763,6 +815,7 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 			// Never wait forever on a previous generation that is still settling
 			// (e.g. blocked behind the managed repository lane in finalization).
 			if (!(await quiesced(thread.generationCompletion))) {
+				if (ownsResumeReservation(runtime, thread, reservation)) thread.state = previousState;
 				return failedStartResult(
 					thread.agentName,
 					thread.task,
@@ -829,6 +882,8 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 				thread.isolation,
 				{
 					existingThread: thread,
+					phaseId: continuationPhaseId,
+					scope: continuationScope,
 					appendedObjectiveOnResume: objective !== undefined,
 					environment: {
 						ctx: currentCtx,
@@ -883,6 +938,7 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 			);
 		} finally {
 			finishPreflight();
+			if (thread.lifecycleVersion === reservation.version) thread.admissionScope = undefined;
 			if (
 				thread.lifecycleOperation === "resume" &&
 				thread.lifecycleVersion === reservation.version

package/src/lifecycle/thread-restore.ts

@@ -58,6 +58,9 @@ function createRestoredThread(
 		generation: record.generation,
 		agentName: record.agentName,
 		task: record.task,
+		phaseId: record.phaseId,
+		scope: record.scope,
+		writeCapable: record.writeCapable ?? record.agentName !== "scout",
 		cwd: record.cwd,
 		executionCwd: record.executionCwd,
 		...(record.thinkingLevel ? { thinkingLevel: record.thinkingLevel as ThinkingLevel } : {}),

package/src/lifecycle/thread-shared.ts

@@ -4,6 +4,7 @@ import { realpath } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isWriteCapableAgent, type AgentConfig } from "../delegation/agents.ts";
+import type { PhaseScope } from "../delegation/phase-scope.ts";
 import { roleThinkingLevel, type SubagentsConfig, type ThinkingLevel } from "../configuration/config.ts";
 import { removeThreadRecord, threadRecordFromThread, upsertThreadRecord } from "./durable.ts";
 import {
@@ -170,9 +171,10 @@ export function withWorktreeSystemPrompt(agent: AgentConfig): AgentConfig {
 	};
 }
 
-/** Only write-capable agents can run in an isolated worktree. */
+/** Only write-capable agents can run in an isolated worktree. Sentinel reviews
+ * the caller's uncommitted diff, which a detached worktree cannot contain. */
 export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
-	return isWriteCapableAgent(agent);
+	return agent.name !== "sentinel" && isWriteCapableAgent(agent);
 }
 
 export interface DispatchEnvironment {
@@ -194,9 +196,14 @@ export interface ResumeReservation {
 	sessionDir?: string;
 }
 
-/** The dispatcher's full internal entry point; the public tool surface only
- * uses the first four parameters. */
+/** Dispatcher's internal entry point. Public phase/scope claims are normalized
+ * into options; resume adds lifecycle-only continuation fields there too. */
 export interface StartBackgroundOptions {
+	/** Normalized identity and claims for a fresh or resumed generation. */
+	phaseId?: string;
+	scope?: PhaseScope;
+	/** Fresh-dispatch hint OR-merged with live capability; false cannot downgrade a writer. Resume stays monotonic. */
+	writeCapable?: boolean;
 	/** Resume path only: the thread whose retained context continues. */
 	existingThread?: SubagentThread;
 	appendedObjectiveOnResume?: boolean;

package/src/lifecycle/tools.ts

@@ -34,6 +34,13 @@ function renderFirstLine(result: { content?: unknown }, label: string, theme: an
 }
 
 export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime): void {
+	const ResumeScopeSchema = Type.Optional(Type.Object({
+		paths: Type.Optional(Type.Array(Type.String({ minLength: 1, pattern: "\\S" }))),
+		symbols: Type.Optional(Type.Array(Type.Object({
+			path: Type.String({ minLength: 1, pattern: "\\S" }),
+			name: Type.String({ minLength: 1, pattern: "\\S" }),
+		}))),
+	}, { description: "Additional declarative write claims for resume; normalized claims are unioned with retained scope and cannot remove it. Scope is conflict metadata, not permissions or a sandbox." }));
 	const SubagentControlParams = Type.Object({
 		action: StringEnum(["steer", "resume", "park"] as const, {
 			description:
@@ -43,6 +50,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 		objective: Type.Optional(
 			Type.String({ description: "Guidance for steer (required and nonblank), or an optional appended objective for resume. Ignored by park." }),
 		),
+		scope: ResumeScopeSchema,
 	});
 
 	/** A thread that a steer can continue instead of reject: it is not live, but
@@ -52,7 +60,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 	pi.registerTool({
 		name: "subagent_control",
 		label: "Subagent Control",
-		description: "Steer a running child with additional guidance (continuing it if it has settled or is parked), resume a parked/settled thread, or park a running thread at a stable checkpoint, by stable run id.",
+		description: "Steer a running child, resume a parked/settled thread, or park a running thread by stable run id. Resume keeps phaseId immutable and may only extend retained scope.",
 		parameters: SubagentControlParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -103,7 +111,9 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					return textResult("resume objective must be non-blank when provided.");
 				}
 				const hadRetainedSession = Boolean(thread.sessionId && thread.sessionDir);
-				const pending = await thread.resume(requestedObjective, ctx);
+				const pending = await thread.resume(requestedObjective, ctx, {
+					scope: params.scope,
+				});
 				if (pending.exitCode !== -1) return textResult(getResultOutput(pending));
 				const currentObjective = formatTaskSummary(requestedObjective ?? thread.task, 80, false);
 				const mode = requestedObjective