@iowarp/clio-coder 0.5.1 → 0.5.2

package/src/interactive/turn-middleware.ts

@@ -22,6 +22,7 @@ import { extractText, hasStructuredToolCall, toolNamesFromAgentState } from "./c
 import type { AgentRuntime, ChatTurnState } from "./turn-state.js";
 
 export interface TurnMiddlewareDeps {
+	memoryContentGuard?: (() => () => boolean) | undefined;
 	state: ChatTurnState;
 	middleware?: MiddlewareContract | undefined;
 	session?: SessionContract | undefined;
@@ -50,6 +51,7 @@ export interface TurnMiddleware {
 		tokensBefore?: number,
 	): void;
 	flushPendingReminders(): string;
+	takePendingReminderProjection(): () => string;
 	clearPendingReminders(): void;
 	/**
 	 * Deliver a reminder produced after its own turn boundary already closed.
@@ -57,7 +59,7 @@ export interface TurnMiddleware {
 	 * value; the reminder joins the same buffer, ledger, and transcript path a
 	 * turn_end reminder takes.
 	 */
-	injectDeferredReminder(message: string, severity?: MiddlewareReminderSeverity): void;
+	injectDeferredReminder(message: string, severity?: MiddlewareReminderSeverity, isCurrent?: () => boolean): void;
 	/**
 	 * Deliver an operator-facing finding produced after its turn boundary closed.
 	 * The watchdog seam: its run settles well after the turn it reviewed, and
@@ -76,11 +78,29 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 	// injections). The next accepted prompt flushes them into the model
 	// request as one system-reminder block. Completed background reminders
 	// can also drain at a native tool-batch boundary; session switches clear all.
-	const pendingReminders: Array<{ message: string; severity: MiddlewareReminderSeverity; deferred: boolean }> = [];
+	const pendingReminders: Array<{
+		message: string;
+		severity: MiddlewareReminderSeverity;
+		deferred: boolean;
+		isCurrent?: (() => boolean) | undefined;
+	}> = [];
+	const dropStale = () => {
+		for (let index = pendingReminders.length - 1; index >= 0; index--) {
+			if (pendingReminders[index]?.isCurrent?.() === false) pendingReminders.splice(index, 1);
+		}
+	};
 
-	const bufferReminder = (message: string, severity: MiddlewareReminderSeverity, deferred = false): void => {
+	const bufferReminder = (
+		message: string,
+		severity: MiddlewareReminderSeverity,
+		deferred = false,
+		isCurrent?: () => boolean,
+	): void => {
+		dropStale();
+		isCurrent ??= message.startsWith("Memory:") ? deps.memoryContentGuard?.() : undefined;
+		if (isCurrent?.() === false) return;
 		if (pendingReminders.some((entry) => entry.message === message && entry.severity === severity)) return;
-		pendingReminders.push({ message, severity, deferred });
+		pendingReminders.push({ message, severity, deferred, isCurrent });
 	};
 
 	const runMiddlewareTurnHook = (input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> => {
@@ -194,6 +214,7 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 				[],
 			);
 			if (!current()) return false;
+			dropStale();
 			const ready = pendingReminders.filter((entry) => entry.deferred);
 			if (ready.length === 0) return false;
 			const content = `<system-reminder>\n${[...new Set(ready.map((entry) => entry.message))].join("\n\n")}\n</system-reminder>`;
@@ -314,7 +335,17 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			});
 		},
 
+		takePendingReminderProjection(): () => string {
+			const entries = pendingReminders.splice(0);
+			return () => {
+				const messages = [
+					...new Set(entries.filter((entry) => entry.isCurrent?.() !== false).map((entry) => entry.message)),
+				];
+				return messages.length ? `<system-reminder>\n${messages.join("\n\n")}\n</system-reminder>` : "";
+			};
+		},
 		flushPendingReminders(): string {
+			dropStale();
 			if (pendingReminders.length === 0) return "";
 			// Severity affects host actions, not the text delivered to the model.
 			// A paired continuation/info and reminder/warn still needs one copy.
@@ -327,14 +358,16 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			pendingReminders.length = 0;
 		},
 
-		injectDeferredReminder(message, severity = "advisory"): void {
+		injectDeferredReminder(message, severity = "advisory", isCurrent): void {
+			dropStale();
+			if (isCurrent?.() === false) return;
 			const text = message.trim();
 			if (text.length === 0) return;
 			// A deferred reminder never carries hard-block authority: the turn it
 			// could have interrupted is already over.
 			const level: MiddlewareReminderSeverity = severity === "hard-block" ? "advisory" : severity;
 			if (pendingReminders.some((entry) => entry.message === text)) return;
-			bufferReminder(text, level, true);
+			bufferReminder(text, level, true, isCurrent);
 			appendMiddlewareReminderEntry(text, level);
 			deps.emitNotice(text);
 		},

package/src/interactive/turn-persistence.ts

@@ -60,7 +60,11 @@ export interface TurnPersistenceDeps {
 export interface TurnPersistence {
 	/** True when this exact assistant message object was already persisted. */
 	wasPersisted(message: unknown): boolean;
-	appendAssistantTurn(message: AgentMessage, timing?: AssistantCallTiming | null): void;
+	appendAssistantTurn(
+		message: AgentMessage,
+		timing?: AssistantCallTiming | null,
+		deliveryId?: string,
+	): string | undefined;
 	appendQueuedUserTurn(message: AgentMessage): void;
 	appendToolCallTurn(event: Extract<AgentEvent, { type: "tool_execution_start" }>): void;
 	appendToolResultTurn(
@@ -226,7 +230,11 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 		};
 	};
 
