@shanepadgett/tau-agent 0.35.0 → 0.37.0

package/extensions/explore/README.md

@@ -1,6 +1,6 @@
 # Explore
 
-Explore gives Tau 12 structural source tools: outlines, declaration slices, discovery, structural search, graph and relationship queries, impact, and context packs. Targets use path + declaration name, with an optional line to disambiguate.
+Explore gives Tau 12 structural source tools: outlines, declaration slices, discovery, structural search, graph and relationship queries, impact, and context packs. `show` takes a top-level `targets` array of path + declaration-name objects, with an optional line to disambiguate.
 
 Pi keeps ordinary filesystem tools (`ls`, `find`, `grep`, `read`). Explore adds structure on top of supported source languages via in-process tree-sitter (WASM) on every platform supported by the Node runtime. Registered languages share the same tools and exploration workflow.
 
@@ -11,7 +11,7 @@ When `explore.read.enabled` is on (default), a full Pi `read` or autoread of a r
 ## Tools
 
 - `outline` — declarations and structure for a file, one-level directory, or recursive subtree (no bodies).
-- `show` — exact signature / docs / declaration / declaration+imports for path+name targets.
+- `show` — exact signature / docs / declaration / declaration+imports for one or more targets in its top-level `targets` array.
 - `discover` — find reusable declarations across a repo/package/subtree by name, kind, or docs (signatures only).
 - `deps` / `reverse_deps` — file import graph forward and reverse.
 - `callers` / `callees` / `references` / `implementations` — symbol relationship sites.

package/extensions/explore/guidance.ts

