one-code-extension 0.1.0

package/docs/decisions/code-review-remediation.md

@@ -0,0 +1,106 @@
+# Code review remediation
+
+The first whole-codebase pass of `/simplify` + `/code-review` (2026-08-10), and
+what came of it. Run report-first over the entire source tree (the code had
+never been reviewed). Seven correctness findings were confirmed by an
+independent verify pass; ~22 quality cleanups were applied and the more invasive
+refactors deferred.
+
+## Auto-mode gate hardening: four false "safe" verdicts closed (2026-08-10)
+
+The shell pre-gate's contract is that it may **only ever conclude "safe", never
+deny** — a gap costs one classifier call, never a bypass (see
+[`auto-mode.md`](auto-mode.md)). The review found four commands reaching "safe"
+without their real effect being weighed, plus one allow-rule class skipping the
+classifier entirely:
+
+- **A bare redirect with no command word** (`> /etc/hosts`) — the analyze loop
+  `continue`d on an empty command name before it ever looked at the segment's
+  redirects.
+- **A read-only command's redirect** (`git log > outside.txt`) — the git/cd
+  branches `continue`d before the write-target check ran.
+- **`git -C <dir>`** whose directory escapes the working tree — the global-flag
+  loop skipped `-C` and its value without validating the target.
+- **`sort -o <file>`** — `sort` is fast-pathed as read-only, but `-o` writes an
+  arbitrary path.
+- **`Bash(sh -c *)` / `python -c *` / `node -e *`** allow rules — `isBroadExecutionRule`
+  only recognised `run|exec|x` as a runner's escape hatch, so interpreter
+  inline-code flags matched and returned `allow` without ever reaching the
+  classifier.
+
+**Fix keeps the contract.** Every change converts a false "safe" into an
+escalation — none adds a deny path. The structural fix for the two redirect
+gaps was to lift redirect checks to run **first for every segment** (a shared
+`checkWriteTarget` closure), so no command-specific `continue` can skip a write
+target — deeper than patching the bare-redirect case alone. `git -C`/`--git-dir`/
+`--work-tree` now escalate when their directory leaves the working tree; `sort -o`
+escalates as a write; interpreter `-c`/`-e` flags are treated as broad (which, if
+it over-flags a runner's unrelated `-c`, only costs a classifier call — the safe
+direction). All five are covered by regression tests
+(`test/unit/auto-mode-shell.test.ts`, `test/unit/matcher.test.ts`).
+
+**Live-verified both directions** (2026-08-10, `openai-codex/gpt-5.6-luna` in
+`--permission-mode auto`, `logDecisions` on): plainly-safe commands (`cat`,
+`git status`) resolved on the deterministic pre-gate (`source: pre-gate`), while
+the two newly-covered commands (`sort -o …`, `git -C /etc status`) routed to the
+classifier (`source: classifier`) — i.e. escalated rather than fast-pathed to
+"safe", the fix's whole point. The classifier then allowed both (an in-cwd sort
+and a read-only status are not dangerous); the fix owns the escalation, the
+classifier owns the verdict.
+
+## Worktree vs. permission rules — preserve-original, not reorder (2026-08-10)
+
+A worktree session rewrites bash commands into `cd '<wt>' && (…)` on the
+`tool_call` hook, and worktree loads before permissions, so the gate saw the
+wrapped command — defeating every configured `Bash(...)` allow/ask/deny rule for
+the whole session.
+
+**Chosen: preserve-original.** worktree stashes the model's pre-wrap command on
+`event.input` (`ORIGINAL_COMMAND_KEY`); only rule-matching reads it, while the
+classifier and safety floor keep seeing the wrapped command (whose `cd` makes
+containment resolve inside the worktree).
+
+**Rejected: reorder permissions ahead of worktree** — the mechanism the hooks
+decision used for "matchers see the model's original call"
+([`hooks.md`](hooks.md)). It would have shifted worktree-session protected-path
+containment from the actual write location (the worktree) back to the original
+checkout, a semantic change worse than the bug (which fails toward *more*
+prompting/classifier review — the safe direction).
+
+## Background subagents now get the holistic review (2026-08-10)
+
+Auto mode's third subagent checkpoint — reviewing a finished child's action
+*sequence* as a whole ("read the deploy config, read a token, open a PR") — only
+fired for foreground runs, because it attaches to the spawning call's
+`tool_result`, which a background/resident run has already returned.
+
+**Chosen: review-on-receipt.** Background turns now emit their action sequence;
+the gate reviews it on receipt (shared `reviewCompletedRun`, using the last live
+context) and surfaces any concern as its own follow-up notification, alongside
+the completion report. The foreground path is unchanged; both share one helper.
+
+## Next-turn reminders no longer lost without a user message (2026-08-10)
+
+`reminderQueue.drain()` cleared the next-turn queue unconditionally, but
+`injectReminders` is a no-op when there is no user message to attach to — so a
+`context` event on a user-message-less array silently dropped every pending
+reminder. The gate now only drains once a user message exists, honoring the
+module's own documented re-enqueue contract.
+
+## Quality cleanups, and what was deferred
+
+~22 reuse/dedup/dead-code cleanups were applied; their rationale is the drift
+they remove. Highlights: shared `lib/` helpers (`isWritingTool` hoisted to the
+lower layer, `projectMemoryDir`, `restoreLatestDetails`, `perCwd`,
+`safeThemePaint`, `tryReadFile`, notification-format constants); dead code
+removed (workflow `AgentCallMeta`/`tokenUsage`/`ReplayCursor.totals()`, the
+misleading `readCapped` size branch); two efficiency wins (MCP connect via
+`Promise.allSettled`, `findRoleProfileModel` no longer double-computes
+containment on the classifier hot path). A behavior fix surfaced by the review:
+**`CLAUDE_CONFIG_DIR` is now honored** for CLAUDE.md/skills/commands discovery
+(`claude-context`, `claude-compat`), matching real Claude Code.
+
+**Deferred** as focused follow-ups — internal structure or low value, zero
+correctness impact, high edit-risk to batch here: the `subagents/index.ts`
+`execute()` split and its sibling helpers, background-worktree parallelization,
+the notify-envelope consolidation across five dirs, and a few minor dedups.

