@shanepadgett/tau-agent 0.16.0 → 0.18.0

package/docs/subagents.md

@@ -5,11 +5,19 @@ Tau's `subagent` tool delegates one focused task to an isolated child Pi session
 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({ agent: "review", task: "Review 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.
+Retained threads keep their complete child conversation for five minutes after the latest child response. A later follow-up keeps the same thread, agent, model, thinking level, tools, and cwd, but starts a clean child session. Tau supplies prior tasks, exact terminal results, and paths passed through `files`; it does not run a summarization request. Old source, tool history, intermediate responses, and thinking are absent, so the child reads current source before relying on a retained path. Start fresh for unrelated work. Tau keeps up to 16 threads and evicts the least recently used idle thread when needed.
+
+If the relevant files are already known, autoread them into a fresh or retained child turn:
+
+```text
+subagent({ agent: "review", task: "Review the runtime change", files: ["src/runtime.ts", "test/runtime.test.ts"] })
+```
+
+Paths may be relative to the parent's current working directory or absolute. Tau reads current, line-numbered snapshots when the turn starts. Unreadable files produce failed context entries without stopping the child. Keep the list focused because complete snapshots consume the child's context window.
 
 ## Where definitions live
 
@@ -18,7 +26,7 @@ Retained threads keep their child conversation and tool results for the current
 | **User (global)** | `~/.pi/agent/tau/agents/*.md` | You want the agent in every project |
 | **Project** | nearest trusted `.pi/tau/agents/*.md` | Repo-specific helpers |
 
-Precedence: **project overrides user**, which overrides Tau's built-ins (`scout`, `web-research`). Duplicate names in one scope are invalid.
+Precedence: **project overrides user**, which overrides Tau's built-ins (`review`, `web-research`). Duplicate names in one scope are invalid.
 
 ## Definition format
 
@@ -31,6 +39,10 @@ description: Inspect API declarations and usage
 tools:
   - read
   - grep
+names:
+  - Ledger
+  - Quill
+  - Beacon
 model: openai-codex/gpt-5.4-mini
 thinking: medium
 ---
@@ -46,25 +58,32 @@ Required:
 
 Optional:
 
+- `names`: a non-empty list of unique display names
 - `model` as `provider/model`
 - `thinking`: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`
 
 Named tools and configured models must exist in the normally loaded child Pi environment (including tools from installed packages such as Tau).
 
+Tau assigns one display name to each fresh child and keeps it for follow-up turns on that thread. It cycles through the list in order. When the list wraps, reused names get numeric suffixes such as `Ledger-2`, so any number of concurrent children can still have distinct names. Without `names`, the agent name is used as a one-item pool.
+
 ## Runtime rules
 
 - 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.
+- Calls can include `files` to autoread line-numbered snapshots into that child turn.
+- Follow-up calls within five minutes reuse the complete child conversation. Colder calls resume from exact prior results and relevant paths in a clean session.
+- Cold resume keeps the selected model, thinking level, tools, cwd, definition, display name, and thread ID.
 - 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.
+- Display names identify children in Tau's tool rows and cmux dashboard; thread IDs remain the identifiers used for continuation calls.
 - Returned text is capped (50 KB / 2,000 lines); full truncated output is saved to a private temp file.
+- Interactive cmux sessions get one temporary Markdown dashboard for waiting and running invocations. It is observational only: cmux latency or failure cannot delay, fail, or reorder children. The dashboard closes shortly after the active cohort finishes. Print mode never opens it.
 
 ## Built-ins
 
-- `generalist` — focused analysis, review, implementation, or mixed work when no narrower agent fits
-- `scout` — local exploration with `read`, `grep`, `find`, `ls`
+- `review` — adversarial, read-only review for correctness, runtime risks, duplication, and over- or under-engineering
 - `web-research` — `websearch`, `codesearch`, `webfetch`
+- `context-sync` — maps meaningful uncommitted work into `.pi/contexts`. Offered to the coding agent when `extensions.context.sync.enabled` and `sync.automation` are true. Manual `/context-sync` remains when sync is enabled with `automation` false. Validation can auto-run it when `validation.enabled` and `sync.enabled`
 
 Ask Tau to delegate, or let it call `subagent` with an agent name and task.

package/extensions/attention/README.md

@@ -5,6 +5,7 @@ Sends a terminal-driven attention notification when Tau is ready for input, fini
 ## Behavior
 
 - Emits an attention notification after the agent settles with no automatic continuation pending.
+- Waits for automatic post-turn checks before deciding whether the agent is ready for input.
 - 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.

package/extensions/attention/index.ts

@@ -25,6 +25,10 @@ function playMacOSSound(pi: ExtensionAPI): void {
 }
 
 export default function attentionExtension(pi: ExtensionAPI): void {
+	const holds = new Set<string>();
+	let pendingAttention: (() => void) | undefined;
+	let discardNextSettlement = false;
+
 	function notify(data: { title?: string; body?: string }): void {
 		const raw: unknown = data;
 		const record = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
@@ -65,9 +69,37 @@ export default function attentionExtension(pi: ExtensionAPI): void {
 	}
 
 	onTauEvent(pi, "attention.agent-blocked", "tau:agent.blocked", notify);
+	onTauEvent(pi, "attention.hold-acquire", "tau:attention.hold.acquire", ({ id }) => {
+		holds.add(id);
+	});
+	onTauEvent(pi, "attention.hold-release", "tau:attention.hold.release", ({ id, disposition }) => {
+		if (!holds.delete(id)) return;
+		if (disposition === "discard") {
+			if (pendingAttention) pendingAttention = undefined;
+			else discardNextSettlement = true;
+		}
+		if (holds.size > 0 || !pendingAttention) return;
+		const notifyPending = pendingAttention;
+		pendingAttention = undefined;
+		notifyPending();
+	});
+
+	pi.on("session_start", () => {
+		holds.clear();
+		pendingAttention = undefined;
+		discardNextSettlement = false;
+	});
 
 	pi.on("agent_settled", (_event, ctx) => {
 		if (ctx.mode === "print") return;
+		if (discardNextSettlement) {
+			discardNextSettlement = false;
+			return;
+		}
+		if (holds.size > 0) {
+			pendingAttention = () => notify({ title: DEFAULT_TITLE, body: DEFAULT_BODY });
+			return;
+		}
 		notify({ title: DEFAULT_TITLE, body: DEFAULT_BODY });
 	});
 
@@ -80,4 +112,10 @@ export default function attentionExtension(pi: ExtensionAPI): void {
 		if (ctx.mode === "print" || !event.summaryEntry) return;
 		notify({ title: DEFAULT_TITLE, body: BRANCH_SUMMARY_BODY });
 	});
+
+	pi.on("session_shutdown", () => {
+		holds.clear();
+		pendingAttention = undefined;
+		discardNextSettlement = false;
+	});
 }

package/extensions/context/README.md

@@ -2,16 +2,26 @@
 
 Context stores reusable repository work scopes in `.pi/contexts`. Folder names become selector tabs, TOML files become concepts, and TOML sections become selectable entries.
 
-Use `/context` to select entries. Entry `files` are injected through Tau autoread. Entry `anchors` supply lazy navigation paths that the agent can grep or read in ranges when needed. Use `/context-sync` to reconcile affected scopes from the current Git changes. Tau validates both file classes as context membership after agent turns and asks the agent to sync uncovered changed files or stale references automatically.
+Use `/context` to select entries. Entry `files` are injected through Tau autoread. Entry `anchors` supply lazy navigation paths that the agent can grep or read in ranges when needed.
 
-Validation is disabled by default. Enable it globally or per project in Tau settings:
+After meaningful uncommitted work (new/moved ownership, not trivial already-covered polish), the coding agent should run the `context-sync` subagent so `.pi/contexts` stays aligned. Context sync catalogs durable code and long-lived documentation. Scratch pads, working plans, interviews, rough ideas, and other temporary artifacts should stay out; add recurring transient paths to `validation.ignoreGlobs`. Humans can also run `/context-sync` or `/context-sync <nudge>` and press Escape to cancel a running sync. It walks domain → concept → entry → membership, edits only `.pi/contexts` with `patch`, and the harness verifies write scope plus catalog invariants afterward. Out-of-scope writes are restored and the run fails. Optional nudge text soft-steers judgment without skipping evidence.
+
+Sync surface is configurable:
+
+- `sync.enabled` (default true) — master switch. Off: no `/context-sync`, parent cannot call `context-sync`, validation does not auto-run sync.
+- `sync.automation` (default true) — when false with sync still enabled: manual `/context-sync` only (coding agent does not see context-sync). Validation auto-run still works if validation is enabled.
+- `validation.enabled` (default false) — after agent turns, check membership and auto-run context-sync on failure (requires `sync.enabled`).
 
 ```json
 {
   "extensions": {
     "context": {
+      "sync": {
+        "enabled": true,
+        "automation": true
+      },
       "validation": {
-  "enabled": true,
+        "enabled": true,
         "ignoreGlobs": ["generated/**"]
       }
     }

package/extensions/context/definitions.ts

@@ -1,4 +1,4 @@
-import { access, readFile, readdir, stat } from "node:fs/promises";
+import { access, readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { parse } from "smol-toml";
@@ -81,13 +81,13 @@ export async function findProjectRoot(cwd: string): Promise<string> {
 	return gitRoot ?? resolve(cwd);
 }
 
-export function validSlug(value: string, label: string): string {
+function validSlug(value: string, label: string): string {
 	const slug = value.trim();
 	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) throw new Error(`${label} must use lowercase kebab-case: ${value}`);
 	return slug;
 }
 
-export function normalizeProjectPath(root: string, input: string): string {
+function normalizeProjectPath(root: string, input: string): string {
 	const absolute = resolve(root, input.trim().replace(/^@/, ""));
 	const path = relative(root, absolute).split(sep).join("/");
 	if (!path || path === "." || path === ".." || path.startsWith("../"))
@@ -103,18 +103,6 @@ export function contextEntryPaths(entry: Pick<ContextEntry, "files" | "anchors">
 	return sortedUnique([...entry.files, ...entry.anchors]);
 }
 
-export async function requireFiles(root: string, inputs: readonly string[]): Promise<string[]> {
-	const files = sortedUnique(inputs.map((input) => normalizeProjectPath(root, input)));
-	for (const file of files) {
-		try {
-			if (!(await stat(join(root, file))).isFile()) throw new Error();
-		} catch {
-			throw new Error(`Context file does not exist: ${file}`);
-		}
-	}
-	return files;
-}
-
 export async function loadContextEntries(root: string): Promise<ContextEntry[]> {
 	const contextsRoot = join(root, ".pi", "contexts");
 	if (!(await pathExists(contextsRoot))) return [];