@@ -4,7 +4,8 @@ const GUIDANCE = `## Explore
 Shape-backed languages: \`markdown\`, \`typescript\`, \`tsx\`, \`go\`, \`rust\`, \`c_sharp\`, \`java\`, \`kotlin\`, \`swift\`.
 
 Structural tools (\`outline\`, \`show\`, \`discover\`, \`ast_search\`, deps/relationships, \`impact\`, \`context\`) apply to those languages. Other files: harness \`read\` / \`grep\` / \`find\` / \`ls\`.
-Full \`read\` of a large registered source returns outline + follow-up hint, not the body — use ranged \`read\` or \`show\`.`;
+Full \`read\` of a large registered source returns outline + follow-up hint, not the body — use ranged \`read\` or \`show\`.
+\`show\` always takes a top-level \`targets\` array, even for one declaration: \`{"targets":[{"path":"...","name":"..."}],"view":"declaration"}\`.`;
 
 export function registerExploreGuidance(pi: ExtensionAPI): void {
 	pi.on("before_agent_start", (event) => ({ systemPrompt: `${event.systemPrompt}\n\n${GUIDANCE}` }));

package/extensions/explore/tools/render.ts

@@ -1,6 +1,7 @@
 import { formatSize, keyHint, type Theme } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
 import { formatToolRowTitle, type ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import { renderToolOutputPreview } from "../../../shared/text.ts";
 
 export type ExploreToolDetails = {
 	declarationCount: number;
@@ -94,28 +95,21 @@ export function renderExploreResult(
 	context: { lastComponent?: Component; isError: boolean },
 ): Text {
 	const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+	const output = result.content
+		.filter((item): item is { type: string; text: string } => item.type === "text" && typeof item.text === "string")
+		.map((item) => item.text)
+		.join("\n");
 	if (!expanded && !context.isError) {
 		const count = result.details?.declarationCount ?? 0;
 		const noun = count === 1 ? "declaration" : "declarations";
 		const bytes = result.details === undefined ? "" : `, ${formatSize(result.details.returnedBytes)} returned`;
+		const summary = theme.fg("muted", `${count} ${noun}${bytes}`);
+		const preview = renderToolOutputPreview(output, false, theme);
 		text.setText(
-			theme.fg("muted", `${count} ${noun}${bytes} (`) +
-				keyHint("app.tools.expand", "to expand") +
-				theme.fg("muted", ")"),
+			preview ? `${summary}\n${preview}` : `${summary} (` + keyHint("app.tools.expand", "to expand") + ")",
 		);
 		return text;
 	}
-	const output = result.content
-		.filter((item): item is { type: string; text: string } => item.type === "text" && typeof item.text === "string")
-		.map((item) => item.text)
-		.join("\n");
-	text.setText(
-		output
-			? output
-					.split("\n")
-					.map((line) => theme.fg("toolOutput", line))
-					.join("\n")
-			: "",
-	);
+	text.setText(renderToolOutputPreview(output, true, theme));
 	return text;
 }

package/extensions/explore/tools/show.ts

@@ -12,7 +12,7 @@ import { ExploreCallComponent, renderExploreResult, shrinkingListVariants, type
 
 const showTargetSchema = Type.Object(
 	{
-		path: Type.String({ description: "Defining file" }),
+		path: Type.String({ description: "Defining file for this target" }),
 		name: Type.String({ minLength: 1, description: "Decl name; dotted Type.method ok" }),
 		line: Type.Optional(Type.Integer({ minimum: 1, description: "1-based line inside decl range" })),
 	},
@@ -23,7 +23,8 @@ const showParams = Type.Object(
 	{
 		targets: Type.Array(showTargetSchema, {
 			minItems: 1,
-			description: "path+name targets (optional line pin)",
+			description:
+				'Required top-level array, even for one declaration. For one target: [{"path":"...","name":"..."}].',
 		}),
 		view: StringEnum(["signature", "signatureWithDocs", "declaration", "declarationWithImports"] as const, {
 			description: "signature | signatureWithDocs | declaration | declarationWithImports",
@@ -68,13 +69,30 @@ export function createShowTool(rowState: ToolRowStateStore, engineFor: (cwd: str
 		name: "show",
 		label: "show",
 		description:
-			"Exact signature or source for path+name targets. Whole batch fails on any missing/ambiguous target (candidate list, no partials). Views: signature → signatureWithDocs → declaration → declarationWithImports. Over budget throws — request fewer targets (bodies are not truncated).",
-		promptSnippet: "Signature or source for path+name targets",
+			'Show one or more declarations. Arguments always require a top-level `targets` array, even for one target: `{"targets":[{"path":"...","name":"..."}],"view":"declaration"}`. Whole batch fails on any missing/ambiguous target (candidate list, no partials). Views: signature → signatureWithDocs → declaration → declarationWithImports. Over budget throws — request fewer targets (bodies are not truncated).',
+		promptSnippet: "Show declarations using a top-level targets array",
 		promptGuidelines: [
+			"show always requires a top-level targets array, even for one declaration; do not pass path or name at the root.",
 			"Cheapest view that answers; declarationWithImports only when edits need imports.",
 			"Pin with path and line when names collide — do not guess.",
 		],
 		parameters: showParams,
+		prepareArguments(args) {
+			if (args === null || typeof args !== "object" || Array.isArray(args)) {
+				return args as Static<typeof showParams>;
+			}
+
+			const input = args as Record<string, unknown>;
+			if ("targets" in input || typeof input.path !== "string" || typeof input.name !== "string") {
+				return input as Static<typeof showParams>;
+			}
+
+			const { path, name, line, ...rest } = input;
+			return {
+				...rest,
+				targets: [{ path, name, ...(line === undefined ? {} : { line }) }],
+			} as Static<typeof showParams>;
+		},
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const engine = engineFor(ctx.cwd);
 			const abort = signal ?? new AbortController().signal;

package/extensions/patch/render.ts

@@ -1,4 +1,4 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
+import { keyHint, type Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.js";
 import { type ApplyPatchSummary, deriveStats } from "./executor.ts";
@@ -23,6 +23,7 @@ const REPLACE_FILE_MARKER = "*** Replace File: ";
 const DELETE_FILE_MARKER = "*** Delete File: ";
 const UPDATE_FILE_MARKER = "*** Update File: ";
 const MOVE_TO_MARKER = "*** Move to: ";
+const PATCH_PREVIEW_OPERATIONS = 10;
 
 function topLevelDirective(line: string): string {
 	return line.trim();
@@ -156,6 +157,21 @@ function renderOpLine(op: PreviewOp, status: OpStatus | undefined, theme: Theme)
 	return ind ? `${label}  ${ind}` : label;
 }
 
+function renderPreviewLines(preview: PreviewOp[], statuses: Map<number, OpStatus> | undefined, theme: Theme): string[] {
+	const lines = preview
+		.slice(0, PATCH_PREVIEW_OPERATIONS)
+		.map((op) => renderOpLine(op, statuses?.get(op.sectionIndex), theme));
+	const remaining = preview.length - lines.length;
+	if (remaining > 0) {
+		lines.push(
+			`${theme.fg("muted", `... (${remaining} more operations, ${preview.length} total,`)} ` +
+				keyHint("app.tools.expand", "to expand") +
+				theme.fg("muted", ")"),
+		);
+	}
+	return lines;
+}
+
 interface RenderCallContext {
 	expanded: boolean;
 	executionStarted: boolean;
@@ -198,7 +214,7 @@ export function renderPatchCall(args: { input?: string } | undefined, theme: The
 		text.setText(header);
 		return text;
 	}
-	const lines = preview.map((op) => renderOpLine(op, "pending", theme));
+	const lines = renderPreviewLines(preview, undefined, theme);
 	text.setText([header, ...lines].join("\n"));
 	return text;
 }
@@ -234,7 +250,7 @@ export function renderPatchResult(
 		return text;
 	}
 
-	const lines = preview.map((op) => renderOpLine(op, statuses.get(op.sectionIndex), theme));
+	const lines = renderPreviewLines(preview, statuses, theme);
 	text.setText([header, ...lines].join("\n"));
 	return text;
 }

package/extensions/script-runner/index.ts

@@ -15,6 +15,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { renderToolOutputPreview } from "../../shared/text.ts";
 
 type Language = "python3" | "node" | "deno";
 
@@ -295,6 +296,19 @@ export default function scriptRunnerExtension(pi: ExtensionAPI): void {
 			text.setText(body ? `${header}\n${body}` : header);
 			return text;
 		},
+		renderResult(result, options, theme, context) {
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			if (options.isPartial) {
+				text.setText("");
+				return text;
+			}
+			const output = result.content
+				.filter((item): item is { type: "text"; text: string } => item.type === "text")
+				.map((item) => item.text)
+				.join("\n");
+			text.setText(renderToolOutputPreview(output, options.expanded || context.isError, theme));
+			return text;
+		},
 	});
 
 	pi.registerTool(tool);

package/extensions/subagent/agents/scout.md

@@ -48,7 +48,7 @@ Use cheapest source that proves each returned fact. Skip steps when task supplie
 1. **Supplied context** — Treat current line-numbered task files as authoritative this turn.
 2. **Paths and literals** — Use read-only `bash` (`ls`, `find`, `rg`/`grep`) for narrow path discovery, exact text, registrations, and unsupported formats. Use ranged `read` for formatting or source without structural support.
 3. **Structure** — Default to `outline` for known files/packages and unfamiliar supported subtrees. Use `discover` when requested declaration path or exact name is unknown. Use `ast_search` for source shapes.
-4. **Exact declarations** — Use `show` with path + name (+ line when needed). Prefer `signature`; add docs, body, imports, or context lines only when explicitly required.
+4. **Exact declarations** — Use `show` with a top-level `targets` array containing path + name (+ line when needed), even for one declaration. Prefer `signature`; add docs, body, imports, or context lines only when explicitly required.
 5. **Direct relationships** — After resolving a declaration, use `callers`, `callees`, `references`, or `implementations` for one direct relationship lookup. Use `deps` and `reverse_deps` for file imports, not declaration calls.
 
 Structural results prove bounded syntax, not runtime dispatch. Preserve exact, inferred, and ambiguous labels emitted by tools. Never convert an ambiguous result into a fact.

package/extensions/tau-help/help.md

@@ -22,10 +22,6 @@ Names sessions from their first request so saved sessions remain findable.
 
 Adds `/branch` to create and switch Git branches from the TUI.
 
-## bash-approval
-
-Reviews every agent `bash` call with a quick-effort model before execution. Set `extensions.bashApproval.autoApprove` to run every reviewer-approved command without another confirmation. The reviewer approves routine local development work. Concrete destructive, system, production, privileged, or security-sensitive effects require human approval with one explanatory paragraph. Reviewer failures fall back to human approval and send an attention notification.
-
 ## cache-diagnostics
 
 Records private prompt-cache fingerprints without storing prompt content. Run `/cache-debug` after suspicious cache misses to write a bounded investigation report under `~/.pi/agent/cache-diagnostics/reports/`.
@@ -52,7 +48,7 @@ Adds `/effort [quick|standard|deep]` to select effort and a provider from curren
 
 ## explore
 
-Structural source tools on in-process tree-sitter (WASM), available on every Node-supported platform. Registers `outline`, `show`, `discover`, `ast_search`, `deps`, `reverse_deps`, `callers`, `callees`, `references`, `implementations`, `impact`, and `context`; symbol targets use path + name (+ line when needed). Pi keeps `ls` / `find` / `grep` / `read`. Large full `read`/autoread of registered source (including Markdown) returns outline by default (`explore.read.*`); ranged `read` or `show` for bodies. Disable with `explore.read.enabled: false`.
+Structural source tools on in-process tree-sitter (WASM), available on every Node-supported platform. Registers `outline`, `show`, `discover`, `ast_search`, `deps`, `reverse_deps`, `callers`, `callees`, `references`, `implementations`, `impact`, and `context`; `show` takes a top-level `targets` array of path + name objects (+ line when needed). Pi keeps `ls` / `find` / `grep` / `read`. Large full `read`/autoread of registered source (including Markdown) returns outline by default (`explore.read.*`); ranged `read` or `show` for bodies. Disable with `explore.read.enabled: false`.
 
 ## footer
 
@@ -130,6 +126,10 @@ Adds `/tau-help` to show this guide as rendered Markdown in the chat.
 
 Adds `/tau`, `/tau init [--global|--project]`, and `/tau doctor` for Tau setup and diagnostics.
 
+## tool-approval
+
+Reviews agent `bash` and `script_runner` requests before they run. Common read-only bash commands skip review. Set `extensions.toolApproval.autoApprove` to run every reviewer-approved request without another confirmation. Those auto-approvals show a user-only marker. The reviewer approves routine local development work. Concrete destructive, system, production, privileged, or security-sensitive effects require human approval with one explanatory paragraph. Reviewer failures fall back to human approval and send an attention notification.
+
 ## tool-loader
 
 Progressively exposes registered specialist tool groups through `load_tools`. Tau registers `web`, `image`, and `appshot`; project or global package extensions can add groups with `registerDeferredToolGroup()` from `@shanepadgett/tau-agent`. Supported providers can preserve more prompt-cache reuse.

package/extensions/tool-approval/README.md

@@ -0,0 +1,22 @@
+# Tool Approval
+
+Reviews agent `bash` and `script_runner` requests before they run.
+
+Common read-only bash commands skip review and run immediately. Other bash and every `script_runner` request go to a quick-effort model. The reviewer returns a validated decision and one concise paragraph that explains the request.
+
+With `autoApprove` enabled, reviewer-approved requests run without another confirmation. Tau shows a user-only marker after those auto-approvals. Common read-only bash that skips review does not get a marker. Routine local development work should be approved, including requests that modify project files or run scripts. The reviewer asks for human approval only when it finds a concrete destructive, system, production, privileged, or security-sensitive effect.
+
+When approval is required, Tau shows one paragraph that explains the effect and risk without repeating the request. If the reviewer fails or returns a malformed decision, Tau asks for direct human approval instead of running it automatically. Tau also sends an attention notification when the approval window opens.
+
+Configure under `extensions.toolApproval`:
+
+```json
+{
+  "extensions": {
+    "toolApproval": {
+      "enabled": true,
+      "autoApprove": true
+    }
+  }
+}
+```