@shanepadgett/tau-agent 0.11.1 → 0.13.0

package/docs/subagents.md

@@ -2,6 +2,15 @@
 
 Tau's `subagent` tool delegates one focused task to an isolated child Pi session. You can add your own agent definitions without writing TypeScript.
 
+Each fresh call returns a thread ID. Continue that thread when feedback or follow-up work depends on the child's prior reads and reasoning:
+
+```text
+subagent({ agent: "scout", task: "Trace configuration loading" })
+subagent({ thread: "thread-1", task: "Now check whether this proposed fix covers every caller" })
+```
+
+Retained threads keep their child conversation and tool results for the current parent session. Start fresh for unrelated work or when earlier context is stale or oversized. Tau keeps up to 16 threads and evicts the least recently used idle thread when needed.
+
 ## Where definitions live
 
 | Scope | Path | Use when |
@@ -46,8 +55,10 @@ Named tools and configured models must exist in the normally loaded child Pi env
 
 - Children use the parent's cwd and inherit model/thinking unless the definition overrides them.
 - Children do not receive the parent conversation.
+- Follow-up calls reuse the retained child's conversation, model, thinking level, tools, and cwd.
 - Children load only the extensions that own their declared tools. Unrelated extension hooks do not run in child sessions.
 - At most four children run at once; extra calls wait in order.
+- Calls to the same retained thread run one at a time.
 - Returned text is capped (50 KB / 2,000 lines); full truncated output is saved to a private temp file.
 
 ## Built-ins

package/extensions/attention/README.md

@@ -1,10 +1,12 @@
 # Attention
 
-Sends a terminal-driven attention notification when Tau is ready for input.
+Sends a terminal-driven attention notification when Tau is ready for input, finishes compacting a session, or summarizes an abandoned branch during tree navigation.
 
 ## Behavior
 
 - Emits an attention notification on `agent_end`.
+- Emits an attention notification on `session_compact`.
+- Emits an attention notification on `session_tree` when it includes a branch summary.
 - Listens for shared event `tau:agent.blocked` when Tau is waiting on user input.
 - Uses the terminal or host OS notification path that best fits the current environment.
 

package/extensions/attention/index.ts

@@ -4,6 +4,8 @@ import { onTauEvent } from "../../shared/events.js";
 
 const DEFAULT_TITLE = "Tau";
 const DEFAULT_BODY = "Ready for input";
+const COMPACTION_BODY = "Compaction complete";
+const BRANCH_SUMMARY_BODY = "Branch summary complete";
 const MACOS_SOUND = "/System/Library/Sounds/Submarine.aiff";
 
 function oscText(value: string): string {
@@ -68,4 +70,14 @@ export default function attentionExtension(pi: ExtensionAPI): void {
 		if (ctx.mode === "print") return;
 		notify({ title: DEFAULT_TITLE, body: DEFAULT_BODY });
 	});
+
+	pi.on("session_compact", (_event, ctx) => {
+		if (ctx.mode === "print") return;
+		notify({ title: DEFAULT_TITLE, body: COMPACTION_BODY });
+	});
+
+	pi.on("session_tree", (event, ctx) => {
+		if (ctx.mode === "print" || !event.summaryEntry) return;
+		notify({ title: DEFAULT_TITLE, body: BRANCH_SUMMARY_BODY });
+	});
 }

package/extensions/publish/README.md

