one-code-extension 0.1.0

package/docs/decisions/tools.md

@@ -0,0 +1,407 @@
+# Tools
+
+Part of [Decisions](../decisions.md).
+
+## Tool names stay pi-idiomatic (snake_case)
+
+pi keys its built-in overrides and typed `tool_call` events on `read`, `bash`,
+`edit`, `write`, `grep`, `find`, `ls`. We register custom tools in the same
+style (`todo_write`, `enter_plan_mode`, `subagent`). Users' Claude Code
+permission rules still work: `matcher.ts` maps `Bash`, `Glob`, `WebFetch`,
+`Task`, … onto our names. pi's Anthropic OAuth mode separately renames tools to
+Claude Code's casing on the wire, so nothing is lost there either.
+
+## Deferred tools (ToolSearch)
+
+`extensions/lib/deferred.ts` holds a registry; any extension defers its own
+tools by emitting `pi-claude-code:defer-tool` on the event bus. `tool-search`
+deactivates them at session start, announces the names in an every-turn
+`<system-reminder>` (as Claude Code does), and activates matches additively so
+pi can use native deferred loading.
+
+**Load order is load-bearing:** `tool-search` must appear before any extension
+that defers a tool, because those emit during extension loading and pi's event
+bus only delivers to already-registered listeners. Deferred tools also omit
+`promptSnippet`/`promptGuidelines` — activating a tool that has them rebuilds
+the system prompt and invalidates the cached prefix, defeating the purpose.
+
+Verified on OpenAI (gpt-5.5): after `tool_search`, pi injected native
+`tool_search_call` / `tool_search_output` items at the load point rather than
+appending the schema to the request's tool array, and the model then called the
+tool successfully.
+
+Verified on Anthropic (2026-08-05, API key): both pi-owned paths, with
+request-payload capture. Native (`claude-sonnet-5`, and any
+`supportsToolReferences` model — first-party opus/sonnet/fable ≥5.4-ish, never
+haiku): before activation the deactivated tools are simply absent from
+`tools`; after `tool_search` activates `web_fetch`, the next request carries it
+in `tools` with `defer_loading: true`. Fallback (`claude-haiku-4-5`): the
+activated tool is appended as a full definition, complete `input_schema`, no
+`defer_loading` flag. Both runs completed normally.
+
+## Web tools
+
+**Search — kept as a dependency.** `web_search` comes from **`pi-web-search`**:
+it calls the *current model provider's own* search API (OpenAI/Codex, Anthropic,
+Gemini), so no extra API key and no scraping. At 1,610 lines with **zero runtime
+dependencies**, what it encodes is knowledge — three providers' search API shapes
+— rather than machinery, and tracking those ourselves would be a worse trade.
+It also registers Gemini-only `url_context`. Both tools are deferred.
+
+One coupling to preserve: pi-web-search drives `setActiveTools` to hide
+`url_context` on non-Gemini models. That composes with our deferral **only
+because `tool-search` loads first**, so deferred tools are already deactivated
+when pi-web-search snapshots the active set.
+
+**Fetch — replaced with our own.** `extensions/web-fetch/` (~250 lines) replaces
+`pi-web-access`, which was the heaviest thing in the tree: 21,719 lines, 7.5 MB,
+seven runtime dependencies, and **114 of our then-208 installed packages** — to
+supply one tool we used. Its other three tools were unused, its `web_search` was
+deliberately overridden, and it spawned processes for GitHub cloning, video
+extraction, and reading the browser's cookie store. That is a lot of unreviewed
+surface and startup weight for an HTTP GET.
+
+Ours keeps three focused dependencies (`@mozilla/readability`, `linkedom`,
+`turndown`) because HTML-to-markdown quality genuinely affects what the model
+reads; a regex stripper produces poor input on real documentation. Total install
+went from 208 packages to 109.
+
+Claude Code parity notes for `web_fetch`: http is upgraded to https,
+non-web schemes are refused, responses are cached 15 minutes, and cross-host
+redirects are reported rather than followed (so a redirect cannot quietly take
+the agent elsewhere; same-host ones are followed).
+
+**Deliberate deviation:** Claude Code answers a `prompt` against the page using a
+small fast model. pi exposes no clean in-process completion helper, and a
+summarisation call that fails silently would degrade quality invisibly — the
+exact failure shape we have been removing. Instead the tool returns extracted
+markdown windowed to 30k characters and reports `nextOffset`, so the model reads
+the page itself and can page through a long one.
+
+## AskUserQuestion — our own
+
+`extensions/ask-user/` replaces the community `pi-ask-user`. That package worked
+and had a nicer overlay UI, but it carried two problems:
+
+1. It pulled **`@sinclair/typebox@0.34`** — a second, different schema library,
+   since pi itself uses `typebox@1.x` — and built its tool schema with it. It
+   worked, but two schema implementations in one process is a silent-divergence
+   risk, not a visible one.
+2. It asked **one question per call**, while Claude Code's AskUserQuestion takes
+   up to four questions, each with `header`, optional `multiSelect`, and 2–4
+   labelled options with descriptions.
+
+Ours matches Claude Code's schema and drops the duplicate dependency, at the cost
+of a plainer presentation: pi has no native multi-question widget, so questions
+are asked one dialog at a time via `ctx.ui.select`, with a `✓` marker
+accumulating multi-select choices, a "Done selecting" entry, and an automatic
+"Other (type your own answer)" escape hatch routed to `ctx.ui.input`. Cancelling
+any question cancels the batch, since later answers are meaningless without the
+earlier ones. Non-interactive sessions get an instruction to ask in the reply
+instead.
+
+Verified over RPC: a two-question call produced three dialogs — single-select,
+then multi-select showing `✓ Caching` on the second pass — and returned both
+answers in one structured result.
+
+## web_fetch answers a `prompt` with a reader model
+
+The original deviation ("no clean in-process completion helper; a summariser
+that fails silently degrades quality invisibly") went stale on both halves: the
+auto-mode classifier has been making exactly this call via pi-ai's
+`completeSimple` for months, and the silent-failure objection argues for a
+*loud fallback*, not for omitting the feature. So `web_fetch` now takes Claude
+Code's optional `prompt`, and a reader model answers it against up to 120k
+chars of the page — four times the window the main model would get — returning
+just the answer with a header naming the reader.
+
+The reader reuses the **classifier role profile** rather than adding a third
+curated inventory: summarisation wants the same small-but-capable floor, and
+two lists drifting apart helps nobody. Same containment (the page and the
+query go to the reader, so it never leaves the session's provider/family) and
+the same cost ceiling (never pricier than the session model); with no vetted
+smaller model the session model reads the page itself, which still wins by
+keeping the full page out of the conversation. `reasoning` and `temperature`
+are not sent, for the same fail-closed reasons recorded for the classifier.
+Any reader failure returns the raw windowed markdown with a note naming the
+error — the fetch is never wasted and the degradation is never silent. Page
+content rides in the user message tagged as untrusted data, and the system
+prompt pins the reader to extraction.
+
+Verified live on an OpenAI Codex Sol session (one-shot `--mode json` run with
+`--dangerously-skip-permissions`; the tool's permission surface is unchanged by
+this feature): the reader resolved to `openai-codex/gpt-5.6-luna` via the
+classifier profile, and the tool result read "Answered by
+openai-codex/gpt-5.6-luna from the full page" with a correct answer for the
+fetched page. Typecheck and all 698 unit tests pass.
+
+## Tool errors fail loud, never soft-fallback
+
+A tool's `execute()` handler must, on a malformed / ambiguous / missing-required
+call, return `isError: true` with the **corrective action named** — never a
+plausible-but-wrong success. Reserve a non-error empty result for a genuine
+no-op (an unsupported filetype, an intentionally cleared list), not for "the
+operation failed" or "you called me wrong."
+
+The archetype: `subagent` with run options but no `agent` silently returned the
+agent catalog. A capable model self-corrects from that; a weaker one
+(**observed on deepseek-v4-flash**, 2026-08-07) reads the catalog as a
+non-sequitur, gets stuck, and — worse — invents a wrong cause (it blamed the
+auto-mode gate). The failure mode is general: one response shape serving two
+intents, a real failure reported as success (`isError` unset), or an error
+message that states no next step. All three send a weak model chasing the wrong
+fix.
+
+A read-only audit of every `pi.registerTool` `execute()` (four parallel Sonnet
+agents, one per tool group) found the same family across twelve tools; the
+high/medium set was fixed in one pass:
+
+- **Ambiguous overload** (like the archetype): `skill` (`args` without `skill`),
+  `list_mcp_resources` (bad `server` name read as "no resources"),
+  `enter_worktree` (empty `path` string fell through to *create*).
+- **Silent failure / `isError` unset on a real failure**: `workflow`'s `agent()`
+  swallowed a `WorkflowScriptError` (script-config mistake) into a `null` the way
+  a genuine agent failure resolves — now it rethrows, matching `parallel()` /
+  `pipeline()`; `tool_search` dropped typo'd `select:` names and reported the rest
+  "Loaded", and its zero-match branch was a non-error — now unmatched names are
+  surfaced and a total miss is `isError: true`; `lsp_diagnostics` after a
+  mid-session server *crash* fell through to "install `<command>`" for an
+  already-installed server, and a start failure was reported as a clean "no
+  diagnostics" — now the crash reason is recorded and a recognised-but-unavailable
+  language is an error (only a truly unsupported filetype stays non-error).
+- **Destructive-before-validate**: `schedule_wakeup` cancelled the pending wakeup
+  *before* validating params, so a malformed reschedule silently killed a running
+  `/loop` — validation now runs first and a rejected call leaves the loop intact.
+- **Misleading cause**: `exit_plan_mode` called cold blamed "the plan file is
+  empty" instead of "you're not in plan mode"; `task_update` reported a
+  self-reference as "Unknown task id"; `send_message` to an unstarted run said
+  "No agent named …" in the same words as the catalog, hiding that the fix is to
+  spawn the run first.
+
+Deliberately left for later (logged, not silently dropped): the **lows**
+(`send_message`'s `""`-prefix matching the only run; `monitor`'s unwrapped bad
+`ws.url`; `notebook_edit`'s raw `ENOENT`; `schedule_wakeup`'s silent clamp) and
+two **vendor** gaps outside our code — `pi-web-search` never sets `isError`
+(would need a wrapper in `web/index.ts`), and `mcp/client.ts` swallows
+`listTools`/`listResources` failures into empty arrays.
+
+## Harness discipline (divergences found by self-comparison)
+
+Comparing our implementation against the real Claude Code harness *as observed
+from inside a session* surfaced behaviours that reading a request payload would
+never reveal, because they are enforcement, not prompting.
+
+**File freshness — `extensions/file-tracker/`.** Claude Code refuses to edit a
+file the model has not read, refuses to write over an unread existing file,
+rejects an edit when the file changed after the read, and reports out-of-band
+changes with a line-numbered excerpt. This exists to prevent lost updates, and it
+is why Claude Code can tell the model "do not re-read a file you just edited — the
+harness tracks file state for you". We now do the same.
+
+Tracking is **by content, not by tool call**, which is the load-bearing detail:
+it catches writes made through bash that no tool hook can see. (In the session
+that prompted this, the reminders I received were triggered by my own `python3`
+edits.)
+
+One conflict worth recording, because the first implementation had it backwards:
+announcing an external change must **not** mark the file as read. If the pre-turn
+scan records the new content, the file becomes "fresh" and the stale-edit guard
+stops firing — so the harness would helpfully report the change and then permit
+the clobbering edit. Notifications are tracked separately from reads, purely to
+suppress repeat warnings.
+
+**Denial feedback carries the user's words.** The prompt option says "No, tell the
+agent what to do differently", so it now actually asks, and the typed reason is
+appended to the block reason (`The user said: …`). Previously the option promised
+something the code did not deliver.
+
+**State-driven nudges.** Claude Code injects a reminder when the task tools have
+gone unused. `todo_write` now does the same after eight quiet turns, and also
+flags a list with no `in_progress` item or several of them. A todo tool nobody
+remembers to call is decoration.
+
+**CLAUDE.md framing.** Context files are now introduced with Claude Code's own
+wording — "IMPORTANT: These instructions OVERRIDE any default behavior and you
+MUST follow them exactly as written" — rather than a neutral "project-specific
+instructions" header. Placement still differs deliberately: ours sits in the
+system prompt (via pi), Claude Code's arrives in a first-user-message reminder.
+Ours caches better.
+
+**`context_management` — on by default for first-party Anthropic only.**
+Claude Code sends `clear_thinking_20251015` on every request so long sessions
+stop carrying old reasoning blocks. `extensions/context-management/` does this
+via `before_provider_request`. Default: enabled when the model's provider is
+`anthropic` on `api.anthropic.com` (verified there, and it is what Claude Code
+does); disabled for every other `anthropic-messages` endpoint.
+`CC_CLEAR_THINKING=0` forces it off; `=1` forces it on for an endpoint you
+have confirmed accepts it.
+
+**Enabling for other providers later** — the default is scoped narrowly only
+because these are untested, not because they can't work. What each needs
+before flipping it on:
+
+- **Bedrock**: takes beta flags as `anthropic_beta` (array) *in the request
+  body*, not the `anthropic-beta` header — needs its own request shaping plus
+  a live check that it accepts `context_management` at all.
+- **Vertex**: `anthropic_version` in the body; same question about
+  `context_management` support.
+- **Proxies/gateways (LiteLLM etc.)**: pass-through varies per deployment;
+  users can already opt in per-endpoint with `CC_CLEAR_THINKING=1` once they
+  have confirmed theirs forwards the header and body param.
+
+To extend: broaden `clearThinkingEnabled()` per provider and add the
+endpoint's beta representation next to `anthropicBetas()`; verify with a live
+run using `debug-capture.ts` (remember it logs pre-mutation payloads — confirm
+via absence of the 400, not via the capture).
+
+Verified against the live API (2026-08-05, API key) — the body param alone is
+not enough, found via a curl A/B:
+
+- It requires `anthropic-beta: context-management-2025-06-27`, else 400
+  "context_management: Extra inputs are not permitted".
+- The edit requires thinking enabled or an adaptive-thinking model, else 400
+  "`clear_thinking_20251015` strategy requires `thinking` to be enabled or
+  adaptive" — so the payload hook gates on `payload.thinking` /
+  `compat.forceAdaptiveThinking`.
+- **Header clobber hazard**: an extension's `before_provider_headers` value
+  merges *after* pi's computed headers, replacing pi's own `anthropic-beta`
+  (OAuth identity betas, interleaved thinking for non-adaptive models,
+  fine-grained tool streaming). `anthropicBetas()` therefore rebuilds pi's
+  list (pinned v0.83 logic) and appends ours; OAuth is detected from
+  `~/.pi/agent/auth.json` entry `type`. Re-check on pi upgrades.
+
+Confirmed working end-to-end on `claude-haiku-4-5` (non-adaptive, thinking
+gated) and `claude-sonnet-5` (adaptive): no API errors, normal completions.
+
+Verified end-to-end: an unread-file edit was blocked and the file left untouched;
+after an external edit the stale guard blocked the edit and the change reminder
+reached the model (both visible in the request payload); a declined write
+delivered `The user said: Use append mode instead…`; and the todo nudge appeared
+after ten quiet turns.
+
+**Deliberately not copied:** OS sandboxing (pi's stance is to containerize);
+harness-level command shaping such as blocking foreground `sleep`; background
+agents with task notifications (still Phase 8); and mid-conversation
+`role: "system"` messages, which pi's message types cannot express — our
+user-message reminders are the closest equivalent. (The LLM safety classifier
+that gates bash, once listed here as not copied because it needs a model call
+per command, is now built — see [`auto-mode.md`](auto-mode.md).)
+
+## Tier-aware tool surface: search built-ins for mid/low only (unreviewed)
+
+**Decision.** pi registers `grep`/`find`/`ls` but never activates them (only
+`read`/`bash`/`edit`/`write` are active by default — findings §2). One Code
+activates the three search tools at session start (and on model change) for
+the **mid/low** prompt tiers only; **frontier keeps pi's lean default**
+(`extensions/search-tools/`).
+
+**Why.** Every captured One Code payload carried no search tools while the
+mid/low tier prompts explicitly steer to "the search tools" — instructions
+pointing at tools that did not exist in the request, a weak-model trap.
+Frontier is deliberately different: Claude Code v2.1.81 ships no
+Grep/Glob/LS to frontier models (verified in `tools/eager-tools.json`) —
+bash covers search there, and CC's own frontier prompt keeps only the generic
+"prefer dedicated tools" line. The tier classifier from the prompt-tier
+decision is reused so prompt text and tool surface always agree.
+
+**Rejected.** Activating unconditionally (anti-parity for frontier, wasted
+schema tokens); editing the tier prompts to say "use bash grep" (weaker
+models measurably do better with structured tools, which is why the tiers
+exist).
+
+## Subagent steering: injected catalog, fork hardening (unreviewed)
+
+**Decision.** (a) The agent catalog is injected as an every-turn keyed system
+reminder (`subagent-agents`), and the `subagent` schema descriptions point at
+it; (b) a fork child's task is wrapped in a framing preamble
+(`forkTaskMessage` in `subagents/child.ts`): inherited context is reference
+only, do ONLY the task, the parent's background task ids are not addressable;
+(c) `model`/`thinking` overrides on a fork run are rejected with a corrective
+error.
+
+**Why.** A captured weak-model payload showed the model had no way to know
+agent names without a discovery call (Claude Code injects the agent-type
+list in a system reminder). The fork preamble and override rejection close
+the fork-confabulation incident (docs/handoff-tool-ambiguity.md): a fork on
+`thinking:"minimal"` abandoned its task and continued the inherited topic,
+and the parent read the returned text as independent confirmation. Claude
+Code silently *ignores* `model` for forks; rejection was chosen over silent
+ignoring per the fail-loud convention.
+
+**Rejected.** Renaming `agent` to CC's `subagent_type` (the tool is named
+`subagent`, byte-parity is unreachable, and the pi-idiomatic naming decision
+stands); silently coercing fork overrides (hides the caller's mistake).
+
+## Background bash: override the built-in, gate before detaching (unreviewed)
+
+**Decision.** `extensions/bash/` registers a tool named `bash`, overriding
+pi's built-in (same-name registration — findings §2, the pattern pi's own
+sandbox example uses). Foreground calls delegate to pi's real executor
+(`createBashToolDefinition`, re-created per cwd). `run_in_background: true`
+spawns detached in its own process group, returns a task id, spools to
+`<sessionDir>/bash/<id>/output.log`, and registers a `kind:"bash"`
+`BackgroundTask` — `task_output`/`task_stop` are kind-agnostic and work
+unchanged. Completion notifications carry byte-identical text to
+`task_output`, and legitimately-empty output is explicitly marked
+`(no output — …)`. The permission gate / auto-mode classifier runs before
+execute like any bash call — background bash is **not** auto-allowed, and the
+gate fires before anything detaches (verified live).
+
+**Why / rejected.** Full rationale and the rejected shapes (separate
+`bash_background` tool; generalising `monitor`) in
+[`../plan/background-bash.md`](../plan/background-bash.md), now implemented.
+A separate tool name would diverge from Claude Code's single-Bash shape and
+lose the existing `bash` permission rules for free.
+
+## Deferral runs on all tiers; steering follows CC's channels (2026-08-10)
+
+**Decision.** (a) Tool deferral (ToolSearch) applies on **every** tier, not just
+frontier — the deferred-registry tools are deactivated and listed in the
+deferred-tools reminder regardless of model; core tools (read/edit/write/bash/…)
+never register as deferrable and stay eager. (b) Every harness-injected
+notification shares `lib/notifications.ts`'s anti-confabulation preamble
+(adapted from CC's). (c) MCP servers' `instructions` are injected as an
+every-turn reminder in CC's format instead of being dropped.
+
+**Why (a) reversed.** The original "frontier-only" was justified by a false
+premise — findings §14 wrongly claimed CC ships Haiku all tools eagerly. The raw
+captures (`haiku-4-6.json`, `latest-haiku.json`) show CC defers the long tail on
+Haiku too. And it costs nothing to do everywhere: `pi.setActiveTools` edits
+`agent.state.tools`, which *is* the request tool list, so deactivation omits a
+tool from the wire on **any** provider (OpenRouter/deepseek included) — verified
+live, 35→15 tools on `deepseek-v4-flash-free`. Provider-native deferral
+(Anthropic `defer_loading`, OpenAI `tool_search_call`) is only a cache
+optimization on top; without it, loading a tool mid-session invalidates the
+prompt cache from the tools block down — an accepted tradeoff for cheap models.
+
+**Rejected.** Keeping frontier-only as a deliberate divergence (weak models
+fumble the indirection) — the user chose CC fidelity; the risk is documented and
+revisitable. A One Code-specific notification format (CC's wording is
+field-tested against exactly this hazard).
+
+## CLAUDE.md, memory, and skills injected as the CC reminder stack (2026-08-10)
+
+**Decision.** CLAUDE.md contents, the `MEMORY.md` index, and the skills listing
+are no longer in the system prompt. They ride the first-user-message
+`<system-reminder>` stack, prepended before the user's text in CC's fixed order
+(deferred tools → subagent-models → agents → MCP → skills → `# claudeMd`), via
+placement/order/suffix on the shared reminder queue (`lib/reminders.ts`,
+`CONTEXT_ORDER`). CLAUDE.md + memory + `# userEmail` + `# currentDate` are bundled
+into ONE byte-identical `# claudeMd` block (`extensions/claude-context` +
+`lib/claude-context.ts`); discovery mirrors CC (global + project ancestors, not
+pi's AGENTS.md-first loader). Tier-independent: the block is identical across
+models — only the `# Memory` *spec* in the system prompt varies by tier (already
+handled by `lib/memory.ts`).
+
+**Why (reversed from "stay in the system prompt").** The goal is byte-identity
+with CC's payload, which the user made explicit. CC puts this content in the user
+turn (trust boundary: project/user-authored content isn't in the system role),
+and the diff was visible and real. Injection is transient (pi's `context` event
+runs on a `structuredClone`; the session keeps the clean user message), so
+re-injecting every turn is safe on resume. The claudeMd block reproduces CC's
+exact bytes including the trailing `\n\n` (findings §14).
+
+**Rejected.** Keeping it in the system prompt (the earlier call — abandoned once
+byte-identity became the requirement); a first-message idempotent-prepend without
+the shared queue (the queue already models transient per-turn injection and
+placement generalizes to all five reminders).

package/docs/decisions/tui.md

@@ -0,0 +1,202 @@
+# TUI
+
+Part of [decisions](../decisions.md).
+
+## Compact tool rendering — the Claude Code transcript look (unreviewed)
+
+*2026-08-08.* The transcript was cluttered: every custom tool rendered through
+pi's fallback (bold tool name + full JSON args + full output) inside a heavy
+colored box, harness notifications printed their whole anti-confabulation
+framing to the user, and thinking text was barely distinguishable from answer
+text. Claude Code's transcript shows a one-line call (`● Tool(args)`), a
+collapsed indented result (`⎿ …` + `+N lines (ctrl+o to expand)`), and hides
+model-facing boilerplate.
+
+**What was done:**
+
+- **`extensions/lib/tui-render.ts`** (pure, unit-tested) provides
+  `ccToolRenderers(label, spec?)` — `renderShell: "self"` +
+  `renderCall`/`renderResult` producing the `●`/`⎿` layout with pi's native
+  ctrl+o expansion (`options.expanded`), status-colored bullet
+  (muted → success/error), a primary-arg heuristic for the call line
+  (per-tool `title`/`result` overrides where the heuristic is wrong), and
+  ANSI-aware width truncation on every line (pi-tui crashes on overwide
+  lines — findings §3). Every One Code-registered tool spreads it in; pi's
+  built-ins (read/bash/edit/…) keep their own upstream renderers.
+- **Notifications render compact.** `task-notification`, `wakeup`,
+  `subagent-message`, `subagent-result`, `workflow-result` get
+  `registerMessageRenderer` components: one dim `✳ headline` line collapsed,
+  full body on ctrl+o. The `systemNotification` framing stays in the model
+  payload but is stripped from display (`notificationBody`) — it exists for
+  the model, not the user.
+- **Bash background starts** render `⎿ Running in background (task <id> ·
+  log: …)` instead of the model-facing instruction paragraph; foreground
+  bash delegates to pi's own renderer untouched.
+- **Themes:** `toolPendingBg`/`toolSuccessBg` set to `""` (terminal default —
+  pi maps the empty string to "no background"), which removes the box look
+  for *all* tools including pi built-ins; `toolErrorBg` kept as the one
+  remaining background signal. `thinkingText` moved from `gray` to `grayDim`
+  (240 dark / 245 light) so thinking reads clearly dimmer than answer text —
+  pi already italicizes it, and ctrl+t (`hideThinkingBlock`) remains the
+  user's collapse toggle.
+
+**Rejected:** overriding pi's built-in tool renderers for a bullet-style call
+line on read/grep/etc. — re-registering seven built-ins to restyle them is
+high-risk surgery for marginal polish, and the theme change already de-boxes
+them. Also rejected: hiding notifications entirely (CC-like) — a dim one-liner
+keeps the transcript honest about turn triggers.
+
+## Built-in tools joined the ● language; banner cut to four lines (unreviewed)
+
+*2026-08-08, same session.* With custom tools on `●`/`⎿` and pi's built-ins on
+their own style (`$ cmd`, `edit path`), the transcript spoke two languages —
+the user asked for one (`● Bash(command)`, like Claude Code).
+
+- **`extensions/tool-style/`** overrides read/write/edit/grep/find/ls under
+  their built-in names (the bash-extension mechanism, findings §2). Every
+  model-facing field is passed through byte-identical (system prompt
+  unchanged); execute delegates to a per-cwd instance of pi's real definition
+  (worktree moves). Rendering wraps rather than reimplements —
+  `ccWrapBuiltinRenderers` in the shared lib: `● Label(primary arg)` call
+  line; the **base result component indented under a `⎿` elbow**, so pi's
+  streaming, truncation, and ctrl+o expansion behavior stays upstream's.
+  Edit keeps its own call component (the diff preview a permission decision
+  depends on) with only the header line swapped (`● Update(path)`).
+  Inner components live on `context.state`, never `lastComponent` — base
+  renderers cast `lastComponent` to their concrete classes and would throw.
+  grep/find/ls stay tier-gated: search-tools reconciles the active list on
+  session_start/model_select either way. Bash reuses the same wrapper (in
+  `extensions/bash/`), which also dropped the "Took Ns" timer that counted
+  permission-prompt wait time as command time.
+- **Trap that cost a debugging loop:** a padded Box's "blank" lines carry
+  ANSI paint (`\x1b[49m…`), so `line.trim() === ""` is false — blank-line
+  detection in renderers must strip ANSI first (`isBlankLine`). The stale
+  render looked exactly like a stale jiti cache and wasn't.
+- **Banner** (`extensions/branding/`): three keymap-dump hint lines became
+  one curated line — only the controls a user can't discover (renamed dials,
+  collapsed-state toggles, input prefixes, the ultracode keyword), led by
+  `/hotkeys all keys` so the pointer to everything else survives narrow
+  terminals (`fitItems` drops whole trailing hints instead of cutting
+  mid-word). Sections collapse to one line: names when ≤3 items, counts
+  beyond (a truncated name dump carries no information). Startup warnings
+  point at their commands (`(/lsp for status)`, `(/mcp for status)`), and the
+  LSP one is capped at one line — the full server error stays in `/lsp`.
+
+Verified live: `● Read/Grep/Update/Bash/LS` with `⎿` results, edit's diff
+preview intact before approval, `seq 1 30` showing pi's "(25 earlier lines,
+ctrl+o to expand)" under the elbow, banner at 170 and 80 columns.
+
+## Thinking collapsed by default, expandable with ctrl+t (unreviewed)
+
+*2026-08-08, follow-up to the same complaint.* Even dimmed and italic, visible
+thinking still read as answer narration. pi already has the exact mechanism
+Claude Code uses — `hideThinkingBlock` (persisted global setting, toggled by
+ctrl+t and /settings) collapses each thinking run to a one-line label, and
+`ctx.ui.setHiddenThinkingLabel()` is a public extension API for the label
+text — so One Code adopts it instead of building rendering of its own (assistant
+message rendering is not extension-replaceable anyway).
+
+- **`branding` defaults `hideThinkingBlock: true` exactly once**: only when
+  the key is *absent* from `~/.pi/agent/settings.json` (pure decision helper
+  `shouldDefaultHideThinking` — a present key, either value, is the user's
+  choice and is never overridden; an unparseable file is left alone). Write
+  goes through pi's exported `SettingsManager` (locked merge-write).
+- **Label**: `✻ Thinking… (ctrl+t to expand)`, set on every `session_start`
+  (pi resets it to "Thinking..." on /reload via `resetExtensionUI`).
+- **Timing caveat (finding)**: pi creates its runtime `SettingsManager` — and
+  caches the file in memory — *before* extensions load, so the written default
+  lands from the **next** session; the install session still shows thinking
+  expanded until the user toggles.
+
+Verified live across a restart: first launch writes the key, second session
+renders `✻ Thinking… (ctrl+t to expand)`, ctrl+t expands to the dim italic
+text and back, choice persists.
+
+**Verified live** (tmux capture, deepseek-v4-flash-free): boxless transcript,
+`● Todos(2 items)` / `● Task Output(<id>)` call lines, collapsed results,
+`✳ Background bash … completed. (+2 lines, ctrl+o to expand)` notification,
+ctrl+o expanding/collapsing both, thinking at `38;5;240` italic, no crash at
+170 cols; 789 unit tests green.
+
+## Fullscreen (alt-screen) for Claude Code's clean exit — a setting, not extension code (unreviewed)
+
+Claude Code runs its whole session in the terminal's **alternate screen
+buffer** (`ESC[?1049h` on start, `ESC[?1049l` on exit), so quitting restores
+the terminal to whatever preceded it and CC prints only a one-line resume hint.
+One Code's default looked different: pi's `TuiMainScreen` (inline, main buffer)
+leaves the banner and whole conversation in scrollback after exit.
+
+pi already has the machinery — `TuiAltScreen` (mode `"fullscreen"`), whose
+`.stop()` writes `ESC[?1049l` and then pi prints `To resume this session:
+pi --resume …` (`interactive-mode.ts`). It is gated behind the `tuiMode`
+setting (`"regular"` default vs `"fullscreen"`), marked *experimental* by pi.
+
+**Decision: recommend `tuiMode: "fullscreen"` as the One Code experience, but
+deliver it as a documented user/global setting — not extension code.** The
+renderer is a pi-core startup choice: it is built once from
+`--tui-mode <mode>` (CLI) or `settingsManager.getUiMode()` (settings.json), and
+the live switch (`switchUiMode`) is **private** to pi's `InteractiveMode` with
+no extension-facing hook. A One Code extension therefore cannot set or flip it.
+
+- **Rejected — flip it from an extension:** impossible; no API reaches the
+  renderer, and it is read before/independent of which package loads.
+- **Rejected — One Code writes the user's global settings on load:** invasive
+  (mutating user config the package doesn't own) and it would change plain `pi`
+  everywhere, not just One Code sessions — the setting cannot be scoped to
+  "this package is active."
+- **Chosen — document the toggle.** Set `"tuiMode": "fullscreen"` in
+  `~/.pi/agent/settings.json` (global, per-user; right for a user who always
+  runs One Code), or a project's `.pi/settings.json` (project settings override
+  global — `deepMergeSettings`), or `pi --tui-mode fullscreen` ad-hoc. `/settings
+  → Interface layout → regular` reverts.
+
+**Trade-off (accepted):** alt-screen means the conversation does not persist in
+terminal scrollback after quit — that is the whole point of the clean exit, and
+`pi --resume` covers re-entry.
+
+**Trap this surfaced (finding §10.16):** the setting key was `uiMode` in the
+pinned reference clone (v0.83.0) but was renamed `tuiMode` in installed pi
+(v0.84.1); a `uiMode` key is silently ignored on 0.84.1. Clone re-pinned to
+`v0.84.1` to match.
+
+Set in `~/.pi/agent/settings.json` on 2026-08-10; live clean-exit behavior to be
+confirmed by the user.
+
+## Render memoization: components cache by width (2026-08-10)
+
+pi-tui calls `render(width)` on **every mounted component on every frame**
+(~60fps during streaming, every keystroke; fullscreen mode additionally
+re-measures the full unclipped scrollback to compute scroll height) — findings
+§15. Our `linesComponent` recomputed `build(width)` plus `truncateLine`'s
+per-character ANSI scan on every call, so every historical `●`/`⎿` row taxed
+every frame for the life of the session. Profiled on a 750-entry thread:
+`lib/tui-render.ts` was the largest app-level CPU consumer during typing
+(~0.5s self time per 10s, plus ~1s induced in pi-tui width/wrap utils).
+
+**Decision:** memoize by width inside the component, and rely on the
+factory-per-state-change contract for correctness:
+
+- Any state change (spinner tick, args streaming in, result arriving, expand
+  toggle) makes pi re-invoke `renderCall`/`renderResult`, minting a **fresh
+  component with a fresh cache** — so within one component's lifetime `build`
+  is pure and a `Map<width, lines>` (capped at 4 entries) cannot go stale.
+- `invalidate()` clears the cache — that is the path pi-tui uses for theme
+  swaps and resizes.
+- The `ccWrapBuiltinRenderers` wrappers cache only when the call/result is
+  settled (`!isPartial`): a live base component may stream internally without
+  a factory re-run, so in-flight rows stay uncached.
+- `truncateLine` gained the structural fast path: raw length bounds visible
+  width (escapes only add), so `line.length <= width` returns immediately —
+  the hot path for nearly every line; the scan itself now uses a sticky
+  module-level regex instead of per-character `slice().match()` allocations.
+
+Verified: same typing/scrolling profile after the change — `truncateLine` and
+`tui-render.ts` no longer appear in the top-30 functions at all; remaining
+per-frame cost is pi-tui's own (upstream candidates: `docs/upstream_prs.md`
+#2-#4). Unit tests pin the contract (build-once-per-width, invalidate clears).
+
+**Rule for future renderers:** a component returned from
+`renderCall`/`renderResult`/`registerMessageRenderer` must memoize its
+`render(width)` (use `linesComponent`, or replicate its cache) — an uncached
+component re-renders 60×/s for as long as it is mounted, and the cost
+compounds linearly with thread length.