@iowarp/clio-coder 0.4.4 → 0.4.5

package/src/tools/dispatch-runner.ts

@@ -51,6 +51,7 @@ import { summarizeTrustStatus } from "../domains/evidence/trust-projection.js";
 import { adaptRunReceiptTrustStatus } from "../domains/evidence/trust-status.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
 import { activeDecisionRefs } from "../domains/session/decision-board.js";
+import { renderCompeteJudgeTask } from "./compete-judge-task.js";
 import {
 	type CandidateWorktree,
 	type CompeteGroupOwnership,
@@ -560,7 +561,12 @@ function dispatchDetails(
 	}
 	return {
 		mode,
-		assignmentIds: runs.map((run) => run.receipt.lineage?.rootRunId ?? run.receipt.runId),
+		assignmentIds: runs.map(
+			(run) =>
+				deps.dispatch.assignments?.getStored(run.receipt.runId)?.assignmentId ??
+				run.receipt.lineage?.rootRunId ??
+				run.receipt.runId,
+		),
 		terminalRunIds: runs.map((run) => run.receipt.runId),
 		receiptCount: runs.length,
 		failedCount: failed.length,
@@ -787,6 +793,7 @@ async function runReviewGated(
 			}
 			const reviewerRequest: DispatchRequest = {
 				agentId: gateDeciderAgentId(review.reviewer),
+				...(base.budget === undefined ? {} : { budget: base.budget }),
 				executionRole: "reviewer",
 				task: renderDispatchReviewerTask(base.task, builder.receipt.runId, cycle, base.intent),
 				systemPrompt: REVIEWER_GATE_PROMPT,
@@ -865,20 +872,6 @@ async function runReviewGated(
 	}
 }
 
-function judgeTask(originalTask: string, candidates: ReadonlyArray<CandidateWorktree>, stats: string[]): string {
-	const lines = [
-		`Rank ${candidates.length} candidate implementations of this task and pick the best one.`,
-		"Original task:",
-		originalTask,
-		"Candidates:",
-		...candidates.map(
-			(candidate, index) =>
-				`  ${candidate.index}. branch=${candidate.branch} worktree=${candidate.path} (${stats[index] ?? "?"})`,
-		),
-	];
-	return lines.join("\n\n");
-}
-
 function readVerifiedGateReceipt(deps: DispatchToolDeps, runId: string): RunReceipt | null {
 	const envelope = deps.dispatch.getRun(runId);
 	if (envelope === null) return null;
@@ -1173,6 +1166,11 @@ async function runCompete(
 	const throwIfStopped = (): void => {
 		if (stop !== null) throw new Error(stop.message);
 	};
+	// A stopped phase still has terminal receipts worth reporting. Keep the
+	// ordinary error result and no winner, without discarding those identities
+	// through the generic exception path after the settlement barrier.
+	const stoppedOutcome = (): CompeteOutcome | null =>
+		stop === null ? null : { runs, decisions, group, winner: null, needsDecision: stop.message };
 	const settleRun = async (
 		handle: Awaited<ReturnType<DispatchContract["dispatch"]>>,
 		request: DispatchRequest,
@@ -1331,7 +1329,8 @@ async function runCompete(
 			});
 			const candidateRuns = await settledCompletedRuns(candidateOwned, "candidate settlement");
 			runs.push(...candidateRuns);
-			throwIfStopped();
+			const stoppedCandidates = stoppedOutcome();
+			if (stoppedCandidates !== null) return stoppedCandidates;
 			const stats = worktrees.map((worktree, index) => {
 				const receipt = candidateRuns[index]?.receipt;
 				const failed = receipt !== undefined && isPipelineStepFailure(receipt);
@@ -1356,8 +1355,22 @@ async function runCompete(
 			}
 			const judgeRequest: DispatchRequest = {
 				agentId: gateDeciderAgentId(compete.judge?.agent),
+				...(base.budget === undefined ? {} : { budget: base.budget }),
 				executionRole: "judge",
-				task: judgeTask(base.task, worktrees, stats),
+				task: renderCompeteJudgeTask(base.task, worktrees, stats, candidateRuns),
+				// Candidate prose and receipt locators are evidence, not inferred authority.
+				// Read-only execution is enforced by the role/autonomy, not empty write roots.
+				intent: narrowDispatchIntentToReadOnly(
+					base.intent ?? {
+						version: 2,
+						readRoots: [],
+						writeRoots: [],
+						relevantPaths: [],
+						pathProvenance: [],
+						expectedOutputs: [],
+						verification: [],
+					},
+				),
 				systemPrompt: JUDGE_GATE_PROMPT,
 				autonomy: "read-only",
 				cwd: root,
@@ -1390,7 +1403,8 @@ async function runCompete(
 			const judgeRun = (await settledCompletedRuns([judgeOwned], "judge settlement"))[0];
 			if (judgeRun === undefined) throw new Error("judge produced no completed run");
 			runs.push(judgeRun);
-			throwIfStopped();
+			const stoppedJudge = stoppedOutcome();
+			if (stoppedJudge !== null) return stoppedJudge;
 			const judgeReceipt = judgeRun.receipt;
 			const judgeSummary = judgeRun.summary;
 			// Every judged outcome names the same subjects, decider, and correlation;
@@ -1532,7 +1546,7 @@ async function runCompete(
 
 	// Losers are always cleaned; the winner's worktree and branch survive
 	// only while an operator decision is pending (supervised pick or a
-	// failed merge). The durable state transition happens after the worker
+	// failed merge). Every removed candidate is archived under a durable recovery ref. The durable state transition happens after the worker
 	// barrier and before deletion, defining the safe restart boundary.
 	const winnerAtFinalization = currentWinner();
 	if (ownership !== null) {
@@ -1588,8 +1602,7 @@ async function runCompete(
 /**
  * Apply a preserved compete winner. Plan-scale by definition, so supervised
  * autonomy levels park this call for operator confirmation; the approval IS
- * the winner confirmation. After a successful merge the whole compete group
- * is cleaned up.
+ * the winner confirmation. After a successful merge scratch worktrees are cleaned up; candidate recovery refs remain.
  */
 function runApplyWinner(
 	input: { branch: string; cwd: string },
@@ -1736,7 +1749,7 @@ function runApplyWinner(
 	}
 	return {
 		kind: "ok",
-		output: `winner ${branch} merged into the current branch; compete group ${group} cleaned up`,
+		output: `winner ${branch} merged into the current branch; compete group ${group} scratch cleaned up; candidate states remain under refs/clio-coder/compete/ (list with git for-each-ref)`,
 		details: {
 			mode: "apply_winner",
 			branch,
@@ -1801,14 +1814,14 @@ function competeResult(
 	if (outcome.winner?.applied === true) {
 		return {
 			kind: "ok",
-			output: `compete winner candidate ${outcome.winner.index} applied (branch ${outcome.winner.branch} merged)\n\n${body}`,
+			output: `compete winner candidate ${outcome.winner.index} applied (branch ${outcome.winner.branch} merged); candidate states remain under refs/clio-coder/compete/ (list with git for-each-ref)\n\n${body}`,
 			details,
 		};
 	}
 	if (outcome.winner !== null && outcome.needsDecision === undefined) {
 		const lines = [
 			`compete winner: candidate ${outcome.winner.index} (branch ${outcome.winner.branch}), preserved for confirmation at autonomy ${autonomy}`,
-			`Apply it with dispatch apply_winner={branch: "${outcome.winner.branch}"}; the approval prompt is the winner confirmation. Losing candidates were cleaned up.`,
+			`Apply it with dispatch apply_winner={branch: "${outcome.winner.branch}"}; the approval prompt is the winner confirmation. Losing candidate states remain under refs/clio-coder/compete/; list them with git for-each-ref.`,
 		];
 		return { kind: "ok", output: `${lines.join("\n")}\n\n${body}`, details };
 	}
@@ -1998,6 +2011,7 @@ async function runCouncil(
 		const finalRuns = [...prior.values()];
 		const judgeRequest: DispatchRequest = {
 			agentId: council.judge?.agent ?? base.agentId,
+			...(base.budget === undefined ? {} : { budget: base.budget }),
 			executionRole: "judge",
 			task: `Synthesize the council answers for this task:\n\n${base.task}`,
 			briefing: boundedCouncilBriefing(
@@ -2165,6 +2179,7 @@ export async function runDispatchTool(
 	// admission bounds. Keep these off the serializable approved request.
 	const dispatch = deps.dispatch;
 	const preparation = {
+		...(options?.hostRun === undefined ? {} : { hostRun: structuredClone(options.hostRun) }),
 		...(options?.signal === undefined ? {} : { signal: options.signal }),
 		...(timeoutMs === undefined ? {} : { deadlineAt: Date.now() + timeoutMs }),
 	};
@@ -2305,12 +2320,7 @@ export async function runDispatchTool(
 	try {
 		if (resolvedPlan?.topology === "fleet") {
 			const executionPlan = admissionState.trustedExecutionPlans.get(args);
-			if (
-				executionPlan === undefined ||
-				resolvedPlan.source === null ||
-				resolvedPlan.deadlineMs === null ||
-				reservationOwnerId === undefined
-			) {
+			if (executionPlan === undefined || resolvedPlan.source === null || reservationOwnerId === undefined) {
 				return { kind: "error", message: "dispatch: trusted Scout dependency plan is unavailable" };
 			}
 			if (executionPlan.hash !== resolvedPlan.source.executionPlanHash) {
@@ -2611,10 +2621,16 @@ async function runPipeline(
 			const { receipt, summary } = await registered.completion;
 			activeRunId = null;
 			runs.push(completeRun(deps, receipt, summary));
-			if (isPipelineStepFailure(receipt)) {
+			// Execution can succeed while a conforming report records a failed
+			// check. Keep that receipt truthful, but do not feed failed quality
+			// into a dependent step. Review/compete use failure to drive their
+			// own repair loops, so this condition belongs only to the pipeline.
+			const failedQuality = receipt.quality.resultContract?.quality === "fail";
+			if (isPipelineStepFailure(receipt) || failedQuality) {
 				const skipped = requests.length - (index + 1);
+				const reason = isPipelineStepFailure(receipt) ? pipelineFailureReason(receipt) : "result quality=fail";
 				throw new PipelineHaltError(
-					`pipeline dispatch halted at step ${index + 1}/${requests.length} (run ${receipt.runId}, ${pipelineFailureReason(receipt)}); skipped ${skipped} later step(s)`,
+					`pipeline dispatch halted at step ${index + 1}/${requests.length} (run ${receipt.runId}, ${reason}); skipped ${skipped} later step(s)`,
 					[...runs],
 				);
 			}

package/src/tools/dispatch-schema.ts

@@ -1,5 +1,6 @@
 import { type Static, Type } from "typebox";
 import type { FleetSettings } from "../core/defaults.js";
+import { RESULT_SUMMARY_MAX_BYTES_CEILING } from "../domains/agents/result-contract.js";
 import { DISPATCH_BRIEFING_MAX_BYTES } from "../domains/dispatch/validation.js";
 import { StringEnum } from "../engine/ai.js";
 import { TOOL_PROFILE_NAMES } from "./profiles.js";
@@ -18,7 +19,7 @@ import { TOOL_PROFILE_NAMES } from "./profiles.js";
 export interface DispatchSchemaComposition {
 	/** `roster`, `members`, `synthesis`, `rounds`: a council needs a configured roster to name. */
 	council: boolean;
-	/** `candidates`, `judge`, `apply_winner`: a compete needs more than one fleet route to compare. */
+	/** `candidates`, `judge`, `apply_winner`: distinct executions may share one fleet route. */
 	compete: boolean;
 	/** `routing.posture`, `minimumQuality`, `locality`, `failover`: they act only once adaptive routing is activated. */
 	adaptiveRouting: boolean;
@@ -30,28 +31,15 @@ export const FULL_DISPATCH_SCHEMA_COMPOSITION: DispatchSchemaComposition = Objec
 	adaptiveRouting: true,
 });
 
-type FleetShape = Pick<FleetSettings, "default" | "profiles" | "rosters" | "adaptiveRouting">;
-
-/** Distinct target/model routes the fleet can dispatch to: the default plus every profile and roster member. */
-function distinctFleetRoutes(fleet: FleetShape): number {
-	const routes = new Set<string>();
-	const add = (target: string | null | undefined, model: string | null | undefined): void => {
-		if (!target) return;
-		routes.add(`${target}${model ?? ""}`);
-	};
-	add(fleet.default.target, fleet.default.model);
-	for (const profile of Object.values(fleet.profiles)) add(profile.target, profile.model);
-	for (const roster of Object.values(fleet.rosters)) {
-		for (const member of roster.members) add(member.target, member.model);
-	}
-	return routes.size;
-}
+type FleetShape = Pick<FleetSettings, "rosters" | "adaptiveRouting">;
 
 export function dispatchSchemaCompositionFor(fleet: FleetShape): DispatchSchemaComposition {
 	const routing = fleet.adaptiveRouting;
 	return {
 		council: Object.keys(fleet.rosters).length > 0,
-		compete: distinctFleetRoutes(fleet) > 1,
+		// The runner isolates candidate executions and dispatches a separate judge;
+		// route diversity is not required. Normal admission still validates routes.
+		compete: true,
 		adaptiveRouting: routing.roles.length > 0 || routing.postures.length > 0 || routing.agentRoles.length > 0,
 	};
 }
@@ -85,7 +73,7 @@ const DispatchBudgetSchema = Type.Object(
 	{
 		additionalProperties: false,
 		description:
-			"Tool-call budget within the recipe's range; retryRevision preauthorizes one ceiling for a retry or revision phase.",
+			"Advisory tool-call estimate; choose appropriate counts even above recipe recommendations. retryRevision sets a retry/revision estimate. Crossing estimates does not stop work.",
 	},
 );
 
@@ -124,7 +112,7 @@ const DispatchIntentSchema = Type.Object(
 	{
 		additionalProperties: false,
 		description:
-			"Repository-relative paths and outputs. Declare it on every dispatch: it selects the project rules that apply and pins worker context, where omitting it falls back to path tokens scraped from the task text. verification entries are declared check ids from package scripts or .clio-coder/verifiers.yaml. Per-task intent must fit inside the top-level intent.",
+			"Repository-relative paths and outputs. Declare it on every dispatch: it selects the project rules that apply and pins worker context, where omitting it falls back to path tokens scraped from the task text. verification entries are declared check ids from package scripts or .clio-coder/verifiers.yaml. Per-task intent fields override inherited top-level fields within its scope. For disjoint parallel writes, set each task's write_roots to only its assigned outputs; expected_outputs alone does not narrow write access.",
 	},
 );
 
@@ -193,7 +181,12 @@ export function buildDispatchParameters(composition: DispatchSchemaComposition =
 							briefing: Type.Optional(
 								Type.String({ description: `Per-task parent context, max ${DISPATCH_BRIEFING_MAX_BYTES} UTF-8 bytes.` }),
 							),
-							agent: Type.Optional(Type.String({ description: "Recipe id (default coder)." })),
+							agent: Type.Optional(
+								Type.String({
+									description:
+										"Recipe id for this task: set scout/documenter explicitly in a mixed pipeline; names in task text do not select recipes, and omission inherits the batch/default recipe.",
+								}),
+							),
 							budget: Type.Optional(BudgetRef),
 							target: Type.Optional(Type.String()),
 							model: Type.Optional(Type.String()),
@@ -201,6 +194,13 @@ export function buildDispatchParameters(composition: DispatchSchemaComposition =
 							worktree: Type.Optional(Type.Literal(true, { description: "Run this writer in an isolated git worktree." })),
 							intent: Type.Optional(IntentRef),
 							gate: Type.Optional(Type.String({ description: "One declared check id, shorthand for intent.verification." })),
+							result_summary_max_bytes: Type.Optional(
+								Type.Integer({
+									minimum: 1,
+									maximum: RESULT_SUMMARY_MAX_BYTES_CEILING,
+									description: "This task's inline summary allowance; mutation-report workers (coder, documenter) only.",
+								}),
+							),
 						}),
 					]),
 					{ description: "Batch of assignments; one string or object is wrapped." },
@@ -284,8 +284,8 @@ export function buildDispatchParameters(composition: DispatchSchemaComposition =
 			agent: Type.Optional(
 				Type.String({
 					description: composition.council
-						? "Default recipe id for string tasks, or auto (default coder; researcher for council)."
-						: "Default recipe id for string tasks, or auto (default coder).",
+						? "Default recipe id for tasks without their own agent, or auto (default coder; researcher for council)."
+						: "Default recipe id for tasks without their own agent, or auto (default coder).",
 				}),
 			),
 			briefing: Type.Optional(
@@ -332,6 +332,13 @@ export function buildDispatchParameters(composition: DispatchSchemaComposition =
 			cwd: Type.Optional(Type.String({ description: "Default worker working directory." })),
 			timeout_ms: Type.Optional(Type.Number({ description: "Abort the dispatch after this many ms." })),
 			max_output_bytes: Type.Optional(Type.Number({ description: "Max summary bytes returned." })),
+			result_summary_max_bytes: Type.Optional(
+				Type.Integer({
+					minimum: 1,
+					maximum: RESULT_SUMMARY_MAX_BYTES_CEILING,
+					description: `UTF-8 byte allowance for a mutation-report worker's inline summary (coder, documenter), default 16384. A batch default applies to mutation-report steps only; other steps ignore it. Storage bound, not the returned preview (max_output_bytes).`,
+				}),
+			),
 		},
 		{ $defs: DISPATCH_DEFS },
 	);

package/src/tools/dispatch-scout-admission.ts

@@ -11,14 +11,11 @@ import type {
 } from "../domains/dispatch/contract.js";
 import { type ExecutionPlan, requireAgentSteps } from "../domains/dispatch/execution-plan.js";
 import { verifyReceiptIntegrity } from "../domains/dispatch/receipt-integrity.js";
-import { sameRouteIdentity } from "../domains/dispatch/route-decision.js";
 import type { RoutingIntent } from "../domains/dispatch/routing-intent.js";
 import { compileScoutTransition, type ScoutAgentBinding } from "../domains/dispatch/scout-transition.js";
 import type { RunEnvelope, RunReceipt } from "../domains/dispatch/types.js";
 import type { ResolvedDispatchPlanArtifact } from "./dispatch-plan.js";
 
-const MAX_SCOUT_PLAN_DEADLINE_MS = 3_600_000;
-
 export interface ScoutContinuationRef {
 	runId: string;
 	receiptDigest: string;
@@ -132,8 +129,8 @@ export function prepareScoutContinuation(input: {
 				: {
 						...sourceIntent,
 						posture: sourceIntent.posture === "manual" ? "balanced" : sourceIntent.posture,
-						maxCostUsd: input.costCeilingUsd,
-						deadlineMs: null,
+						maxCostUsd: sourceIntent.maxCostUsd,
+						deadlineMs: sourceIntent.deadlineMs,
 						requiredCapabilities: [...sourceIntent.requiredCapabilities],
 						failover: "approved",
 					};
@@ -164,11 +161,7 @@ export function prepareScoutContinuation(input: {
 			routingIntent,
 		});
 	}
-	const priorCostCeiling = input.source.receipt.routingIntent.maxCostUsd;
-	const effectiveCostCeiling =
-		input.authorization === "full-auto-policy" && priorCostCeiling !== null
-			? Math.min(input.costCeilingUsd, priorCostCeiling)
-			: input.costCeilingUsd;
+	const explicitCostCeiling = input.source.receipt.routingIntent.maxCostUsd;
 	const bindings: ScoutAgentBinding[] = proposals.map(({ subtask, agentSpec }) => ({
 		subtaskId: subtask.id,
 		spec: agentSpec,
@@ -192,35 +185,8 @@ export function prepareScoutContinuation(input: {
 		throw new Error("dispatch: full-auto policy does not grant every requested Scout authority");
 	}
 	const plan = transition.plan;
-	const p95ByStep = new Map(
-		proposals.map((proposal) => {
-			const selected = proposal.decision.candidateEvaluations.find((entry) =>
-				sameRouteIdentity(entry.candidate, proposal.decision.selected),
-			);
-			if (selected === undefined || selected.rejection !== null) {
-				throw new Error(`dispatch: Scout step '${proposal.subtask.id}' has no admissible latency estimate`);
-			}
-			return [proposal.subtask.id, selected.estimate.p95EndToEndMs] as const;
-		}),
-	);
-	const predictedDeadlineMs = Math.ceil(
-		plan.waves.reduce(
-			(total, wave) => total + Math.max(...wave.map((stepId) => p95ByStep.get(stepId) ?? Number.POSITIVE_INFINITY)),
-			0,
-		),
-	);
-	if (
-		!Number.isFinite(predictedDeadlineMs) ||
-		predictedDeadlineMs < 1 ||
-		predictedDeadlineMs > MAX_SCOUT_PLAN_DEADLINE_MS
-	) {
-		throw new Error("dispatch: Scout continuation exceeds the finite whole-plan deadline ceiling");
-	}
-	const priorDeadlineMs = input.source.receipt.routingIntent.deadlineMs;
-	if (input.authorization === "full-auto-policy" && priorDeadlineMs !== null && predictedDeadlineMs > priorDeadlineMs) {
-		throw new Error("dispatch: full-auto Scout continuation exceeds the previously granted deadline");
-	}
-	const deadlineMs = Math.max(priorDeadlineMs ?? 0, predictedDeadlineMs);
+	// Route estimates are advisory. Only a caller-supplied deadline grants stop authority.
+	const deadlineMs = input.source.receipt.routingIntent.deadlineMs;
 	const requests: DispatchRequest[] = [];
 	const resolutions: DispatchPlanTaskResolution[] = [];
 	const tasks = requireAgentSteps(plan.steps).map((step, index): ResolvedDispatchPlanArtifact["tasks"][number] => {
@@ -241,7 +207,7 @@ export function prepareScoutContinuation(input: {
 			cwd: input.source.envelope.cwd,
 			requestOrigin: "user",
 			agentSelection: selection,
-			routingIntent: { ...proposal.routingIntent, maxCostUsd: effectiveCostCeiling, deadlineMs, failover: "none" },
+			routingIntent: { ...proposal.routingIntent, maxCostUsd: explicitCostCeiling, deadlineMs, failover: "none" },
 			failover: "none",
 		});
 		resolutions.push(proposal.resolution);
@@ -253,7 +219,7 @@ export function prepareScoutContinuation(input: {
 			node: proposal.resolution.node.id,
 			nodeKind: proposal.resolution.node.kind,
 			...(proposal.resolution.node.host === undefined ? {} : { nodeHost: proposal.resolution.node.host }),
-			routingIntent: { ...proposal.routingIntent, maxCostUsd: effectiveCostCeiling, deadlineMs, failover: "none" },
+			routingIntent: { ...proposal.routingIntent, maxCostUsd: explicitCostCeiling, deadlineMs, failover: "none" },
 			failover: "none",
 			routeApproval: null,
 			agentSelection: selection,
@@ -269,8 +235,8 @@ export function prepareScoutContinuation(input: {
 		};
 	});
 	const aggregateCost = resolutions.reduce((sum, resolution) => sum + resolution.costUpperBoundUsd, 0);
-	if (!Number.isFinite(aggregateCost) || aggregateCost > effectiveCostCeiling) {
-		throw new Error("dispatch: Scout continuation exceeds the scheduling cost ceiling");
+	if (!Number.isFinite(aggregateCost) || (explicitCostCeiling !== null && aggregateCost > explicitCostCeiling)) {
+		throw new Error("dispatch: Scout continuation exceeds the explicit routing cost ceiling");
 	}
 	return {
 		artifact: {
@@ -285,7 +251,7 @@ export function prepareScoutContinuation(input: {
 			maxWorkers: plan.maxWorkers,
 			onFailure: plan.onFailure,
 			tasks,
-			costCeilingUsd: effectiveCostCeiling,
+			costCeilingUsd: input.costCeilingUsd,
 			deadlineMs,
 		},
 		requests,

package/src/tools/dispatch-scout.ts

@@ -186,8 +186,7 @@ export async function runScoutContinuationPlan<T, S>(input: {
 	): Promise<{ receipt: RunReceipt; summary: S }>;
 	complete(receipt: RunReceipt, summary: S): { value: T; integrityValid: boolean };
 }): Promise<{ runs: T[]; skipped: ReadonlyArray<string> }> {
-	if (input.artifact.deadlineMs === null) throw new Error("Scout dependency plan has no whole-plan deadline");
-	const assignmentDeadlineAt = Date.now() + input.artifact.deadlineMs;
+	const assignmentDeadlineAt = input.artifact.deadlineMs === null ? undefined : Date.now() + input.artifact.deadlineMs;
 	const completedByStep = new Map<string, T>();
 	const byStep = new Map(
 		input.artifact.tasks.map((task, index) => [task.stepId, { task, request: input.requests[index] }]),
@@ -234,7 +233,7 @@ export async function runScoutContinuationPlan<T, S>(input: {
 					...bound.request,
 					predecessorHandoffs: handoffs,
 					reservation,
-					assignmentDeadlineAt,
+					...(assignmentDeadlineAt === undefined ? {} : { assignmentDeadlineAt }),
 					...(ledger !== undefined ? { ledger } : {}),
 				};
 				const handle = await input.dispatch.dispatch(request);

package/src/tools/find.ts

@@ -8,6 +8,7 @@ import { resolveFdBinary } from "./executables.js";
 import { compileGlobRegex, fallbackIgnoredDirs, fdIgnoreArgs, normalizeGlobInput } from "./ignore-policy.js";
 import {
 	commitObservationReservation,
+	createObservationPathFilter,
 	finalizeObservation,
 	OBSERVE_SELF_CAPS,
 	type ObservationReservation,
@@ -148,6 +149,7 @@ function orderByMtime(paths: string[], searchPath: string, limit: number, candid
 }
 
 function renderFindResult(input: {
+	withheldPaths: number;
 	ordered: OrderedPaths;
 	collected: number;
 	collectLimit: number;
@@ -160,11 +162,13 @@ function renderFindResult(input: {
 	if (ordered.paths.length === 0) {
 		return finalizeObservation({
 			tool: ToolNames.Find,
+			withheldPaths: input.withheldPaths,
 			unit: "paths",
-			output: "No files found matching pattern",
+			output: "No visible files found matching pattern",
 			shownCount: 0,
-			totalCount: 0,
-			truncated: false,
+			totalCount: collected >= collectLimit ? null : 0,
+			truncated: collected >= collectLimit,
+			...(collected >= collectLimit ? { next: `limit=${limit * 2}` } : {}),
 			reservation,
 			...(options ? { options } : {}),
 		});
@@ -191,6 +195,7 @@ function renderFindResult(input: {
 	}
 	return finalizeObservation({
 		tool: ToolNames.Find,
+		withheldPaths: input.withheldPaths,
 		unit: "paths",
 		output: truncation.content,
 		// Offload only when the byte cap cut collected paths; a bare result
@@ -269,13 +274,17 @@ export const findTool: ToolSpec = {
 				}
 			}
 
+			const collectedCount = collectedPaths.length;
+			const pathFilter = createObservationPathFilter(process.cwd(), options?.allowsObservationPath);
+			collectedPaths = collectedPaths.filter((entry) => pathFilter.allows(join(searchPath, entry)));
 			const ordered: OrderedPaths =
 				order === "mtime"
 					? orderByMtime(collectedPaths, searchPath, limit, collectLimit)
 					: { paths: collectedPaths.slice(0, limit), candidateCapHit: false, candidateCap: null };
 			return renderFindResult({
+				withheldPaths: pathFilter.withheldPaths,
 				ordered,
-				collected: collectedPaths.length,
+				collected: collectedCount,
 				collectLimit,
 				limit,
 				order,

package/src/tools/grep.ts

@@ -7,6 +7,7 @@ import { resolveRgBinary } from "./executables.js";
 import { compileGlobRegex, fallbackIgnoredDirs, normalizeGlobInput, rgIgnoreArgs } from "./ignore-policy.js";
 import {
 	commitObservationReservation,
+	createObservationPathFilter,
 	finalizeObservation,
 	OBSERVE_SELF_CAPS,
 	type ObservationReservation,
@@ -67,6 +68,7 @@ interface RenderedLine {
 }
 
 interface GrepRenderInput {
+	withheldPaths: number;
 	mode: GrepMode;
 	lines: RenderedLine[];
 	matchCount: number;
@@ -90,6 +92,7 @@ function renderGrepResult(input: GrepRenderInput): ToolResult {
 	if (lines.length === 0) {
 		return finalizeObservation({
 			tool: ToolNames.Grep,
+			withheldPaths: input.withheldPaths,
 			unit: MODE_UNITS[mode],
 			output: NO_MATCH_OUTPUT,
 			shownCount: 0,
@@ -120,6 +123,7 @@ function renderGrepResult(input: GrepRenderInput): ToolResult {
 	}
 	return finalizeObservation({
 		tool: ToolNames.Grep,
+		withheldPaths: input.withheldPaths,
 		unit: MODE_UNITS[mode],
 		output,
 		// Offload only when the byte cap cut collected content; a bare match
@@ -139,6 +143,7 @@ function sanitizeMatchText(text: string): string {
 }
 
 interface RgSearchInput {
+	pathFilter: ReturnType<typeof createObservationPathFilter>;
 	rgPath: string;
 	mode: GrepMode;
 	pattern: string;
@@ -195,6 +200,7 @@ async function runRipgrep(input: RgSearchInput): Promise<ToolResult> {
 		const lineNumber = data?.line_number;
 		const lineText = (data?.lines as { text?: unknown } | undefined)?.text;
 		if (typeof filePath !== "string" || typeof lineNumber !== "number" || typeof lineText !== "string") return;
+		if (!input.pathFilter.allows(filePath)) return;
 		const { text, wasTruncated } = truncateLine(sanitizeMatchText(lineText));
 		if (wasTruncated) linesTruncated = true;
 		const isMatch = type === "match";
@@ -214,6 +220,8 @@ async function runRipgrep(input: RgSearchInput): Promise<ToolResult> {
 	const onListLine = (line: string, stop: () => void): void => {
 		const trimmed = line.replace(/\r$/, "");
 		if (trimmed.length === 0) return;
+		const filePath = input.mode === "count" ? trimmed.slice(0, trimmed.lastIndexOf(":")) : trimmed;
+		if (!input.pathFilter.allows(filePath)) return;
 		let text: string;
 		if (input.mode === "count") {
 			const sep = trimmed.lastIndexOf(":");
@@ -245,6 +253,7 @@ async function runRipgrep(input: RgSearchInput): Promise<ToolResult> {
 		return { kind: "error", message: `grep: ${result.stderr.trim() || `ripgrep exited with code ${result.exitCode}`}` };
 	}
 	return renderGrepResult({
+		withheldPaths: input.pathFilter.withheldPaths,
 		mode: input.mode,
 		lines: rendered,
 		matchCount,
@@ -279,6 +288,7 @@ function looksBinary(buffer: Buffer): boolean {
 }
 
 interface FallbackSearchInput {
+	pathFilter: ReturnType<typeof createObservationPathFilter>;
 	mode: GrepMode;
 	pattern: string;
 	searchPath: string;
@@ -328,7 +338,7 @@ function fallbackGrep(input: FallbackSearchInput): ToolResult {
 	};
 
 	const searchFile = (filePath: string): void => {
-		if (limitHit) return;
+		if (limitHit || !input.pathFilter.allows(filePath)) return;
 		let buffer: Buffer;
 		try {
 			const stat = statSync(filePath);
@@ -403,6 +413,7 @@ function fallbackGrep(input: FallbackSearchInput): ToolResult {
 	else searchFile(input.searchPath);
 	if (signal?.aborted) return { kind: "error", message: "grep: operation aborted" };
 	return renderGrepResult({
+		withheldPaths: input.pathFilter.withheldPaths,
 		mode: input.mode,
 		lines: rendered,
 		matchCount,
@@ -463,6 +474,7 @@ export const grepTool: ToolSpec = {
 			});
 		}
 		const shared = {
+			pathFilter: createObservationPathFilter(process.cwd(), options?.allowsObservationPath),
 			mode,
 			pattern,
 			searchPath,

package/src/tools/ls.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
 import {
+	createObservationPathFilter,
 	finalizeObservation,
 	OBSERVE_SELF_CAPS,
 	observationBudgetExhausted,
@@ -53,7 +54,10 @@ export const lsTool: ToolSpec = {
 		}
 
 		try {
-			const entries = readdirSync(root).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+			const pathFilter = createObservationPathFilter(process.cwd(), options?.allowsObservationPath);
+			const entries = readdirSync(root)
+				.filter((entry) => pathFilter.allows(path.join(root, entry)))
+				.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
 			const outputEntries: string[] = [];
 			let entryLimitReached = false;
 			for (const entry of entries) {
@@ -72,6 +76,7 @@ export const lsTool: ToolSpec = {
 			if (outputEntries.length === 0) {
 				return finalizeObservation({
 					tool: ToolNames.Ls,
+					withheldPaths: pathFilter.withheldPaths,
 					unit: "entries",
 					output: "(empty directory)",
 					shownCount: 0,
@@ -90,6 +95,7 @@ export const lsTool: ToolSpec = {
 			const truncated = entryLimitReached || truncation.truncated;
 			return finalizeObservation({
 				tool: ToolNames.Ls,
+				withheldPaths: pathFilter.withheldPaths,
 				unit: "entries",
 				output: truncation.content,
 				// Offload only when the byte cap cut collected entries; a bare