@@ -9,3 +9,5 @@ Create a tagged Tau release and monitor its GitHub Actions npm publish run.
 ```
 
 `/publish` requires a clean Git working tree, authenticated GitHub CLI, and public approved npm package sources. It recommends a semantic version bump from commits since the previous release tag, asks for confirmation, then pushes a release tag. GitHub Actions publishes the TUI package before the agent package through npm trusted publishing.
+
+If publishing fails, the agent runs read-only diagnostics and recommends a solution. It does not apply the fix or retry the release.

package/extensions/publish/index.ts

@@ -42,7 +42,18 @@ export default function publishExtension(pi: ExtensionAPI): void {
 			try {
 				await publish(pi, ctx);
 			} catch (error) {
-				ctx.ui.notify(`Publish failed: ${errorText(error)}`, "error");
+				pi.sendMessage(
+					{
+						customType: "tau.publish-failure",
+						content: [
+							"The /publish command failed with this error:",
+							errorText(error),
+							"Investigate the failure using read-only diagnostics. Determine the likely cause and recommend a solution to the user. Do not change files, git state, package state, or remote state, and do not retry publishing.",
+						].join("\n\n"),
+						display: false,
+					},
+					{ triggerTurn: true },
+				);
 			}
 		},
 	});

package/extensions/subagent/README.md

@@ -12,6 +12,8 @@ Tau includes three built-in agents:
 
 Ask Tau to delegate a task, or let it call `subagent` with an agent name and task. Children use the parent's current working directory and inherit its model and thinking level unless their definition overrides either value. They do not receive the parent conversation. Tau loads only the extensions that own a child's declared tools, so unrelated extension hooks do not run in child sessions. When a child must inspect another repository, put its exact absolute path in the delegated task.
 
+Fresh calls return a thread ID. Tau can send feedback or follow-up work to that thread, preserving the child's conversation, prior reads, and tool results. It starts a fresh thread for unrelated work or when retained context is stale or oversized. Threads live for the current parent session. Tau retains up to 16 and evicts the least recently used idle thread when needed. Calls to one thread run sequentially.
+
 ## Agent definitions
 
 Add Markdown definitions at `~/.pi/agent/tau/agents/*.md` or, in a trusted project, the nearest `.pi/tau/agents/*.md`. Project definitions override user definitions, which override built-ins. Duplicate names in one scope are invalid.

package/extensions/subagent/index.ts

@@ -1,20 +1,66 @@
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { createToolRowStateStore } from "../../shared/tool-row-state.js";
-import { discoverAgents, type AgentDiscovery } from "./agents.ts";
+import { discoverAgents, type AgentDefinition, type AgentDiscovery } from "./agents.ts";
 import { renderSubagentCall, renderSubagentResult } from "./render.ts";
-import { extensionPathsForTools, FifoGate, runSubagent, type SubagentDetails } from "./run.ts";
+import {
+	createSubagentThread,
+	disposeSubagentThread,
+	extensionPathsForTools,
+	FifoGate,
+	runSubagentTurn,
+	type SubagentDetails,
+	type SubagentThread,
+} from "./run.ts";
 
-const params = Type.Object(
-	{ agent: Type.String({ minLength: 1 }), task: Type.String({ minLength: 1 }) },
-	{ additionalProperties: false },
-);
+const params = Type.Union([
+	Type.Object(
+		{ agent: Type.String({ minLength: 1 }), task: Type.String({ minLength: 1 }) },
+		{ additionalProperties: false },
+	),
+	Type.Object(
+		{ thread: Type.String({ minLength: 1 }), task: Type.String({ minLength: 1 }) },
+		{ additionalProperties: false },
+	),
+]);
+
+const MAX_RETAINED_THREADS = 16;
+
+function emptyDetails(
+	agent: string,
+	task: string,
+	status: "waiting" | "failed" | "aborted",
+	phase: "discovery" | "queue" | "startup",
+	model: string,
+	thinkingLevel: string,
+	threadId: string | undefined,
+	error: string | undefined,
+): SubagentDetails {
+	return {
+		agent,
+		...(threadId === undefined ? {} : { threadId }),
+		status,
+		phase,
+		task,
+		model,
+		thinkingLevel,
+		toolCalls: 0,
+		actions: [],
+		omittedActions: 0,
+		omittedErrors: 0,
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+		durationMs: 0,
+		...(error === undefined ? {} : { error }),
+	};
+}
 
 export default function subagentExtension(pi: ExtensionAPI): void {
 	const gate = new FifoGate(4);
 	const controllers = new Set<AbortController>();
+	const threads = new Map<string, SubagentThread>();
 	const fingerprints = new Map<string, string>();
 	const runtimeWarnings = new Set<string>();
+	let nextThreadId = 1;
 	const rowState = createToolRowStateStore(pi, "subagent.tool-row-state");
 	const warn = (discovery: AgentDiscovery, ctx: ExtensionContext) => {
 		const current = new Set<string>();
@@ -33,6 +79,11 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		}
 		for (const path of fingerprints.keys()) if (!current.has(path)) fingerprints.delete(path);
 	};
+	const disposeThreads = async () => {
+		const retained = [...threads.values()];
+		threads.clear();
+		await Promise.all(retained.map((thread) => disposeSubagentThread(thread)));
+	};
 	pi.on("before_agent_start", async (event, ctx) => {
 		if (!pi.getActiveTools().includes("subagent")) return undefined;
 		const discovery = await discoverAgents(ctx.cwd, ctx.isProjectTrusted());
@@ -40,7 +91,23 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		const lines = [...discovery.agents.values()]
 			.sort((a, b) => a.name.localeCompare(b.name))
 			.map((agent) => `- ${agent.name}: ${agent.description}`);
-		const prompt = `## Subagents\nUse \`subagent\` when an available agent matches a focused part of the task.\n\nAvailable agents for this turn:\n${lines.join("\n")}\n\nDelegate one focused task per call. Children do not inherit parent messages. Include exact absolute reference paths when a child must inspect a repository outside the current working directory.`;
+		const activeThreads = [...threads.values()]
+			.filter((thread) => thread.cwd === ctx.cwd)
+			.sort((a, b) => a.id.localeCompare(b.id))
+			.map((thread) => {
+				const task = thread.initialTask.replace(/\s+/g, " ").trim();
+				return `- ${thread.id} (${thread.definition.name}): ${task.length <= 160 ? task : `${task.slice(0, 159)}…`}`;
+			});
+		const threadSection = activeThreads.length ? `\n\nActive reusable threads:\n${activeThreads.join("\n")}` : "";
+		const prompt = `## Subagents
+Use \`subagent\` when an available agent matches a focused part of the task.
+
+Available agents for this turn:
+${lines.join("\n")}
+
+Start a fresh thread with \`agent\` and \`task\`. Continue an existing thread with \`thread\` and \`task\`. Reuse a thread when feedback or follow-up work depends on its prior reads and reasoning. Start fresh for unrelated work or when its context is stale or oversized.${threadSection}
+
+Delegate one focused task per call. Children do not inherit parent messages. Include exact absolute reference paths when a child must inspect a repository outside the current working directory.`;
 		return { systemPrompt: `${event.systemPrompt}\n\n${prompt}` };
 	});
 	pi.registerTool(
@@ -48,116 +115,142 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			name: "subagent",
 			label: "Subagent",
 			description:
-				"Delegate one focused task to a named isolated child agent. Output is limited to 50KB or 2,000 lines.",
-			promptSnippet: "Delegate one focused task to a named isolated child agent",
+				"Start a focused isolated child agent or continue a retained child thread. Output is limited to 50KB or 2,000 lines.",
+			promptSnippet: "Start a focused child agent or continue a retained child thread",
 			parameters: params,
 			executionMode: "parallel",
 			async execute(_id, raw, signal, onUpdate, ctx) {
-				const agent = raw.agent.trim();
 				const task = raw.task.trim();
-				const thinkingLevel = pi.getThinkingLevel();
-				if (!agent || !task)
-					return {
-						content: [{ type: "text", text: "Subagent input requires non-empty agent and task" }],
-						details: {
-							agent,
-							task,
-							status: "failed",
-							phase: "queue",
-							model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable",
-							thinkingLevel,
-							toolCalls: 0,
-							actions: [],
-							omittedActions: 0,
-							omittedErrors: 0,
-							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
-							durationMs: 0,
-							error: "Invalid input",
-						},
-					};
-				const discovery = await discoverAgents(ctx.cwd, ctx.isProjectTrusted());
-				warn(discovery, ctx);
-				const definition = discovery.agents.get(agent);
-				const invalid = discovery.invalid.get(agent);
-				if (!definition) {
-					const reason = invalid?.map((item) => item.reason).join("; ") ?? "unknown agent";
-					const names = [...discovery.agents.keys()].sort().join(", ") || "none";
-					const error = `Agent ${agent} discovery failed: ${reason}. Runnable agents: ${names}`;
+				const continuing = "thread" in raw;
+				const parentModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable";
+				const parentThinking = pi.getThinkingLevel();
+				let thread: SubagentThread | undefined;
+				let definition: AgentDefinition | undefined;
+				let agent = continuing ? raw.thread.trim() : raw.agent.trim();
+				let threadId = continuing ? raw.thread.trim() : undefined;
+				if (!task || !agent) {
+					const error = continuing
+						? "Subagent continuation requires non-empty thread and task"
+						: "Subagent input requires non-empty agent and task";
 					return {
 						content: [{ type: "text", text: error }],
-						details: {
-							agent,
-							task,
-							status: "failed",
-							phase: "discovery",
-							model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable",
-							thinkingLevel,
-							toolCalls: 0,
-							actions: [],
-							omittedActions: 0,
-							omittedErrors: 0,
-							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
-							durationMs: 0,
-							error,
-						},
+						details: emptyDetails(agent, task, "failed", "queue", parentModel, parentThinking, threadId, error),
 					};
 				}
+				if (continuing) {
+					thread = threads.get(agent);
+					if (!thread || thread.cwd !== ctx.cwd) {
+						const names =
+							[...threads.values()]
+								.filter((item) => item.cwd === ctx.cwd)
+								.map((item) => item.id)
+								.sort()
+								.join(", ") || "none";
+						const error = `Subagent thread ${agent} is unavailable. Active threads: ${names}`;
+						return {
+							content: [{ type: "text", text: error }],
+							details: emptyDetails(
+								agent,
+								task,
+								"failed",
+								"discovery",
+								parentModel,
+								parentThinking,
+								agent,
+								error,
+							),
+						};
+					}
+					agent = thread.definition.name;
+					threadId = thread.id;
+					definition = thread.definition;
+				} else {
+					const discovery = await discoverAgents(ctx.cwd, ctx.isProjectTrusted());
+					warn(discovery, ctx);
+					definition = discovery.agents.get(agent);
+					const invalid = discovery.invalid.get(agent);
+					if (!definition) {
+						const reason = invalid?.map((item) => item.reason).join("; ") ?? "unknown agent";
+						const names = [...discovery.agents.keys()].sort().join(", ") || "none";
+						const error = `Agent ${agent} discovery failed: ${reason}. Runnable agents: ${names}`;
+						return {
+							content: [{ type: "text", text: error }],
+							details: emptyDetails(
+								agent,
+								task,
+								"failed",
+								"discovery",
+								parentModel,
+								parentThinking,
+								undefined,
+								error,
+							),
+						};
+					}
+					threadId = `thread-${nextThreadId++}`;
+				}
 				const controller = new AbortController();
 				controllers.add(controller);
 				const combined = AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]);
-				let release: (() => void) | undefined;
+				let releaseThread: (() => void) | undefined;
+				let releaseGlobal: (() => void) | undefined;
+				let reservedThread: SubagentThread | undefined;
+				let phase: "queue" | "startup" = "queue";
 				try {
-					await onUpdate?.({
-						content: [{ type: "text", text: `${agent}: waiting` }],
-						details: {
-							agent,
-							task,
-							status: "waiting",
-							phase: "queue",
-							model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable",
-							thinkingLevel,
-							toolCalls: 0,
-							actions: [],
-							omittedActions: 0,
-							omittedErrors: 0,
-							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
-							durationMs: 0,
-						},
-					});
-					try {
-						release = await gate.acquire(combined);
-					} catch (error) {
-						const message = error instanceof Error ? error.message : `Agent ${agent} queue failed`;
-						const details: SubagentDetails = {
-							agent,
-							task,
-							status: combined.aborted ? "aborted" : "failed",
-							phase: "queue",
-							model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable",
-							thinkingLevel,
-							toolCalls: 0,
-							actions: [],
-							omittedActions: 0,
-							omittedErrors: 0,
-							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
-							durationMs: 0,
-							error: message,
-						};
-						return { content: [{ type: "text", text: message }], details };
+					const waiting = emptyDetails(
+						agent,
+						task,
+						"waiting",
+						"queue",
+						thread?.model ?? parentModel,
+						thread?.thinkingLevel ?? parentThinking,
+						threadId,
+						undefined,
+					);
+					await onUpdate?.({ content: [{ type: "text", text: `${agent}: waiting` }], details: waiting });
+					if (thread) {
+						reservedThread = thread;
+						thread.pendingTurns += 1;
+						releaseThread = await thread.turnGate.acquire(combined);
 					}
-					const result = await runSubagent({
-						definition,
-						extensionPaths: extensionPathsForTools(pi, definition.tools),
+					releaseGlobal = await gate.acquire(combined);
+					if (!thread) {
+						phase = "startup";
+						if (!threadId || !definition) throw new Error("Subagent startup state is incomplete");
+						const selectedDefinition = definition;
+						if (threads.size >= MAX_RETAINED_THREADS) {
+							const evicted = [...threads.values()]
+								.filter((item) => item.pendingTurns === 0)
+								.sort((a, b) => a.lastUsedAt - b.lastUsedAt)[0];
+							if (!evicted) throw new Error("Subagent thread limit reached while all retained threads are busy");
+							threads.delete(evicted.id);
+							await disposeSubagentThread(evicted);
+						}
+						thread = await createSubagentThread({
+							id: threadId,
+							definition: selectedDefinition,
+							extensionPaths: extensionPathsForTools(pi, selectedDefinition.tools),
+							initialTask: task,
+							ctx,
+							thinkingLevel: parentThinking,
+							signal: combined,
+							onWarning: (warning) => {
+								const message = `Subagent definition ${selectedDefinition.path}: ${warning}`;
+								if (runtimeWarnings.has(message)) return;
+								runtimeWarnings.add(message);
+								ctx.ui.notify(message, "warning");
+							},
+						});
+						threads.set(thread.id, thread);
+						reservedThread = thread;
+						thread.pendingTurns += 1;
+					}
+					if (!thread) throw new Error("Subagent thread startup failed");
+					const result = await runSubagentTurn({
+						thread,
 						task,
-						ctx,
-						thinkingLevel,
+						initial: thread.turns === 0,
 						signal: combined,
-						onWarning: (warning) => {
-							const message = `Subagent definition ${definition.path}: ${warning}`;
-							if (runtimeWarnings.has(message)) return;
-							runtimeWarnings.add(message);
-							ctx.ui.notify(message, "warning");
-						},
 						onUpdate: (details) =>
 							onUpdate?.({
 								content: [
@@ -169,9 +262,33 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 								details,
 							}),
 					});
-					return { content: [{ type: "text", text: result.content }], details: result.details };
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Thread: ${thread.id}\nReuse with subagent({ thread: "${thread.id}", task: "..." })\n\n${result.content}`,
+							},
+						],
+						details: result.details,
+					};
+				} catch (error) {
+					const message = error instanceof Error ? error.message : `Agent ${agent} ${phase} failed`;
+					const status = combined.aborted ? "aborted" : "failed";
+					const details = emptyDetails(
+						agent,
+						task,
+						status,
+						phase,
+						thread?.model ?? parentModel,
+						thread?.thinkingLevel ?? parentThinking,
+						thread?.id ?? threadId,
+						message,
+					);
+					return { content: [{ type: "text", text: message }], details };
 				} finally {
-					release?.();
+					if (reservedThread) reservedThread.pendingTurns -= 1;
+					releaseGlobal?.();
+					releaseThread?.();
 					controllers.delete(controller);
 				}
 			},
@@ -200,12 +317,17 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		const details = event.details as SubagentDetails | undefined;
 		if (details?.status === "failed" || details?.status === "aborted") return { isError: true };
 	});
-	pi.on("session_start", () => {
+	pi.on("session_start", async () => {
+		for (const controller of controllers) controller.abort();
+		controllers.clear();
+		await disposeThreads();
+		nextThreadId = 1;
 		rowState.clear();
 		runtimeWarnings.clear();
 	});
-	pi.on("session_shutdown", () => {
+	pi.on("session_shutdown", async () => {
 		for (const controller of controllers) controller.abort();
 		controllers.clear();
+		await disposeThreads();
 	});
 }

package/extensions/subagent/render.ts

@@ -12,7 +12,7 @@ const title = (theme: Theme, rowState: ToolRowStateStore, rowId: string, invalid
 };
 
 export function renderSubagentCall(
-	args: { agent?: string; task?: string },
+	args: { agent?: string; thread?: string; task?: string },
 	theme: Theme,
 	context: {
 		executionStarted: boolean;
@@ -29,7 +29,7 @@ export function renderSubagentCall(
 		return text;
 	}
 	const prefix =
-		`${title(theme, context.rowState, context.rowId, context.invalidate)}  ${theme.fg("accent", args.agent ?? "")}`.trimEnd();
+		`${title(theme, context.rowState, context.rowId, context.invalidate)}  ${theme.fg("accent", args.agent ?? args.thread ?? "")}`.trimEnd();
 	const task = args.task?.replace(/\s+/g, " ").trim();
 	text.setText(task ? `${prefix}  ${theme.fg("muted", task)}` : prefix);
 	return text;
@@ -47,7 +47,8 @@ export function renderSubagentResult(
 		text.setText("");
 		return text;
 	}
-	const header = `${title(theme, context.rowState, context.rowId, context.invalidate)}  ${theme.fg("accent", details.agent)}  ${theme.fg("muted", `$${details.usage.cost.toFixed(4)} · ${(details.durationMs / 1000).toFixed(1)}s · ${details.toolCalls} tools`)}`;
+	const identity = details.threadId ? `${details.agent} · ${details.threadId}` : details.agent;
+	const header = `${title(theme, context.rowState, context.rowId, context.invalidate)}  ${theme.fg("accent", identity)}  ${theme.fg("muted", `$${details.usage.cost.toFixed(4)} · ${(details.durationMs / 1000).toFixed(1)}s · ${details.toolCalls} tools`)}`;
 	if (!expanded) {
 		text.setText(`${header}  ${theme.fg("muted", details.task.replace(/\s+/g, " ").trim())}`);
 		return text;

package/extensions/subagent/run.ts

@@ -55,6 +55,7 @@ export interface SubagentUsage {
 }
 export interface SubagentDetails {
 	agent: string;
+	threadId?: string;
 	status: "waiting" | "running" | "completed" | "failed" | "aborted";
 	phase: "discovery" | "queue" | "startup" | "run" | "output";
 	completionState?: string;
@@ -80,6 +81,20 @@ export interface SubagentDetails {
 	};
 }
 
+export interface SubagentThread {
+	id: string;
+	definition: AgentDefinition;
+	session: AgentSession;
+	cwd: string;
+	model: string;
+	thinkingLevel: string;
+	initialTask: string;
+	turns: number;
+	turnGate: FifoGate;
+	pendingTurns: number;
+	lastUsedAt: number;
+}
+
 export function extensionPathsForTools(pi: ExtensionAPI, tools: readonly string[]): string[] {
 	const selected = new Set(tools);
 	return [
@@ -154,31 +169,26 @@ function textOf(message: AssistantMessage): string {
 		.join("");
 }
 
-function assistants(session: AgentSession): AssistantMessage[] {
-	return session.messages.filter((message): message is AssistantMessage => message.role === "assistant");
-}
-
-export async function runSubagent(options: {
+export async function createSubagentThread(options: {
+	id: string;
 	definition: AgentDefinition;
 	extensionPaths: readonly string[];
-	task: string;
+	initialTask: string;
 	ctx: ExtensionContext;
 	thinkingLevel: string;
 	signal: AbortSignal;
-	onUpdate?: (details: SubagentDetails) => void | Promise<void>;
 	onWarning?: (warning: string) => void;
-}): Promise<{ content: string; details: SubagentDetails }> {
+}): Promise<SubagentThread> {
 	const {
+		id,
 		definition,
 		extensionPaths,
-		task,
+		initialTask,
 		ctx,
 		thinkingLevel: parentThinkingLevel,
 		signal,
-		onUpdate,
 		onWarning,
 	} = options;
-	const started = Date.now();
 	let model = ctx.model;
 	let thinkingLevel = parentThinkingLevel;
 	if (definition.model) {
@@ -205,34 +215,7 @@ export async function runSubagent(options: {
 		else thinkingLevel = definition.thinking;
 	}
 	const modelName = model ? `${model.provider}/${model.id}` : "unavailable";
-	const usage: SubagentUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
-	const details: SubagentDetails = {
-		agent: definition.name,
-		status: "running",
-		phase: "startup",
-		task,
-		model: modelName,
-		thinkingLevel,
-		toolCalls: 0,
-		actions: [],
-		omittedActions: 0,
-		omittedErrors: 0,
-		usage,
-		durationMs: 0,
-	};
 	let session: AgentSession | undefined;
-	let unsubscribe: (() => void) | undefined;
-	let updateChain = Promise.resolve();
-	let lastTextUpdate = 0;
-	const publish = (force = false) => {
-		const now = Date.now();
-		if (!force && now - lastTextUpdate < 100) return;
-		lastTextUpdate = now;
-		details.durationMs = now - started;
-		const snapshot = structuredClone(details);
-		snapshot.actions = snapshot.actions.slice(-5);
-		updateChain = updateChain.then(() => onUpdate?.(snapshot)).catch(() => undefined);
-	};
 	try {
 		if (!model) throw new Error(`Agent ${definition.name} startup failed: parent has no model`);
 		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
@@ -267,12 +250,78 @@ export async function runSubagent(options: {
 				`Agent ${definition.name} startup failed: unavailable tools: ${missing.join(", ") || "active tool mismatch"}`,
 			);
 		}
-		details.phase = "run";
+		return {
+			id,
+			definition,
+			session,
+			cwd: ctx.cwd,
+			model: modelName,
+			thinkingLevel,
+			initialTask,
+			turns: 0,
+			turnGate: new FifoGate(1),
+			pendingTurns: 0,
+			lastUsedAt: Date.now(),
+		};
+	} catch (error) {
+		if (session?.isStreaming) await session.abort().catch(() => undefined);
+		session?.dispose();
+		throw error;
+	}
+}
+
+export async function disposeSubagentThread(thread: SubagentThread): Promise<void> {
+	if (thread.session.isStreaming) await thread.session.abort().catch(() => undefined);
+	thread.session.dispose();
+}
+
+export async function runSubagentTurn(options: {
+	thread: SubagentThread;
+	task: string;
+	initial: boolean;
+	signal: AbortSignal;
+	onUpdate?: (details: SubagentDetails) => void | Promise<void>;
+}): Promise<{ content: string; details: SubagentDetails }> {
+	const { thread, task, initial, signal, onUpdate } = options;
+	const { definition, session } = thread;
+	const started = Date.now();
+	const usage: SubagentUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+	const details: SubagentDetails = {
+		agent: definition.name,
+		threadId: thread.id,
+		status: "running",
+		phase: "run",
+		task,
+		model: thread.model,
+		thinkingLevel: thread.thinkingLevel,
+		toolCalls: 0,
+		actions: [],
+		omittedActions: 0,
+		omittedErrors: 0,
+		usage,
+		durationMs: 0,
+	};
+	let unsubscribe: (() => void) | undefined;
+	let updateChain = Promise.resolve();
+	let lastTextUpdate = 0;
+	const turnMessages: AssistantMessage[] = [];
+	const publish = (force = false) => {
+		const now = Date.now();
+		if (!force && now - lastTextUpdate < 100) return;
+		lastTextUpdate = now;
+		details.durationMs = now - started;
+		const snapshot = structuredClone(details);
+		snapshot.actions = snapshot.actions.slice(-5);
+		updateChain = updateChain.then(() => onUpdate?.(snapshot)).catch(() => undefined);
+	};
+	try {
 		const actionById = new Map<string, string>();
 		unsubscribe = session.subscribe((event: AgentSessionEvent) => {
 			if (event.type === "message_update" && event.message.role === "assistant") {
 				details.response = capped(textOf(event.message), PREVIEW_LIMIT);
 				publish();
+			} else if (event.type === "message_end" && event.message.role === "assistant") {
+				turnMessages.push(event.message);
 			} else if (event.type === "tool_execution_start") {
 				details.toolCalls += 1;
 				const summary = `${event.toolName} ${capped(event.args)}`.trim();
@@ -302,14 +351,15 @@ export async function runSubagent(options: {
 		signal.addEventListener("abort", abort, { once: true });
 		try {
 			await session.prompt(
-				`You are an isolated delegated child agent. Stay within the delegated task and return only the requested result.\n\n## Agent instructions\n${definition.prompt}\n\n## Delegated task\n${task}`,
+				initial
+					? `You are an isolated delegated child agent. Stay within the delegated task and return only the requested result.\n\n## Agent instructions\n${definition.prompt}\n\n## Delegated task\n${task}`
+					: `Continue the existing delegated work using the context already in this thread. Return only the requested result.\n\n## Parent follow-up\n${task}`,
 				{ expandPromptTemplates: false },
 			);
 		} finally {
 			signal.removeEventListener("abort", abort);
 		}
-		const messages = assistants(session);
-		for (const message of messages) {
+		for (const message of turnMessages) {
 			usage.input += message.usage.input;
 			usage.output += message.usage.output;
 			usage.cacheRead += message.usage.cacheRead;
@@ -317,7 +367,7 @@ export async function runSubagent(options: {
 			usage.cost += message.usage.cost.total;
 			usage.turns += 1;
 		}
-		const terminal = messages.at(-1);
+		const terminal = turnMessages.at(-1);
 		if (!terminal) throw new Error(`Agent ${definition.name} run failed: no terminal assistant response`);
 		const response = textOf(terminal);
 		if (terminal.stopReason === "aborted") {
@@ -374,7 +424,8 @@ export async function runSubagent(options: {
 		return { content: details.error, details };
 	} finally {
 		unsubscribe?.();
-		if (session?.isStreaming) await session.abort().catch(() => undefined);
-		session?.dispose();
+		thread.turns += 1;
+		thread.lastUsedAt = Date.now();
+		if (session.isStreaming) await session.abort().catch(() => undefined);
 	}
 }

package/extensions/tau-help/help.md

@@ -8,7 +8,7 @@ Gives the agent macOS window discovery, screenshots, and app activation tools fo
 
 ## attention
 
-Shows attention state when Tau needs the user to look at the chat.
+Shows attention state when Tau needs the user to look at the chat, finishes compacting a session, or summarizes an abandoned branch.
 
 ## auto-name
 
@@ -60,7 +60,7 @@ Replaces separate edit/write operations with one multi-file `patch` tool. It can
 
 ## publish
 
-Adds `/publish` to create a tagged release, trigger trusted npm publishing in GitHub Actions, and show its status. It recommends a semantic version bump from commits since the prior release tag, but you must confirm the release type and publish action.
+Adds `/publish` to create a tagged release, trigger trusted npm publishing in GitHub Actions, and show its status. It recommends a semantic version bump from commits since the prior release tag, but you must confirm the release type and publish action. If publishing fails, the agent investigates with read-only diagnostics and recommends a solution without applying it or retrying the release.
 
 ## qna
 
@@ -92,7 +92,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. 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 `scout` and `web-research` subagents show the pattern. Each subagent can register its own model and the tools it is allowed to use.
+Gives Tau a subagent delegation tool for isolated, focused work. 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 and the tools it is allowed to use.
 
 ## tau-help
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.11.1",
+	"version": "0.13.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"license": "MIT",
@@ -28,7 +28,7 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.11.1",
+		"@shanepadgett/tau-tui": "0.13.0",
 		"@toon-format/toon": "2.3.0",
 		"smol-toml": "1.7.0"
 	},