one-code-extension 0.3.1 → 0.4.1

package/extensions/powershell/description.ts

@@ -0,0 +1,139 @@
+/**
+ * The `powershell` tool's model-facing description: Claude Code's own text
+ * (pure).
+ *
+ * The body is the 2.1.276 capture, byte for byte
+ * (`tools/powershell-tool-2.1.276-macos-pwsh7.json`, locked by
+ * `test/unit/powershell-description.test.ts`); the edition section is the
+ * one slot Claude Code fills per machine — PowerShell 7+ text captured, the
+ * Windows PowerShell 5.1 and unknown-edition texts from the binary's JS
+ * (identical in the reconstructed `PowerShellTool/prompt.ts`). The
+ * "Developer tools verified on this machine's PATH" list Claude Code can add
+ * sits behind a remote flag that was off in the capture, so it is not
+ * reproduced. One Code appends its own short note about the deferred task
+ * tools and the `Start-Sleep` guard, after the captured text, the way the
+ * bash tool does.
+ */
+
+export type PowerShellEditionName = "core" | "desktop" | "unknown";
+
+/** Claude Code's edition sections (binary JS, 2.1.276). */
+export const EDITION_SECTIONS: Record<PowerShellEditionName, string> = {
+	core: `PowerShell edition: PowerShell 7+ (pwsh)
+   - Pipeline chain operators \`&&\` and \`||\` ARE available and work like bash. Prefer \`cmd1 && cmd2\` over \`cmd1; cmd2\` when cmd2 should only run if cmd1 succeeds.
+   - Ternary (\`$cond ? $a : $b\`), null-coalescing (\`??\`), and null-conditional (\`?.\`) operators are available.
+   - Default file encoding is UTF-8 without BOM.`,
+	desktop: `PowerShell edition: Windows PowerShell 5.1 (powershell.exe)
+   - Pipeline chain operators \`&&\` and \`||\` are NOT available — they cause a parser error. To run B only if A succeeds: \`A; if ($?) { B }\`. To chain unconditionally: \`A; B\`.
+   - Ternary (\`?:\`), null-coalescing (\`??\`), and null-conditional (\`?.\`) operators are NOT available. Use \`if/else\` and explicit \`$null -eq\` checks instead.
+   - Avoid \`2>&1\` on native executables. In 5.1, redirecting a native command's stderr inside PowerShell wraps each line in an ErrorRecord (NativeCommandError) and sets \`$?\` to \`$false\` even when the exe returned exit code 0. stderr is already captured for you — don't redirect it.
+   - Default file encoding is UTF-16 LE (with BOM). When writing files other tools will read, pass \`-Encoding utf8\` to \`Out-File\`/\`Set-Content\`.
+   - \`ConvertFrom-Json\` returns a PSCustomObject, not a hashtable. \`-AsHashtable\` is not available.`,
+	unknown: `PowerShell edition: unknown — assume Windows PowerShell 5.1 for compatibility
+   - Do NOT use \`&&\`, \`||\`, ternary \`?:\`, null-coalescing \`??\`, or null-conditional \`?.\`. These are PowerShell 7+ only and parser-error on 5.1.
+   - To chain commands conditionally: \`A; if ($?) { B }\`. Unconditionally: \`A; B\`.`,
+};
+
+/** The captured description with the edition section replaced by a slot. */
+const TEMPLATE = `Executes a given PowerShell command with optional timeout. Working directory persists between commands; shell state (variables, functions) does not.
+
+IMPORTANT: This tool is for terminal operations via PowerShell: git, npm, docker, and PS cmdlets. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.
+
+{{EDITION}}
+
+Before executing the command, please follow these steps:
+
+1. Directory Verification:
+   - If the command will create new directories or files, first use \`Get-ChildItem\` (or \`ls\`) to verify the parent directory exists and is the correct location
+
+2. Command Execution:
+   - Always quote file paths that contain spaces with double quotes
+   - Capture the output of the command.
+
+PowerShell Syntax Notes:
+   - Variables use $ prefix: $myVar = "value"
+   - Escape character is backtick (\`), not backslash
+   - Use Verb-Noun cmdlet naming: Get-ChildItem, Set-Location, New-Item, Remove-Item
+   - Common aliases: ls (Get-ChildItem), cd (Set-Location), cat (Get-Content), rm (Remove-Item)
+   - Pipe operator | works similarly to bash but passes objects, not text
+   - Use Select-Object, Where-Object, ForEach-Object for filtering and transformation
+   - String interpolation: "Hello $name" or "Hello $($obj.Property)"
+   - Registry access uses PSDrive prefixes: \`HKLM:\\SOFTWARE\\...\`, \`HKCU:\\...\` — NOT raw \`HKEY_LOCAL_MACHINE\\...\`
+   - Environment variables: read with \`$env:NAME\`, set with \`$env:NAME = "value"\` (NOT \`Set-Variable\` or bash \`export\`)
+   - Call native exe with spaces in path via call operator: \`& "C:\\Program Files\\App\\app.exe" arg1 arg2\`
+
+Unix commands that DO NOT exist in PowerShell — use the equivalent instead:
+   - head / tail → \`Get-Content file -TotalCount N\` / \`-Tail N\`; piped: \`| Select-Object -First N\` / \`-Last N\`
+   - which → \`(Get-Command name).Source\`
+   - touch → \`if (-not (Test-Path path)) { New-Item -ItemType File path }\` (NEVER use \`New-Item -Force\` on a file — it truncates existing content)
+   - wc -l → \`(Get-Content file | Measure-Object -Line).Lines\`
+   - mkdir -p → \`New-Item -ItemType Directory -Force path\` (\`-p\` is not a PowerShell flag)
+   - rm -rf → \`Remove-Item -Recurse -Force path\`
+   - ln -s → \`New-Item -ItemType SymbolicLink -Path link -Target target\`
+   - chmod / chown → not applicable on Windows; use \`icacls\` only if ACL changes are required
+   - 2>/dev/null → \`2>$null\` (but stderr is captured for you — usually unnecessary)
+   - VAR=x cmd → \`$env:VAR = 'x'; cmd\` (PowerShell has no inline env-var prefix)
+   - Bash control flow (\`if [ -f x ]\`, \`for x in *\`, backtick \`\`cmd\`\` substitution) is a parser error — use \`if (Test-Path x)\`, \`foreach ($x in ...)\`, \`$(cmd)\`
+
+Exit-code note: \`-ErrorAction SilentlyContinue\` suppresses error OUTPUT but the cmdlet failure still causes this tool to report exit 1. To make a cmdlet failure truly non-fatal, promote it to terminating and swallow it: \`try { Cmdlet ... -ErrorAction Stop } catch {}\` (without \`-ErrorAction Stop\`, non-terminating errors skip the \`catch\` and still exit 1).
+
+Interactive and blocking commands (this tool runs with -NonInteractive and stdin attached to the null device — console prompts read EOF or error immediately; GUI prompts can still block until timeout):
+   - NEVER use \`Read-Host\`, \`Get-Credential\`, \`Out-GridView\`, \`$Host.UI.PromptForChoice\`, or \`pause\`
+   - Destructive cmdlets (\`Remove-Item\`, \`Stop-Process\`, \`Clear-Content\`, etc.) may prompt for confirmation. Add \`-Confirm:$false\` when you intend the action to proceed. Use \`-Force\` for read-only/hidden items.
+   - Never use \`git rebase -i\`, \`git add -i\`, or other commands that open an interactive editor
+
+Passing multiline strings (commit messages, file content) to native executables:
+   - Use a single-quoted here-string so PowerShell does not expand \`$\` or backticks inside. The closing \`'@\` MUST be at column 0 (no leading whitespace) on its own line — indenting it is a parse error:
+<example>
+git commit -m @'
+Commit message here.
+Second line with $literal dollar signs.
+'@
+</example>
+   - Use \`@'...'@\` (single-quoted, literal) not \`@"..."@\` (double-quoted, interpolated) unless you need variable expansion
+   - For arguments containing \`-\`, \`@\`, or other characters PowerShell parses as operators, use the stop-parsing token: \`git log --% --format=%H\`
+
+Usage notes:
+  - The command argument is required.
+  - You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands will timeout after 120000ms (2 minutes).
+  - It is very helpful if you write a clear, concise description of what this command does.
+  - If the output exceeds 30000 characters, output will be truncated before being returned to you.
+  - 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.
+  - Avoid using PowerShell to run commands that have dedicated tools, unless explicitly instructed:
+    - File search: Use Glob (NOT Get-ChildItem -Recurse)
+    - Content search: Use Grep (NOT Select-String)
+    - Read files: Use Read (NOT Get-Content)
+    - Edit files: Use Edit
+    - Write files: Use Write (NOT Set-Content/Out-File)
+    - Communication: Output text directly (NOT Write-Output/Write-Host)
+  - When issuing multiple commands:
+    - If the commands are independent and can run in parallel, make multiple PowerShell tool calls in a single message.
+    - If the commands depend on each other and must run sequentially, chain them in a single PowerShell call (see edition-specific chaining syntax above).
+    - Use \`;\` only when you need to run commands sequentially but don't care if earlier commands fail.
+    - DO NOT use newlines to separate commands (newlines are ok in quoted strings and here-strings)
+  - Do NOT prefix commands with \`cd\` or \`Set-Location\` -- the working directory is already set to the correct project directory automatically.
+  - Avoid unnecessary \`Start-Sleep\` commands:
+    - Do not sleep between commands that can run immediately — just run them.
+    - If your command is long running and you would like to be notified when it finishes — simply run your command using \`run_in_background\`. There is no need to sleep in this case.
+    - Do not retry failing commands in a sleep loop — diagnose the root cause or consider an alternative approach.
+    - If waiting for a background task you started with \`run_in_background\`, you will be notified when it completes — do not poll.
+    - If you must poll an external process, use a check command rather than sleeping first.
+    - If you must sleep, keep the duration short to avoid blocking the user.
+  - 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.`;
+
+/** One Code's addendum: where the harness differs from Claude Code's runtime (task tools are deferred, the sleep guard). */
+export const ONE_CODE_ADDENDUM =
+	" A background run returns a task id immediately; 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). A foreground command that LEADS with `Start-Sleep` is blocked; to wait on a condition use the monitor tool (deferred — load it with tool_search select:monitor).";
+
+/** Claude Code's description for the detected edition, verbatim, without One Code's addendum. */
+export function claudeCodePowerShellDescription(edition: PowerShellEditionName): string {
+	return TEMPLATE.replace("{{EDITION}}", EDITION_SECTIONS[edition]);
+}
+
+/** The description the `powershell` tool ships: Claude Code's text plus One Code's addendum. */
+export function powerShellToolDescription(edition: PowerShellEditionName): string {
+	return `${claudeCodePowerShellDescription(edition)}${ONE_CODE_ADDENDUM}`;
+}

