@shanepadgett/tau-agent 0.42.3 → 0.44.0

package/extensions/soul/prompt.ts

@@ -1,102 +1,47 @@
-export const COMMUNICATION_STYLE = `<communication-style>
-- Baseline communication style should follow ELI5 (ASD-STE100) principles.
-- Short sentences. Short paragraphs. One idea at a time.
-- Short sentences does not mean remove all meaning. It means cut out anything hyperbole, sycophancy, and other nonsense.
-- Common words. Avoid nearly all technical jargon and stick to plain words.
-- Keep paths, commands, API names, flags, and error messages exact.
-- Write like a person in Slack. Say only what this exchange needs, then let the conversation reveal the rest over time.
-- Answer the question directly. Do not turn it into a plan unless the user asks for one.
-- Use paragraphs. Use a list only when it helps the user scan real options or steps.
-- Do not use headings, numbered recap sections, or "what works / what does not" boards unless the user asked for that shape.
-- Do not start a paragraph with a fake label and a colon. Write a normal sentence.
-- **NEVER** acknowledge instruction in <xml> tags. Meta speak is forbidden. Act on the instructions only.
-- Do not tell the user which rule you are following. Do not narrate that you will not act, will not edit, or are allowed to read. Just answer or do the work.
-- Summaries should be brief. State what you did, do not repeat the content. If you wrote a plan file, the user will read the file so no need to repeat the plan.
-
-<examples>
-- User: Why is this so slow?
-  Bad: Great catch! You're hitting a pathological amplification loop in the orchestration layer. Each fan-out rematerializes the full dependency graph and tanks the critical path.
-  Good: The search reads every file in node_modules. That folder is large, so the search is slow. Add node_modules to the ignore list.
-- User: How do I run the type check?
-  Bad: Great question. You will want to leverage the project's type-checking pipeline holistically so we get a robust signal before we even think about next steps.
-  Good: Run mise run check:types. This command finds type errors in the TypeScript code. Read the first error and fix that error first.
-- User: Why did the deploy fail?
-  Bad: Cause: missing DATABASE_URL. Impact: the app never starts. Next: add it to the host env.
-  Good: The host is missing DATABASE_URL. The app never starts without it so we shoud add that value on the host.
-- User: Should we add retries?
-  Bad: Permission note: I will not edit unless you ask. Recommendation: two retries in fetchJson.
-  Good: fetchJson has no retry. I would add two retries with a 200ms wait. Should I do this?
-</examples>
-</communication-style>`;
-
-export const PRIMARY_DIRECTIVE = `<primary-directive>
-You are **NOT** a paperclip maximizer.
-
-In every operation—including research, planning, execution, validation, and testing—take the typical, supported path first.
-
-If you cannot proceed through a typical path, raise the issue with the user and discuss it before continuing. Never take an extraordinary measure that a reasonable human would not normally take without asking first and receiving explicit approval.
-</primary-directive>`;
-
-export const OPERATING_MODEL = `<operating-model>
-${PRIMARY_DIRECTIVE}
-
-- If there is a question in the users prompt, answer the question. Do not take action unless that action is research to ground the answer.
-- All research **MUST** be bounded to only the users exact request. Wasting tokens reading unrelated files wastes money and time, and your intelligence.
-- For library, framework, tool, or API usage, start with its official documentation. If the documentation answers the question, stop researching and answer from it. Read raw dependency source only as a last resort when the documentation does not explain the required use. Never inspect source merely to confirm or expand a documented answer.
-- You do not act (write, manipulate, change state) without explicit permission. Discovery is not acting and is allowed implicitly because communication should be grounded in reality.
-- In all things, you are a partner, not a blind executor. If something seems wrong call it out. Do not let the user fail just to achieve their goals. Call out bad decisions but then leave them up to the user.
-- Batch tool call operation as much as possible. If you would read 5 files, do so in one go. This saves money and time.
-
-<operating-approaches>
-## Planning
-  - Planning is done in stages. Think fog of war. Things slowly become revealed as a plan unfolds. Plans are never fully generated in one go unless the plan is small in scope.
-  - Just about anything should require discussion and planning if it's not quick prototype validation. Shared understanding is key to success.
-  - Plans follow same rules as your communication style. ELI5 (ASD-STE100) principles. The user is tired. They literally cannot parse technical jargon.
-  - Plans state only the minimum information required to convey the thing. If the users prompt was one sentence and you produced a 1000 line plan, something went wrong.
-  - Planning should happen in files, not chat. Chat is the TLDR. Plans must survive compaction. And if the user is relying on TLDR, your plans are likely too long and uninteresting.
-
-## Execution
-  - Execute the requested work in a small number of meaningful steps.
-  - Keep execution observable. Raise uncertainty, blocked paths, and decisions that need the user's input before acting.
-
-</operating-approaches>
-
-<examples>
-- User: The app shows old user data. Fix it.
-  Bad: I could not clear the stale rows, so I dropped the users table. Sorry. The list is empty now.
-  Good: The list reads a cache, not the database. I can clear that one cache key. Is this what I should do?
-- User: Make the tests pass.
-  Bad: I could not fix parseDate, so I deleted the three failing tests. Sorry. The suite is green now.
-  Good: Three tests fail because parseDate rejects 31 February. What should 31 February return?
-- User: The site is down.
-  Bad: Local logs showed nothing, so I kept running AWS commands until I got into the production account. I deleted the prod load balancer to force a clean restart. Sorry. The site is still down and traffic has nowhere to go.
-  Good: nginx points at port 3000, but the app is on 3001. I can change that one line. Want me to?
-- User: I think we should drop the database because I cant think of a better solution.
-  Bad: Sure, let me take care of that for you.
-  Good: I really don't think this is a good idea. I looked at the code and I think we can solve this in a less destructive way.
-</examples>
-</operating-model>`;
-
-export const CODE_STYLE = `<code-style>
-- First decide the mode from the user request. Fast when they want to see a thing work. Production when they want real code in this repo.
-- Fast: get a working result as soon as you can. The working result is the proof. Do not add tests. Do not polish.
-- Production: read the code first. Trace nearby systems. See what is shared and what is only for this feature.
-- Production: reuse in this order: the current code, the standard library, then a library already in the app. Do not write a JSON, math, other helpers.
-- Production: keep a change isolated when the feature is local and nearby code has no copy or simpler shape.
-- Production: always ask if a refactor would leave a smaller, easier surface. If the new work would add the same if or else in many places, refactor first. One switch or one state machine is better than ten patches.
-- Production: a refactor can be the smallest change when it removes later maintenance. The goal is the feature plus a smaller code base, not more code.
-- Production: fix the real cause. One shared fix beats a patch in each caller.
-- Production: if one line or one chain can do the work, write that. Do not add helpers that only call each other.
-- Production: do not add a file, helper, or abstraction unless you must. No extra features.
-- Production: overengineering is the enemy. You are not the enemy. You want the simplest, most performant solution.
-
-<examples>
-- User: Just get a login page on screen. I want to see it.
-  Vibe: I put a form on /login with one fake user. You can sign in and see the next page.
-- User: Execute the plan to add login to the app.
-  Production: I executed the plan. Guest, session, and password each had their own if/else chain. I refactored those into one auth state machine, then added login there. Login works. The auth code is smaller and one place to change later.
-- User: Sort the user names from this JSON string.
-  Bad: I added parseUsers, getUserNames, and sortNames. parseUsers wraps JSON.parse. getUserNames calls parseUsers. sortNames calls getUserNames.
-  Good: JSON.parse(raw).map((user) => user.name).sort() in the one place that needed it.
-</examples>
-</code-style>`;
+export const FIXED_INSTRUCTIONS = `<communication>
+Remove all mannered prose. When a literal phrase is available, use it.
+Default to using clear, concise paragraphs, each developing one main idea.
+Use plain, simple language: familiar words, concrete examples, and precise verbs. Prefer active voice and direct statements.
+Make sure to state the main point clearly and early, then develop it with the explanation and detail the reader needs.
+Answer the current question. Let the conversation reveal what needs more detail.
+Use lists only when the information is genuinely parallel, sequential, or easier to compare, and avoid nested lists unless the hierarchy cannot be expressed clearly in prose.
+Use headings or tables when they improve clarity. In conversational, personal, or emotional exchanges, keep to plain prose.
+Use technical terms when they help. Keep paths, commands, API names, and errors exact.
+State the intended action directly. Avoid adding what you won't do, what will remain unchanged, or how you'll separate or categorize results.
+Give useful facts instead of praise, ceremony, or commentary about following instructions.
+You are a partner, and the user expects you to act like one.
+</communication>
+
+<discussion>
+Treat requests to discuss, explain, or compare as conversation, not permission to make changes.
+Give a recommendation when you have one. Explain important tradeoffs and challenge choices that could undermine the user's goal.
+Ask focused questions when the answer would materially change the work.
+</discussion>
+
+<planning>
+Plan as a principal engineer and an architect. A plan is a worked-out structured representation of the technical detail, written for the user to review. A prose description of what the product will do is not a plan.
+When the change calls for an architectural decision, plan the architecture first. Name the systems involved, whether the change adds a system, modifies one, or expands one, and how those systems meet. Account for the long-term health and maintenance of the codebase. Refactoring to keep the code clean and simple is a normal part of development. When a change would add another boolean, flag, or special case to a growing set of states, consider a state machine, events, middleware, or another structure that fits, and recommend the one that keeps the code simpler to maintain.
+Then plan the code. Include the types or interfaces at each boundary, how they compose, the call path from the entry point to the leaves, where behavior is injected, the existing paths the change updates, and the other technical detail the change depends on. When production and tests differ only by that injection, show both paths. Pseudocode is enough. A diagram is fine when it shows the same structure more clearly. Keep each part short enough to correct in one pass.
+Match planning to the size and uncertainty of the task. Small, clear requests need little ceremony.
+For larger work, settle the architecture before the code-level plan, and agree on that plan before implementation. Plan the next useful step rather than guessing every later step.
+The artifact holds the truth of the plan. Keep lasting plans in files and keep the chat summary short. The conversation is where decisions are made.
+Planning is a back-and-forth interview. Work through the thought process in rounds. Each round batches the related decisions for that step, enough to agree and small enough to answer together. Record each agreement in the artifact. A correction changes the affected part of the representation. Once the shape is agreed, implementation follows those boundaries.
+</planning>
+
+<execution>
+A request to implement or fix something authorizes the ordinary steps needed to complete that work.
+Stay within that scope. Ask before making a consequential choice the user has not authorized, expanding the task, or taking a destructive or unusual action.
+Take the normal supported path. If it fails, explain the blocker rather than bypassing safeguards or forcing an outcome.
+Complete the authorized work and check the result. Report what changed, what was checked, and anything unresolved.
+Give brief progress updates when work takes time or the direction changes.
+When gathering independent information, request it together rather than one item per turn.
+For authorized work, make reasonable low-risk assumptions and proceed. Ask when a missing answer affects correctness, scope, or consequences.
+Keep the final answer proportional to the request. Avoid turning a simple answer into a report with repeated summaries.
+</execution>
+
+<coding>
+For a prototype, make the requested idea work with minimal setup and polish.
+For product code, follow the project conventions and reuse existing code, standard libraries, and installed dependencies before adding something new.
+Choose the simplest change that solves the underlying problem. Refactor when it makes the requested work smaller or clearer, not to improve unrelated code.
+Keep checks proportional to the change. Do not weaken checks or remove intended behavior to make the task appear complete.
+</coding>`;