-	const appendAssistantTurn = (message: AgentMessage, timing?: AssistantCallTiming | null): void => {
+	const appendAssistantTurn = (
+		message: AgentMessage,
+		timing?: AssistantCallTiming | null,
+		deliveryId?: string,
+	): string | undefined => {
 		if (message?.role !== "assistant") return;
 		if (persistedAssistantMessages.has(message)) return;
 		// A loop-guard interrupt already persisted a durable closing turn with the
@@ -237,6 +245,10 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 		const failure = terminalFailureFromAssistantMessage(message);
 		const payload = assistantSessionPayload(message, failure);
 		if (timing) payload.timing = timing;
+		if (deliveryId) {
+			payload.continuityDeliveryId = deliveryId;
+			payload.stopReason = message.stopReason;
+		}
 		const usage = (message as { usage?: Usage }).usage;
 		if (usage && typeof usage === "object") {
 			const backendTimings = (message as { backendTimings?: BackendCompletionTimings }).backendTimings;
@@ -279,6 +291,7 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 			tokens: traceUsage?.totalTokens ?? null,
 		});
 		if (!turnContinues) finishTracedTurn(failure ? "fail" : "success", failure?.errorMessage ?? null);
+		return turn.id;
 	};
 
 	return {

package/src/interactive/turn-runtime.ts

@@ -1,4 +1,8 @@
+import { requestFits } from "../domains/context/budget/request-fit.js";
+import { estimateInputTokensFromContext } from "../engine/apis/output-budget.js";
 import { resolvedRequestContext } from "../engine/context.js";
+import type { ContinuityController } from "./continuity-controller.js";
+import { resolveTurnOutputReserve } from "./output-reserve.js";
 /**
  * Turn runtime ownership: orchestrator target resolution, model synthesis,
  * live-agent construction and model hot-swap, thinking-level reconciliation,
@@ -133,6 +137,8 @@ export interface TurnRuntimeDeps {
 	middlewareToolChoice: MiddlewareToolChoiceControl;
 	persistence: TurnPersistence;
 	context: TurnContext;
+	continuity?: ContinuityController;
+	hasQueuedSteering?: () => boolean;
 	middleware: TurnMiddleware;
 	retrySettings: () => RetrySettings;
 	/** Stable Clio session id forwarded only to gateway runtimes that understand it. */
@@ -512,6 +518,37 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			},
 			maxRetryDelayMs: deps.retrySettings().maxDelayMs,
 			...(gatewaySessionId ? { sessionId: gatewaySessionId } : {}),