package/extensions/powershell/guards.ts

@@ -0,0 +1,91 @@
+/**
+ * Deterministic pre-execution guards for the powershell tool (pure) — the
+ * PowerShell spelling of `bash/guards.ts`'s wait and interactive guards, on
+ * the same shared `leadingSleepReason` core. Steering, not security: the
+ * permission gate and the auto-mode classifier still judge everything that
+ * passes. A guard concludes only on a positive parse, so an unparseable line
+ * always passes through.
+ *
+ * - wait guard (foreground): a line that LEADS with `Start-Sleep` (or its
+ *   `sleep` alias) exists only to wait and stalls the session; a provably
+ *   short sleep (< 2 s) is pacing and passes.
+ * - interactive guard (foreground + background): `Read-Host`, `Get-Credential`,
+ *   `Out-GridView`, `pause` and interactive git open a prompt this
+ *   -NonInteractive shell answers with EOF or an error — the tool description
+ *   already forbids them; the guard makes the refusal instructive.
+ */
+
+import { leadingSleepReason } from "../bash/guards.ts";
+import { gitSubcommand } from "../auto-mode/shell-analysis.ts";
+import { powershellStatements, statementCommand } from "../permissions/powershell-rules.ts";
+
+/** Seconds a `Start-Sleep` statement provably lasts, or undefined when its argument is not a literal. */
+export function startSleepSeconds(statement: string): number | undefined {
+	const tokens = statement.trim().split(/\s+/).slice(1);
+	if (tokens.length === 0) return undefined;
+	let unit: "s" | "ms" = "s";
+	let value: number | undefined;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		const named = /^-(s|sec|seconds|ms|milliseconds)(?::(.+))?$/i.exec(token);
+		if (named) {
+			unit = named[1].toLowerCase().startsWith("m") ? "ms" : "s";
+			const inline = named[2] ?? tokens[++i];
+			if (inline === undefined) return undefined;
+			if (!/^\d+(\.\d+)?$/.test(inline)) return undefined;
+			value = Number(inline);
+			continue;
+		}
+		if (/^-d(uration)?$/i.test(token)) return undefined; // a TimeSpan literal — not modelled
+		if (!/^\d+(\.\d+)?$/.test(token)) return undefined;
+		value = Number(token);
+	}
+	if (value === undefined) return undefined;
+	return unit === "ms" ? value / 1000 : value;
+}
+
+const INTERACTIVE = new Set(["read-host", "get-credential", "out-gridview", "pause"]);
+
+export function powershellGuardReason(command: string, opts: { background: boolean }): string | undefined {
+	const statements = powershellStatements(command);
+	if (!statements || statements.length === 0) return undefined;
+
+	for (const statement of statements) {
+		const cmd = statementCommand(statement);
+		if (INTERACTIVE.has(cmd)) {
+			return (
+				`Blocked: \`${cmd}\` waits on a console or GUI prompt, and this shell runs -NonInteractive with stdin on the null device — it would error or hang until the timeout. ` +
+				"Ask the user with ask_user_question instead, or pass the value on the command line."
+			);
+		}
+		if (cmd === "git") {
+			// `gitSubcommand` skips git's value-taking global flags (`-C <dir>`,
+			// `--git-dir <dir>`, `-c <key=val>`, …) so `git -C X rebase -i` still
+			// finds "rebase" instead of misreading the flag's value as the
+			// subcommand and missing the interactive-editor guard entirely.
+			const words = statement.trim().split(/\s+/).slice(1);
+			const { sub, rest } = gitSubcommand(words.map((value) => ({ value, hadExpansion: false })));
+			const flags = new Set(rest.map((t) => t.value));
+			if (sub === "rebase" && (flags.has("-i") || flags.has("--interactive"))) {
+				return (
+					"Blocked: `git rebase -i` opens an interactive editor, which this shell cannot provide — it would hang until the timeout. " +
+					"Drive it non-interactively instead: `$env:GIT_SEQUENCE_EDITOR = ':'; git rebase …` accepts the todo list as-is, or restructure history with `git rebase --onto`, `git commit --amend`, or `git cherry-pick`."
+				);
+			}
+			if (sub === "add" && ["-i", "--interactive", "-p", "--patch"].some((f) => flags.has(f))) {
+				return (
+					"Blocked: interactive `git add` prompts on a TTY this shell does not have — it would read EOF and stage nothing while appearing to succeed. " +
+					"Stage whole files with `git add <paths>`, or stage a partial change non-interactively with `git apply --cached` and a crafted diff."
+				);
+			}
+		}
+	}
+	if (opts.background) return undefined;
+
+	return leadingSleepReason(
+		statements,
+		(statement) => (statementCommand(statement) === "start-sleep" ? startSleepSeconds(statement) : null),
+		(statement) => statement,
+		{ sleepName: "Start-Sleep", joiner: "; ", untilExample: "while (-not (<check>)) { Start-Sleep 2 }" },
+	);
+}

