one-code-extension 0.4.0 → 0.5.0

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,130 @@
  * 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 { CONTEXT_BASELINE_CHANNEL, restoredContext } from "../lib/context-stack.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 tier follows the model; the permission-mode variant freezes when the
+	// first request starts. Re-registering on a mode switch changes both the
+	// description and pi's tool order, losing the entire cached prefix. Mode
+	// reminders and the live permission gate carry later changes instead.
+	let form: DescriptionForm = "short";
+	// Tiny's dedicated search tools replace the long form's shell-find advice.
+	let searchTools = false;
+	let autoMode = false;
+	let liveAutoMode = false;
+	let modeFrozen = false;
+	const restoredAutoMode = (): boolean | undefined => {
+		const baselines = restoredContext(pi.events)?.baselines;
+		// Older snapshots' last mode chose the last request's description.
+		const saved = baselines?.["bash-auto-mode"];
+		if (typeof saved === "boolean") return saved;
+		return typeof baselines?.["permission-mode"] === "string" ? baselines["permission-mode"] === "auto" : undefined;
+	};
+	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) => {
+		liveAutoMode = (data as PermissionStatus).mode === "auto";
+		if (modeFrozen) return;
+		// Permissions' startup broadcast precedes this extension's session_start.
+		// Honor a restored variant even here: a temporary re-registration would
+		// move the tool despite putting its original description back afterwards.
+		autoMode = restoredAutoMode() ?? liveAutoMode;
+		setDescription(describe());
+	});
+	pi.on("session_start", () => {
+		const saved = restoredAutoMode();
+		modeFrozen = saved !== undefined;
+		autoMode = saved ?? liveAutoMode;
+		setDescription(describe());
+	});
+	pi.on("turn_start", () => {
+		modeFrozen = true;
+		pi.events.emit(CONTEXT_BASELINE_CHANNEL, { key: "bash-auto-mode", value: autoMode });
+	});
+
+	// 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 });
+}

package/extensions/branding/index.ts

@@ -14,6 +14,9 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { ARGUMENT_HINT_CHANNEL, type ArgumentHint, type CommandHint, frontmatterCommandHint, hintForInput, PI_BUILTIN_HINTS } from "../lib/argument-hints.ts";
+import { parseFrontmatterLoosely } from "../lib/frontmatter.ts";
+import { promptTemplateFiles } from "../lib/skill-scan.ts";
 import { modeCycleKey } from "../lib/keys.ts";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