package/docs/decisions/compaction.md

@@ -0,0 +1,140 @@
+# Compaction
+
+Part of [Decisions](../decisions.md).
+
+## Compaction runs Claude Code's prompt, via session_before_compact
+
+pi hardcodes its own summarization prompt (settings only expose
+enabled/reserveTokens/keepRecentTokens), but `session_before_compact` lets an
+extension supply the whole `CompactionResult` — so One Code now compacts the
+way Claude Code does. Three design points:
+
+- **The prompt**: appended as user text after the conversation; the model
+  answers `<analysis>` + `<summary>`, and only the `<summary>` content
+  survives. `extractSummary` matches tags at *line starts* and spans to the
+  last closing tag; an untagged reply is used whole minus any analysis block —
+  losing a compaction to a formatting slip is worse than untidy text. Empty
+  means failure. Trap, caught live: the first run's analysis said "wrapped in
+  `<analysis>` and `<summary>` tags", a loose regex anchored on that inline
+  mention, and the stored summary began with the tail of the analysis — prose
+  *about* the format is indistinguishable from the format unless tags are
+  line-anchored.
+- **The model — the session model, for the cache**: Claude Code keeps the
+  session's system prompt, tool definitions, and message prefix intact,
+  appends the instruction, and runs the call on the session's own model. That
+  is not thrift on the model choice — it is thrift on the *tokens*: the
+  summarization call replays the
+  already-cached prefix, so it is mostly cache reads. The extension does the
+  same: session model, `ctx.getSystemPrompt()`, the active tool definitions in
+  active order (a mismatch there costs cache hits, never correctness), and — the
+  key to actually hitting the cache — the session's *last real outgoing
+  messages*, captured from the `context` event (see the cache section below)
+  rather than reconstructed from entries, with the instruction as a
+  final user message: one `<system-reminder>` holding the trigger notice
+  ("the user has triggered a /compact command" vs "the conversation context
+  window is running out") directly above the verbatim instruction, preceded by
+  any `/compact <instructions>` as a "## Compact Instructions" reminder. The
+  stored summary gets a continuation preamble baked in ("This session is being
+  continued from a previous conversation that ran out of context…") plus a
+  pointer to the session JSONL with a NEVER-read-it-whole warning — details
+  the summary lost stay grepable instead of gone, and `read`/`grep` are
+  safe-tier tools, so following the pointer never prompts, auto mode included.
+  All inside pi's own hardcoded `<summary>` frame. A previous compaction's summary lives
+  in the *live* context but is excluded from `messagesToSummarize`
+  (prepareCompaction starts after that entry, handing the text over
+  separately) — it is reattached as the leading `compactionSummary` message,
+  the exact shape the live context carries, so convertToLlm renders the same
+  bytes the cached prefix holds and re-compactions stay cache reads too.
+- **Reasoning mirrors the session's thinking level.** The call sends
+  `reasoning: ctx.thinkingLevel` (with `off`→none). This began as a deliberate
+  omission — `reasoning` fails closed on providers pi's compat data mispredicts,
+  the classifier's documented trade — but that reasoning does not apply here and
+  omitting it turned out to be the last thing keeping the cache cold (see below).
+  Unlike the classifier, compaction runs the *session's own* model, already
+  proven to accept the level, and `streamSimple` clamps an unsupported level down
+  rather than erroring — so mirroring never fails closed. It also restores the
+  extended-thinking behavior for free.
+
+All three reasons (manual, threshold, overflow) take this path; any failure —
+no auth, timeout, empty summary — returns nothing and pi's own compaction
+serves: a different summary style, never a broken compaction. `CC_COMPACTION=0`
+opts out entirely.
+
+Verified live on a Luna session with the final shape: two /compact runs in one
+session (48,356 then 30,838 tokens) both stored fromHook entries — preamble
+first, transcript pointer with the warning, all nine sections, no tag bleed
+(inline backtick *mentions* of the tags in the second summary are content, and
+line-anchored extraction correctly ignored them).
+
+## The cache miss, and the two-part fix (2026-08-07)
+
+For a while the summarization call read `cacheRead: 0` on openai-codex even
+though the surrounding session sat at ~78–96% cache hits. Passing
+`options.sessionId` (pi's prompt_cache_key / session-affinity carrier, which
+completeSimple otherwise omits) was necessary but not sufficient. Two things
+were wrong, both now fixed:
+
+1. **Reconstruction diverged from the cached prefix at message one.** The
+   request was rebuilt from session *entries*, but per-request `<system-reminder>`
+   injections (the memory index, the every-turn reminders) are added at request
+   time and never become entries — so no reconstruction can reproduce them. The
+   fix is *capture, not reconstruct*: a `context`-event listener stashes the
+   exact `AgentMessage[]` the session last handed the provider (a held reference —
+   pi `structuredClone`s the array per turn, and compaction is the last `context`
+   handler, so it is the array actually sent). pi's agent loop builds a request as
+   `transformContext` then `convertToLlm`; running the *same* `convertToLlm` on
+   the captured array makes the message prefix byte-identical, and appending only
+   the instruction leaves that whole prefix a cache read. The entry path survives
+   as a fallback for when no turn has run yet (e.g. `/compact` first thing in a
+   resumed session).
+
+2. **The reasoning config is part of the cache identity.** Even with a
+   byte-identical prefix, `prompt_cache_key`, tools, and system prompt, the
+   request *still* missed — because it omitted `reasoning` while the session's
+   normal requests sent it. On the Responses API that is a different request
+   configuration and the cached prefix is not reused. Found by dumping the last
+   normal payload and the compaction payload and diffing: everything matched
+   except `reasoning`. Fixed by mirroring the session thinking level (above).
+
+Measured after the fix (thinking high, ~48–56k-token context):
+
+| provider / model | before | after |
+|---|---|---|
+| openai-codex `gpt-5.6-luna` | `input 49776, cacheRead 0` | `input 2094, cacheRead 47616` |
+| anthropic `claude-haiku-4-5` | — | `input 10, cacheRead 13042, cacheWrite 44287` |
+| openrouter `deepseek/deepseek-v4-flash` | — | `input 1402, cacheRead 51200` |
+
+openai-codex and deepseek get near-total prefix reuse immediately (automatic
+prefix caching keyed by `prompt_cache_key`, no explicit breakpoints). Anthropic
+needed a third fix. At first it reused only ~13k (≈ system + tools) and re-cached
+the ~44k of history. Two dead-end explanations were ruled out by experiment
+before the real one: it is **not** `cache_control` breakpoint placement (adding
+an explicit anchor on the history's last block changed nothing — still 13k) and
+**not** the reasoning param (identical in both). The confirmed cause, found by
+diffing the compaction wire payload against the session's last normal payload and
+by A/B-ing `CC_CLEAR_THINKING`:
+
+- The `context-management` extension (default-on for first-party Anthropic) puts
+  `context_management: { edits: [clear_thinking_20251015] }` on every agent-loop
+  request plus the `context-management-2025-06-27` beta. So the session's cached
+  **message** prefix is stored in the thinking-cleared form.
+- `completeSimple` bypasses `before_provider_headers`/`before_provider_request`,
+  so the compaction request omitted both — sending full thinking blocks with no
+  `clear_thinking`. On Anthropic that mismatch invalidates the *message* cache
+  (system+tools are unaffected, hence they still read), so the whole history
+  re-caches: cacheRead ~13k, cacheWrite ~44k.
+- Fix: when `clearThinkingEnabled(...)` is true, the compaction call replays the
+  same beta header and `clear_thinking` body edit (reusing context-management's
+  exported helpers), so its message prefix matches the session's cache. Measured
+  after: `input 10, cacheRead 56032, cacheWrite 1460` on `claude-haiku-4-5:high`
+  — near-total reuse, matching the other providers.
+
+So the compaction request must be a faithful replay of the session's request in
+*three* dimensions the naive shape got wrong: the request-time reminder
+injections (capture, not reconstruct), the reasoning config (Responses-API cache
+identity), and — on Anthropic — the context-management beta + `clear_thinking`
+edit. All three providers now produce valid fromHook summaries with near-total
+cache reuse, and none fail-closed. (Any provider-specific request mutation an
+extension adds via `before_provider_*` is invisible to `completeSimple`; a future
+compaction refactor that routed through the same request builder would get these
+for free — a point for the upstream pi PR.)

package/docs/decisions/distribution.md

@@ -0,0 +1,133 @@
+# Distribution & dependencies
+
+Part of [Decisions](../decisions.md).
+
+## Two artifacts from one codebase: the app and the package (2026-08-10, unreviewed)
+
+One Code ships two npm packages built from this single repo:
+
+| npm name | What it is | pi relationship |
+|---|---|---|
+| **`one-code`** (`app/`) | the bundled app — a `one-code` bin | **exact-pins** pi (`0.84.1`) as a dependency |
+| **`one-code-extension`** (repo root) | the pi package | **peerDependency** range; runs on the user's own pi |
+
+The split exists because the two installs need opposite dependency stances
+(reproducible pin vs. ride-the-user's-pi), and nothing else: the app is a thin
+launcher over the same extension set. `one-code-extension` was chosen over
+`one-code-pi`, which reads as "one-code *with* pi bundled" — the opposite of
+what it is. A Homebrew tap (`brew install IsuruMaduranga/one-code/one-code`)
+delivers the same app and solves the Node ≥22.19 requirement via
+`depends_on "node"`; a single compiled binary is not viable (pi-tui ships
+per-platform native modules).
+
+**How the app loads the extensions — package registration, not
+`extensionFactories`.** The bin sets `PI_CODING_AGENT_DIR=~/.one-code/agent`
+(pi's env override for its config dir) and idempotently registers the
+`one-code-extension` directory from its own `node_modules` as a local-path
+package in the isolated `settings.json`, then calls pi's public `main(argv)`.
+pi resolves local-path package sources **in place** (no copying), so the
+manifest drives everything exactly as a `pi install` would: extensions in
+their load-bearing order, `pi.themes`, and the bundled agents (which resolve
+relative to the extension files). The alternative — passing our factories via
+`main(argv, { extensionFactories })` — was prototyped and rejected: it loads
+no themes without extra plumbing, and our extensions are TypeScript that only
+pi's jiti loader handles; a plain Node bin cannot import them. Verified live
+from packed tarballs: themes, agents, permission prompts, session resume, and
+full state isolation (`~/.one-code` created, `~/.pi` untouched, and a stale
+`packages` entry in a user's pi settings cannot double-load us because the
+isolated dir never reads them).
+
+**Version drift is guarded at runtime, not by the peer range.** pi renames
+settings/flags between minors (0.83→0.84: `uiMode`→`tuiMode`, and 0.84 rejects
+the old flag), so the package variant warns at startup when the running pi is
+outside the tested range (`extensions/lib/pi-version.ts`, wired in branding's
+`session_start`; fail-silent on unparseable versions). The app never warns —
+its pin is inside the range by construction. The peer range stays loose
+(`>=0.83.0`); a hard range would make `pi install` fail instead of warn.
+
+**Branding: a surgical stdout rewrite in the bin.** pi prints its own command
+name from `APP_NAME` (fork-gated, resolved from pi's *own* package.json) in
+two plain-stdout places: the post-TUI resume hint and `--help`. Under
+isolation the resume hint `pi --session <id>` is not just mis-branded but
+broken (stock pi cannot see `~/.one-code` sessions), so the bin rewrites
+` pi --session ` → ` one-code --session ` on that line (matched on the label,
+which carries ANSI dim codes) and standalone-word `pi` in help output only.
+Nothing else is touched — TUI escape streams pass through byte-identical.
+Verified: the rewritten resume command actually resumes the session. The real
+fix is an upstream `PI_APP_NAME` env override PR; the rewrite shrinks then.
+
+**Updates: pi's check suppressed, ours added.** The bin sets
+`PI_SKIP_VERSION_CHECK=1` (pi's endpoint is hardcoded to its own registry) and
+injects one inline JS extension (`app/update-check.mjs`) via
+`extensionFactories`: a non-blocking, fail-silent fetch of
+`registry.npmjs.org/one-code/latest` on session start, notifying with an
+install-aware hint (`brew upgrade one-code` when the bin resolves under a
+Homebrew prefix, else `npm i -g one-code`). pi's semver helpers are not
+exported from the package root, so the dotted-numeric compare lives in the
+app. `one-code --version` reports the app version with the pinned pi in
+parentheses. Both paths live-verified (drift warning and update notice each
+fired against a real TUI).
+
+Registering the package also seeds first-run settings (`theme: "one-code"`,
+`quietStartup: true`), which doubles as skipping pi's stock first-time theme
+picker — the branded first run. Three hardcoded `~/.pi` paths found during
+this work (quiet-startup detection, the skills listing, the Anthropic-OAuth
+check) now resolve through pi's `getAgentDir()`, which honours the isolation
+env var.
+
+## Distribution: pi package, not a wrapper binary
+
+*(Partially superseded 2026-08-10 by the two-artifact model above: a wrapper
+**app** now exists alongside the package. What still stands: never fork, and
+the package variant remains first-class.)*
+
+pi's `piConfig` rebranding (app name, config dir) resolves from pi's *own*
+installed `package.json`, so a dependent package cannot rebrand it. Shipping as
+a pi package (`pi install npm:pi-claude-code`) costs nothing extra and keeps
+upstream pi upgrades a version bump away. All Claude-Code-shaped paths
+(`.claude/settings.json`, `.claude/commands`, `.claude/agents`) are discovered
+by our own code rather than by changing pi's `.pi` namespace.
+
+## Community packages: adopted where they work
+
+Per project directive, prefer ecosystem packages over new code.
+
+- **Adopted:** `pi-ask-user` for the AskUserQuestion role (option lists,
+  multi-select, freeform, headless fallback). Bundled as a dependency and
+  re-exported from `extensions/ask-user`, so users get it automatically.
+- **Rejected: `pi-subagents` (0.40.0).** Its child processes were SIGKILLed by
+  the parent ~29 ms after spawn in this environment (macOS, Node 26,
+  pi 0.83.0), in both print and RPC mode, with our extensions absent and the
+  same failure when spawning through an explicit `PI_SUBAGENT_PI_BINARY`
+  wrapper. The identical child command line runs fine standalone, so the fault
+  is in the package's parent-side lifecycle management, not our integration.
+  `extensions/subagents` is therefore our own implementation, modeled on pi's
+  official `examples/extensions/subagent`: spawn `pi --mode json -p`, parse the
+  event stream, return the child's final text. Worth re-evaluating the package
+  on a future release.
+
+## Publish readiness (Phase 7)
+
+`npm pack` produces a 69 kB / 47-file tarball: `extensions/`, `agents/`, `types/`,
+README, LICENSE and `docs/decisions.md`. Every path in the `pi.extensions`
+manifest is checked to be present in the tarball.
+
+**A path install does not fetch dependencies.** Verified by installing the packed
+copy from a directory: pi registered it, then every extension importing a
+dependency failed to load (`Cannot find module '@modelcontextprotocol/sdk/...'`).
+`pi install npm:<name>` is fine, because npm resolves the dependency tree — so
+the README tells anyone installing from a checkout to run `npm install` first.
+
+The published path was verified by simulating its layout: `npm install <tarball>`
+into a scratch project (348 packages resolved), then `pi install
+<scratch>/node_modules/pi-claude-code`. A fresh run listed all bundled and plugin
+agents correctly.
+
+**Portability**: `web_fetch` through `tool_search` was exercised on
+`gpt-5.4`, `gpt-5.5` and `gpt-5.6-terra` — a pre-native-deferred-loading model,
+a native one, and a newer family — all correct. Anthropic's `defer_loading` path
+and the non-native fallback remain unexercised for lack of a credential.
+
+**Declined:** the CC-style UI packages (`pi-cc-header`, `pi-cc-extensions`). They
+are cosmetic and would add a dependency for appearance only, which fails our own
+adopt-vs-build checklist.

package/docs/decisions/hooks.md

@@ -0,0 +1,64 @@
+# Hooks
+
+Part of [Decisions](../decisions.md).
+
+## Hooks: own the mechanism, port the best of three references
+
+Claude Code command hooks were the biggest remaining compat gap — real setups
+carry `PreToolUse`/`PostToolUse`/`UserPromptSubmit` hooks in settings.json and
+plugins ship `hooks/hooks.json`. Three MIT community implementations were
+studied before building (`extensions/hooks/`); none survived as a dependency,
+all three contributed:
+
+- **`pi-code`** (ilovepixelart): the executor hardening — absolute `/bin/sh`,
+  `detached: true` + SIGKILL to the negative pid so grandchildren holding the
+  stdio pipes die with the timeout, utf8 stream decoding, 1MB output caps,
+  `CLAUDE_PROJECT_DIR`, the Node timer-overflow clamp — plus reading real
+  `.claude/settings.json` and the deliberate **ask→block** fail-closed mapping
+  (pi's tool_call is allow-or-block; ask-as-allow is the unsafe reading).
+- **`@hsingjui/pi-hooks`**: the CC JSON envelope parsing, hidden-custom-message
+  context injection, and the Stop-hook loop re-trigger
+  (`deliverAs: "followUp", triggerTurn: true` + a `stop_hook_active`
+  re-entrancy flag). Not adopted as a dependency because it reads
+  `.pi/settings.json` rather than `.claude`, and its bugs were ported *around*:
+  snake_case event aliases, `if` conditions silently disabling non-tool hooks,
+  compact trigger hardcoded to "manual".
+- **`pi-fairy-tales`**: the mtime-keyed config reload (both others only reload
+  at session_start).
+
+Decisions that shaped the wiring:
+
+- **Position in `pi.extensions` is the mechanism** for CC's "hook updatedInput
+  applies before permission evaluation": hooks sits right after
+  system-reminder, ahead of worktree (which rewrites `input.command` into a
+  `cd … && (…)` block — matchers must see the model's original call),
+  file-tracker, and permissions. pi passes the same `event.input` object to
+  every handler, so an in-place mutation is exactly what the gate, safety
+  floor, and classifier evaluate.
+- **A hook can never pre-approve**: `permissionDecision: "allow"` is parsed and
+  ignored. Deny direction is honoured everywhere; timeouts fail closed for
+  PreToolUse/UserPromptSubmit only.
+- **Trust**: project/local hooks are arbitrary code execution, so they run
+  after a once-per-config consent (sha256 of the canonicalised project hook
+  config, persisted in `~/.one-code/hooks/project-approvals.json`; a decline
+  sticks for the session only). pi's own project-trust store was deliberately
+  not reused — it never triggers for repos that have only `.claude/*` files.
+  Plugin hooks are user scope: installing the plugin was the consent.
+- **No loader exemption** (user decision): a hook may block `tool_search`/
+  `skill`/`structured_output`, full CC fidelity — see the foot-gun note in
+  findings.
+- **additionalContext** is a hidden `pi.sendMessage` custom message (persisted,
+  survives resume), not a reminder-queue entry (transient) and not deferred to
+  `before_agent_start` (fires once per outer turn — mid-loop context would
+  arrive a turn late). Mid-loop events use `deliverAs: "steer"`; prompt-time
+  context is stashed and injected at `before_agent_start` so it lands on the
+  same turn as the prompt.
+- **Notification is unsupported**: pi has no event carrying that concept;
+  documented rather than stubbed. `http`/`prompt`/`agent` hook types are
+  skipped with a diagnostic.
+
+Verified live (rpc e2e, no --dangerously-skip-permissions): consent prompt
+shown once; approved run executes the hook, blocks the bash call with the
+hook's stderr as reason, and no permission prompt fires for it (the hook
+short-circuits ahead of the gate); declined run never executes the hook and
+the same call flows to the ordinary permission prompt.

package/docs/decisions/lsp.md

@@ -0,0 +1,58 @@
+# LSP
+
+Part of [Decisions](../decisions.md).
+
+## LSP: our own client, not a package
+
+Originally adopted **`pi-lsp-extension`** (MIT). It worked, but proved fragile in
+four ways, all of which needed workarounds on our side:
+
+1. A stale transitive import (`vscode-languageserver-protocol/node.js`, an export
+   removed in 3.18) had to be pinned with an npm `override`.
+2. Its language servers kept the process alive after the final turn, so `pi -p`
+   **never exited**. We had to gate the whole extension off in one-shot runs,
+   which meant no diagnostics there at all.
+3. Its auto-append hook only fired when a server was *already* running, and
+   servers started lazily on the first file **read** — so an edit as the first
+   action of a session silently produced nothing.
+4. Against TypeScript 7 (whose native compiler dropped `lib/tsserver.js`) the
+   server failed and diagnostics **silently** degraded to tree-sitter syntax
+   checks, with no signal that type checking was gone.
+
+It also carried far more than we need: ~7000 lines and twelve tools, including
+tree-sitter search, a workspace index, completions, and code actions. Claude Code
+has **no** LSP tools — it only receives diagnostics after edits — so eleven of
+those were beyond parity, and their schemas would crowd the prompt.
+
+`extensions/lsp/` is now our own, ~600 lines with **zero dependencies**:
+`protocol.ts` (Content-Length framing), `servers.ts` (language/server/root
+detection, table taken from pi-lsp-extension), `client.ts` (spawn, initialize,
+document sync, diagnostics), `format.ts` (rendering), `index.ts` (wiring).
+Two behaviors only: error diagnostics appended to `edit`/`write` results, and a
+deferred `lsp_diagnostics` tool. Adding hover or definition later is one
+`client.request(...)` each.
+
+Each fragility above is addressed by design:
+
+- **No dependencies**, so no transitive protocol conflicts to pin.
+- Child process and stdio handles are `unref`'d and shut down on
+  `session_shutdown`, so one-shot runs exit — **the argv gate is gone and
+  diagnostics now work in `-p` too**.
+- Content is pushed with `didOpen`/`didChange` before every read, so an edit as
+  the session's first action is covered, and answers reflect current content
+  rather than whatever the server happened to cache.
+- `getDiagnostics` awaits the server's next publish for that document (timeout
+  plus last-known fallback) instead of sleeping a fixed interval.
+- A TypeScript preflight detects the missing `tsserver.js` and returns a
+  sentence explaining it, rather than degrading silently.
+
+Diagnostics are still delivered in the tool result rather than through our
+system-reminder queue: that is where the model needs them, and it costs one
+delivery instead of two.
+
+Verified end-to-end in one-shot mode: an edit introducing a type error appended
+`src/index.ts:5:30 error: Argument of type 'number' is not assignable to
+parameter of type 'string'. (2345) [typescript]` — matching `tsc` — the run
+exited in 16s, no language-server processes leaked, the deferred tool loaded and
+answered on demand, and a TypeScript 7 project returned the preflight
+explanation.

package/docs/decisions/mcp.md

@@ -0,0 +1,104 @@
+# MCP
+
+Part of [Decisions](../decisions.md).
+
+## MCP — our own client on the official SDK
+
+pi ships no MCP support by design, so this is `extensions/mcp/` (~500 lines) on
+top of `@modelcontextprotocol/sdk`. That split is the point: the SDK carries the
+protocol (a genuine standard, worth depending on), and we own the thin part —
+config discovery, namespacing, lifecycle, deferral.
+
+Both community options were rejected on the checklist:
+
+- **`pi-mcp-extension`** still peers on the pre-rename `@mariozechner/pi-*`
+  packages, i.e. it has not been touched since pi moved to Earendil.
+- **`pi-mcp-adapter`** is 19,284 lines with twelve dependencies including a
+  native keyring binding, a browser launcher, and a TOML parser — the same
+  surface-far-past-the-need profile as the packages already removed.
+
+Design notes:
+
+- **Config is Claude Code's format**, merged lowest-to-highest from
+  `~/.claude.json`, then `.mcp.json` walked from cwd up to the repo root
+  (so a monorepo root config applies in subdirectories), then
+  `.claude/settings.local.json`. `$VAR`/`${VAR}` are expanded in commands, args,
+  env, urls and headers. Both stdio (`command`) and remote (`url`) servers work;
+  a `disabled: true` entry *removes* a server inherited from a broader scope.
+- **Tools are namespaced `mcp__<server>__<tool>`**, sanitised to legal tool-name
+  characters, so users' existing Claude Code permission rules match. Verified:
+  a `deny: ["mcp__fixture__add_numbers"]` rule blocked the call.
+- **Every MCP tool is deferred.** A few servers can contribute dozens of tools;
+  putting those schemas in the prompt is what `tool_search` exists to prevent.
+- **JSON Schema is converted to TypeBox explicitly** (`schema.ts`) rather than
+  passing raw schemas through and hoping TypeBox's runtime checks accept them.
+  Unrecognised constructs degrade to permissive types, so an unusual server
+  schema means arguments pass through rather than every call being rejected.
+- Servers connect once at `session_start` (their tool lists are needed before
+  anything can be registered), in parallel, each with a timeout, and close on
+  `session_shutdown`. A failing server is reported by name and does not affect
+  the others.
+
+One bug worth remembering, caught only by the end-to-end test: `resources/read`
+returns resource *contents* (`{uri, mimeType, text|blob}`) — **not** the typed
+content blocks that `tools/call` returns. Running them through the content-block
+formatter yielded `[undefined content]`. They now have their own formatter, which
+also summarises binary blobs instead of dumping base64 into the context.
+
+Verified against a fixture stdio server: `.mcp.json` discovered, tool loaded via
+`tool_search` and called (`mcp__fixture__add_numbers` → `SUM_IS_42`), resources
+listed and read, the deny rule enforced, and the run exited in 16s with no
+lingering processes.
+
+## MCP servers with unset credentials
+
+Found from a real run: the `github` plugin's config is
+`Authorization: "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"`, and with the variable
+unset our expansion produced the literal `"Bearer "`. The server then failed with
+"Authorization header is badly formatted" — a confusing protocol error for what is
+really a missing token.
+
+`missingEnvVars()` now reports variables a config references but that are not set
+(across command, args, env, url and headers), and such servers are **skipped with
+an explanatory message** rather than connected with an empty credential:
+`MCP server "github" failed: not started — GITHUB_PERSONAL_ACCESS_TOKEN not set in
+the environment`.
+
+## Background connect: session_start no longer blocks the prompt (2026-08-10)
+
+The connect ran as an awaited `session_start` handler — and pi awaits every
+extension's `session_start` serially before the interactive input loop opens
+(findings §15). With two remote HTTP servers configured (user-level deepwiki
+plus the context7 plugin), that made the MCP handshake **the entire perceived
+startup**: 4.9s to a usable prompt measured with `PI_STARTUP_BENCHMARK`, of
+which everything-but-mcp was 0.24s.
+
+**Decision:** in the interactive main session, `connectAll` runs in the
+background — `session_start` kicks it off and returns. Tools register as each
+server answers (late registration is what `tool-search` was already built to
+handle for exactly this producer), `/mcp` reports `still connecting` until the
+connect settles, and per-server failures surface through the existing
+notify-on-failure path. Measured after: 501ms to a usable prompt; both remote
+servers connected and registered their tools a few seconds later while the
+session was already live.
+
+Two paths deliberately still **await** the connect:
+
+- **Print-mode one-shots** (`!ctx.hasUI`): the single turn starts immediately
+  and would race past tools that are not registered yet.
+- **Subagent RPC children** (`PI_SUBAGENT_CHILD=1` — they have `hasUI: true`,
+  so the env var is the discriminator): same race, and a child is often
+  spawned specifically to use an MCP tool.
+
+Hardening that came with the change: the background promise is caught (an
+unhandled rejection would crash Node; per-server failures were already
+collected, so the catch only guards setup bugs and surfaces them loud via
+notify), and a connection that lands after `session_shutdown` is closed
+immediately instead of leaking its transport. The MCP SDK import also moved
+into the first `connect()` call — ~70-80ms off every startup, and a session
+with zero configured servers never loads it.
+
+Accepted trade-off: the first turn(s) of an interactive session may run before
+MCP `instructions` reminders and tool registrations exist. The tools are
+deferred behind `tool_search` anyway, so the model discovers them on first
+search after registration.