@iowarp/clio-coder 0.4.3 → 0.4.5

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/dispatch-types.ts

@@ -3,6 +3,7 @@ import type { AgentSpec } from "../domains/agents/spec.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
 import type { AgentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
+import type { DecisionLedgerEntry } from "../domains/session/entries.js";
 import type {
 	CandidateWorktree,
 	CompeteGroupOwnership,
@@ -108,4 +109,9 @@ export interface DispatchToolDeps {
 	getWorkerRosters?: () => Readonly<Record<string, { members: ReadonlyArray<DispatchCouncilMember> }>>;
 	/** Which optional schema blocks this session advertises; absent means every block. */
 	getSchemaComposition?: () => DispatchSchemaComposition;
+	/**
+	 * Live decision board snapshot. Every request the tool builds carries the
+	 * active decisions' refs, sealed here and never from model arguments.
+	 */
+	getDecisionBoard?: () => ReadonlyArray<DecisionLedgerEntry>;
 }

package/src/tools/evidence.ts

@@ -0,0 +1,96 @@
+import { Type } from "typebox";
+import { assertSafeId } from "../core/safe-id.js";
+import { ToolNames } from "../core/tool-names.js";
+import { clioDataDir, clioStateDir } from "../core/xdg.js";
+import { StringEnum } from "../engine/ai.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+import { truncateUtf8 } from "./truncate-utf8.js";
+
+export const EVIDENCE_TOOL_MAX_BYTES = 16_384;
+
+/** Keep truncated results valid JSON and never hide an unbounded copy in details. */
+function boundedResult(value: unknown): ToolResult {
+	const serialized = JSON.stringify(value, null, 2);
+	if (Buffer.byteLength(serialized, "utf8") <= EVIDENCE_TOOL_MAX_BYTES) {
+		return { kind: "ok", output: serialized, details: { truncated: false } };
+	}
+	const hint = "Inspect one run to narrow the output; this preview is incomplete JSON text.";
+	let preview = truncateUtf8(serialized, EVIDENCE_TOOL_MAX_BYTES, "");
+	let output = JSON.stringify({ truncated: true, hint, preview });
+	while (Buffer.byteLength(output, "utf8") > EVIDENCE_TOOL_MAX_BYTES) {
+		const excess = Buffer.byteLength(output, "utf8") - EVIDENCE_TOOL_MAX_BYTES;
+		preview = truncateUtf8(preview, Math.max(0, Buffer.byteLength(preview, "utf8") - excess), "");
+		output = JSON.stringify({ truncated: true, hint, preview });
+	}
+	return { kind: "ok", output, details: { truncated: true } };
+}
+
+export const evidenceTool: ToolSpec = {
+	name: ToolNames.Evidence,
+	description:
+		"Read canonical evidence as JSON. List recent bundles, inspect a bundle's overview, trust axes and tier, gate decisions, and findings, or build/read evidence for a run.",
+	parameters: Type.Object({
+		mode: StringEnum(["list", "inspect", "run"]),
+		id: Type.Optional(Type.String({ description: "Evidence bundle id for inspect." })),
+		runId: Type.Optional(Type.String({ description: "Run id for run." })),
+	}),
+	baseActionClass: "read",
+	// Run mode may materialize a derived bundle in Clio's data directory.
+	executionMode: "sequential",
+	async run(args): Promise<ToolResult> {
+		const mode = args.mode;
+		if (mode !== "list" && mode !== "inspect" && mode !== "run") {
+			return { kind: "error", message: "evidence: mode must be list, inspect, or run" };
+		}
+		try {
+			const dataDir = clioDataDir();
+			if (mode === "list") {
+				const { evidenceInventorySnapshot } = await import("../domains/evidence/inventory.js");
+				return boundedResult(await evidenceInventorySnapshot(Date.now, dataDir));
+			}
+			const id = mode === "inspect" ? args.id : args.runId;
+			if (typeof id !== "string" || id.length === 0) {
+				return { kind: "error", message: `evidence: ${mode} requires ${mode === "inspect" ? "id" : "runId"}` };
+			}
+			assertSafeId(id, mode === "inspect" ? "evidence" : "run");
+			const { buildEvidence, EvidenceNotFoundError, inspectEvidence, loadEvidenceGateDecisions } = await import(
+				"../domains/evidence/index.js"
+			);
+			const { evidenceDetailSnapshot } = await import("../domains/evidence/detail.js");
+			let evidenceId = mode === "run" ? `run-${id}` : id;
+			let inspected: Awaited<ReturnType<typeof inspectEvidence>>;
+			try {
+				inspected = await inspectEvidence(dataDir, evidenceId);
+			} catch (error) {
+				if (mode !== "run" || !(error instanceof EvidenceNotFoundError)) throw error;
+				try {
+					evidenceId = (await buildEvidence({ dataDir, stateDir: clioStateDir(), runId: id })).evidenceId;
+				} catch (buildError) {
+					if (
+						buildError instanceof Error &&
+						(buildError.message === "run ledger not found" || buildError.message === `run not found: ${id}`)
+					)
+						throw new EvidenceNotFoundError(evidenceId);
+					throw buildError;
+				}
+				inspected = await inspectEvidence(dataDir, evidenceId);
+			}
+			return boundedResult({
+				...inspected,
+				...(await evidenceDetailSnapshot(evidenceId, Date.now, dataDir)),
+				gateDecisions: await loadEvidenceGateDecisions(dataDir, evidenceId),
+			});
+		} catch (error) {
+			const absent = error instanceof Error && error.name === "EvidenceNotFoundError";
+			return {
+				kind: "error",
+				message: truncateUtf8(
+					`evidence: ${error instanceof Error ? error.message : String(error)}`,
+					EVIDENCE_TOOL_MAX_BYTES - 3,
+					"...",
+				),
+				details: { code: absent ? "artifact_absent" : "evidence_error", artifactAbsent: absent },
+			};
+		}
+	},
+};

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/limitation.ts

@@ -0,0 +1,76 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import { StringEnum } from "../engine/ai.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+
+/**
+ * The typed limitation signal the finish contract reads. Calling the tool
+ * records a `limitation` tool_call and tool_result pair in the session ledger,
+ * and that successful receipt is what `assessFinishContract` accepts in place
+ * of validation evidence. The tool is pure: it touches no filesystem and runs
+ * no shell, so the receipt itself is its whole effect.
+ */
+
+export const LIMITATION_REASONS = ["no-runner", "blocked", "out-of-scope", "environment", "other"] as const;
+
+export type LimitationReason = (typeof LIMITATION_REASONS)[number];
+
+export interface LimitationRecord {
+	scope: string;
+	reason: LimitationReason;
+	paths: string[];
+}
+
+function isLimitationReason(value: unknown): value is LimitationReason {
+	return typeof value === "string" && (LIMITATION_REASONS as ReadonlyArray<string>).includes(value);
+}
+
+function trimString(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizePaths(value: unknown): string[] | null {
+	if (value === undefined || value === null) return [];
+	if (!Array.isArray(value)) return null;
+	const paths: string[] = [];
+	for (const item of value) {
+		const path = trimString(item);
+		if (path === null) return null;
+		if (!paths.includes(path)) paths.push(path);
+	}
+	return paths;
+}
+
+export const limitationTool: ToolSpec = {
+	name: ToolNames.Limitation,
+	description:
+		"Record what this turn could not verify and why. Call it once, before your final reply, when you changed files but could not run validation; the receipt stands in for validation evidence at the finish gate.",
+	parameters: Type.Object({
+		scope: Type.String({ description: "What could not be verified, in one sentence." }),
+		reason: StringEnum(LIMITATION_REASONS, {
+			description:
+				"no-runner: no test or build runner is available; blocked: a safety gate or denial stopped the check; out-of-scope: verification was excluded by the task; environment: the environment cannot run the check; other.",
+		}),
+		paths: Type.Optional(Type.Array(Type.String(), { description: "Repository-relative paths left unverified." })),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+	async run(args): Promise<ToolResult> {
+		const scope = trimString(args.scope);
+		if (scope === null) return { kind: "error", message: "limitation: scope is required" };
+		if (!isLimitationReason(args.reason)) {
+			return { kind: "error", message: `limitation: reason must be one of ${LIMITATION_REASONS.join(", ")}` };
+		}
+		const paths = normalizePaths(args.paths);
+		if (paths === null) return { kind: "error", message: "limitation: paths must be an array of non-empty strings" };
+		const limitation: LimitationRecord = { scope, reason: args.reason, paths };
+		const pathSuffix = paths.length > 0 ? ` paths=${paths.join(",")}` : "";
+		return {
+			kind: "ok",
+			output: `limitation recorded: ${scope} (reason=${limitation.reason}${pathSuffix})\n`,
+			details: { limitation },
+		};
+	},
+};

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