package/extensions/powershell/index.ts

@@ -0,0 +1,89 @@
+/**
+ * powershell extension — Claude Code's PowerShell tool on top of pi's own
+ * `powershell` built-in (docs/decisions/windows.md, findings §22).
+ *
+ * Registering a tool named `powershell` overrides pi's built-in (findings §2),
+ * exactly as `extensions/bash` overrides `bash`, and the shared body in
+ * lib/shell-tool.ts supplies the `run_in_background` orchestration for both.
+ * The foreground path delegates to pi's real definition
+ * (`createPowerShellToolDefinition`) so schema, cwd handling, truncation and
+ * streaming stay upstream's — with One Code's own `operations`
+ * (lib/shell-spawn.ts), because pi's local operations throw off Windows and
+ * this tool is developed against a `pwsh` on this Mac. The description is
+ * Claude Code's captured text (description.ts); the guards are the PowerShell
+ * spelling of bash's.
+ *
+ * Activation follows Claude Code's gate (policy.ts): pi never activates a
+ * registered override of a built-in name on its own, so `session_start` and
+ * `model_select` reconcile the active list — `powershell` on when the policy
+ * says so, `bash` off when no bash exists (Windows without Git for Windows).
+ * Children get the same reconcile: `openChildSession` binds extensions, which
+ * emits `session_start`.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createPowerShellToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { perCwd } from "../lib/per-cwd.ts";
+import { bashSpawn, createPowerShellOperations, POWERSHELL_UTF8_PREFIX, powerShellEdition, powerShellSpawn } from "../lib/shell-spawn.ts";
+import { registerShellTool } from "../lib/shell-tool.ts";
+import { powerShellToolDescription } from "./description.ts";
+import { powershellGuardReason } from "./guards.ts";
+import { shellToolPolicy, withShellTools } from "./policy.ts";
+
+/** Claude Code's PowerShell schema (captured), minus `dangerouslyDisableSandbox` — One Code has no sandbox to disable. */
+const PowerShellParams = Type.Object({
+	command: Type.String({ description: "The PowerShell command to execute" }),
+	timeout: Type.Optional(Type.Number({ description: "Optional timeout in milliseconds (max 600000)" })),
+	description: Type.Optional(Type.String({ description: "Clear, concise description of what this command does in active voice." })),
+	run_in_background: Type.Optional(Type.Boolean({ description: "Set to true to run this command in the background." })),
+});
+
+export default function powershellExtension(pi: ExtensionAPI) {
+	const spec = powerShellSpawn();
+	const operations = createPowerShellOperations(() => spec);
+	const base = createPowerShellToolDefinition(process.cwd(), { operations });
+	const policy = () =>
+		shellToolPolicy({ platform: process.platform, env: process.env, bash: !!bashSpawn().spawn, powershell: spec !== undefined });
+	const startupPolicy = policy();
+
+	registerShellTool(pi, {
+		name: "powershell",
+		ccLabel: "PowerShell",
+		description: powerShellToolDescription(powerShellEdition(spec)),
+		parameters: PowerShellParams,
+		base,
+		// The guideline joins the system prompt's tool guidelines at registration
+		// (before the first request), so it is part of the cached prefix, never a
+		// mid-session rebuild. Claude Code names PowerShell the primary shell when
+		// the tool is on (2.1.126).
+		promptGuidelines: [
+			...(base.promptGuidelines ?? []),
+			...(startupPolicy.primary === "powershell"
+				? ["PowerShell is the primary shell on this machine: use the powershell tool for terminal operations (git, npm, build tools)"]
+				: []),
+		],
+		foreground: perCwd((cwd: string) => createPowerShellToolDefinition(cwd, { operations })),
+		guard: powershellGuardReason,
+		backgroundShell: () => spec,
+		// The foreground path prepends pi's UTF-8 prefix inside the operations; the background spawn needs it too.
+		wrapBackgroundCommand: (command) => `${POWERSHELL_UTF8_PREFIX}${command}`,
+	});
+
+	let noticesShown = false;
+	const reconcile = (ctx?: Pick<ExtensionContext, "hasUI" | "ui">) => {
+		const current = policy();
+		const active = pi.getActiveTools();
+		const next = withShellTools(active, current);
+		if (next.join(" ") !== active.join(" ")) pi.setActiveTools(next);
+		if (noticesShown || current.notices.length === 0) return;
+		noticesShown = true;
+		for (const notice of current.notices) {
+			if (ctx?.hasUI) ctx.ui.notify(notice, "warning");
+			else process.stderr.write(`${notice}\n`);
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => reconcile(ctx));
+	pi.on("model_select", () => reconcile());
+}

package/extensions/powershell/policy.ts

@@ -0,0 +1,91 @@
+/**
+ * When the `powershell` tool is on, and which shell tool is primary (pure).
+ *
+ * Claude Code's gate (2.1.276 binary function `f0`, findings §22):
+ * `CLAUDE_CODE_USE_POWERSHELL_TOOL` wins wherever it is set — truthy turns the
+ * tool on, `0`/`false` off. Unset: on Windows the tool is on (Git Bash absent
+ * → on by necessity; Git Bash present → on, the claude.ai/Console default the
+ * docs describe — plan §Open questions 1, resolved "on"); off Windows it is
+ * off, so a Mac or Linux user opts in with the same variable Claude Code
+ * uses. When it is on, PowerShell is the primary shell (CC 2.1.126) and bash
+ * stays alongside when a bash exists. A Windows box with neither shell fails
+ * loud at startup in Claude Code's words.
+ */
+
+export type PowerShellSwitch = "on" | "off" | "unset";
+
+/** `CLAUDE_CODE_USE_POWERSHELL_TOOL` as Claude Code reads it: unset/empty → unset, `0`/`false`/`no`/`off` → off, anything else → on. */
+export function powerShellSwitch(env: NodeJS.ProcessEnv): PowerShellSwitch {
+	const raw = env.CLAUDE_CODE_USE_POWERSHELL_TOOL?.trim().toLowerCase();
+	if (raw === undefined || raw === "") return "unset";
+	return ["0", "false", "no", "off"].includes(raw) ? "off" : "on";
+}
+
+export interface ShellAvailability {
+	platform: NodeJS.Platform;
+	env: NodeJS.ProcessEnv;
+	/** A bash resolved (Git Bash on Windows, /bin/bash elsewhere). */
+	bash: boolean;
+	/** A PowerShell resolved (pwsh/powershell.exe on Windows, pwsh on PATH elsewhere). */
+	powershell: boolean;
+}
+
+export type PrimaryShell = "powershell" | "bash" | "none";
+
+export interface ShellToolPolicy {
+	/** The `powershell` tool is active. */
+	powershell: boolean;
+	/** The `bash` tool is active. */
+	bash: boolean;
+	primary: PrimaryShell;
+	/** Startup notices for the user (a set switch with no PowerShell; no shell at all). */
+	notices: string[];
+	/**
+	 * The powershell tool is meant to be on here (the env switch, else Windows),
+	 * whether or not an executable was found. The doctor reports a missing
+	 * PowerShell as needed only when this is true.
+	 */
+	powershellWanted: boolean;
+	/**
+	 * A bash is part of this platform's expected shape: everywhere but Windows,
+	 * where Git for Windows is optional. The doctor's "needed" versus "optional"
+	 * for bash reads this rather than re-deriving the platform rule.
+	 */
+	bashExpected: boolean;
+}
+
+/** Claude Code's own wording for a Windows machine with no shell tool. */
+export const NO_SHELL_NOTICE =
+	"No shell available: install Git for Windows (https://git-scm.com/download/win) so the bash tool can run, " +
+	"or install PowerShell and set CLAUDE_CODE_USE_POWERSHELL_TOOL=1.";
+
+export function shellToolPolicy(a: ShellAvailability): ShellToolPolicy {
+	const sw = powerShellSwitch(a.env);
+	const wanted = sw === "on" ? true : sw === "off" ? false : a.platform === "win32";
+	const powershell = wanted && a.powershell;
+	const notices: string[] = [];
+	if (sw === "on" && !a.powershell) {
+		notices.push(
+			a.platform === "win32"
+				? "CLAUDE_CODE_USE_POWERSHELL_TOOL is set but no pwsh.exe or powershell.exe was found on PATH; the powershell tool stays off."
+				: "CLAUDE_CODE_USE_POWERSHELL_TOOL is set but no `pwsh` was found on PATH; install PowerShell 7 to use the powershell tool.",
+		);
+	}
+	const bash = a.bash;
+	const primary: PrimaryShell = powershell ? "powershell" : bash ? "bash" : "none";
+	if (primary === "none" && a.platform === "win32") notices.push(NO_SHELL_NOTICE);
+	return { powershell, bash, primary, notices, powershellWanted: wanted, bashExpected: a.platform !== "win32" };
+}
+
+/**
+ * The active-tool list adjusted for the policy: `powershell` appended when
+ * on (pi never activates it on its own — a registered override of a built-in
+ * name does not join the active set), removed when off; `bash` removed when
+ * no bash exists (its executor would throw on every call). Existing order is
+ * kept so the rebuilt system prompt stays byte-stable.
+ */
+export function withShellTools(active: string[], policy: Pick<ShellToolPolicy, "powershell" | "bash">): string[] {
+	const next = active.filter((name) => (name === "powershell" ? policy.powershell : name === "bash" ? policy.bash : true));
+	if (policy.powershell && !next.includes("powershell")) next.push("powershell");
+	return next;
+}

package/extensions/recap/index.ts

@@ -25,12 +25,13 @@
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { Api, Model, Tool } from "@earendil-works/pi-ai";
+import type { Api, Model } from "@earendil-works/pi-ai";
 import { completeSimple } from "@earendil-works/pi-ai/compat";
 import { convertToLlm, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { withReasoningFallback } from "../lib/model-policy.ts";
 import { recordUsage } from "../lib/usage-bus.ts";
 import { pickEconomicalContainedModel } from "../lib/model-tier.ts";
+import { answerText, stripImageBlocks, toolStubs } from "../lib/side-call.ts";
 import { dimMarkedLine } from "../lib/tui-render.ts";
 import { RECAP_PROMPT, recapLine, recentForRecap, REFERENCE_MARK } from "./prompt.ts";
 import { RecapScheduler } from "./scheduler.ts";
@@ -38,6 +39,8 @@ import { RecapScheduler } from "./scheduler.ts";
 const ENTRY_TYPE = "one-code:recap";
 const DEFAULT_IDLE_MS = 5 * 60_000; // CC's BLUR_DELAY_MS
 const RECAP_MAX_TOKENS = 256; // 1-3 short sentences
+/** Description on the name-only tool stubs sent with the recap. */
+const STUB_REASON = "Unavailable during this summary; answer in text.";
 const RECAP_TIMEOUT_MS = 30_000;
 
 /** The idle delay before a recap, overridable via CC_RECAP_IDLE_MS (floor 1s). */
@@ -50,22 +53,6 @@ interface RecapData {
 	content: string;
 }
 
-/**
- * Name-only tool declarations: enough for a provider to accept the tool_use
- * blocks already in the history, without the descriptions and schemas (the
- * recap never calls a tool, and its prompt asks for text).
- */
-export function toolStubs(names: readonly string[]): Tool[] {
-	return names.map(
-		(name) =>
-			({
-				name,
-				description: "Unavailable during this summary; answer in text.",
-				parameters: { type: "object", properties: {} },
-			}) as unknown as Tool,
-	);
-}
-
 export default function recapExtension(pi: ExtensionAPI) {
 	pi.registerEntryRenderer<RecapData>(ENTRY_TYPE, (entry, _options, theme) => {
 		const content = entry.data?.content;
@@ -123,10 +110,13 @@ export default function recapExtension(pi: ExtensionAPI) {
 			// blocks stays valid on strict providers (see the header note) without
 			// shipping every full schema (~6k tokens) to a call that must answer
 			// in text.
-			const tools = toolStubs(pi.getActiveTools());
+			const tools = toolStubs(pi.getActiveTools(), STUB_REASON);
 
 			const recent = recentForRecap(messages);
-			const recapMessages = [...convertToLlm(recent), { role: "user" as const, content: RECAP_PROMPT, timestamp: Date.now() }];
+			// The cheap reader may be a text-only model, and the recap does not need
+			// images — strip them so a pasted image or one a Read returned cannot break
+			// the call (docs/decisions/model-policy.md).
+			const recapMessages = [...stripImageBlocks(convertToLlm(recent)), { role: "user" as const, content: RECAP_PROMPT, timestamp: Date.now() }];
 			// Thinking off unless the model cannot disable it; withReasoningFallback
 			// sends a level up front for catalog-marked models and retries on the 400
 			// for the rest. Fires on a 5-min idle timer, so no cross-call memo.
@@ -146,11 +136,7 @@ export default function recapExtension(pi: ExtensionAPI) {
 				);
 			}, undefined, (usage) => recordUsage(pi, "recap", usage));
 			if (controller.signal.aborted) return;
-			const content = result.content
-				.filter((block): block is { type: "text"; text: string } => block.type === "text")
-				.map((block) => block.text)
-				.join("\n")
-				.trim();
+			const content = answerText(result.content);
 			if (!content) return;
 			scheduler.markFired();
 			pi.appendEntry<RecapData>(ENTRY_TYPE, { content });

package/extensions/recap/prompt.ts

@@ -6,6 +6,8 @@
  * prepends is omitted here (kept decoupled from One Code's memory extension).
  */
 
+import { trimToTurnBoundary } from "../lib/side-call.ts";
+
 /** CC's REFERENCE_MARK (figures.ts) — the away-summary/recap marker. */
 export const REFERENCE_MARK = "※";
 
@@ -38,7 +40,5 @@ export function recapLine(content: string): string {
  * `{ role }` so it is testable with plain objects.
  */
 export function recentForRecap<T extends { role: string }>(messages: readonly T[], window = RECENT_MESSAGE_WINDOW): T[] {
-	const tail = messages.slice(-window);
-	const start = tail.findIndex((message) => message.role === "user" || message.role === "assistant");
-	return start === -1 ? [] : tail.slice(start);
+	return trimToTurnBoundary(messages.slice(-window));
 }

package/extensions/session-title/index.ts

@@ -0,0 +1,120 @@
+/**
+ * session-title extension — Claude Code's automatic session name.
+ *
+ * CC names every session once, from the first real user message, with one
+ * small-model call (`utils/sessionTitle.ts` `generateSessionTitle`; the 2.1.278
+ * request is `captures/session_name.json` — findings §14), and shows the name
+ * in the terminal title and the session list. pi has the slot for it —
+ * `pi.setSessionName()`, what `/name` sets: the session picker shows it instead
+ * of the first message, and `session_info_changed` lets the branding extension
+ * retitle the terminal — but never fills it by itself.
+ *
+ * Shape (title.ts holds the strings): the cheapest capable contained model
+ * (pickEconomicalContainedModel — CC's Haiku analog, the same pick the recap
+ * makes), CC's naming instruction as the system prompt, the first prose
+ * wrapped in `<session>` tags, no tools, thinking off, ~a line of output.
+ * Fire-and-forget: the turn never waits for it, a failure names nothing and
+ * does not retry (CC retries on the next message when Haiku returns nothing;
+ * here one attempt per session keeps a broken provider from being hit on
+ * every prompt), and a user's own `/name` is never overwritten. Skipped in
+ * one-shot modes (`-p`, `--mode json`: the process exits at settle, a title
+ * has nowhere to show) and under CC_SESSION_TITLE=0.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { withReasoningFallback } from "../lib/model-policy.ts";
+import { pickEconomicalContainedModel } from "../lib/model-tier.ts";
+import { sessionOutlivesTurn } from "../lib/notifications.ts";
+import { recordUsage } from "../lib/usage-bus.ts";
+import { firstUserText, isNameableText, parseTitle, SESSION_TITLE_PROMPT, sessionTitleInput } from "./title.ts";
+
+const TITLE_MAX_TOKENS = 128; // a noun phrase, with room for a JSON wrapper
+const TITLE_TIMEOUT_MS = 30_000;
+
+export default function sessionTitleExtension(pi: ExtensionAPI) {
+	/** One attempt per session, like CC's `haikuTitleAttemptedRef`. */
+	let attempted = false;
+	let inFlight: AbortController | undefined;
+
+	const reset = () => {
+		attempted = false;
+		inFlight?.abort();
+		inFlight = undefined;
+	};
+
+	// A new session (startup, /clear, a resume, a /tree switch) is a new
+	// naming opportunity; an in-flight request belonged to the old one.
+	pi.on("session_start", reset);
+	pi.on("session_shutdown", reset);
+
+	pi.on("before_agent_start", (event, ctx) => {
+		if (attempted || process.env.CC_SESSION_TITLE === "0") return;
+		if (!sessionOutlivesTurn(ctx.mode)) return;
+		if (pi.getSessionName()) {
+			attempted = true; // the user (or a resume) named it already
+			return;
+		}
+		// CC names after the FIRST user message; on a fresh session that is the
+		// prompt being submitted (not yet in the entries when this fires). That
+		// message never changes, so it is examined once: a first message that is
+		// not prose (a breadcrumb, a slash command sent as text) leaves the
+		// session unnamed rather than re-scanning the entries every turn.
+		attempted = true;
+		const text = firstUserText(ctx.sessionManager.getEntries() as never) ?? event.prompt;
+		if (!isNameableText(text)) return;
+		void generate(text, ctx);
+	});
+
+	async function generate(text: string, ctx: ExtensionContext) {
+		const controller = new AbortController();
+		inFlight = controller;
+		try {
+			const model = ctx.model;
+			if (!model) return;
+			const choice = pickEconomicalContainedModel(ctx.modelRegistry.getAvailable(), model);
+			if (!choice) return;
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(choice.model);
+			if (!auth.ok) return;
+			const baseUrl = (auth as { baseUrl?: string }).baseUrl;
+			const result = await withReasoningFallback(
+				choice.model,
+				(reasoning) => {
+					const timeout = AbortSignal.timeout(TITLE_TIMEOUT_MS);
+					return completeSimple(
+						baseUrl ? ({ ...choice.model, baseUrl } as Model<Api>) : choice.model,
+						{
+							systemPrompt: SESSION_TITLE_PROMPT,
+							messages: [{ role: "user", content: sessionTitleInput(text), timestamp: Date.now() }],
+							tools: [],
+						},
+						{
+							apiKey: auth.apiKey,
+							headers: auth.headers,
+							env: auth.env,
+							signal: AbortSignal.any([controller.signal, timeout]),
+							maxTokens: TITLE_MAX_TOKENS,
+							...(reasoning ? { reasoning } : {}),
+						},
+					);
+				},
+				undefined,
+				(usage) => recordUsage(pi, "session-title", usage),
+			);
+			if (controller.signal.aborted) return;
+			const reply = result.content
+				.filter((block): block is { type: "text"; text: string } => block.type === "text")
+				.map((block) => block.text)
+				.join("\n");
+			const title = parseTitle(reply);
+			// The user may have typed /name while the request was out; theirs wins.
+			if (!title || pi.getSessionName()) return;
+			pi.setSessionName(title);
+		} catch {
+			// Best-effort, like CC: an unnamed session is the only consequence.
+		} finally {
+			if (inFlight === controller) inFlight = undefined;
+		}
+	}
+}