@@ -21,6 +24,8 @@ import { basename, dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, SettingsManager, VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent";
 import { piVersionWarning } from "../lib/pi-version.ts";
+import { handleCompactionKeep } from "./compaction-keep.ts";
+import { handleReplacedBuiltins } from "./replaced-builtins.ts";
 import { extensionVersion } from "../lib/package-version.ts";
 import {
 	formatModel,
@@ -38,9 +43,11 @@ import {
 	shouldDefaultHideThinking,
 	type StartupSection,
 } from "./startup.ts";
-import { linesComponent, safeThemePaint, truncateLine } from "../lib/tui-render.ts";
+import { linesComponent, safeThemeInverse, safeThemePaint, truncateLine } from "../lib/tui-render.ts";
+import { AGENT_VIEW_CHANNEL, type AgentViewAnnouncement, type AgentViewTarget } from "../lib/agent-view.ts";
 import { markAssistantMarkdown } from "./assistant-marker.ts";
 import { PROMPT_PADDING, PromptEditor } from "./prompt-editor.ts";
+import { sanitizeTitle } from "../lib/terminal-text.ts";
 
 export { truncateLine };
 
@@ -138,6 +145,19 @@ export function sectionSummary(sections: StartupSection[], paint: (color: string
 		.join(paint("muted", " · "));
 }
 
+/** The mode line's words for each permission mode, so the banner never says "default" beside "manual mode on". */
+const MODE_WORDS: Record<string, string> = {
+	default: "manual",
+	acceptEdits: "accept edits",
+	bypassPermissions: "bypass permissions",
+	dontAsk: "don't ask",
+};
+
+/** The banner's mode field: the permission display with the mode named as the mode line names it. */
+export function bannerModeLabel(display: string): string {
+	return MODE_WORDS[display] ?? display;
+}
+
 /**
  * Banner layout: the wordmark block, then a one-space-indented text column
  * (tagline + version, context, hints, sections). Kept pure so the layout is
@@ -213,7 +233,11 @@ interface BrandingEditorUI {
  * a pi-tui render change ever makes the marker misplace (cosmetic only — typing
  * is never affected; see prompt-marker.ts).
  */
-function installPromptMarker(ctx: { hasUI: boolean; mode: string; ui: BrandingEditorUI }): void {
+function installPromptMarker(
+	ctx: { hasUI: boolean; mode: string; ui: BrandingEditorUI; isIdle(): boolean; hasPendingMessages(): boolean },
+	argumentHints: ReadonlyMap<string, CommandHint>,
+	agentView: { target?: AgentViewTarget },
+): void {
 	if (process.env.CC_NO_INPUT_MARKER === "1") return;
 	if (!ctx.hasUI || ctx.mode !== "tui") return;
 	const ui = ctx.ui;
@@ -223,7 +247,26 @@ function installPromptMarker(ctx: { hasUI: boolean; mode: string; ui: BrandingEd
 		// Bold makes the chevron read heavier than the input text beside it.
 		return `\x1b[1m${safeThemePaint(ui.theme)("accent", PROMPT_GLYPH)}\x1b[0m${" ".repeat(PROMPT_PADDING - 1)}`;
 	};
-	ui.setEditorComponent((tui: unknown, theme: unknown, keybindings: unknown) => new PromptEditor(tui as never, theme as never, keybindings as never, renderMarker));
+	const renderHint = (text: string) => {
+		// While an agent is viewed the empty editor addresses it (lib/agent-view.ts).
+		const placeholder = text === "" && agentView.target ? agentView.target.placeholder : hintForInput(text, argumentHints);
+		return placeholder === undefined ? undefined : safeThemePaint(ui.theme)("dim", placeholder);
+	};
+	const badge = () => agentView.target?.badge;
+	const paintBadge = (label: string) => safeThemeInverse(ui.theme)(safeThemePaint(ui.theme)("accent", ` ${label} `));
+	// The editor can outlive this context across a session replacement; a stale
+	// context throws, and ↑ must still reach the editor then.
+	const queued = () => {
+		try {
+			return !ctx.isIdle() && ctx.hasPendingMessages();
+		} catch {
+			return false;
+		}
+	};
+	ui.setEditorComponent(
+		(tui: unknown, theme: unknown, keybindings: unknown) =>
+			new PromptEditor(tui as never, theme as never, keybindings as never, renderMarker, renderHint, badge, paintBadge, queued),
+	);
 }
 
 /**
@@ -268,6 +311,25 @@ function applyOutputPadDefault(): void {
 }
 
 export default function brandingExtension(pi: ExtensionAPI) {
+	/**
+	 * pi's merged `quietStartup` (global settings with the project's
+	 * `.pi/settings.json` over them), so the banner and pi agree on whether pi
+	 * lists its own startup sections. `pi.getSettings()` is in pi 1.0.1; a pi
+	 * near the 0.84.3 floor without it falls back to the global file alone.
+	 */
+	const effectiveQuietStartup = (agentDir: string): unknown => {
+		try {
+			if (typeof (pi as { getSettings?: unknown }).getSettings === "function") return pi.getSettings().quietStartup;
+		} catch {
+			// The banner must still install: fall back to the global file.
+		}
+		try {
+			return (JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf8")) as { quietStartup?: unknown }).quietStartup;
+		} catch {
+			return undefined;
+		}
+	};
+
 	applyThinkingDefault();
 	applyOutputPadDefault();
 	// Mark each block of assistant prose with Claude Code's "●" bullet. Only
@@ -296,7 +358,9 @@ export default function brandingExtension(pi: ExtensionAPI) {
 	const retitle = (ctx: { hasUI: boolean; cwd: string; ui: { setTitle(title: string): void } }) => {
 		if (!live || !ctx.hasUI) return;
 		const name = pi.getSessionName?.()?.trim();
-		const title = name ? `${NAME} - ${name} - ${basename(ctx.cwd)}` : NAME;
+		// pi writes the title inside its OSC 0 and strips only CR and LF; a BEL or
+		// ESC in the session name (any source) or the directory would end it early.
+		const title = sanitizeTitle(name ? `${NAME} - ${name} - ${basename(ctx.cwd)}` : NAME);
 		if (title === lastTitle) return; // agent_start fires every turn; write only on change
 		lastTitle = title;
 		ctx.ui.setTitle(title);
@@ -307,18 +371,76 @@ export default function brandingExtension(pi: ExtensionAPI) {
 		live = false;
 	});
 
-	pi.on("session_start", (_event, ctx) => {
+	// Commands' argument placeholders (lib/argument-hints.ts), drawn by the prompt editor.
+	// Declared before the CC_NO_BANNER return below: session_start reads it.
+	const argumentHints = new Map<string, CommandHint>(Object.entries(PI_BUILTIN_HINTS).map(([command, hint]) => [command, { hint }]));
+	// The agent the user is viewing, if any: the editor then targets it (lib/agent-view.ts).
+	const agentView: { target?: AgentViewTarget } = {};
+	pi.events.on(AGENT_VIEW_CHANNEL, (data) => {
+		agentView.target = (data as AgentViewAnnouncement | undefined)?.target;
+	});
+	pi.events.on(ARGUMENT_HINT_CHANNEL, (data) => {
+		const { command, ...hint } = data as ArgumentHint;
+		argumentHints.set(command, hint);
+	});
+	// pi's prompt templates and `/skill:` commands carry their file's
+	// `argument-hint` frontmatter. pi lists them only once a turn resolves them,
+	// so the template folders are scanned at session_start (the skill extension
+	// announces `/skill:` hints from its own scan) and pi's list read each turn.
+	// pi runs a built-in or extension command before a command file of the same
+	// name, so such a file's hint is never read.
+	const hintedFiles = new Set<string>();
+	const readFileHints = (files: { name: string; path: string }[], commands = pi.getCommands()) => {
+		const extensionCommands = new Set(commands.filter((c) => c.source === "extension").map((c) => c.name));
+		for (const { name, path } of files) {
+			if (hintedFiles.has(path)) continue;
+			if (Object.hasOwn(PI_BUILTIN_HINTS, name) || extensionCommands.has(name)) continue;
+			try {
+				const hint = frontmatterCommandHint(parseFrontmatterLoosely(readFileSync(path, "utf-8")).frontmatter);
+				if (hint) argumentHints.set(name, hint);
+				hintedFiles.add(path);
+			} catch {
+				// Unreadable (mid-replace, say): no hint now; a later scan retries it.
+			}
+		}
+	};
+	pi.on("before_agent_start", () => {
+		try {
+			const commands = pi.getCommands();
+			readFileHints(
+				commands.filter((c) => c.source !== "extension").map((c) => ({ name: c.name, path: c.sourceInfo.path })),
+				commands,
+			);
+		} catch {
+			// Not bound (a torn-down session): the next turn looks again.
+		}
+	});
+	pi.on("session_start", (event, ctx) => {
 		// pi's own write lands after this handler, so only the deferred write
 		// sticks; a new session may carry a name (resume), so forget the last.
 		lastTitle = undefined;
 		live = true;
 		setTimeout(() => retitle(ctx), 0).unref?.();
 		ctx.ui.setHiddenThinkingLabel(THINKING_LABEL);
-		installPromptMarker(ctx as unknown as { hasUI: boolean; mode: string; ui: BrandingEditorUI });
+		installPromptMarker(ctx as unknown as Parameters<typeof installPromptMarker>[0], argumentHints, agentView);
+		try {
+			readFileHints(promptTemplateFiles(ctx.cwd, os.homedir(), getAgentDir()));
+		} catch {
+			// Commands not bound: nothing was marked read, so the next turn reads pi's list.
+		}
 		// Soft drift guard: warn once at startup when the hosting pi is outside
 		// the range this release was tested against (see lib/pi-version.ts).
 		const versionWarning = piVersionWarning(PI_VERSION);
 		if (versionWarning) ctx.ui.notify(versionWarning, "warning");
+		// pi 0.99 skips its built-in tool search and MCP for ours and warns at
+		// every start, advising the user to remove One Code: offer to turn them
+		// off once, else answer with the notice (replaced-builtins.ts). Only
+		// when pi resolves its built-ins again (startup, /reload), not on a
+		// /new, resume or fork, which re-run this handler too. Not awaited: a
+		// dialog must not hold up startup. The compaction keep-window question
+		// (compaction-keep.ts) follows it, so the two dialogs never overlap.
+		const reason = (event as { reason?: string }).reason ?? "startup";
+		if (reason === "startup" || reason === "reload") void handleReplacedBuiltins(ctx).then(() => handleCompactionKeep(ctx));
 	});
 
 	if (process.env.CC_NO_BANNER === "1") return;
@@ -363,9 +485,11 @@ export default function brandingExtension(pi: ExtensionAPI) {
 		// instead (minus the internal [Extensions] noise).
 		const home = os.homedir();
 		// Resolve pi's live agent dir (honours PI_CODING_AGENT_DIR) so an
-		// isolated one-code app reads its own settings/skills, never ~/.pi.
+		// isolated one-code app reads its own skills, never ~/.pi.
 		const agentDir = getAgentDir();
-		const sections = quietStartupEnabled(join(agentDir, "settings.json"))
+		// Use pi's effective settings, including project overrides, so the two
+		// listings agree on whether quiet startup is enabled.
+		const sections = quietStartupEnabled(effectiveQuietStartup(agentDir))
 			? collectStartupSections(ctx.cwd, home, join(dirname(fileURLToPath(import.meta.url)), "..", "..", "themes"), agentDir)
 			: undefined;
 
@@ -387,7 +511,7 @@ export default function brandingExtension(pi: ExtensionAPI) {
 							version,
 							model: modelLabel ?? "none",
 							cwd: ctx.cwd,
-							mode: permissionModeDisplay(permissionStatus ?? { mode: "default", paused: false }),
+							mode: bannerModeLabel(permissionModeDisplay(permissionStatus ?? { mode: "default", paused: false })),
 							subagents:
 								modelLabel === undefined
 									? "none"