one-code-extension 0.4.1 → 0.6.0

package/extensions/bash/description.ts

@@ -0,0 +1,188 @@
+/**
+ * The bash tool's model-facing texts: Claude Code's Bash descriptions (pure).
+ *
+ * Claude Code has three: a short form for its current models, with one extra
+ * bullet ("IMPORTANT: Avoid using this tool to run `cat`…") when auto mode is
+ * off, and a long form for its weakest models that is the same in every mode.
+ * One Code picks the form by tier (lib/tool-variants.ts) and the extra bullet
+ * by the permission mode. Two kinds of change from Claude Code's text: tool
+ * names are One Code's (`read`, `edit`, `write`, `monitor`, `task_create`),
+ * and the working-directory sentence says what this tool does, since each
+ * command starts in the session's working directory and a `cd` does not carry
+ * over (lib/shell-tool.ts), where Claude Code tracks the directory between
+ * calls. The parameter texts are Claude Code's. On the tiny tier, the one
+ * with dedicated grep, find and ls tools (search-tools/tools.ts), the long
+ * form's two shell-`find` bullets give way to a pointer at those tools, as
+ * tiny's system prompt says (system-prompt/tiers/low.ts).
+ */
+
+import type { DescriptionForm } from "../lib/tool-variants.ts";
+
+/** The bullet Claude Code adds to the short form when auto mode is off. */
+export const BASH_AVOID_SHELL_READS_LINE = "- IMPORTANT: Avoid using this tool to run `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.\n";
+
+/** The short form outside auto mode. */
+export const BASH_SHORT_DESCRIPTION = `Executes a bash command and returns its output.
+
+- Each call starts in the session's working directory and a \`cd\` does not carry over, so prefer absolute paths — \`cd\` in a compound command can trigger a permission prompt. Shell state (env vars, functions) does not persist.
+- IMPORTANT: Avoid using this tool to run \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.
+- Command output is displayed to you, not reliably to the user.
+- \`timeout\` is in milliseconds: default 120000, max 600000 for a foreground command.
+- \`run_in_background\` runs the command detached: it keeps running across turns and re-invokes you when it exits. No \`&\` needed. Foreground \`sleep\` is blocked; use monitor with an until-loop to wait on a condition.
+
+# Git
+- Interactive flags (\`-i\`, e.g. \`git rebase -i\`, \`git add -i\`) are not supported in this environment.
+- Use the \`gh\` CLI for GitHub operations (PRs, issues, API).
+- Commit or push only when the user asks. If on the default branch, branch first.
+- End git commit messages and PR bodies with the attribution lines given in the conversation's system-reminder, when one is present.`;
+
+/** The long form (every permission mode). */
+export const BASH_LONG_DESCRIPTION = `Executes a given bash command and returns its output.
+
+Each command starts in the session's working directory; neither a directory change (\`cd\`) nor shell state (variables, functions) carries over to the next command.
+
+IMPORTANT: Avoid using this tool to run \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
+
+ - Read files: Use read (NOT cat/head/tail)
+ - Edit files: Use edit (NOT sed/awk)
+ - Write files: Use write (NOT echo >/cat <<EOF)
+ - Communication: Output text directly (NOT echo/printf)
+While the bash tool can do similar things, it’s better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
+
+# Instructions
+ - If your command will create new directories or files, first use this tool to run \`ls\` to verify the parent directory exists and is the correct location.
+ - Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")
+ - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of \`cd\`. You may use \`cd\` if the User explicitly requests it. In particular, never prepend \`cd <current-directory>\` to a \`git\` command — \`git\` already operates on the current working tree, and the compound triggers a permission prompt.
+ - You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes for a foreground command). By default, your command will timeout after 120000ms (2 minutes).
+ - You can use the \`run_in_background\` parameter to run the command in the background. Only use this if you don't need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away - you'll be notified when it finishes. You do not need to use '&' at the end of the command when using this parameter.
+ - For git commands:
+  - Prefer to create a new commit rather than amending an existing commit.
+  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
+  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
+ - Avoid unnecessary \`sleep\` commands:
+  - Do not sleep between commands that can run immediately — just run them.
+  - Use the monitor tool to stream events from a background process (each stdout line is a notification). For one-shot "wait until done," use bash with run_in_background instead.
+  - If your command is long running and you would like to be notified when it finishes — use \`run_in_background\`. No sleep needed.
+  - Do not retry failing commands in a sleep loop — diagnose the root cause.
+  - If waiting for a background task you started with \`run_in_background\`, you will be notified when it completes — do not poll.
+  - Long leading \`sleep\` commands are blocked. To poll until a condition is met, use monitor with an until-loop (e.g. \`until <check>; do sleep 2; done\`) — you get a notification when the loop exits. Do not chain shorter sleeps to work around the block.
+ - When running \`find\`, search from \`.\` (or a specific path), not \`/\` — scanning the full filesystem can exhaust system resources on large trees.
+ - When using \`find -regex\` with alternation, put the longest alternative first. Example: use \`'.*\\.\\(tsx\\|ts\\)'\` not \`'.*\\.\\(ts\\|tsx\\)'\` — the second form silently skips \`.tsx\` files.
+
+
+# Committing changes with git
+
+Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
+
+You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. The numbered steps below indicate which commands should be batched in parallel.
+
+Git Safety Protocol:
+- NEVER update the git config
+- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests these actions. Taking unauthorized destructive actions is unhelpful and can result in lost work, so it's best to ONLY run these commands when given direct instructions 
+- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
+- NEVER run force push to main/master, warn the user if they request it
+- CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit, which may result in destroying work or losing previous changes. Instead, after hook failure, fix the issue, re-stage, and create a NEW commit
+- When staging files, prefer adding specific files by name rather than using "git add -A" or "git add .", which can accidentally include sensitive files (.env, credentials) or large binaries
+- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive
+
+1. Run the following bash commands in parallel, each using the bash tool:
+  - Run a git status command to see all untracked files. IMPORTANT: Never use the -uall flag as it can cause memory issues on large repos.
+  - Run a git diff command to see both staged and unstaged changes that will be committed.
+  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
+2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
+  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
+  - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files
+  - Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
+  - Ensure it accurately reflects the changes and their purpose
+3. Run the following commands in parallel:
+   - Add relevant untracked files to the staging area.
+   - Create the commit with a message, ending with the attribution lines given in the conversation's system-reminder, when one is present.
+   - Run git status after the commit completes to verify success.
+   Note: git status depends on the commit completing, so run it sequentially after the commit.
+4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit
+
+Important notes:
+- NEVER run additional commands to read or explore code, besides git bash commands
+- NEVER use the task_create or Agent tools
+- DO NOT push to the remote repository unless the user explicitly asks you to do so
+- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
+- IMPORTANT: Do not use --no-edit with git rebase commands, as the --no-edit flag is not a valid option for git rebase.
+- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
+- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:
+<example>
+git commit -m "$(cat <<'EOF'
+   Commit message here.
+   EOF
+   )"
+</example>
+
+# Creating pull requests
+Use the gh command via the bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a Github URL use the gh command to get the information needed.
+
+IMPORTANT: When the user asks you to create a pull request, follow these steps carefully:
+
+1. Run the following bash commands in parallel using the bash tool, in order to understand the current state of the branch since it diverged from the main branch:
+   - Run a git status command to see all untracked files (never use -uall flag)
+   - Run a git diff command to see both staged and unstaged changes that will be committed
+   - Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote
+   - Run a git log command and \`git diff [base-branch]...HEAD\` to understand the full commit history for the current branch (from the time it diverged from the base branch)
+2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request title and summary:
+   - Keep the PR title short (under 70 characters)
+   - Use the description/body for details, not the title
+3. Run the following commands in parallel:
+   - Create new branch if needed
+   - Push to remote with -u flag if needed
+   - Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting. End the body with the attribution lines given in the conversation's system-reminder, when one is present.
+<example>
+gh pr create --title "the pr title" --body "$(cat <<'EOF'
+## Summary
+<1-3 bullet points>
+
+## Test plan
+[Bulleted markdown checklist of TODOs for testing the pull request...]
+EOF
+)"
+</example>
+
+Important:
+- DO NOT use the task_create or Agent tools
+- Return the PR URL when you're done, so the user can see it
+
+# Other common operations
+- View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments`;
+
+/** The long form's shell-`find` advice, which the tiny tier's search tools replace. */
+const SHELL_FIND_LINES = ` - When running \`find\`, search from \`.\` (or a specific path), not \`/\` — scanning the full filesystem can exhaust system resources on large trees.
+ - When using \`find -regex\` with alternation, put the longest alternative first. Example: use \`'.*\\.\\(tsx\\|ts\\)'\` not \`'.*\\.\\(ts\\|tsx\\)'\` — the second form silently skips \`.tsx\` files.
+`;
+const SEARCH_TOOLS_LINE = ` - Search with the dedicated tools, not this shell: the find tool for files, the grep tool for content, the ls tool to list a directory.
+`;
+
+/** The long form on the tiny tier, whose grep, find and ls tools replace shell searches. */
+export const BASH_LONG_SEARCH_TOOLS_DESCRIPTION = BASH_LONG_DESCRIPTION.replace(SHELL_FIND_LINES, SEARCH_TOOLS_LINE);
+
+/** The description for a form and permission mode; `searchTools` when the session has the dedicated search tools. */
+export function bashDescription(form: DescriptionForm, autoMode: boolean, searchTools = false): string {
+	if (form === "long") return searchTools ? BASH_LONG_SEARCH_TOOLS_DESCRIPTION : BASH_LONG_DESCRIPTION;
+	return autoMode ? BASH_SHORT_DESCRIPTION.replace(BASH_AVOID_SHELL_READS_LINE, "") : BASH_SHORT_DESCRIPTION;
+}
+
+/** Claude Code's parameter descriptions. */
+export const BASH_PARAMS = {
+	command: `The command to execute`,
+	timeout: `Optional timeout in milliseconds (max 600000 for a foreground command)`,
+	description: `Clear, concise description of what this command does in active voice. Never use words like "complex" or "risk" in the description - just describe what it does.
+
+Say what the command does in plain words: do not echo the command's text, its flags, or file paths - the user reads this description, often without seeing the command.
+
+For simple commands (git, npm, standard CLI tools), keep it brief (5-10 words):
+- ls → "List files in current directory"
+- git status → "Show working tree status"
+- npm install → "Install package dependencies"
+
+For commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does:
+- find . -name "*.tmp" -exec rm {} \\; → "Find and delete all .tmp files recursively"
+- git reset --hard origin/main → "Discard all local changes and match remote main"
+- curl -s url | jq '.data[]' → "Fetch JSON from URL and extract data array elements"`,
+	run_in_background: `Set to true to run this command in the background.`,
+} as const;