+			beforeToolBatch: ({ assistantMessage }) => {
+				const calls = assistantMessage.content.filter((block) => block.type === "toolCall");
+				if (calls.some((call) => call.name === "self_compact") && calls.length !== 1) {
+					return { reason: "self_compact must be the only call in its batch; no sibling was executed." };
+				}
+				return undefined;
+			},
+			beforeStreamRequest: ({ context: request }) => {
+				setGlobalDefaultMaxOutputTokens(deps.getSettings().chat.maxOutputTokens);
+				if (state.activeInterruptReason !== null || state.runtime !== localRuntime) {
+					return { block: true, reason: "Request ownership changed before invocation." };
+				}
+				if (deps.hasQueuedSteering?.() && deps.continuity?.admission().block === false) {
+					const handoff = deps.continuity.admission();
+					if (!handoff.block && handoff.correlationId)
+						return { block: true, reason: "Operator steering arrived during handoff preparation; handoff paused." };
+				}
+				const view = context.refreshLiveBudget();
+				const resolved = resolvedRequestContext(request);
+				const actual = state.synthesisToolLock
+					? { ...resolved, systemPrompt: lockedSynthesisSystemPrompt(resolved.systemPrompt ?? "") }
+					: request;
+				const input = Math.max(estimateInputTokensFromContext(actual), view.inputTokens ?? 0);
+				const output = resolveTurnOutputReserve(localRuntime, input);
+				return requestFits(input, output, view.effectiveWindow)
+					? (deps.continuity?.admission() ?? { block: false })
+					: {
+							block: true,
+							reason: `Context window exceeded: input ${input} + output ${output}, window ${view.effectiveWindow ?? "unknown"}.`,
+						};
+			},
 			onStreamInvocation: () => {
 				setGlobalDefaultMaxOutputTokens(deps.getSettings().chat.maxOutputTokens);
 				apiCallStartedAt = performance.now();
@@ -634,19 +671,22 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			stallTimer.unref?.();
 		};
 
