pi-ui-extend 1.0.39 → 1.0.41

package/external/pi-tools-suite/src/session-recovery/index.ts

@@ -43,6 +43,11 @@ type Section = {
 	label: string;
 };
 
+type RecoveryCursor =
+	| { version: 1; kind: "overview"; scope: Scope; afterSectionId: string }
+	| { version: 1; kind: "search"; scope: Scope; query: string; caseSensitive: boolean; afterEntryId: string }
+	| { version: 1; kind: "read"; scope: Scope; sectionId?: string; entryId: string; offset: number };
+
 const SCOPE_SCHEMA = StringEnum(["active", "all"] as const, {
 	description: "Raw session scope. Defaults to the active root-to-leaf branch; all includes abandoned branches.",
 });
@@ -61,6 +66,8 @@ const MAX_RECENT_ERRORS = 20;
 const MAX_RECOVERY_FILES = 200;
 const MAX_PENDING_TOOL_CALLS = 50;
 const MAX_SEARCH_QUERY_CHARS = 500;
+const CURSOR_VERSION = 1;
+const DCP_CONTROL_CUSTOM_TYPES = new Set(["dcp-journal", "dcp-nudge"]);
 
 const READ_TOOL_NAMES = new Set([
 	"read",
@@ -88,6 +95,10 @@ function isEntry(value: unknown): value is EntryLike {
 		&& typeof value.type === "string" && value.type.length > 0;
 }
 
+function isDcpControlEntry(entry: EntryLike): boolean {
+	return entry.type === "custom" && typeof entry.customType === "string" && DCP_CONTROL_CUSTOM_TYPES.has(entry.customType);
+}
+
 function clampInteger(value: unknown, fallback: number, minimum: number, maximum: number): number {
 	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
 	return Math.min(maximum, Math.max(minimum, Math.floor(value)));
@@ -119,7 +130,39 @@ function entriesFor(manager: SessionManagerLike | undefined, scope: Scope): Entr
 			: () => manager.getBranch?.(),
 		[],
 	);
-	return Array.isArray(raw) ? raw.filter(isEntry) : [];
+	return Array.isArray(raw) ? raw.filter(isEntry).filter((entry) => !isDcpControlEntry(entry)) : [];
+}
+
+function encodeCursor(cursor: RecoveryCursor): string {
+	return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+
+function decodeCursor(value: unknown): RecoveryCursor | undefined {
+	if (typeof value !== "string" || value.length === 0 || value.length > 2_000) return undefined;
+	try {
+		const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+		if (!isRecord(parsed) || parsed.version !== CURSOR_VERSION || typeof parsed.kind !== "string") return undefined;
+		if (parsed.scope !== "active" && parsed.scope !== "all") return undefined;
+		if (parsed.kind === "overview" && typeof parsed.afterSectionId === "string") {
+			return parsed as RecoveryCursor;
+		}
+		if (
+			parsed.kind === "search" && typeof parsed.query === "string" && typeof parsed.caseSensitive === "boolean"
+			&& typeof parsed.afterEntryId === "string"
+		) {
+			return parsed as RecoveryCursor;
+		}
+		if (
+			parsed.kind === "read" && typeof parsed.entryId === "string" && typeof parsed.offset === "number"
+			&& Number.isInteger(parsed.offset) && parsed.offset >= 0
+			&& (parsed.sectionId === undefined || typeof parsed.sectionId === "string")
+		) {
+			return parsed as RecoveryCursor;
+		}
+	} catch {
+		return undefined;
+	}
+	return undefined;
 }
 
 function messageFrom(entry: EntryLike): UnknownRecord | undefined {
@@ -358,16 +401,16 @@ function leafCount(entries: EntryLike[]): number {
 	return entries.reduce((count, entry) => count + (parents.has(entry.id) ? 0 : 1), 0);
 }
 
-function renderEntry(entry: EntryLike, bodyChars: number): string {
+function renderEntryFull(entry: EntryLike): string {
 	const heading = [`[${entry.id}]`, entry.timestamp, entry.type, messageRole(entry)].filter(Boolean).join(" ");
 	const lines = [heading];
 	const message = messageFrom(entry);
 
 	if (message) {
 		const text = textFromContent(message.content);
-		if (text) lines.push(truncate(text, bodyChars));
+		if (text) lines.push(text);
 		for (const call of toolCallsFrom(entry)) {
-			lines.push(`tool_call ${call.name}#${call.id} ${safeJson(call.arguments, bodyChars)}`);
+			lines.push(`tool_call ${call.name}#${call.id} ${serializeJson(call.arguments)}`);
 		}
 		if (message.role === "toolResult") {
 			const toolName = typeof message.toolName === "string" ? message.toolName : "unknown";
@@ -375,25 +418,39 @@ function renderEntry(entry: EntryLike, bodyChars: number): string {
 			lines.push(`tool_result ${toolName}#${callId}${message.isError === true ? " error" : ""}`);
 		}
 	} else if (entry.type === "compaction") {
-		lines.push(truncate(summaryFrom(entry), bodyChars));
+		lines.push(summaryFrom(entry));
 		if (typeof entry.firstKeptEntryId === "string") lines.push(`firstKeptEntryId: ${entry.firstKeptEntryId}`);
 		if (typeof entry.tokensBefore === "number") lines.push(`tokensBefore: ${entry.tokensBefore}`);
 	} else if (entry.type === "branch_summary") {
-		lines.push(truncate(summaryFrom(entry), bodyChars));
+		lines.push(summaryFrom(entry));
 		if (typeof entry.fromId === "string") lines.push(`fromId: ${entry.fromId}`);
 	} else if (entry.type === "custom_message") {
 		const text = textFromContent(entry.content);
-		if (text) lines.push(truncate(text, bodyChars));
+		if (text) lines.push(text);
 	} else {
 		const fields = Object.fromEntries(
 			Object.entries(entry).filter(([key]) => !["id", "parentId", "timestamp", "type"].includes(key)),
 		);
-		if (Object.keys(fields).length > 0) lines.push(safeJson(fields, bodyChars));
+		if (Object.keys(fields).length > 0) lines.push(safeJson(fields, MAX_BODY_CHARS));
 	}
 
 	return lines.join("\n");
 }
 
+function renderEntry(entry: EntryLike, bodyChars: number): string {
+	return truncate(renderEntryFull(entry), bodyChars);
+}
+
+function readEntryChunk(entry: EntryLike, offset: number, bodyChars: number): { text: string; nextOffset?: number } {
+	const rendered = renderEntryFull(entry);
+	const start = Math.min(Math.max(0, offset), rendered.length);
+	const end = Math.min(rendered.length, start + bodyChars);
+	return {
+		text: rendered.slice(start, end),
+		...(end < rendered.length ? { nextOffset: end } : {}),
+	};
+}
+
 function contentResult(payload: unknown, details: UnknownRecord): { content: Array<{ type: "text"; text: string }>; details: UnknownRecord } {
 	const serialized = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
 	return {
@@ -448,14 +505,19 @@ export default function sessionRecovery(pi: ExtensionAPI): void {
 		...SESSION_RECOVERY_TOOL_DESCRIPTIONS.overview,
 		parameters: Type.Object({
 			scope: Type.Optional(SCOPE_SCHEMA),
+			cursor: Type.Optional(Type.String({ description: "Opaque continuation cursor returned by a previous session_overview call.", maxLength: 2_000 })),
 			max_sections: Type.Optional(Type.Number({
-				description: "Maximum section summaries to return, split between the head and tail.",
+				description: "Maximum consecutive section summaries to return.",
 				minimum: 1,
 				maximum: MAX_OVERVIEW_SECTIONS,
 			})),
 		}, { additionalProperties: false }),
-		async execute(_toolCallId: string, params: { scope?: Scope; max_sections?: number }, _signal: AbortSignal, _onUpdate: unknown, ctx: unknown) {
+		async execute(_toolCallId: string, params: { scope?: Scope; cursor?: string; max_sections?: number }, _signal: AbortSignal, _onUpdate: unknown, ctx: unknown) {
 			const scope = scopeFrom(params.scope);
+			const cursor = params.cursor ? decodeCursor(params.cursor) : undefined;
+			if (params.cursor && (!cursor || cursor.kind !== "overview" || cursor.scope !== scope)) {
+				return contentResult("Invalid or stale session_overview cursor for this scope.", { scope, cursorValid: false });
+			}
 			const manager = sessionManagerFrom(ctx);
 			const entries = entriesFor(manager, scope);
 			if (entries.length === 0) return emptyResult(scope);
@@ -464,7 +526,19 @@ export default function sessionRecovery(pi: ExtensionAPI): void {
 			const allEntries = entriesFor(manager, "all");
 			const sections = buildSections(entries);
 			const maximum = clampInteger(params.max_sections, DEFAULT_OVERVIEW_SECTIONS, 1, MAX_OVERVIEW_SECTIONS);
-			const selected = boundedHeadAndTail(sections, maximum);
+			let startIndex = 0;
+			if (cursor?.kind === "overview") {
+				const index = sections.findIndex((section) => section.id === cursor.afterSectionId);
+				if (index < 0) {
+					return contentResult("The session changed and the overview cursor no longer resolves on this branch.", { scope, cursorValid: false });
+				}
+				startIndex = index + 1;
+			}
+			const selected = sections.slice(startIndex, startIndex + maximum);
+			const hasMore = startIndex + selected.length < sections.length;
+			const nextCursor = hasMore && selected.length > 0
+				? encodeCursor({ version: CURSOR_VERSION, kind: "overview", scope, afterSectionId: selected[selected.length - 1]!.id })
+				: undefined;
 			const allLeaves = leafCount(allEntries);
 			const header = callSafely<unknown>(() => manager?.getHeader?.(), undefined);
 			const sessionId = callSafely<unknown>(() => manager?.getSessionId?.(), undefined);
@@ -487,57 +561,101 @@ export default function sessionRecovery(pi: ExtensionAPI): void {
 					leaves: allLeaves,
 					otherBranches: Math.max(0, allLeaves - (activeEntries.length > 0 ? 1 : 0)),
 				},
-				sections: selected.values.map(sectionSummary),
-				omittedSections: selected.omitted,
+				sections: selected.map(sectionSummary),
+				hasMore,
+				nextCursor: nextCursor ?? null,
 			};
-			return contentResult(payload, { scope, entryCount: entries.length, sectionCount: sections.length, omittedSections: selected.omitted });
+			return contentResult(payload, { scope, entryCount: entries.length, sectionCount: sections.length, returnedSections: selected.length, hasMore, nextCursor });
 		},
 	});
 
 	pi.registerTool({
 		...SESSION_RECOVERY_TOOL_DESCRIPTIONS.readSection,
 		parameters: Type.Object({
-			section_id: Type.String({ description: "Stable section ID returned by session_overview or session_search.", maxLength: 200 }),
+			section_id: Type.Optional(Type.String({ description: "Stable section ID returned by session_overview or session_search.", maxLength: 200 })),
+			entry_id: Type.Optional(Type.String({ description: "Read one exact raw session entry by ID without scanning from the start of its section.", maxLength: 200 })),
+			cursor: Type.Optional(Type.String({ description: "Opaque continuation cursor returned by a previous session_read_section call.", maxLength: 2_000 })),
 			scope: Type.Optional(SCOPE_SCHEMA),
 			max_entries: Type.Optional(Type.Number({ description: "Maximum entries to render from the section.", minimum: 1, maximum: MAX_SECTION_ENTRIES })),
-			max_body_chars: Type.Optional(Type.Number({ description: "Maximum rendered body characters per entry.", minimum: 100, maximum: MAX_BODY_CHARS })),
+			max_body_chars: Type.Optional(Type.Number({ description: "Maximum rendered characters per entry page. Use the returned cursor to continue long entries.", minimum: 100, maximum: MAX_BODY_CHARS })),
 		}, { additionalProperties: false }),
-		async execute(_toolCallId: string, params: { section_id: string; scope?: Scope; max_entries?: number; max_body_chars?: number }, _signal: AbortSignal, _onUpdate: unknown, ctx: unknown) {
+		async execute(_toolCallId: string, params: { section_id?: string; entry_id?: string; cursor?: string; scope?: Scope; max_entries?: number; max_body_chars?: number }, _signal: AbortSignal, _onUpdate: unknown, ctx: unknown) {
 			const scope = scopeFrom(params.scope);
+			if (!params.cursor && Boolean(params.section_id) === Boolean(params.entry_id)) {
+				return contentResult("Pass exactly one of section_id or entry_id, or continue with cursor.", { scope, found: false });
+			}
+			const cursor = params.cursor ? decodeCursor(params.cursor) : undefined;
+			if (params.cursor && (!cursor || cursor.kind !== "read" || cursor.scope !== scope)) {
+				return contentResult("Invalid or stale session_read_section cursor for this scope.", { scope, cursorValid: false, sourceAvailable: false });
+			}
 			const entries = entriesFor(sessionManagerFrom(ctx), scope);
 			if (entries.length === 0) return emptyResult(scope);
-			const section = buildSections(entries).find((candidate) => candidate.id === params.section_id);
-			if (!section) {
+			const sections = buildSections(entries);
+			const requestedSectionId = cursor?.kind === "read" ? cursor.sectionId : params.section_id;
+			const requestedEntryId = cursor?.kind === "read" ? cursor.entryId : params.entry_id;
+			const offset = cursor?.kind === "read" ? cursor.offset : 0;
+			const section = requestedSectionId ? sections.find((candidate) => candidate.id === requestedSectionId) : undefined;
+			if (requestedSectionId && !section) {
 				return contentResult(
-					`Section ${params.section_id} was not found in scope ${scope}. Run session_overview with the same scope to refresh section IDs.`,
-					{ scope, sectionId: params.section_id, found: false },
+					`Section ${requestedSectionId} was not found in scope ${scope}. Run session_overview with the same scope to refresh section IDs.`,
+					{ scope, sectionId: requestedSectionId, found: false, sourceAvailable: false },
 				);
 			}
 
 			const maximum = clampInteger(params.max_entries, DEFAULT_SECTION_ENTRIES, 1, MAX_SECTION_ENTRIES);
 			const bodyChars = clampInteger(params.max_body_chars, DEFAULT_BODY_CHARS, 100, MAX_BODY_CHARS);
+			const candidates = section ? section.entries : entries;
+			let startIndex = requestedEntryId ? candidates.findIndex((entry) => entry.id === requestedEntryId) : 0;
+			if (startIndex < 0) {
+				return contentResult(
+					`Entry ${requestedEntryId} was not found in scope ${scope}${section ? ` within ${section.id}` : ""}.`,
+					{ scope, sectionId: section?.id, entryId: requestedEntryId, found: false, sourceAvailable: false },
+				);
+			}
 			const rendered: string[] = [];
 			let renderedChars = 0;
-			let truncatedOutput = false;
-			for (const entry of section.entries.slice(0, maximum)) {
-				const next = renderEntry(entry, bodyChars);
-				if (renderedChars + next.length + 2 > MAX_OUTPUT_CHARS - 500) {
-					truncatedOutput = true;
-					break;
-				}
+			let nextCursor: string | undefined;
+			let renderedCount = 0;
+			for (let index = startIndex; index < candidates.length && renderedCount < maximum; index += 1) {
+				const entry = candidates[index]!;
+				const entryOffset = index === startIndex ? offset : 0;
+				const chunk = readEntryChunk(entry, entryOffset, bodyChars);
+				const heading = entryOffset > 0 ? `[${entry.id}] continuation @${entryOffset}` : undefined;
+				const next = [heading, chunk.text].filter(Boolean).join("\n");
+				if (renderedChars + next.length + 2 > MAX_OUTPUT_CHARS - 1_000) break;
 				rendered.push(next);
 				renderedChars += next.length + 2;
+				renderedCount += 1;
+				if (chunk.nextOffset !== undefined) {
+					nextCursor = encodeCursor({ version: CURSOR_VERSION, kind: "read", scope, sectionId: section?.id, entryId: entry.id, offset: chunk.nextOffset });
+					break;
+				}
+				const nextEntry = candidates[index + 1];
+				if (nextEntry && (renderedCount >= maximum || renderedChars >= MAX_OUTPUT_CHARS - 1_000)) {
+					nextCursor = encodeCursor({ version: CURSOR_VERSION, kind: "read", scope, sectionId: section?.id, entryId: nextEntry.id, offset: 0 });
+					break;
+				}
 			}
-			const omittedEntries = section.entries.length - rendered.length;
+			if (!nextCursor) {
+				const lastRendered = renderedCount > 0 ? startIndex + renderedCount - 1 : startIndex - 1;
+				const nextEntry = candidates[lastRendered + 1];
+				if (nextEntry) nextCursor = encodeCursor({ version: CURSOR_VERSION, kind: "read", scope, sectionId: section?.id, entryId: nextEntry.id, offset: 0 });
+			}
+			const hasMore = nextCursor !== undefined;
+			const title = section ? `Section ${section.id}: ${section.label}` : `Entry ${requestedEntryId}`;
 			return contentResult(
-				[`Section ${section.id}: ${section.label}`, ...rendered, omittedEntries > 0 ? `… ${omittedEntries} entries omitted` : ""].filter(Boolean).join("\n\n"),
+				[title, ...rendered, hasMore ? "… more available; continue with next_cursor" : ""].filter(Boolean).join("\n\n"),
 				{
 					scope,
-					sectionId: section.id,
-					entryCount: section.entries.length,
-					renderedCount: rendered.length,
-					omittedEntries,
-					truncated: truncatedOutput || omittedEntries > 0,
+					sectionId: section?.id,
+					entryId: requestedEntryId,
+					entryCount: candidates.length,
+					renderedCount,
+					found: true,
+					sourceAvailable: true,
+					hasMore,
+					truncated: hasMore,
+					nextCursor,
 				},
 			);
 		},
@@ -552,10 +670,11 @@ export default function sessionRecovery(pi: ExtensionAPI): void {
 				maxLength: MAX_SEARCH_QUERY_CHARS,
 			}),
 			scope: Type.Optional(SCOPE_SCHEMA),
+			cursor: Type.Optional(Type.String({ description: "Opaque continuation cursor returned by a previous session_search call.", maxLength: 2_000 })),
 			case_sensitive: Type.Optional(Type.Boolean({ description: "Use exact case matching. Defaults to false." })),
 			limit: Type.Optional(Type.Number({ description: "Maximum matches to return.", minimum: 1, maximum: MAX_SEARCH_RESULTS })),
 		}, { additionalProperties: false }),
-		async execute(_toolCallId: string, params: { query: string; scope?: Scope; case_sensitive?: boolean; limit?: number }, _signal: AbortSignal, _onUpdate: unknown, ctx: unknown) {
+		async execute(_toolCallId: string, params: { query: string; scope?: Scope; cursor?: string; case_sensitive?: boolean; limit?: number }, _signal: AbortSignal, _onUpdate: unknown, ctx: unknown) {
 			const scope = scopeFrom(params.scope);
 			const entries = entriesFor(sessionManagerFrom(ctx), scope);
 			if (entries.length === 0) return emptyResult(scope);
@@ -563,20 +682,24 @@ export default function sessionRecovery(pi: ExtensionAPI): void {
 			if (!query) return contentResult("Search query must not be empty.", { scope, query, matchCount: 0 });
 
 			const caseSensitive = params.case_sensitive === true;
+			const cursor = params.cursor ? decodeCursor(params.cursor) : undefined;
+			if (
+				params.cursor && (!cursor || cursor.kind !== "search" || cursor.scope !== scope
+					|| cursor.query !== query || cursor.caseSensitive !== caseSensitive)
+			) {
+				return contentResult("Invalid or stale session_search cursor for this scope/query.", { scope, query, cursorValid: false });
+			}
 			const needle = caseSensitive ? query : query.toLocaleLowerCase();
 			const limit = clampInteger(params.limit, DEFAULT_SEARCH_RESULTS, 1, MAX_SEARCH_RESULTS);
 			const sections = buildSections(entries);
 			const entrySections = sectionIdByEntry(sections);
-			const matches: UnknownRecord[] = [];
-			let totalMatches = 0;
+			const allMatches: UnknownRecord[] = [];
 
 			for (const entry of entries) {
 				const text = entryText(entry);
 				const haystack = caseSensitive ? text : text.toLocaleLowerCase();
 				if (!text || !haystack.includes(needle)) continue;
-				totalMatches += 1;
-				if (matches.length >= limit) continue;
-				matches.push({
+				allMatches.push({
 					entryId: entry.id,
 					sectionId: entrySections.get(entry.id),
 					type: entry.type,
@@ -586,8 +709,31 @@ export default function sessionRecovery(pi: ExtensionAPI): void {
 				});
 			}
 
-			const payload = { scope, query, caseSensitive, totalMatches, returnedMatches: matches.length, matches };
-			return contentResult(payload, { scope, query, matchCount: totalMatches, returnedCount: matches.length, truncated: totalMatches > matches.length });
+			let startIndex = 0;
+			if (cursor?.kind === "search") {
+				const index = allMatches.findIndex((match) => match.entryId === cursor.afterEntryId);
+				if (index < 0) {
+					return contentResult("The session changed and the search cursor no longer resolves on this branch.", { scope, query, cursorValid: false });
+				}
+				startIndex = index + 1;
+			}
+			const matches = allMatches.slice(startIndex, startIndex + limit);
+			const hasMore = startIndex + matches.length < allMatches.length;
+			const lastEntryId = matches.at(-1)?.entryId;
+			const nextCursor = hasMore && typeof lastEntryId === "string"
+				? encodeCursor({ version: CURSOR_VERSION, kind: "search", scope, query, caseSensitive, afterEntryId: lastEntryId })
+				: undefined;
+			const payload = {
+				scope,
+				query,
+				caseSensitive,
+				totalMatches: allMatches.length,
+				returnedMatches: matches.length,
+				hasMore,
+				nextCursor: nextCursor ?? null,
+				matches,
+			};
+			return contentResult(payload, { scope, query, matchCount: allMatches.length, returnedCount: matches.length, hasMore, truncated: hasMore, nextCursor });
 		},
 	});
 

package/external/pi-tools-suite/src/tool-descriptions.ts

@@ -1,4 +1,6 @@
 import { COMPRESS_RANGE_DESCRIPTION } from "./dcp/prompts.js";
+import { SUBAGENT_TYPE_SELECTION_GUIDANCE } from "./async-subagents/core/agent-catalog.js";
+import { SUBAGENT_DELEGATION_GUIDANCE } from "./async-subagents/core/agent-strategy.js";
 
 export type ToolDescription = {
 	name: string;
@@ -39,10 +41,11 @@ export function astGrepToolDescriptions(maxLines: number, maxBytesLabel: string)
 		astGrep: {
 			name: "ast_grep",
 			label: "ast-grep",
-			description: `Read-only AST structural search/scan. Use for language-aware patterns, sgconfig/rule scans, JSON matches, and rewrite previews. Use text search for plain strings and ast_apply for mutations. Output truncates at ${maxLines} lines or ${maxBytesLabel} with full output saved to a temp file.`,
-			promptSnippet: "Use ast_grep for AST/structural code search, not plain text search. It previews rewrites only; use ast_apply to mutate files.",
+			description: `Read-only AST structural search/scan. MANDATORY ROUTING: for structural, syntax-aware, AST, language-aware, or code-shape matching, ast_grep must be the FIRST tool call. Never preflight with Glob, Grep, Read, or shell even when files are unknown; omit paths to scan the current project. Use for sgconfig/rule scans, JSON matches, and rewrite previews. Use Grep for exact literals/regex, Glob only for filename/path-only requests, and ast_apply for mutations. Output truncates at ${maxLines} lines or ${maxBytesLabel} with full output saved to a temp file.`,
+			promptSnippet: "MANDATORY: structural/syntax-aware/AST/code-shape matching => call ast_grep FIRST. Do not call Glob, Grep, Read, or shell before it; unknown files are not a reason to pre-search because ast_grep scans the project by default. Exact literal/regex only => Grep; filename/path only => Glob. Use ast_apply for mutations.",
 			promptGuidelines: [
-				"Use ast_grep when syntax/AST structure matters; use text search for exact strings/regex. Keep paths/globs narrow and set lang for ambiguous snippets.",
+				"The first tool for syntax relationships or code-shape matching must be ast_grep, even when the file or language is unknown. Do not make a preliminary Glob/Grep/Read/shell call; start at the current project and narrow within ast_grep when needed.",
+				"Use Grep/Read directly for exact literal or regex lookups and Glob only for filename/path-only discovery; those text-only tasks must not trigger ast_grep.",
 				"ast_grep is read-only: use rewrite to preview only; use ast_apply for mutations or command=scan fixes.",
 			],
 		},
@@ -70,9 +73,9 @@ export function asyncSubagentToolDescriptions(options: ToolDescriptionSetOptions
 				"For every real-browser QA request, immediately spawn subagentType='browser-qa' before checking files, URLs, servers, or other prerequisites; the QA sub-agent owns feasibility checks and blocked reports, so the parent must not attempt browser QA itself.",
 				"If browser-qa reports that credentials are required, it must identify the generated project-local template and explicitly ask the user to fill it; the parent relays that request without reading or editing the credential file.",
 				"After browser testing, browser-qa must return clickable links for every available screenshot, video, and trace; the parent must preserve those links in its user-facing report.",
-				"Otherwise, manage isolated async sub-agents for large, parallel, context-heavy work.",
-				"Presets from async-subagents config and /subagent-preset choose role model/thinking/args; AGENTS_PRESET or /subagent-preset session <name> overrides the current session; /subagent-preset init creates a sample config.",
-				"Omit subagentType so the router chooses a configured role unless the user or task requires a role or deterministic override.",
+				SUBAGENT_DELEGATION_GUIDANCE,
+				"Presets declare available models; each agent's ordered models selects the first usable model in that pool. AGENTS_PRESET or /subagent-preset session <name> selects the current session pool; /subagent-preset init creates a sample config. Do not override the model merely to choose a role.",
+				SUBAGENT_TYPE_SELECTION_GUIDANCE,
 				repoDiscovery
 					? "Use for broad independent tracks, review axes, or hypotheses even though repo_* tools are available."
 					: "Use first for broad codebase discovery split into tracks, review axes, or incident-triage hypotheses when repo_* tools are unavailable.",
@@ -82,25 +85,26 @@ export function asyncSubagentToolDescriptions(options: ToolDescriptionSetOptions
 			promptSnippet:
 				"For every browser-based visual QA, UI bug reproduction, or real-browser fix-verification request, immediately spawn subagentType='browser-qa' even for a single track and before inspecting files or checking prerequisites. The browser-qa sub-agent must discover the target and report missing prerequisites; do not preflight, perform, or substitute browser QA in the parent agent. " +
 				"Give browser-qa a concise acceptance brief: the known target URL/app, user-visible flow, expected observable result, and required artifacts. Do not prescribe repository files, searches, commands, server setup, or mock/synthetic substitutes; unknown setup belongs to the QA sub-agent's discovery. " +
-				"For other work, use subagents action='spawn' for multiple independent agents, explicit delegate/parallelize/split work requests, or one large review/debug track that should stay out of the parent context. " +
-				"Usually omit subagentType so the router chooses; set it only for user-named roles, deterministic tests, or another concrete override. Avoid trivial reads/edits and do not call status/wait immediately after spawn just for progress. " +
+				"For other work, use subagents action='spawn' for economical execution or context isolation, including one bounded sequential task or explicit delegate/parallelize/split work requests. " +
+				SUBAGENT_TYPE_SELECTION_GUIDANCE + " Avoid trivial reads/edits and do not call status/wait immediately after spawn just for progress. " +
 				(repoDiscovery
 					? "For one semantic code-discovery question, use repo_search; for independent tracks/hypotheses/review axes, delegate even when repo_* tools exist. Read result only after completion when findings are needed."
-					: "For one focused code-discovery question, use direct read/grep. Without repo_* tools, spawn several focused scan/quick agents first for broad multi-track discovery, incident triage, release readiness, risk strategy, or parallel reviews. Read result only after completion when findings are needed."),
+					: "For one focused code-discovery question, use direct read/grep. Without repo_* tools, delegate bounded research tracks for broad discovery rather than flooding parent context. Read result only after completion when findings are needed."),
 			promptGuidelines: [
 				"Treat every real-browser QA request as a mandatory delegation trigger and an explicit exception to the large/parallel threshold: immediately spawn with `subagentType: \"browser-qa\"` before checking prerequisites. The QA sub-agent owns target discovery, feasibility checks, browser automation, evidence, and blocked reports; the parent must not inspect the project first or substitute non-browser checks.",
 				"Keep the browser-qa task payload at the user-visible acceptance level: known target URL/app, actions to perform, expected observable outcome, and requested evidence. Do not turn it into a repository investigation plan, name internal files or commands, dictate server setup, or invent a mock/synthetic target. Leave unknown prerequisites to the QA sub-agent.",
 				"When browser-qa reports missing credentials, relay its explicit request and generated `.pi/qa_auth.jsonc` template path; never inspect, populate, or edit that credential file in the parent.",
 				"After browser-qa completes a test, preserve its clickable screenshot, video, and trace links in the final user-facing response whenever those artifacts exist.",
-				"For non-browser-QA work, use action='spawn' only for LARGE/PARALLEL work: independent investigations, repo-wide sweeps, deep debugging, code review/audit, or explicit delegate/parallelize/split requests; these are spawn triggers unless trivial/single-file.",
+				SUBAGENT_DELEGATION_GUIDANCE,
 				repoDiscovery
 					? "For one discovery question, use repo_search; spawn for independent tracks/hypotheses/review axes, and do not let repo_* availability suppress delegation."
-					: "For one discovery question, use direct read/grep; when repo_* tools are unavailable, spawn several focused scan/quick agents first for broad multi-file/module/hypothesis work.",
+					: "For one small discovery question, use direct read/grep; when repo_* tools are unavailable, delegate scoped research to keep broad search output outside the parent context.",
 				repoDiscovery
 					? "For incident triage, release readiness, or risk/test strategy with separate hypotheses/review tracks, prefer focused agents over serial parent-context work."
 					: "For incident triage, release readiness, or risk/test strategy with separate hypotheses/review tracks and no repo_* tools, call action='spawn' as the first discovery step; direct read/grep can follow.",
-				"Do not use subagents for exact-string lookups, known-file edits, typo/text replacements, obvious one-file changes, or interactive user input; use the cheapest direct path.",
-				"Spawn multiple focused agents in one action='spawn' call for independent questions; for bounded probes set timeoutSeconds; omit subagentType unless user-named/deterministic, and use oracle sparingly for high-stakes uncertainty/final checks.",
+				"Do not use subagents for trivial exact-string lookups, typo replacements, or interactive user input; use the cheapest direct path. A substantive bounded edit can be delegated even in one file.",
+				"Spawn multiple focused agents in one action='spawn' call for independent questions; set subagentType for clear role matches, timeoutSeconds for bounded probes, and use oracle sparingly for high-stakes uncertainty/final checks.",
+				"If spawn reports a routing error, no agents from that batch were launched. Correct the invalid or unresolved subagentType values using the available catalog and resubmit the whole batch; do not blindly retry omitted types or substitute an unsuitable role to suppress the error.",
 				"For screenshot/image inspection by blind models, use lookup; subagents only receive imagePaths when a broader delegated track genuinely needs them.",
 				"If asked to start/run/launch/test parallel sub-agents, spawn and stop; do not status/wait just for progress. Use status for recovery, wait only when needed/requested, result only after completion; compact results include artifact links.",
 				"Use action='stop' for stop/cancel/kill requests and action='cleanup' with delete=true only after collecting results.",
@@ -154,11 +158,10 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		name: "repo_architecture",
 		label: "Repo Architecture",
 		command: "architecture",
-		description: "Indexed repo architecture map: entrypoints, module boundaries, cycles, and unresolved dependency classes. Use before broad reads in unfamiliar codebases; skip for exact-string lookups, known-file edits, or other trivial changes.",
-		promptSnippet: "Use repo_architecture for a compact indexed architecture overview before broad multi-file reads, not for simple literal searches or small known-scope edits.",
+		description: "Indexed entrypoints, module boundaries, cycles and unresolved dependencies for broad, unfamiliar code.",
+		promptSnippet: "Map an unfamiliar area once; skip repo_architecture for known paths or exact lookups.",
 		promptGuidelines: [
-			"Exact strings, filenames, known symbols, typo/text replacements, or obvious one-file edits: skip repo_architecture and use direct text search/read/edit.",
-			"Broad unfamiliar codebase: make one narrow repo_architecture call first, add --path-prefix when a subsystem is known, then use repo_structure for files/symbols and repo_search for behavior.",
+			"Scope with --path-prefix; then use repo_structure or repo_search only for remaining gaps.",
 		],
 	},
 	{
@@ -166,19 +169,19 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		label: "Repo Structure",
 		command: "structure",
 		description: "Indexed file tree and exported-symbol view for a directory/module. Use to choose files/ranges without dumping source.",
-		promptSnippet: "Use repo_structure for file trees, module contents, and exported symbols; narrow with idx flags.",
+		promptSnippet: "List one area with --max-files 20 --max-depth 2; continue with --cursor.",
 		promptGuidelines: [
-			"Pass --path-prefix, --kind, --max-files, or --max-depth when useful; use repo_ast for one large file's syntax map and repo_search for semantic behavior discovery.",
+			"Narrow with --path-prefix/--kind. Add --include-internal or --include-tests-summary only for a named gap; page instead of listing hundreds of files.",
 		],
 	},
 	{
 		name: "repo_ast",
 		label: "Repo AST",
 		command: "ast",
-		description: "Indexed AST map for one file. Use before repeated reads of a large file or when parent syntax structure matters.",
-		promptSnippet: "Use repo_ast with target=<file> to map one large file before choosing exact ranges to read.",
+		description: "Indexed AST outline for one known large file; locate exact ranges before reading source.",
+		promptSnippet: "Start --max-depth 3 --max-nodes 40 --no-include-text; read needed ranges with offset/limit.",
 		promptGuidelines: [
-			"Use for one known file, not repo-wide search; pass --max-depth or --max-nodes to keep output compact.",
+			"Continue with --cursor; include snippets only when the outline cannot answer the question.",
 		],
 		targetDescription: "File path to map, e.g. src/api/client.ts.",
 	},
@@ -186,12 +189,12 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		name: "repo_search",
 		label: "Repo Search",
 		command: "search",
-		description: "Indexed hybrid/semantic repository search for behavior questions when exact identifiers or files are unknown. Use natural-language behavior queries, not synonym dumps. Defaults to hybrid ranking; read returned ranges next.",
-		promptSnippet: "Use repo_search for conceptual codebase questions; query for behavior, not a bag of synonyms. Leave default hybrid ranking for first-pass searches and use Grep/read when exact names or positions are known.",
+		description: "Indexed hybrid search for behavior when files or symbols are unknown. First pass: at most 3 results, no --include-content.",
+		promptSnippet: "Search behavior, not synonyms; keep hybrid unless lexical matches mislead. Read best returned ranges with offset/limit, not whole files.",
 		promptGuidelines: [
-			"Phrase target as behavior, not synonym dumps; keep exact identifiers only as anchors. Prefer default hybrid first, using --mode semantic only when lexical/symbol terms mislead.",
-			"Make one targeted search, narrow with --path-prefix/--max-files/--dedupe-file/--exclude-tests when useful, read best ranges, then refine only for a named gap; avoid duplicate broad searches.",
-			"For bug/cause questions, stop when a read range shows the causal assignment/write/branch/call; continue only for named gaps such as callers, persistence, tests, or requested impact.",
+			"Use --path-prefix/--dedupe-file when appropriate. Expand only for a named gap; use Grep for exact identifiers.",
+			"--include-content only for a narrow follow-up needing inline code, with --max-files 1; otherwise use read.",
+			"After finding the causal code, stop broad search; inspect callers, persistence or tests only for a named gap.",
 		],
 		targetDescription: "Natural-language behavior query, e.g. auth session token validation.",
 	},
@@ -200,9 +203,9 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		label: "Repo Explain",
 		command: "explain",
 		description: "Indexed explanation for a known symbol. Prefer file::symbol when the name may be ambiguous.",
-		promptSnippet: "Use repo_explain for a known symbol after you already know its name or file scope.",
+		promptSnippet: "Use file::symbol; start --signature-only when signatures suffice.",
 		promptGuidelines: [
-			"Prefer target=file::symbol for ambiguous names; use repo_search instead when the relevant symbol is still unknown.",
+			"Add --include-body --body-lines 20 only for implementation details; use repo_search when the symbol is unknown.",
 		],
 		targetDescription: "Symbol or file-scoped symbol, e.g. createClient or src/api/client.ts::createClient.",
 	},
@@ -210,10 +213,10 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		name: "repo_deps",
 		label: "Repo Deps",
 		command: "deps",
-		description: "Indexed dependency/caller tracing for a known path or symbol. Use for import impact and first-hop call/dependency analysis.",
-		promptSnippet: "Use repo_deps with target=<path|path::symbol> to trace imports, imported-by, callers, or callees.",
+		description: "Indexed import/call dependencies for a known path or file::symbol.",
+		promptSnippet: "Start --depth 1 and choose --direction callers or callees for the question.",
 		promptGuidelines: [
-			"Use repo_search first when path/symbol is unknown. Otherwise start --depth 1; add --direction, --mode calls, or --show-edges only when needed.",
+			"Use --mode calls for call relationships. Add --show-edges/--tests or deeper traversal only for a named impact-analysis gap.",
 		],
 		targetDescription: "Path or file-scoped symbol, e.g. src/api/client.ts or src/api/client.ts::createClient.",
 	},
@@ -263,10 +266,10 @@ export const SESSION_RECOVERY_TOOL_DESCRIPTIONS = {
 	readSection: {
 		name: "session_read_section",
 		label: "Session Read Section",
-		description: "Read a bounded raw-history section returned by session_overview or session_search, including messages, tool calls/results, and compaction summaries.",
-		promptSnippet: "Read one stable raw-session section by ID after session_overview or session_search.",
+		description: "Read bounded raw session history by stable section ID or exact entry ID, with opaque continuation cursors for long sections and long entries.",
+		promptSnippet: "Read one raw-session section or exact entry; continue with the returned cursor when more text is available.",
 		promptGuidelines: [
-			"Pass a section ID produced with the same active/all scope; keep entry and body limits small unless more detail is necessary.",
+			"Pass either section_id or entry_id with the same active/all scope; use next_cursor to continue instead of restarting from the section head.",
 		],
 	},
 	search: {
@@ -275,7 +278,7 @@ export const SESSION_RECOVERY_TOOL_DESCRIPTIONS = {
 		description: "Search raw session messages, summaries, tool results, and serialized tool arguments with a bounded literal substring query.",
 		promptSnippet: "Search raw session history lexically when a concrete phrase, path, symbol, tool, or error is known.",
 		promptGuidelines: [
-			"Use session_search after overview when a concrete query is known; it is lexical rather than semantic, and scope defaults to the active branch.",
+			"Use session_search when a concrete query is known; it is lexical rather than semantic, scope defaults to the active branch, and next_cursor continues large match sets.",
 		],
 	},
 	recoveryContext: {
@@ -314,6 +317,8 @@ export const WEB_SEARCH_TOOL_DESCRIPTIONS = {
 	},
 } satisfies Record<string, ToolDescription>;
 
+const SHELL_TEST_OUTPUT_GUIDANCE = "Tests: save full stdout/stderr to a unique log; emit only TEST_RESULT (passed/failed/incomplete), command, original exit code, verified counts (or unknown), and log path. Omit per-test PASS lines; show bounded exact failure diagnostics and flag omissions. Read only needed log ranges, never dump it. Preserve test exit status; timeout/abort is incomplete. Prefer supported compact reporters; do not alter tests/config just to shorten output.";
+
 export function claudeAliasToolDescriptions(options: ToolDescriptionSetOptions | boolean = false) {
 	const repoDiscovery = hasRepoDiscovery(options);
 
@@ -338,7 +343,7 @@ export function claudeAliasToolDescriptions(options: ToolDescriptionSetOptions |
 		Bash: {
 			name: "Bash",
 			label: "Bash",
-			description: "Run shell commands for builds, tests, package managers, git, and project CLIs. Prefer Read/Edit/Write/Grep/Glob for file operations.",
+			description: `Run shell commands for builds, tests, package managers, git, and project CLIs. Prefer Read/Edit/Write/Grep/Glob for file operations. ${SHELL_TEST_OUTPUT_GUIDANCE}`,
 		},
 		Grep: {
 			name: "Grep",
@@ -364,7 +369,7 @@ export const CODEX_ALIAS_TOOL_DESCRIPTIONS = {
 	shellCommand: {
 		name: "shell",
 		label: "shell",
-		description: "Run shell commands for builds, tests, package managers, git, and project CLIs. For long/verification output, redirect to a log and show only bounded tail on failure; summarize passing logs. Set workdir/cwd instead of cd; prefer read for simple file reads.",
+		description: `Run shell commands for builds, tests, package managers, git, and project CLIs. Set workdir/cwd instead of cd; prefer read for simple file reads. ${SHELL_TEST_OUTPUT_GUIDANCE}`,
 	},
 	applyPatch: {
 		name: "apply_patch",

package/external/pi-tools-suite/src/truncation-metadata-normalizer/index.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { normalizeRedundantTruncationMetadata } from "../context-gateway/metadata-normalization.js";
+
+/**
+ * Optional non-store optimization for SDK tool results.
+ *
+ * The module removes only truncation metadata text that is proven to duplicate
+ * the already-delivered visible text. It is disabled by default so existing
+ * sessions, including Context Gateway off/observe, remain byte-equivalent.
+ */
+export default function truncationMetadataNormalizer(pi: ExtensionAPI): void {
+	pi.on("tool_result", async (event) => {
+		const normalized = normalizeRedundantTruncationMetadata(event);
+		return normalized.changed ? { details: normalized.details } : undefined;
+	});
+}