package/extensions/bash/guards.ts

@@ -28,6 +28,7 @@
 import {
 	gitSubcommand,
 	leadTokens,
+	LOOPS,
 	parseCommand,
 	resolvePayload,
 	type Segment,
@@ -37,18 +38,14 @@ import {
 export const clip = (text: string, max = 200): string => (text.length > max ? `${text.slice(0, max)}…` : text);
 
 export function bashGuardReason(command: string, opts: { background: boolean }): string | undefined {
-	// A heredoc/here-string body is data, but parseCommand tokenizes it as live
-	// shell — every guard would misfire on body text (a literal `vim` or
-	// `while … sleep` inside a document). Judge only the command that PRECEDES
-	// the first `<<`: `sleep 600 <<< ""` is still a sleep (review T14), while a
-	// `cat <<EOF` body is never read.
-	const lead = command.split(/<</)[0];
-	if (lead !== command && !lead.trim()) return undefined;
-	const { segments, parseFailed } = parseCommand(lead);
-	if (parseFailed || segments.length === 0) return undefined;
+	// A heredoc body is data to the grammar, so a literal `vim` or `while …
+	// sleep` inside a document never trips a guard (review T14).
+	const parsed = parseCommand(command);
+	if (parsed.parseFailed || parsed.segments.length === 0) return undefined;
+	const { segments } = parsed;
 	const interactive = interactiveReason(segments);
 	if (interactive || opts.background) return interactive;
-	return waitReason(segments) ?? pollLoopReason(lead, segments) ?? orphanReason(lead, segments);
+	return waitReason(segments) ?? pollLoopReason(command, segments) ?? orphanReason(parsed.background, segments);
 }
 
 // ---------------------------------------------------------------------------
@@ -123,15 +120,13 @@ function waitReason(segments: Segment[]): string | undefined {
 // ---------------------------------------------------------------------------
 // Poll-loop guard
 
+const inLoop = (seg: Segment) => seg.enclosing.some((construct) => LOOPS.has(construct));
+
 function pollLoopReason(command: string, segments: Segment[]): string | undefined {
-	const first = leadTokens(segments[0])[0]?.value;
-	if (first !== "while" && first !== "until" && first !== "for") return undefined;
-	// `sleep` counts only in command position (segment lead, or right after a
-	// `do`/`then`/`else` keyword) — `echo sleep` is data, not a wait.
-	const sleeps = segments.some((seg) => {
-		const { command: cmd } = resolvePayload(leadTokens(seg));
-		return cmd === "sleep";
-	});
+	// Wherever the loop sits in the line: `echo start; while true; do sleep 5;
+	// done` stalls the session as surely as the loop alone. `sleep` counts only
+	// as a command inside the loop: `echo sleep` is data.
+	const sleeps = segments.some((seg) => inLoop(seg) && resolvePayload(leadTokens(seg)).command === "sleep");
 	if (!sleeps) return undefined;
 	return (
 		`Blocked: a foreground polling loop (\`${clip(command, 160)}\`). It occupies the whole session while it spins. ` +
@@ -143,54 +138,7 @@ function pollLoopReason(command: string, segments: Segment[]): string | undefine
 // ---------------------------------------------------------------------------
 // Orphan guard
 
-/** True when the command backgrounds something with a top-level unquoted `&`. */
-export function hasBackgroundAmp(command: string): boolean {
-	let inSingle = false;
-	let inDouble = false;
-	let inAnsiC = false; // $'…' honors backslash-escaped quotes, unlike '…'
-	let escape = false;
-	for (let i = 0; i < command.length; i++) {
-		const ch = command[i];
-		if (escape) {
-			escape = false;
-			continue;
-		}
-		if (inAnsiC) {
-			if (ch === "\\") escape = true;
-			else if (ch === "'") inAnsiC = false;
-			continue;
-		}
-		if (ch === "'" && !inSingle && !inDouble && command[i - 1] === "$") {
-			inAnsiC = true;
-			continue;
-		}
-		if (ch === "\\" && !inSingle) {
-			escape = true;
-			continue;
-		}
-		if (ch === "'" && !inDouble) {
-			inSingle = !inSingle;
-			continue;
-		}
-		if (ch === '"' && !inSingle) {
-			inDouble = !inDouble;
-			continue;
-		}
-		if (inSingle || inDouble || ch !== "&") continue;
-		const prev = command[i - 1];
-		const next = command[i + 1];
-		if (next === "&") {
-			i++; // logical &&
-			continue;
-		}
-		if (next === ">") continue; // &> redirect
-		if (prev === ">" || prev === "|") continue; // 2>&1 fd duplication, |& pipe
-		return true;
-	}
-	return false;
-}
-
-function orphanReason(command: string, segments: Segment[]): string | undefined {
+function orphanReason(background: boolean, segments: Segment[]): string | undefined {
 	const message = (via: string) =>
 		`Blocked: this command detaches a process with ${via}, leaving an orphan this session cannot manage — its output and exit status would be lost. ` +
 		"Run it with run_in_background: true instead: it returns a task id immediately, completion arrives as a task notification, output stays readable with task_output, and it can be stopped with task_stop. " +
@@ -204,7 +152,7 @@ function orphanReason(command: string, segments: Segment[]): string | undefined
 	// Only a `wait` that comes LAST reaps the children — `wait; job &` still
 	// orphans the job it precedes.
 	const lastCmd = resolvePayload(leadTokens(segments[segments.length - 1])).command;
-	if (hasBackgroundAmp(command) && lastCmd !== "wait") return message("`&`");
+	if (background && lastCmd !== "wait") return message("`&`");
 	return undefined;
 }
 

package/extensions/bash/index.ts

@@ -5,77 +5,108 @@
  * Registering a tool named `bash` overrides the built-in (findings §2), which
  * is how pi's official sandbox example does it too. The foreground path
  * delegates to pi's real executor (`createBashToolDefinition`) so upstream
- * bash behavior — timeout handling, truncation, PI_* env, spawn hooks — stays
- * exactly pi's; the shared body in lib/shell-tool.ts adds the background
+ * bash behavior — timeout handling, PI_* env, spawn hooks — stays exactly
+ * pi's (its tail cut of a long output is replaced by Claude Code's head-first
+ * one, lib/spill-file.ts); the shared body in lib/shell-tool.ts adds the background
  * branch (spool to `<sessionDir>/bash/<taskId>/output.log`, the shared
  * background registry, a steered completion notification), and this file only
  * supplies what is bash's: pi's definition, the bash the session resolved
  * (lib/shell-spawn.ts — Git Bash on Windows, `CLAUDE_CODE_GIT_BASH_PATH`
- * honoured), the CC-shaped description and the bash guards. The permission
+ * honoured), Claude Code's description (description.ts) and the bash guards. The permission
  * gate and auto-mode classifier run before execute like any bash call — a
  * background command is NOT auto-allowed, and the gate fires before anything
  * detaches.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import type { BashSpawnContext, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createBashToolDefinition, createLocalBashOperations, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { childProcessEnv, LAUNCHER_ENV_VAR } from "../lib/app-launch.mjs";
 import { perCwd } from "../lib/per-cwd.ts";
-import { bashSpawn } from "../lib/shell-spawn.ts";
+import { bashSpawn, piShellEnv, withChildProcessEnv } from "../lib/shell-spawn.ts";
 import { registerShellTool } from "../lib/shell-tool.ts";
+import { type DescriptionForm, followDescriptionForm } from "../lib/tool-variants.ts";
+import { PERMISSION_STATUS_CHANNEL, type PermissionStatus } from "../permissions/modes.ts";
+import { BASH_PARAMS, bashDescription } from "./description.ts";
 import { bashGuardReason } from "./guards.ts";
 
 const BashParams = Type.Object({
-	command: Type.String({ description: "Bash command to execute" }),
-	timeout: Type.Optional(Type.Number({ description: "Optional timeout in milliseconds (max 600000)" })),
-	run_in_background: Type.Optional(
-		Type.Boolean({
-			description:
-				"Run detached and return a task id immediately instead of waiting. Completion arrives as a task notification; inspect with task_output, stop with task_stop. Use this instead of nohup/'&' — those leave an unmanaged orphan process",
-		}),
-	),
-	description: Type.Optional(
-		Type.String({ description: "5-10 word description of what the command does (shown in notifications)" }),
-	),
+	command: Type.String({ description: BASH_PARAMS.command }),
+	timeout: Type.Optional(Type.Number({ description: BASH_PARAMS.timeout })),
+	description: Type.Optional(Type.String({ description: BASH_PARAMS.description })),
+	run_in_background: Type.Optional(Type.Boolean({ description: BASH_PARAMS.run_in_background })),
 });
 
 export default function bashExtension(pi: ExtensionAPI) {
+	bashTool(pi, { announce: true });
+}
+
+/**
+ * The tool itself. `announce: false` is the in-process child's shape
+ * (bash/child.ts): the same tool, but a child has no terminal of its own
+ * (stderr is the parent's TUI), so it prints nothing.
+ */
+export function bashTool(pi: ExtensionAPI, { announce }: { announce: boolean }) {
 	// The session's bash, resolved once (lib/shell-spawn.ts). An ignored
 	// CLAUDE_CODE_GIT_BASH_PATH is reported once, at the first session start.
 	const bash = bashSpawn();
 	const shellPath = bash.spawn?.commandTransport === "stdin" ? undefined : bash.spawn?.shell;
 	let warned = false;
-	pi.on("session_start", (_event, ctx) => {
+	if (announce) pi.on("session_start", (_event, ctx) => {
 		if (warned || !bash.warning) return;
 		warned = true;
 		if (ctx.hasUI) ctx.ui.notify(bash.warning, "warning");
 		else process.stderr.write(`${bash.warning}\n`);
 	});
 
-	// pi's definition supplies the description and TUI renderers; the executor
-	// is re-created per working directory because it closes over cwd (worktree
-	// switches change ctx.cwd mid-session). The same bash drives pi's foreground
+	// pi's definition supplies the TUI renderers; the executor is re-created
+	// per working directory because it closes over cwd (worktree switches
+	// change ctx.cwd mid-session). The same bash drives pi's foreground
 	// executor, so the override applies there too.
-	const base = createBashToolDefinition(process.cwd(), { shellPath });
-	// pi's base sentence is "Optionally provide a timeout in seconds." — but the
-	// `timeout` parameter and the execute path both use milliseconds (Claude
-	// Code's Bash unit; the executor divides by 1000). The two must not
-	// contradict, or a model that trusts the description sends `timeout: 120`
-	// and gets a 120 ms deadline (TOOL-FIDELITY-REVIEW-2026-09-07 H3). Swap in
-	// CC's Bash sentence.
-	const baseDescription = base.description.replace(
-		"Optionally provide a timeout in seconds.",
-		"`timeout` is in milliseconds: default 120000, max 600000.",
-	);
+	// Every command the model runs gets the user's own environment back under
+	// the bundled app (lib/app-launch.mjs), so a `pi` it starts is the user's pi.
+	const spawnHook = (context: BashSpawnContext): BashSpawnContext => ({ ...context, env: childProcessEnv(context.env) });
+	const base = createBashToolDefinition(process.cwd(), { shellPath, spawnHook });
 
-	registerShellTool(pi, {
+	// The description follows the tier and the permission mode. It reaches the
+	// wire only when a request opens an epoch: inside one the ledger keeps the
+	// tools array as recorded (extensions/ledger), so a mode switch never moves
+	// the tool or re-caches the prefix; mode reminders and the live permission
+	// gate carry the change instead.
+	let form: DescriptionForm = "short";
+	// Tiny's dedicated search tools replace the long form's shell-find advice.
+	let searchTools = false;
+	let autoMode = false;
+	const describe = () => bashDescription(form, autoMode, searchTools);
+	const setDescription = registerShellTool(pi, {
 		name: "bash",
 		ccLabel: "Bash",
-		description: `${baseDescription} Pass run_in_background: true for long-running commands (builds, servers, watches): it returns a task id immediately so you can keep working, completion arrives as a task notification, and the output is retrievable with task_output / stoppable with task_stop (both deferred — load them with tool_search; in a one-shot print/json session the call runs to completion and returns the output directly). Foreground \`sleep\` is blocked; to wait on a condition use the monitor tool (deferred — load it with tool_search select:monitor) with an until-loop.`,
+		description: describe(),
 		parameters: BashParams,
 		base,
-		foreground: perCwd((cwd: string) => createBashToolDefinition(cwd, { shellPath })),
+		foreground: perCwd((cwd: string) => createBashToolDefinition(cwd, { shellPath, spawnHook })),
 		guard: bashGuardReason,
 		backgroundShell: () => bash.spawn,
 	});
+	followDescriptionForm(pi, (next, tier) => {
+		form = next;
+		searchTools = tier === "tiny";
+		setDescription(describe());
+	});
+	pi.events.on(PERMISSION_STATUS_CHANNEL, (data) => {
+		const next = (data as PermissionStatus).mode === "auto";
+		if (next === autoMode) return;
+		autoMode = next;
+		setDescription(describe());
+	});
+
+	// The user's own `!` commands, under the bundled app only: pi runs them with
+	// its full process environment, so they get the same restore. Outside the app
+	// pi's default path runs untouched. They run in the session's bash, the one
+	// the bash tool uses.
+	pi.on("user_bash", () => {
+		if (process.env[LAUNCHER_ENV_VAR] === undefined) return undefined;
+		return { operations: withChildProcessEnv(createLocalBashOperations({ shellPath }), () => piShellEnv(join(getAgentDir(), "bin"))) };
+	});
 }

package/extensions/branding/compaction-keep.ts

@@ -0,0 +1,63 @@
+/**
+ * pi's compaction keep window, at startup (lib/compaction-keep.mjs has the
+ * rule and why).
+ *
+ * On the user's own pi, while neither the user's nor the project's settings set
+ * `compaction.keepRecentTokens`, One Code asks once whether to set it to 0 in
+ * the user's settings. "Yes" writes that one key (pi merges nested settings
+ * key by key when it saves its own, so the value survives); pi reads it at
+ * the next start. "No" is remembered in `~/.onecode/settings.json` and never
+ * asked again; Escape asks again next start. An explicit value is the user's
+ * and is never questioned; `/doctor` shows it. The bundled app sets 0 itself.
+ */
+
+import os from "node:os";
+import { join } from "node:path";
+import { type ExtensionContext, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { installKind } from "../doctor/builtins.ts";
+import {
+	compactionKeepView,
+	KEEP_NO,
+	KEEP_YES,
+	keepWindowPrompt,
+	ONE_CODE_KEEP_RECENT_TOKENS,
+	withCompactionKeepBackfilled,
+} from "../lib/compaction-keep.mjs";
+import { readSettingsForWrite, writeSettings } from "../lib/one-code-settings.ts";
+import { tildify } from "../lib/paths.ts";
+import { declined, recordDeclined } from "./declined.ts";
+
+/** `~/.onecode/settings.json` key: the user answered "No" to the question. */
+export const KEEP_DECLINED_KEY = "compactionKeepDeclined";
+
+/** Ask once, when nothing sets the keep window. Never throws. */
+export async function handleCompactionKeep(ctx: ExtensionContext): Promise<void> {
+	try {
+		if (installKind() === "app" || !ctx.hasUI || process.env.CC_COMPACTION === "0") return;
+		if (declined(KEEP_DECLINED_KEY)) return;
+		const agentDir = getAgentDir();
+		const manager = SettingsManager.create(ctx.cwd, agentDir);
+		const modelKey = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+		if (compactionKeepView(manager.getGlobalSettings(), manager.getProjectSettings(), modelKey).source !== "default") return;
+
+		const userPath = join(agentDir, "settings.json");
+		const choice = await ctx.ui.select(keepWindowPrompt(tildify(userPath, os.homedir())), [KEEP_YES, KEEP_NO]);
+		if (choice === KEEP_YES) {
+			const { settings, changed } = withCompactionKeepBackfilled(readSettingsForWrite(userPath));
+			if (changed) writeSettings(userPath, settings);
+			ctx.ui.notify(`Set compaction.keepRecentTokens to ${ONE_CODE_KEEP_RECENT_TOKENS}; /compact works on short sessions from the next start.`, "info");
+		} else if (choice === KEEP_NO) {
+			try {
+				recordDeclined(KEEP_DECLINED_KEY);
+			} catch (error) {
+				ctx.ui.notify(`Could not remember the answer in ~/.onecode/settings.json: ${(error as Error).message}. One Code asks again next start.`, "warning");
+			}
+		}
+	} catch (error) {
+		try {
+			ctx.ui.notify(`Could not set pi's compaction keep window: ${(error as Error).message}. Run /doctor for the settings change.`, "warning");
+		} catch {
+			// The session ended while the dialog was open: nothing is left to tell.
+		}
+	}
+}

package/extensions/branding/declined.ts

@@ -0,0 +1,22 @@
+/**
+ * The startup questions' remembered "No" (replaced-builtins.ts,
+ * compaction-keep.ts): a key set to true in `~/.onecode/settings.json`.
+ */
+
+import os from "node:os";
+import { oneCodeSettingsPath, readSettingsForWrite, writeSettings } from "../lib/one-code-settings.ts";
+
+/** Whether the user answered "No" to the question kept under `key`; a malformed settings file reads as not declined. */
+export function declined(key: string): boolean {
+	try {
+		return readSettingsForWrite(oneCodeSettingsPath(os.homedir()))[key] === true;
+	} catch {
+		return false;
+	}
+}
+
+/** Remember a "No" to the question kept under `key`. */
+export function recordDeclined(key: string): void {
+	const path = oneCodeSettingsPath(os.homedir());
+	writeSettings(path, { ...readSettingsForWrite(path), [key]: true });
+}