@shanepadgett/tau-agent 0.29.0 → 0.31.0

package/extensions/tau-help/help.md

@@ -32,11 +32,11 @@ Adds `/commit` for semantic commit grouping, review, and committing selected rep
 
 ## context
 
-Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-sync` or `/context-sync <nudge>` for human-driven catalog sync (optional nudge). Escape cancels a running manual sync. When `sync.automation` is on, the coding agent can also run the `context-sync` subagent after meaningful uncommitted work. Sync catalogs durable code and long-lived documentation; recurring scratch, planning, interview, and rough-idea paths belong in `validation.ignoreGlobs`. `sync.enabled` is the master switch for command, automation, and validation auto-run. Entry `files` are autoread; entry `anchors` are unloaded navigation paths. Context validation is off by default; when on (and sync enabled), Tau auto-runs context-sync on failure. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
+Adds `/context` to set branch-local reusable repository work scopes from `.pi/contexts`, and `/context-sync` or `/context-sync <nudge>` for human-driven catalog sync. Active entries produce one ephemeral per-call projection instead of transcript messages. Entry `read` paths supply exact contents, `outline` paths use Explore, and `references` stay unloaded. Clear all selections and confirm to remove active context. Escape cancels a running manual sync. When `sync.automation` is on, coding agent can also run `context-sync` after meaningful uncommitted work. Sync catalogs durable code and long-lived documentation; recurring scratch, planning, interview, and rough-idea paths belong in `validation.ignoreGlobs`. `sync.enabled` is master switch for command, automation, and validation auto-run. Context validation is off by default; when on (and sync enabled), Tau auto-runs context-sync on failure. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
 
 ## working-memory
 
-Gives agent `working_memory` for selective hard checkpoints. Model-only references identify useful conversation evidence and complete tool exchanges. Requested source files return as structural outlines, while deferred files remain cheap conditional reminders. Everything else before checkpoint leaves future model input without changing saved session. Advisory reminders begin at 40k active-context tokens. Run `/prune` to request reassessment manually.
+Gives agent `working_memory` for selective hard checkpoints. Model-only references identify useful user messages and visible assistant text. Requested source files return as structural outlines, deferred files remain cheap conditional reminders, and a continuation note carries conclusions extracted from exploration. Tool history and full file reads leave future model input without changing saved session. Advisory reminders begin at 40k active-context tokens. Run `/prune` to request reassessment manually.
 
 ## explore
 
@@ -74,6 +74,10 @@ Adds `/publish` to create a tagged release, trigger trusted npm publishing in Gi
 
 Adds `/qna` for when the agent has asked you several questions in chat and you want a friendly UI for answering them on your own terms. It is only active when you manually run the command.
 
+## review
+
+Adds `/review` for explicit isolated review of current Git changes. Choose `simplify`, `architecture`, or `correctness`, or run a mode directly. Results stay outside agent context until you send them from result view, and can be exported under `.pi/tau/reviews/`. `/review show` reopens latest result on current session branch.
+
 ## reference
 
 Adds `/reference` to manage separate repositories kept outside the current project for inspiration or comparison. Add one with `/reference new <git-url>`, update it, switch its referenced branch, or open it in an editor. Select references and explain why they matter; Tau then puts their paths and that reason into the editor for the agent. References stay outside the project so the agent does not wander into unrelated code unless you explicitly point it there.
@@ -86,6 +90,10 @@ Shows a compact display-only marker after each run with wall time and model cost
 
 Supplies the agent with the current local date and an initial root directory snapshot as hidden session context.
 
+## script-runner
+
+Gives the agent a first-class `script_runner` tool to execute Python and TypeScript instead of bash. On failure it returns a `scriptId`; the agent retries with targeted `{oldText,newText}` edits against the script it already wrote rather than resending the whole script. Languages are detected from the environment (Python via `python3`/`python`; TypeScript via Node `--experimental-strip-types`, Node 22.6+). The tool registers only available languages and is hidden from the prompt if neither is present.
+
 ## silent-command-runner
 
 Runs configured commands while keeping their output out of agent context when that is useful.
@@ -100,7 +108,7 @@ Adds `Alt+S` to stash the current prompt draft and `/pop` to browse stashed draf
 
 ## subagent
 
-Gives Tau a subagent delegation tool for isolated, focused work. The built-in `review` agent performs adversarial, read-only code reviews; `scout` finds local files, symbols, data flow, constraints, and unknowns without changing anything; `web-research` handles external research. Known files can be autoread as line-numbered snapshots into a fresh or retained child turn. Tau can continue a retained child thread when follow-up work depends on its prior reads and reasoning. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in agents show the pattern. Each subagent can register its own model, tools, and pool of display names. Reused pool names get numeric suffixes. In interactive cmux sessions, Tau opens one temporary Markdown dashboard for live subagent progress; it does not change how children run and closes shortly after the active cohort finishes.
+Gives Tau a subagent delegation tool for isolated, focused work. Run `/agents` to enable or disable individual agents for the current session, or set `extensions.subagent.disabled` in Tau settings for a persistent choice. `scout` is substantial multi-hop local code lookup that would chew parent context; facts only, not small digs; `web-research` handles external research. Known files can be autoread as line-numbered snapshots into a fresh or retained child turn. Tau can continue a retained child thread when follow-up work depends on its prior reads and reasoning. You can also create your own subagents in supported subagent directories. Ask Tau how to do it and have it consult extension documentation; built-in agents show pattern. Each subagent can register its own model, tools, and pool of display names. Reused pool names get numeric suffixes. In interactive cmux sessions, Tau opens one temporary Markdown dashboard for live subagent progress; it does not change how children run and closes shortly after active cohort finishes.
 
 ## tau-help
 
@@ -114,10 +122,6 @@ Adds `/tau`, `/tau init [--global|--project]`, and `/tau doctor` for Tau setup a
 
 Progressively exposes specialist tools through `load_tools`. Tau normally loads the fixed `web`, `image`, and `appshot` groups itself when needed; supported providers can preserve more prompt-cache reuse.
 
-## turn-budget
-
-Tracks and limits agent turns to keep work bounded.
-
 ## web
 
 Gives the agent compact `websearch`, `webfetch`, and `codesearch` tools for web and implementation research.

package/extensions/working-memory/README.md

@@ -2,7 +2,7 @@
 
 Working Memory gives agent selective checkpoints without changing saved conversation.
 
-`working_memory` keeps referenced conversation evidence and complete tool exchanges, carries requested source files as structural outlines, and records deferred files as conditional reminders. Everything else before checkpoint leaves future model context.
+`working_memory` keeps referenced user messages and visible assistant text, carries requested source files as structural outlines, and records deferred files as conditional reminders. Tool history and full file reads leave model context; useful findings from them are distilled into a compact continuation note.
 
 Automatic reminders begin at 40,000 active-context tokens and remain advisory. Run `/prune` to request reassessment manually.
 

package/extensions/working-memory/checkpoint.ts

@@ -3,7 +3,7 @@ import { type ExtensionAPI, type ExtensionContext, type SessionEntry } from "@ea
 import { type Static, Type } from "typebox";
 import { truncateBoundedHead } from "../../shared/bounded-text-result.ts";
 import { requestOutlineInjections, type PreparedOutlineInjection } from "../../shared/outline-injection.ts";
-import { buildMemoryCatalog } from "./memory.ts";
+import { buildMemoryCatalog, collectPrunedRowIds } from "./memory.ts";
 import { WORKING_MEMORY_TOOL, type DeferredFile, type WorkingMemoryCheckpointDetailsV1 } from "./state.ts";
 
 const PATH = Type.String({ minLength: 1, maxLength: 500, pattern: "\\S" });
@@ -58,7 +58,7 @@ export async function executeWorkingMemory(options: ExecuteWorkingMemoryOptions)
 			const unit = catalog.get(ref);
 			return unit ? [unit] : [];
 		})
-		.sort((left, right) => left.order - right.order || left.suborder - right.suborder);
+		.sort((left, right) => left.order - right.order);
 	const retainedRefs = retained.map((unit) => unit.ref);
 	const warnings = requestedRefs
 		.filter((ref) => !catalog.has(ref))
@@ -89,9 +89,8 @@ export async function executeWorkingMemory(options: ExecuteWorkingMemoryOptions)
 	}
 
 	const anchorIndex = findAnchorEntry(branch, options.toolCallId);
-	const retainedSet = new Set(retainedRefs);
 	const preAnchorUnits = [...catalog.values()].filter((unit) => unit.order < anchorIndex);
-	const prunedRowIds = [...new Set(preAnchorUnits.flatMap((unit) => (retainedSet.has(unit.ref) ? [] : unit.rowIds)))];
+	const prunedRowIds = collectPrunedRowIds(branch, anchorIndex);
 	const details: WorkingMemoryCheckpointDetailsV1 = {
 		v: 1,
 		anchorToolCallId: options.toolCallId,

package/extensions/working-memory/index.ts

@@ -22,7 +22,7 @@ import { replayWorkingMemoryState, WORKING_MEMORY_TOOL, type WorkingMemoryCheckp
 const NUDGE_TYPE = "tau.working-memory.nudge";
 const BASELINE_TYPE = "tau.working-memory.nudge-baseline";
 const TOOL_DESCRIPTION =
-	"Create a selective hard checkpoint for future model context. Keep valuable referenced evidence and complete tool exchanges, carry file structure as outlines, defer conditionally relevant files without reading them, and provide one compact continuation note. Never checkpoint useful evidence merely to reread it.";
+	"Create a selective hard checkpoint for future model context. Keep valuable user and visible assistant messages, carry file structure as outlines, defer conditionally relevant files without reading them, and distill exploration findings into one compact continuation note.";
 
 interface NudgeState {
 	anchorToolCallId: string | undefined;
@@ -98,9 +98,9 @@ export default function workingMemoryExtension(pi: ExtensionAPI): void {
 					promptSnippet: "Reassess and selectively checkpoint active working memory",
 					promptGuidelines: [
 						"Use working_memory when stale evidence has accumulated or a memory reminder asks for reassessment; continue coherent exploration when current evidence remains useful.",
-						"A hidden working-memory reference catalog provides keep refs. Message refs preserve conversational evidence; tool refs preserve one complete call/result exchange.",
-						"Keep active or expensive evidence, outline files when structure suffices, defer paths whose relevance is conditional, and discard evidence with no expected value.",
-						"Everything before working_memory leaves future model context unless selected in keep. Put durable decisions, constraints, unresolved matters, and next action in continuation without duplicating retained evidence.",
+						"A hidden working-memory reference catalog provides keep refs only for user messages and visible assistant text. Tool calls, tool results, hidden reasoning, and framework messages cannot be retained.",
+						"Outline files that remain in the repository working set, defer paths whose relevance is conditional, and discard exploration history after extracting its useful conclusions.",
+						"Everything before working_memory leaves future model context unless selected in keep. Put findings from tools, durable decisions, constraints, unresolved matters, and next action in continuation without duplicating retained messages.",
 					],
 					parameters: workingMemoryParameters,
 					executionMode: "sequential",
@@ -174,14 +174,32 @@ export default function workingMemoryExtension(pi: ExtensionAPI): void {
 		syncBranch(ctx);
 	});
 
-	pi.on("before_agent_start", (event, ctx) => {
+	pi.on("before_agent_start", (_event, ctx) => {
 		if (!enabled) return undefined;
 		const usage = ctx.getContextUsage();
 		if (!usage || usage.tokens === null || !Number.isFinite(usage.tokens)) return undefined;
-		const reminder = Math.floor(Math.max(0, usage.tokens) / interval);
+		const tokens = Math.max(0, Math.floor(usage.tokens));
+		const reminder = Math.floor(tokens / interval);
 		if (reminder < 1) return undefined;
 		const instruction = instructions[Math.min(reminder, instructions.length) - 1] ?? instructions[0];
-		return { systemPrompt: `${event.systemPrompt}\n\n${automaticInstruction(instruction)}` };
+		return {
+			message: {
+				customType: NUDGE_TYPE,
+				content: automaticInstruction(instruction),
+				display: false,
+				details: {
+					v: 1,
+					kind: "automatic",
+					tokens,
+					boundaryTokens: reminder * interval,
+					reminder,
+					tier: Math.min(reminder, instructions.length),
+					tierCount: instructions.length,
+					anchorToolCallId:
+						replayWorkingMemoryState(ctx.sessionManager.getBranch(), true).latestAnchorToolCallId ?? null,
+				},
+			},
+		};
 	});
 
 	pi.on("turn_end", (event, ctx) => {

package/extensions/working-memory/memory.ts

@@ -1,4 +1,5 @@
 import { sessionEntryToContextMessages, type ContextEvent, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { isContextProjectionMessage, isLegacyContextMessage } from "../../shared/context-messages.ts";
 import type { ActiveWorkingMemoryState } from "./state.ts";
 
 type ContextMessage = ContextEvent["messages"][number];
@@ -8,23 +9,13 @@ export interface MemoryUnit {
 	label: string;
 	preview: string;
 	order: number;
-	suborder: number;
 	messages: ContextMessage[];
-	rowIds: string[];
 }
 
-const EXCLUDED_CUSTOM_TYPES = new Set(["tau.autoread", "tau.runtime-context", "tau.working-memory.nudge"]);
 const REFERENCE_CATALOG_TYPE = "tau.working-memory.references";
 
 export function buildMemoryCatalog(branch: readonly SessionEntry[]): Map<string, MemoryUnit> {
 	const catalog = new Map<string, MemoryUnit>();
-	const results = new Map<string, ContextMessage>();
-	for (const entry of branch) {
-		for (const message of sessionEntryToContextMessages(entry)) {
-			if (message.role === "toolResult") results.set(message.toolCallId, message);
-		}
-	}
-
 	for (let order = 0; order < branch.length; order += 1) {
 		const entry = branch[order];
 		if (!entry) continue;
@@ -34,53 +25,56 @@ export function buildMemoryCatalog(branch: readonly SessionEntry[]): Map<string,
 			const calls = message.content.filter((block) => block.type === "toolCall");
 			const frameworkCall = calls.some((call) => call.name === "working_memory");
 			if (frameworkCall) continue;
-			const prose = message.content.filter((block) => block.type !== "toolCall");
-			if (prose.length > 0) {
+			const text = message.content.filter((block) => block.type === "text");
+			if (text.length > 0) {
 				const ref = `m:${entry.id}`;
 				catalog.set(ref, {
 					ref,
 					label: "assistant",
-					preview: previewAssistant(prose),
-					order,
-					suborder: 0,
-					messages: [{ ...message, content: prose }],
-					rowIds: [],
-				});
-			}
-			for (let index = 0; index < calls.length; index += 1) {
-				const call = calls[index];
-				if (!call) continue;
-				const result = results.get(call.id);
-				if (result?.role !== "toolResult" || result.toolName !== call.name) continue;
-				const ref = `t:${entry.id}:${index + 1}`;
-				catalog.set(ref, {
-					ref,
-					label: `tool ${call.name}`,
-					preview: previewTool(call.arguments),
+					preview: previewAssistant(text),
 					order,
-					suborder: index + 1,
-					messages: [{ ...message, content: [call] }, result],
-					rowIds: [call.id],
+					messages: [{ ...message, content: text }],
 				});
 			}
 			continue;
 		}
-		if (message.role === "toolResult") continue;
-		if (message.role === "custom" && EXCLUDED_CUSTOM_TYPES.has(message.customType)) continue;
+		if (message.role !== "user") continue;
 		const ref = `m:${entry.id}`;
 		catalog.set(ref, {
 			ref,
-			label: message.role === "custom" ? message.customType : message.role,
-			preview: previewMessage(message),
+			label: "user",
+			preview: previewUser(message),
 			order,
-			suborder: 0,
 			messages: [message],
-			rowIds: outlineRowIds(message),
 		});
 	}
 	return catalog;
 }
 
+export function collectPrunedRowIds(branch: readonly SessionEntry[], before: number): string[] {
+	const rowIds = new Set<string>();
+	for (let index = 0; index < before; index += 1) {
+		const entry = branch[index];
+		if (!entry) continue;
+		for (const message of sessionEntryToContextMessages(entry)) {
+			if (message.role === "assistant") {
+				for (const block of message.content) {
+					if (block.type === "toolCall" && block.name !== "working_memory") rowIds.add(block.id);
+				}
+			}
+			if (
+				message.role === "custom" &&
+				message.customType === "tau.explore.outline" &&
+				isRecord(message.details) &&
+				typeof message.details.rowId === "string"
+			) {
+				rowIds.add(message.details.rowId);
+			}
+		}
+	}
+	return [...rowIds];
+}
+
 export function projectWorkingMemory(
 	messages: readonly ContextMessage[],
 	state: ActiveWorkingMemoryState,
@@ -100,7 +94,7 @@ export function projectWorkingMemory(
 			const unit = catalog.get(ref);
 			return unit ? [unit] : [];
 		})
-		.sort((left, right) => left.order - right.order || left.suborder - right.suborder);
+		.sort((left, right) => left.order - right.order);
 	const projected: ContextMessage[] = [];
 	const projectedRefs: MemoryUnit[][] = [];
 	for (const unit of retained) {
@@ -121,24 +115,23 @@ function referenceCurrentMessages(
 	entries: readonly SessionEntry[],
 	catalog: ReadonlyMap<string, MemoryUnit>,
 ): MemoryUnit[][] {
-	const generated = entries.flatMap((entry) =>
-		sessionEntryToContextMessages(entry).map((message) => ({ entry, message })),
+	const generated = entries
+		.flatMap((entry) => sessionEntryToContextMessages(entry).map((message) => ({ entry, message })))
+		.filter(({ message }) => !isLegacyContextMessage(message));
+	const sessionMessages = messages.filter(
+		(message) => !isContextProjectionMessage(message) && !isLegacyContextMessage(message),
 	);
-	if (generated.length !== messages.length) return messages.map(() => []);
-	const toolRefs = new Map<string, MemoryUnit[]>();
-	for (const unit of catalog.values()) {
-		const result = unit.messages.find((message) => message.role === "toolResult");
-		if (result?.role !== "toolResult") continue;
-		toolRefs.set(result.toolCallId, [...(toolRefs.get(result.toolCallId) ?? []), unit]);
-	}
-	return generated.map(({ entry, message }, index) => {
-		if (message.role === "assistant") {
-			const unit = catalog.get(`m:${entry.id}`);
-			return unit && messages[index]?.role === "assistant" ? [unit] : [];
-		}
-		if (message.role === "toolResult") return toolRefs.get(message.toolCallId) ?? [];
+	if (generated.length !== sessionMessages.length) return messages.map(() => []);
+	let generatedIndex = 0;
+	return messages.map((currentMessage) => {
+		if (isContextProjectionMessage(currentMessage) || isLegacyContextMessage(currentMessage)) return [];
+		const current = generated[generatedIndex];
+		generatedIndex += 1;
+		if (!current) return [];
+		const { entry, message } = current;
+		if (message.role !== "user" && message.role !== "assistant") return [];
 		const unit = catalog.get(`m:${entry.id}`);
-		return unit ? [unit] : [];
+		return unit && currentMessage.role === message.role ? [unit] : [];
 	});
 }
 
@@ -166,7 +159,7 @@ function addReferenceCatalog(
 			role: "custom",
 			customType: REFERENCE_CATALOG_TYPE,
 			content: [...unique.values()]
-				.sort((left, right) => left.order - right.order || left.suborder - right.suborder)
+				.sort((left, right) => left.order - right.order)
 				.map((unit) => `${unit.ref} (${unit.label}): ${unit.preview}`)
 				.join("\n"),
 			display: false,
@@ -206,36 +199,14 @@ function findAnchor(messages: readonly ContextMessage[], id: string): number {
 function previewAssistant(blocks: ReadonlyArray<{ type: string }>): string {
 	for (const block of blocks) {
 		if (block.type === "text" && "text" in block && typeof block.text === "string") return compact(block.text);
-		if (block.type === "thinking" && "thinking" in block && typeof block.thinking === "string") {
-			return compact(block.thinking);
-		}
 	}
 	return "";
 }
 
-function previewTool(args: Record<string, unknown>): string {
-	return compact(JSON.stringify(args));
-}
-
-function previewMessage(message: ContextMessage): string {
-	if (message.role === "user" || message.role === "custom") {
-		if (typeof message.content === "string") return compact(message.content);
-		const text = message.content.find((part) => part.type === "text");
-		return text?.type === "text" ? compact(text.text) : "";
-	}
-	if (message.role === "bashExecution") return compact(`${message.command}: ${message.output}`);
-	if (message.role === "assistant") return previewAssistant(message.content);
-	if (message.role === "toolResult") {
-		const text = message.content.find((part) => part.type === "text");
-		return text?.type === "text" ? compact(text.text) : "";
-	}
-	return compact(message.summary);
-}
-
-function outlineRowIds(message: ContextMessage): string[] {
-	if (message.role !== "custom" || message.customType !== "tau.explore.outline") return [];
-	if (!isRecord(message.details) || typeof message.details.rowId !== "string") return [];
-	return [message.details.rowId];
+function previewUser(message: Extract<ContextMessage, { role: "user" }>): string {
+	if (typeof message.content === "string") return compact(message.content);
+	const text = message.content.find((part) => part.type === "text");
+	return text?.type === "text" ? compact(text.text) : "";
 }
 
 function compact(value: string): string {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.29.0",
+	"version": "0.31.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -35,7 +35,7 @@
 	],
 	"dependencies": {
 		"@ast-grep/wasm": "0.45.0",
-		"@shanepadgett/tau-tui": "0.29.0",
+		"@shanepadgett/tau-tui": "0.31.0",
 		"@vscode/tree-sitter-wasm": "0.3.1",
 		"image-size": "2.0.2",
 		"smol-toml": "1.7.0",

package/schemas/tau.schema.json

@@ -248,31 +248,17 @@
 					},
 					"additionalProperties": false
 				},
-				"turnBudget": {
+				"subagent": {
 					"type": "object",
 					"properties": {
-						"enabled": {
-							"type": "boolean",
-							"default": true,
-							"description": "Enable turn-budget hints."
-						},
-						"turnLimit": {
-							"type": "integer",
-							"default": 30,
-							"minimum": 1,
-							"description": "Initial soft cap for tool-using turns per user prompt."
-						},
-						"nudgeEveryTurns": {
-							"type": "integer",
-							"default": 5,
-							"minimum": 1,
-							"description": "Tool-using turn interval between turn-budget hints."
-						},
-						"softCapIncrement": {
-							"type": "integer",
-							"default": 10,
-							"minimum": 1,
-							"description": "Turns added when the soft cap is reached."
+						"disabled": {
+							"type": "array",
+							"items": {
+								"type": "string",
+								"minLength": 1
+							},
+							"default": [],
+							"description": "Agent names unavailable for delegation."
 						}
 					},
 					"additionalProperties": false

package/shared/context-messages.ts

@@ -0,0 +1,19 @@
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+type ContextMessage = ContextEvent["messages"][number];
+
+export const CONTEXT_PROJECTION_TYPE = "tau.context.projection";
+
+export function isContextProjectionMessage(message: ContextMessage): boolean {
+	return message.role === "custom" && message.customType === CONTEXT_PROJECTION_TYPE;
+}
+
+export function isLegacyContextMessage(message: ContextMessage): boolean {
+	if (message.role !== "custom") return false;
+	if (message.customType !== "tau.injected-context" && message.customType !== "tau.autoread") return false;
+	return (
+		message.details !== undefined &&
+		typeof message.details === "object" &&
+		(message.details as Record<string, unknown>).source === "context"
+	);
+}

package/shared/injected-context.ts

@@ -3,7 +3,7 @@ import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 export const INJECTED_CONTEXT_TYPE = "tau.injected-context";
 
 export interface InjectedContextDetails {
-	source: "review" | "context";
+	source: "review";
 	title?: string;
 }
 
@@ -61,7 +61,7 @@ export function getBranchInjectedContexts(entries: readonly SessionEntry[]): Inj
 function readDetails(value: unknown): InjectedContextDetails | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const record = value as Record<string, unknown>;
-	if (record.source !== "review" && record.source !== "context") return undefined;
+	if (record.source !== "review") return undefined;
 	return {
 		source: record.source,
 		...(typeof record.title === "string" ? { title: record.title } : {}),

package/shared/isolated-session.ts

@@ -0,0 +1,151 @@
+import {
+	createAgentSession,
+	DefaultResourceLoader,
+	getAgentDir,
+	ModelRuntime,
+	SessionManager,
+	type AgentSession,
+	type ExtensionContext,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+type IsolatedSessionThinkingLevel = NonNullable<ExtensionContext["thinkingLevel"]>;
+
+type SelectedModel = NonNullable<ExtensionContext["model"]>;
+type SelectedProvider = NonNullable<ReturnType<ExtensionContext["modelRegistry"]["getProvider"]>>;
+
+export interface IsolatedSessionInputs {
+	label: string;
+	extensionPaths: readonly string[];
+	cwd: string;
+	model: SelectedModel;
+	provider: SelectedProvider;
+	runtimeApiKey: string | undefined;
+	thinkingLevel: IsolatedSessionThinkingLevel;
+	tools: readonly string[];
+	customTools: readonly ToolDefinition[];
+	bindTarget: { mode: "print" } | { mode: "tui"; uiContext: ExtensionContext["ui"] };
+}
+
+export interface IsolatedSessionResource {
+	readonly session: AgentSession;
+	dispose(): Promise<void>;
+}
+
+export async function resolveIsolatedSessionModel(options: {
+	label: string;
+	preferredModel: string | undefined;
+	preferredThinkingLevel: IsolatedSessionThinkingLevel | undefined;
+	usePreferredThinkingAfterModelFallback: boolean;
+	ctx: ExtensionContext;
+	parentThinkingLevel: IsolatedSessionThinkingLevel;
+	signal: AbortSignal;
+	onWarning?: (warning: string) => void;
+}): Promise<Pick<IsolatedSessionInputs, "model" | "provider" | "runtimeApiKey" | "thinkingLevel">> {
+	const { ctx, signal, onWarning } = options;
+	let model = ctx.model;
+	let thinkingLevel = options.parentThinkingLevel;
+	let preferredModelSelected = false;
+	let selectedAuth: Awaited<ReturnType<ExtensionContext["modelRegistry"]["getApiKeyAndHeaders"]>> | undefined;
+	if (options.preferredModel) {
+		const separator = options.preferredModel.indexOf("/");
+		const configured = ctx.modelRegistry.find(
+			options.preferredModel.slice(0, separator),
+			options.preferredModel.slice(separator + 1),
+		);
+		if (!configured) onWarning?.(`model ${options.preferredModel} is unavailable; using parent model`);
+		else {
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(configured);
+			if (!auth.ok) onWarning?.(`model ${options.preferredModel} is unavailable: ${auth.error}; using parent model`);
+			else {
+				model = configured;
+				selectedAuth = auth;
+				preferredModelSelected = true;
+			}
+		}
+	}
+	if (options.preferredThinkingLevel && (preferredModelSelected || options.usePreferredThinkingAfterModelFallback)) {
+		const preferred = options.preferredThinkingLevel;
+		const mapped = model?.thinkingLevelMap?.[preferred];
+		const unsupported =
+			!model?.reasoning ||
+			mapped === null ||
+			((preferred === "xhigh" || preferred === "max") && mapped === undefined);
+		if (unsupported)
+			onWarning?.(`thinking ${preferred} is unavailable for the selected model; using parent thinking`);
+		else thinkingLevel = preferred;
+	}
+	if (!model) throw new Error(`${options.label} startup failed: parent has no model`);
+	const auth = selectedAuth ?? (await ctx.modelRegistry.getApiKeyAndHeaders(model));
+	if (!auth.ok) throw new Error(`${options.label} startup failed: ${auth.error}`);
+	const provider = ctx.modelRegistry.getProvider(model.provider);
+	if (!provider) throw new Error(`${options.label} startup failed: provider ${model.provider} is unavailable`);
+	if (signal.aborted) throw new Error(`${options.label} startup aborted`);
+	return {
+		model,
+		provider,
+		runtimeApiKey:
+			auth.apiKey && provider.auth.apiKey && !ctx.modelRegistry.isUsingOAuth(model) ? auth.apiKey : undefined,
+		thinkingLevel,
+	};
+}
+
+export async function createIsolatedSessionResource(
+	inputs: IsolatedSessionInputs,
+	signal: AbortSignal,
+): Promise<IsolatedSessionResource> {
+	let session: AgentSession | undefined;
+	try {
+		if (signal.aborted) throw new Error(`${inputs.label} startup aborted`);
+		const modelRuntime = await ModelRuntime.create();
+		modelRuntime.registerNativeProvider(inputs.provider);
+		if (inputs.runtimeApiKey !== undefined)
+			await modelRuntime.setRuntimeApiKey(inputs.model.provider, inputs.runtimeApiKey, { allowNetwork: false });
+		if (signal.aborted) throw new Error(`${inputs.label} startup aborted`);
+		const resourceLoader = new DefaultResourceLoader({
+			cwd: inputs.cwd,
+			agentDir: getAgentDir(),
+			noExtensions: true,
+			additionalExtensionPaths: [...inputs.extensionPaths],
+		});
+		await resourceLoader.reload();
+		if (signal.aborted) throw new Error(`${inputs.label} startup aborted`);
+		const created = await createAgentSession({
+			cwd: inputs.cwd,
+			model: inputs.model,
+			modelRuntime,
+			thinkingLevel: inputs.thinkingLevel,
+			tools: [...inputs.tools],
+			excludeTools: ["subagent"],
+			resourceLoader,
+			customTools: [...inputs.customTools],
+			sessionManager: SessionManager.inMemory(inputs.cwd),
+		});
+		session = created.session;
+		if (signal.aborted) throw new Error(`${inputs.label} startup aborted`);
+		await session.bindExtensions(inputs.bindTarget);
+		if (signal.aborted) throw new Error(`${inputs.label} startup aborted`);
+		const active = session.getActiveToolNames().sort();
+		const expected = [...inputs.tools].sort();
+		if (active.join("\0") !== expected.join("\0") || active.includes("subagent")) {
+			const missing = expected.filter((tool) => !active.includes(tool));
+			throw new Error(
+				`${inputs.label} startup failed: unavailable tools: ${missing.join(", ") || "active tool mismatch"}`,
+			);
+		}
+		let disposed = false;
+		return {
+			session,
+			async dispose() {
+				if (disposed) return;
+				disposed = true;
+				if (session?.isStreaming) await session.abort().catch(() => undefined);
+				session?.dispose();
+			},
+		};
+	} catch (error) {
+		if (session?.isStreaming) await session.abort().catch(() => undefined);
+		session?.dispose();
+		throw error;
+	}
+}