-		handle.agent.prepareNextTurn = async (signal?: AbortSignal) => {
+		handle.agent.prepareNextTurnWithContext = async (_completed, signal?: AbortSignal) => {
 			stallSuspendDepth += 1;
 			try {
 				if (signal?.aborted || state.activeInterruptReason !== null) return undefined;
-				const contextChanged = await middleware.prepareToolContinuation(localRuntime, signal);
+				if (deps.hasQueuedSteering?.()) await deps.continuity?.pause();
+				const handoffChanged = (await deps.continuity?.settle(signal)) ?? false;
+				const contextChanged = (await middleware.prepareToolContinuation(localRuntime, signal)) || handoffChanged;
 				const update = await context.postToolContinuationGuard(localRuntime, signal, contextChanged);
+				const restored = context.installMemoryRestoration(localRuntime);
 				if (signal?.aborted || state.activeInterruptReason !== null) return undefined;
 				// Compaction owns any replacement snapshot. Without one, publish the
 				// already-accounted reminder through context, not message events that
 				// would manufacture a new operator turn and reset task authority.
 				return (
-					update ??
-					(contextChanged
+					(!restored ? update : undefined) ??
+					(contextChanged || restored
 						? {
 								context: {
 									messages: [...localRuntime.agent.state.messages],
@@ -950,7 +990,9 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 								apiMs: Math.round(Math.max(0, eventClock - apiCallStartedAt)),
 							}
 						: null;
-				persistence.appendAssistantTurn(enrichedEvent.message, timing);
+				const correlationId = event.type === "message_end" ? handle.requestCorrelationId(event.message) : undefined;
+				const persistedId = persistence.appendAssistantTurn(enrichedEvent.message, timing, correlationId);
+				await deps.continuity?.response(persistedId, correlationId);
 				if (isAssistant) apiCallStartedAt = null;
 				const usage = (enrichedEvent.message as { usage?: Usage }).usage;
 				if (isAssistant && usage && typeof usage === "object" && runFirstCallVerdict === null) {
@@ -974,6 +1016,7 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 						: null;
 			}
 			if (enrichedEvent.type === "agent_end") {
+				await deps.continuity?.pause();
 				clearStallTimer();
 				const terminal = pendingTerminalToolResult;
 				pendingTerminalToolResult = null;

package/src/tools/agent-tools.ts

@@ -497,5 +497,7 @@ export function resolveSessionTools(
 		supportsImages: runtime.runtimeResolution.capabilityDecisions.vision === true,
 	});
 	if (telemetry) input.telemetry = telemetry;
-	return resolveAgentTools(input);
+	return resolveAgentTools(input).filter(
+		(tool) => tool.name !== ToolNames.SelfCompact || !runtime.runtimeResolution.runtime.externalAgentLoop,
+	);
 }

package/src/tools/bootstrap.ts

@@ -22,11 +22,13 @@ import { lazyTool } from "./lazy-tool.js";
 import { monitorToolSurface } from "./monitor-surface.js";
 import { panesToolSurface } from "./panes-surface.js";
 import type { ToolRegistry } from "./registry.js";
+import { createSelfCompactTool, type RequestSelfCompact } from "./self-compact.js";
 import { steerToolSurface } from "./steer-surface.js";
 
 export { toolPromptHintsForNames };
 
 export interface ToolBootstrapDeps extends Omit<CoreToolBootstrapDeps, "mcpCapabilities"> {
+	requestSelfCompact?: RequestSelfCompact;
 	captureWorkerContext?: () => WorkerContextSnapshot | null;
 	dispatch?: DispatchContract;
 	bus?: SafeEventBus;
@@ -77,6 +79,10 @@ export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps
 		...coreDeps,
 		...(mcpCapabilities ? { mcpCapabilities } : {}),
 	});
+	if (deps.requestSelfCompact)
+		registry.register(
+			builtin(createSelfCompactTool(deps.requestSelfCompact), { path: "src/tools/self-compact.ts", scope: "core" }),
+		);
 	if (deps.dispatch) {
 		const dispatch = deps.dispatch;
 		// Display tail only. In a composed process the dispatch domain writes the

package/src/tools/builtin-tool-catalog.ts

@@ -100,6 +100,15 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		promptHint:
 			"Use code_nav with source=workspace (default) for project code and source=clio for Clio's shipped code map; modes: symbol, path, entries, outline, deps, dependents, wiki (workspace only).",
 	},
+	[ToolNames.SelfCompact]: {
+		objective: "Save an exact assistant handoff and reduce native session context.",
+		uiLabel: "Compact",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: { kind: "exact", maxBytes: 2048 },
+		costLatency: "local_fast",
+		promptHint:
+			'Use self_compact alone at a safe boundary. Preserve decisions, evidence, paths, and next actions in note_to_self. Inspect context(scope="budget") for current pressure; recovery belongs to the operator.',
+	},
 	[ToolNames.Context]: {
 		objective: "Return workspace, effective configuration, skill, or recall context.",
 		uiLabel: "Context",

package/src/tools/context/index.ts

@@ -3,14 +3,9 @@ import path from "node:path";
 import type { ContextRecalledPayload } from "../../core/bus-events.js";
 import type { ClioSettings } from "../../core/config.js";
 import { settingsAwareness } from "../../core/settings-awareness.js";
-import {
-	SKILL_INSTALL_OFFER_OPTION_NEVER,
-	SKILL_INSTALL_OFFER_OPTION_NOT_NOW,
-	SKILL_INSTALL_OFFER_OPTION_PROJECT,
-	SKILL_INSTALL_OFFER_OPTION_USER,
-	SKILL_SUGGESTION_ANCHOR,
-} from "../../core/skill-activation.js";
+import { SKILL_SUGGESTION_ANCHOR } from "../../core/skill-activation.js";
 import { ToolNames } from "../../core/tool-names.js";
+import type { BudgetProvider } from "../../domains/context/budget/inspection.js";
 import type { WorkerRecall } from "../../domains/context/worker/recall.js";
 import { foldWorkingSet } from "../../domains/context/working-set/fold.js";
 import {
@@ -21,7 +16,9 @@ import {
 	resolveRecall,
 } from "../../domains/context/working-set/recall.js";
 import {
+	buildSkillCatalogView,
 	checkSkillDrift,
+	checkSkillDriftBatch,
 	discoverMarketplaceSkills,
 	installedSkillNames,
 	installedSkillPackages,
@@ -30,6 +27,7 @@ import {
 	type MarketplaceSkill,
 	modelVisibleSkills,
 	type Skill,
+	type SkillCatalogRowKind,
 } from "../../domains/resources/index.js";
 import type { SessionEntryInput } from "../../domains/session/contract.js";
 import type { SessionEntry } from "../../domains/session/entries.js";
@@ -78,6 +76,8 @@ export interface ContextSessionDeps {
 }
 
 export interface ContextToolDeps {
+	/** Refreshes this run's native budget; absent for external/worker registries. */
+	getContextBudget?: BudgetProvider;
 	/** Live session view, including overrides. Omit when no authoritative settings snapshot exists. */
 	getSettings?: () => Readonly<ClioSettings>;
 	/** Run-scoped evidence port; never reads or appends the parent session. */
@@ -294,84 +294,29 @@ function marketplaceRowsFor(
 	}
 }
 
-function renderSkillsList(
-	skills: ReadonlyArray<Skill>,
-	marketplace: ReadonlyArray<MarketplaceSkill>,
-	marketplaceOffered: boolean,
-	modelActivation: boolean,
-	packages: ReturnType<typeof installedSkillPackages> = [],
-): string {
-	if (skills.length === 0 && marketplace.length === 0 && packages.length === 0) {
-		// A registry that never offers the marketplace (a worker) must not
-		// claim none is configured; it simply has nothing to list.
-		return marketplaceOffered
-			? "No skills are available in Clio and no additional marketplace skills were found."
-			: "No skills are available in Clio.";
-	}
-	// The header names the listing and nothing more. The reply protocol is
-	// stated once, as the recency anchor at the bottom, because that is the
-	// line literal models act on; a second copy up here cost every listing
-	// call the same sentences again.
-	const lines = ["Available skills.", ""];
-
-	const native = skills.filter((skill) => skill.source === "clio-coder" || skill.source === "plugin");
-	const discovered = skills.filter((skill) => skill.source !== "clio-coder" && skill.source !== "plugin");
-	lines.push(`Ready skills in Clio (${native.length}):`);
-	if (native.length === 0) lines.push("- none");
-	for (const skill of native) {
-		lines.push(`- ${skill.name} (source: ${skill.source}; scope: ${skill.scope}): ${skill.description}`);
-	}
-	if (discovered.length > 0) {
-		lines.push("", "Explicitly supplied session skills (not installed packages):");
-		for (const skill of discovered) {
-			lines.push(
-				`- ${skill.name} (source: ${skill.source}; scope: ${skill.scope}; file: ${skill.filePath}): ${skill.description}`,
-			);
-		}
-		lines.push(
-			"These skills were explicitly supplied for this session. Preserve their source; session availability does not mean Clio installed or copied them.",
-		);
-	}
-
-	if (packages.length > 0) {
-		lines.push("", `Installed packages providing skills (${packages.length}):`);
-		for (const pkg of packages)
-			lines.push(
-				`- ${pkg.name} (scope: ${pkg.scope}; origin: ${pkg.origin === "catalog" ? "marketplace catalog" : pkg.origin}; state: ${pkg.state}; path: ${pkg.path})`,
-			);
-	}
-	lines.push(
-		"",
-		"Other-agent skill folders are discovery-only. Explicitly import into Clio before use; the trust-imports setting does not install or activate loose files.",
-	);
-
-	if (marketplace.length > 0) {
-		// Installable rows are suggested exactly like installed ones: the
-		// operator's /skill <name> prompts to install before it runs, so the
-		// model's move is the same suggest-and-wait. Only the body is out of
-		// reach until then, which is why the description is all that appears.
-		lines.push("", "Marketplace (additional skills available to install; /skill <name> offers to install):");
-		for (const entry of marketplace) {
-			const category = entry.category ? ` [${entry.category}]` : "";
-			lines.push(`- ${entry.name}${category}: ${entry.description}`);
-		}
-	}
-	// Recency anchor with an exact reply shape: literal models act on an output
-	// template where they skip conditional prose in the header.
-	lines.push(
-		"",
-		modelActivation
-			? `If one skill above matches the current task, load it now with context(scope="skills", name="<name>") and continue in the same turn; at this autonomy level you activate installed skills yourself and do not wait for the operator. Marketplace additions still require operator approval. If none match, do not mention skills.`
-			: `If one skill above matches the current task, begin your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose), then continue the task in the same turn without it; only the operator can run it. If none match, do not mention skills.`,
-	);
-	if (marketplace.length > 0) {
-		// The offer protocol mirrors the marketplace-offer middleware: fixed
-		// option labels so the harness recognizes and handles the answer.
-		lines.push(
-			`When no installed skill serves the task but a marketplace skill above genuinely does, you may instead ask the operator with ask_user (mode=single_question, header "Install skill") whether to install it, offering exactly: "${SKILL_INSTALL_OFFER_OPTION_PROJECT}", "${SKILL_INSTALL_OFFER_OPTION_USER}", "${SKILL_INSTALL_OFFER_OPTION_NOT_NOW}", "${SKILL_INSTALL_OFFER_OPTION_NEVER}". The harness handles those exact offer options. An explicit operator request or approval also authorizes the documented library install CLI. After installation, refresh the inventory; distinguish installed from ready and report /library reload when required.`,
-		);
+/**
+ * Ready rows whose installed content no longer matches the hash recorded for
+ * it, resolved for the whole listing in one manifest read.
+ *
+ * Drift used to be checked only in the activation branch below, so the listing
+ * reported a drifted skill as ready with no caveat and the warning arrived only
+ * after the model had already spent its turn loading it. This is the same
+ * comparison, one step earlier, through the batched entry point so a listing
+ * does not re-parse the pin manifest once per row.
+ *
+ * It annotates and nothing else. The skill stays listed, stays ready and stays
+ * loadable, the installed copy keeps its ownership, and the activation warning
+ * is unchanged. A skill with no recorded hash is not marked, because absence of
+ * evidence is not drift, and a failure here yields an unmarked listing rather
+ * than no listing.
+ */
+function driftedSkillNames(skills: ReadonlyArray<Skill>, cwd: string): Set<string> {
+	try {
+		const reports = checkSkillDriftBatch(skills, cwd);
+		return new Set([...reports].filter(([, report]) => report.verdict === "mismatch").map(([name]) => name));
+	} catch {
+		return new Set<string>();
 	}
-	return lines.join("\n");
 }
 
 function runWorkspaceScope(
@@ -496,38 +441,71 @@ function runSkillsScope(
 						cwdFromDeps(deps),
 						deps.getSkillLoaderOptions?.().trustProjectCompatRoots === true,
 					);
-		const rendered = renderSkillsList(
-			visible,
-			marketplace,
-			deps.skillMarketplace !== false,
-			options?.pendingSkillPolicy?.modelActivation === true,
+		// The catalog is bounded but not small, and it has to fit the per-call cap
+		// like any observation. It is cut by whole rows with the reply protocol
+		// reserved first, rather than by head-truncating the finished string:
+		// head truncation keeps the head, and the tail is the one line a model
+		// acts on. `query`, `limit` and `offset` are the context tool's existing
+		// optional arguments, wired here so a caller can ask for less than all of
+		// it; omitting them still lists every row.
+		const view = buildSkillCatalogView({
+			skills: visible,
 			packages,
-		);
-		// The catalog is bounded but not small: the whole listing must fit the
-		// per-call cap like any observation, and a cut list says so instead of
-		// silently dropping the marketplace tail.
-		const truncation = truncateHead(rendered, { maxBytes: reservation.callCapBytes, maxLines: Number.MAX_SAFE_INTEGER });
-		const total = visible.length + marketplace.length + packages.length;
+			marketplace,
+			drifted: driftedSkillNames(visible, cwdFromDeps(deps)),
+			marketplaceOffered: deps.skillMarketplace !== false,
+			modelActivation: options?.pendingSkillPolicy?.modelActivation === true,
+			query: typeof args.query === "string" ? args.query : "",
+			limit: typeof args.limit === "number" ? args.limit : undefined,
+			offset: typeof args.offset === "number" ? args.offset : 0,
+			capBytes: reservation.callCapBytes,
+		});
+		// Shown rows are selected by the row's own stable key, not by its name. An
+		// installed standalone skill has a ready row and a package row under one
+		// name, and the same package id can be installed at user and project scope,
+		// so a name set puts rows in `details` that the text never carried.
+		const shownKeys = new Set(view.rows.map((row) => row.key));
+		const shown = (kind: SkillCatalogRowKind, identity: string): boolean => shownKeys.has(`${kind}:${identity}`);
 		return finalizeObservation({
 			tool: ToolNames.Context,
 			unit: "entries",
-			output: truncation.content,
-			...(truncation.truncated ? { fullOutput: rendered } : {}),
-			shownCount: total,
-			totalCount: total,
-			truncated: truncation.truncated,
+			output: view.text,
+			shownCount: view.shown,
+			totalCount: view.total,
+			truncated: view.nextOffset !== undefined || view.shown < view.total,
+			// Offsets index the filtered result set. A continuation carrying only
+			// the offset would be applied to the unfiltered catalog, which repeats
+			// rows and skips matches, so the envelope says the query is part of it.
+			...(view.nextOffset !== undefined
+				? {
+						next: view.filtered ? `offset=${view.nextOffset} with the same query` : `offset=${view.nextOffset}`,
+					}
+				: {}),
 			details: {
-				skills: visible.map((skill) => ({
-					name: skill.name,
-					scope: skill.scope,
-					source: skill.source,
-					path: skill.filePath,
-				})),
-				installedPackages: packages,
-				marketplace: marketplace.map((entry) => ({
-					name: entry.name,
-					...(entry.category ? { category: entry.category } : {}),
-				})),
+				// Rows on this page, so a caller reading `details` sees the same
+				// listing the text carries. The totals beside them are how a
+				// filtered or paged view is told apart from a complete one.
+				skills: visible
+					.filter((skill) => shown("ready", skill.filePath) || shown("session", skill.filePath))
+					.map((skill) => ({
+						name: skill.name,
+						scope: skill.scope,
+						source: skill.source,
+						path: skill.filePath,
+						...(view.driftedNames.includes(skill.name) ? { drift: "mismatch" } : {}),
+					})),
+				installedPackages: packages.filter((pkg) => shown("package", `${pkg.scope}:${pkg.path}`)),
+				marketplace: marketplace
+					.filter((entry) => shown("marketplace", entry.sourceUrl))
+					.map((entry) => ({
+						name: entry.name,
+						...(entry.category ? { category: entry.category } : {}),
+					})),
+				totalSkills: visible.length,
+				totalPackages: packages.length,
+				totalMarketplace: marketplace.length,
+				...(view.filtered ? { query: (args.query as string).trim(), matchMode: view.matchMode } : {}),
+				...(view.driftedNames.length > 0 ? { drifted: view.driftedNames } : {}),
 			},
 			reservation,
 			...(options ? { options } : {}),
@@ -767,6 +745,52 @@ function runRecallScope(
 	});
 }
 
+/** A byte-fitted JSON observation. Inspection never spills to disk. */
+function runBudgetScope(
+	deps: ContextToolDeps,
+	reservation: ObservationReservation,
+	options?: ToolInvokeOptions,
+): ToolResult {
+	const inspection = deps.getContextBudget?.() ?? {
+		status: "unavailable",
+		reason:
+			"This run has no native session budget port. Worker and external-agent budgets are not the parent session's budget.",
+	};
+	const payload =
+		inspection.status === "available"
+			? {
+					...inspection,
+					mode: "enforced",
+					admissionNote:
+						"Submission and continuation enforce input plus reserved output against the effective window. Counts are estimates unless provider-attested; pressure advice remains advisory.",
+				}
+			: inspection;
+	const full = JSON.stringify(payload);
+	const fits = Buffer.byteLength(full, "utf8") <= reservation.callCapBytes;
+	// Do not pass fullOutput to finalizeObservation: an inspection must not
+	// persist its view even when an optional projection contains huge text.
+	const output = fits
+		? full
+		: JSON.stringify({
+				status: "unavailable",
+				reason: "observation-limit",
+				message:
+					"The budget view exceeds the available observation bytes. Continue in a follow-up turn; do not retry this turn.",
+			});
+	return finalizeObservation({
+		tool: ToolNames.Context,
+		unit: "results",
+		format: "json",
+		output,
+		shownCount: fits ? 1 : 0,
+		totalCount: 1,
+		totalBytes: Buffer.byteLength(full, "utf8"),
+		truncated: !fits,
+		reservation,
+		...(options ? { options } : {}),
+	});
+}
+
 export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 	return {
 		...contextToolSurface,
@@ -782,12 +806,21 @@ export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 					message: `context: scope "${scope}" is a gateway capability now: call gateway(op="call", capability="${capability}", args={...}) or gateway(op="describe", capability="${capability}") for its arguments.`,
 				};
 			}
-			if (scope !== "workspace" && scope !== "settings" && scope !== "skills" && scope !== "recall") {
+			if (
+				scope !== "workspace" &&
+				scope !== "settings" &&
+				scope !== "skills" &&
+				scope !== "recall" &&
+				scope !== "budget"
+			) {
 				return {
 					kind: "error",
-					message: `context: scope must be workspace, settings, skills, or recall; got '${scope}'`,
+					message: `context: scope must be workspace, settings, skills, recall, or budget; got '${scope}'`,
 				};
 			}
+			if (scope === "budget" && Object.keys(args).some((key) => key !== "scope")) {
+				return { kind: "error", message: 'context: scope="budget" accepts only scope; it inspects the current request.' };
+			}
 			const selfCap = scope === "skills" ? OBSERVE_SELF_CAPS.contextSkills : OBSERVE_SELF_CAPS.contextWorkspace;
 			// Reserved before any scope handler runs, so an exhausted pool answers
 			// with the notice and no scope does its work for nothing.
@@ -796,6 +829,7 @@ export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 				return observationBudgetExhausted({
 					tool: ToolNames.Context,
 					unit: scope === "skills" ? "entries" : "results",
+					...(scope === "budget" ? { format: "json" as const } : {}),
 					reservation,
 					subject: `scope=${scope}`,
 					hint: "Continue in a follow-up turn.",
@@ -838,6 +872,7 @@ export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 					...(options ? { options } : {}),
 				});
 			}
+			if (scope === "budget") return runBudgetScope(deps, reservation, options);
 			if (scope === "workspace") return runWorkspaceScope(deps, reservation, options);
 			if (scope === "recall") return runRecallScope(deps, args, reservation, options);
 			return runSkillsScope(deps, args, reservation, options);