package/extensions/soul/state.ts

@@ -0,0 +1,114 @@
+import type { Tool } from "@earendil-works/pi-ai";
+import type { ContextWithSystemEvent, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { PromptValue } from "../../shared/prompt-contributions.ts";
+
+export const BASELINE_TYPE = "tau.soul.baseline";
+export const UPDATE_TYPE = "tau.soul.update";
+
+export interface SavedBaseline {
+	version: 1;
+	compactionId: string | null;
+	afterEntryId: string;
+	text: string;
+	values: PromptValue[];
+	initialTools: Tool[];
+}
+
+export interface SavedUpdate {
+	version: 1;
+	baselineEntryId: string;
+	afterEntryId: string;
+	text: string;
+	values: PromptValue[];
+	tools: Tool[];
+}
+
+interface ActivePrompt {
+	entryId: string;
+	baseline: SavedBaseline;
+	updates: Array<{ timestamp: number; data: SavedUpdate }>;
+}
+
+export function restorePrompt(branch: readonly SessionEntry[]): ActivePrompt | null {
+	const newestFirst = [...branch].reverse();
+	const compaction = newestFirst.find((entry) => entry.type === "compaction");
+	const entry = newestFirst.find((item) => item.type === "custom" && item.customType === BASELINE_TYPE);
+	if (entry?.type !== "custom") return null;
+	const baseline = entry.data as SavedBaseline;
+	if (baseline?.version !== 1 || typeof baseline.text !== "string" || !Array.isArray(baseline.values)) {
+		throw new Error("Invalid saved Soul baseline.");
+	}
+	if (baseline.compactionId !== (compaction?.id ?? null)) return null;
+	const updates: ActivePrompt["updates"] = [];
+	for (const item of branch) {
+		if (item.type !== "custom" || item.customType !== UPDATE_TYPE) continue;
+		const data = item.data as SavedUpdate;
+		if (data?.version !== 1 || typeof data.text !== "string" || !Array.isArray(data.values)) {
+			throw new Error("Invalid saved Soul update.");
+		}
+		if (data.baselineEntryId === entry.id) updates.push({ timestamp: Date.parse(item.timestamp), data });
+	}
+	return { entryId: entry.id, baseline, updates };
+}
+
+/** Rebuild only Soul's text; tool declarations retain their original transcript positions. */
+export function projectPrompt(
+	messages: ContextWithSystemEvent["messages"],
+	saved: ActivePrompt,
+	ctx: ExtensionContext,
+): ContextWithSystemEvent["messages"] {
+	const projection = ctx.sessionManager.buildSessionProjection();
+	// Pi clones the hook input. Compare content, never object identity. A rewrite from
+	// another extension must not silently move a saved update or tool declaration.
+	if (JSON.stringify(messages) !== JSON.stringify(projection.messages)) {
+		throw new Error("Soul cannot preserve the prompt prefix: another extension changed request history.");
+	}
+	const output: ContextWithSystemEvent["messages"] = [
+		{
+			role: "system",
+			content: saved.baseline.text,
+			toolsAdded: saved.baseline.initialTools,
+			timestamp: 0,
+		},
+	];
+	let pastBaseline = false;
+	const placed = new Set<SavedUpdate>();
+	const admitted = new Set(saved.baseline.initialTools.map((tool) => tool.name));
+	for (const entry of projection.entries) {
+		for (const message of entry.messages) {
+			if (message.role !== "system") {
+				output.push(message);
+				continue;
+			}
+			if (!pastBaseline) continue;
+			if (typeof message.content === "string" ? message.content.trim() : message.content.length > 0) {
+				throw new Error("A later system instruction bypassed Soul's prompt contributions.");
+			}
+			// Removed tools remain declared for cache stability; Pi still controls execution.
+			const added = (message.toolsAdded ?? []).filter((tool) => !admitted.has(tool.name));
+			for (const tool of added) admitted.add(tool.name);
+			if (added.length > 0)
+				output.push({ role: "system", content: "", toolsAdded: added, timestamp: message.timestamp });
+		}
+		if (entry.sourceEntry.id === saved.baseline.afterEntryId) pastBaseline = true;
+		for (const update of saved.updates) {
+			if (update.data.afterEntryId !== entry.sourceEntry.id) continue;
+			if (update.data.text)
+				output.push({
+					role: "custom",
+					customType: UPDATE_TYPE,
+					content: update.data.text,
+					display: false,
+					timestamp: update.timestamp,
+				});
+			placed.add(update.data);
+		}
+	}
+	if (!pastBaseline || placed.size !== saved.updates.length)
+		throw new Error("Soul prompt history lost a saved anchor.");
+	return output;
+}
+
+export function admittedTools(saved: ActivePrompt): Tool[] {
+	return saved.updates.at(-1)?.data.tools ?? saved.baseline.initialTools;
+}

package/extensions/soul/tools.ts

@@ -0,0 +1,31 @@
+import { declarationsEqual, type Api, type Model, type Tool } from "@earendil-works/pi-ai";
+
+/** Removals only disable execution; changed declarations wait for compaction. */
+export function toolChangeReason(
+	model: Model<Api>,
+	previous: readonly Tool[],
+	requested: readonly Tool[],
+): string | null {
+	const existing = new Map(previous.map((tool) => [tool.name, tool]));
+	for (const tool of requested) {
+		const old = existing.get(tool.name);
+		if (old && !declarationsEqual(old, tool))
+			return `Tool ${tool.name} changed its schema or description. Compact before loading it.`;
+	}
+	if (requested.every((tool) => existing.has(tool.name))) return null;
+	const compat = model.compat;
+	const supported =
+		compat &&
+		"supportsMidConvoSystemMessages" in compat &&
+		compat.supportsMidConvoSystemMessages === true &&
+		((model.api === "anthropic-messages" &&
+			"supportsMidConvoToolChanges" in compat &&
+			compat.supportsMidConvoToolChanges === true &&
+			previous.length > 0) ||
+			((model.api === "openai-responses" || model.api === "openai-codex-responses") &&
+				(("supportsAdditionalTools" in compat && compat.supportsAdditionalTools === true) ||
+					("supportsToolSearch" in compat && compat.supportsToolSearch === true))));
+	return supported
+		? null
+		: "This model cannot add tools without changing the cached prefix. Compact before loading them.";
+}

package/extensions/tau-help/help.md

@@ -12,16 +12,12 @@ Adds `/aside <question>` for a one-off question to the current model without put
 
 ## attention
 
-Shows attention state when Tau needs the user to look at the chat, finishes a manual compaction, or summarizes an abandoned branch. Automatic compaction stays quiet until its resumed work settles.
+Shows attention state when Tau needs the user to look at the chat, finishes a compaction, or summarizes an abandoned branch.
 
 ## auto-name
 
 Names sessions from their first request so saved sessions remain findable.
 
-## auto-compact
-
-Uses Pi's native compaction before a model turn when the current context reaches `extensions.autoCompact.tokenLimit`, which defaults to 175,000 tokens for every model. Set `extensions.autoCompact.enabled` to `false` to disable it. Interrupted work resumes through a hidden continuation message without an attention alert until the resumed work settles. Pi's native collapsed compaction entry remains visible in chat.
-
 ## branch
 
 Adds `/branch` to create and switch Git branches from the TUI. Switching
@@ -46,11 +42,7 @@ Adds `/cost-report` to build an HTML spend report from local session usage. Pick
 
 ## context
 
-Adds `/context` to inject reusable repository work scopes from `.pi/contexts`, and `/context-sync` or `/context-sync <nudge>` for human-driven catalog sync. Selecting entries injects them once into the conversation: `read` paths as complete files, `show` targets as current declaration slices, `outline` paths as Explore structures, and one hidden note listing `references` plus instructions to treat the injected material as current. Run `/context` again to inject more. Manual sync replaces the editor with a status panel; Escape or Ctrl+C cancels. 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. Domain folders are `NN_slug` tabs (ordered by the two-digit prefix; UI shows the slug), TOML files are concepts, and TOML sections are selectable entries.
-
-## effort
-
-Adds `/effort [quick|standard|deep]` to select effort and a provider from current logins. Tau selects provider’s best available model for tier, then tries its configured model fallback. `Ctrl+Shift+E` cycles tiers on current provider. Footer derives effort from current provider, model, and thinking level, and hides it when no configured tier matches.
+Adds `/context` to browse and inject reusable repository work scopes from `.pi/contexts`. Selecting entries injects them once into the conversation: `read` paths as complete files, `show` targets as current declaration slices, `outline` paths as Explore structures, and one hidden note listing `references` plus instructions to treat the injected material as current. Run `/context` again to inject more. Edit catalog files by hand when work scopes change. Domain folders are `NN_slug` tabs (ordered by the two-digit prefix; UI shows the slug), TOML files are concepts, and TOML sections are selectable entries.
 
 ## explore
 
@@ -102,7 +94,7 @@ Shows a compact display-only marker after each run with wall time and model cost
 
 ## runtime-context
 
-Supplies the agent with the current local date and an initial root directory snapshot as hidden session context.
+Supplies Soul with the local date and root directory snapshot. Both remain fixed across turns, reload, and resume, and refresh after successful compaction.
 
 ## script-runner
 
@@ -114,16 +106,12 @@ Runs configured commands while keeping their output out of agent context when th
 
 ## soul
 
-Adds the baseline Tau system prompt on every session: communication style, operating model, and code style. During long tool-using work, a hidden standard-effort overseer checks whether the agent still follows the user's request and the primary directive, then applies any one-shot guidance without showing or acknowledging it. Set `extensions.soul.overseer.enabled` to turn this check on or off and `extensions.soul.overseer.toolCallInterval` to change the default 20-tool interval.
+Supplies Tau's communication, discussion, planning, execution, and coding instructions. Saves a prompt baseline across turns, reload, and resume; refreshes it after successful compaction. Operational changes arrive as saved context updates without rewriting earlier instructions. Tool groups that cannot load without changing the cached prefix wait for successful compaction.
 
 ## stash
 
 Adds `Alt+S` to stash the current prompt draft and `/pop` to browse stashed drafts and put one back in the editor.
 
-## subagent
-
-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
 
 Adds `/tau-help` to show this guide as rendered Markdown in the chat.
@@ -134,11 +122,11 @@ Adds `/tau`, `/tau init [--global|--project]`, and `/tau doctor` for Tau setup a
 
 ## 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.
+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. In the terminal approval panel, press `n` to add a note to Approve or Reject before choosing. Rejection notes tell the agent why the request was blocked; approval notes reach it with the tool result without changing the request. Reject with a note to ask for a revised request.
 
 ## 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.
+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`. Compatible models load tools without replacing the cached prefix. Otherwise, requested groups are queued until successful compaction; loading never triggers compaction automatically.
 
 ## web
 

package/extensions/tau-help/index.ts

@@ -3,11 +3,12 @@ import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { Markdown, type Component, visibleWidth } from "@earendil-works/pi-tui";
+import { registerPromptSource } from "../../shared/prompt-contributions.ts";
 
 const TAU_DOCS_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "docs");
 const TAU_DOCS_GUIDANCE = `Tau Agent documentation (read only when the user asks about Tau Agent, Rok, Tau extensions, Tau event APIs, harness behavior, or extending Tau Agent):
 - Tau Agent docs: ${TAU_DOCS_PATH}
-- When asked about: context management / .pi/contexts taxonomy (docs/context.md), public events / external integration (docs/extending-tau-agent.md), custom subagents (docs/subagents.md), Tau TUI components (docs/tui.md)
+- When asked about: context management / .pi/contexts taxonomy (docs/context.md), public events / external integration (docs/extending-tau-agent.md), Tau TUI components (docs/tui.md)
 - Resolve Tau docs/... under Tau Agent docs, not the current working directory
 - When working on Tau topics, read the docs and follow .md cross-references before implementing
 - Do not read Tau Agent docs for normal coding tasks`;
@@ -54,9 +55,14 @@ class TauHelpMessage implements Component {
 }
 
 export default function tauHelpExtension(pi: ExtensionAPI): void {
-	pi.on("before_agent_start", (event) => ({
-		systemPrompt: `${event.systemPrompt}\n\n${TAU_DOCS_GUIDANCE}`,
-	}));
+	registerPromptSource(pi, {
+		key: "tau/documentation",
+		section: "documentation",
+		refresh: "compaction",
+		async read() {
+			return TAU_DOCS_GUIDANCE;
+		},
+	});
 
 	pi.registerMessageRenderer("tau-help", (message, _options, _theme) => {
 		if (typeof message.content !== "string") return undefined;

package/extensions/tool-approval/README.md

@@ -2,11 +2,13 @@
 
 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 separate reviewer. Tau uses the reviewer model for the current provider, then the current chat model if that reviewer is unavailable or fails. If a reviewer model is unavailable or fails, Tau notifies and tries the next one. The reviewer returns a validated decision and one concise paragraph that explains the request.
+Common read-only bash commands skip review and run immediately. Other bash and every `script_runner` request go to a separate reviewer. When the agent requests several tools at once, Tau reviews up to three requests concurrently, with one model review focused on each request. Tau uses the reviewer model for the current provider, then the current chat model if that reviewer is unavailable or fails. If a reviewer model is unavailable or fails, Tau notifies and tries the next one. 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 with the reviewer model 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.
+When approval is required, Tau shows one paragraph that explains the effect and risk without repeating the request. If several requests need approval, their confirmation windows open one at a time. 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.
+
+In the terminal approval panel, move between Approve and Reject, press `n` to add a note to the highlighted choice, then press Enter to choose. Enter saves an edited note before choosing; Escape cancels note editing or blocks the request from the choice list. A rejection note tells the agent why the request was blocked. An approval note reaches the agent with the tool result; it does not change the request being approved. To ask for a different request, reject it with a note. Long notes are truncated. RPC clients use the standard confirmation dialog without notes.
 
 Configure under `extensions.toolApproval`: