one-code-extension 0.1.4 → 0.3.0

package/docs/decisions/branding.md

@@ -1,127 +0,0 @@
-# Branding, themes & startup
-
-Part of [Decisions](../decisions.md).
-
-## Branding without a fork
-
-pi's startup banner ("pi v0.83.0 … Ask it how to use or extend Pi") is built from
-its `piConfig`, which resolves from pi's own installed `package.json` — a
-dependent package cannot change it, as recorded in
-[`distribution.md`](distribution.md#distribution-pi-package-not-a-wrapper-binary).
-But `ctx.ui.setHeader()`
-replaces the header component outright, which reaches the same result:
-`extensions/branding/` renders the package name, version, key hints and current
-model/mode instead, and sets the terminal title. `CC_NO_BANNER=1` restores pi's.
-
-Implementation note: a pi-tui `Component` is just `render(width)` plus
-`invalidate()`, so the header is an inline object literal — no dependency on
-pi-tui needed. It only applies when `ctx.mode === "tui"`; print and rpc modes have
-no chrome to replace.
-
-Verified rendering with `test/e2e/tui-capture.sh`:
-
-```
-pi-claude-code v0.1.0  Claude Code on the pi harness
-escape interrupt · ctrl+c/ctrl+d clear/exit · / commands · ! bash · ctrl+o more
-model claude-sonnet-5 · mode default
-```
-
-This is the cosmetic half of what a fork would buy. The other half — the `.pi`
-config directory name — stays as it is; see the integration-shapes section in
-`findings.md` for when that would justify forking.
-
-## Themes: authored, not adopted
-
-The ecosystem has no Claude Code *theme*. What it has are Claude Code-flavoured UI
-**extensions** (`pi-cc-extensions`, `pi-claude-code-tui`, `pi-cc-header`) — code,
-with the dependency risk already declined in the Phase 7 notes.
-
-A pi theme, by contrast, is a JSON file of 51 colour tokens: data, and squarely in
-the "cheaper to own than to depend on" half of the checklist. So `themes/` ships
-two of our own, `claude-code` and `claude-code-light`, declared through
-`pi.themes` in the manifest. The palette is a warm clay accent (`#d97757` dark,
-`#c05f38` light) over neutral surfaces — an approximation of Claude Code's
-terminal look, not values extracted from it.
-
-`test/unit/themes.test.ts` validates every bundled theme: all 51 required tokens
-present, no unknown tokens beyond the two optional ones, every `vars` reference
-resolvable, and colours well-formed. pi rejects an incomplete theme at load time
-without saying which token is missing, so this catches typos before a user does.
-
-Both were then verified with `test/e2e/tui-capture.sh`, which runs pi inside tmux
-to get a real pty: the startup screen lists `[Themes] claude-code,
-claude-code-light` (so `pi.themes` discovery works for an installed package), and
-with the theme selected the clay accent appears as a 24-bit escape in the rendered
-output.
-
-## Rebrand: pincer
-
-Anthropic's branding guidelines (published on the Claude Agent SDK docs, seen
-2026-08) prohibit "Claude Code" product names, Claude Code-mimicking ASCII
-art/visual elements, and products that appear to be Claude Code. They formally
-address SDK partners — which this project is not — but the substance is
-ordinary trademark hygiene and applies to anything published.
-
-What changed (2026-08-05): package `pi-claude-code` → **`pincer-agent`**
-(brand "pincer" — contains *pi*, means *claw*; plain `pincer` is taken on npm
-by an old static file server). Banner `NAME`, system-prompt identity ("You are
-pincer"), MCP client name, and web_fetch User-Agent follow. The banner mascot
-— previously a deliberate homage to Claude Code's — is redrawn as a pixel π,
-which is ours outright. Themes renamed `claude-code`/`claude-code-light` →
-`pincer`/`pincer-light` (users with `"theme": "claude-code"` in pi settings
-must re-select). Event channels renamed `pi-claude-code:*` → `pincer:*` —
-done now, pre-publish, because the channel names are a documented third-party
-contract that would be painful to change later.
-
-What deliberately stays: every *descriptive* reference — "the Claude Code
-experience on the pi harness", "reads your Claude Code settings.json" — is
-nominative use (truthfully naming the thing we are compatible with), which
-trademark law and the guidelines themselves permit. The fidelity references in
-`tools/` and `payload.json` are technical reference data, not branding, and
-are untouched.
-
-## Rebrand: One Code
-
-What changed (2026-08-09): brand **pincer** → **One Code**; npm package
-`pincer-agent` → **`one-code`**. Reason: plainer, more memorable name. Rejected
-alternatives: `pi-code` (taken on npm), `onecode` (taken); `one-code` was free
-and mirrors `claude-code`'s hyphenated npm style. The banner wordmark was
-redrawn as a stacked ANSI-Shadow "ONE" over "CODE" (narrower than the previous
-mark, so it never shears on standard-width terminals — verified live via
-`test/e2e/tui-capture.sh`).
-
-Followed the same surface as the pincer rebrand: banner `NAME`/title/wordmark,
-system-prompt identity ("You are One Code"), MCP client name, `web_fetch`
-User-Agent, themes (`pincer`/`pincer-light` → `one-code`/`one-code-light` —
-users with the old theme selected must re-select), and event channels
-(`pincer:*` → `one-code:*`, locked pre-publish since the channel names are a
-third-party contract). This pass went further than the pincer one and also
-renamed the state directory `~/.pincer` → `~/.one-code`, the env var
-`PINCER_STATE_DIR` → `ONE_CODE_STATE_DIR`, and the internal `pincerStateDir()`
-helper → `oneCodeStateDir()`; existing users lose in-flight plans and hook
-approvals under the old dir, acceptable pre-publish. The GitHub repo was
-renamed `pincer-agent` → `one-code` to match (GitHub keeps a redirect from the
-old path).
-
-What deliberately stays: every *descriptive* "the Claude Code experience"
-reference (nominative use), and the historical records above (the plan
-snapshot, the `pi-claude-code → pincer` history) — rewriting them would falsify
-the record.
-
-## Startup listing: quietStartup + banner sections
-
-pi's startup resource listing has no per-section switch, and its [Extensions]
-section names all twenty of this package's internal modules — noise to an end
-user of the packaged product. The only lever pi offers is `quietStartup: true`
-(global setting), which hides the entire listing but leaves a `setHeader`
-banner alone (verified in tmux). `resourceLoader` is not exposed to
-extensions, so the useful sections cannot be read back; instead the banner
-re-derives compact `context` / `skills` / `themes` lines (the blessed
-re-derive pattern): context files via the git-root walk, skills from the
-Claude Code dirs — `existsSync` on `<dir>/<name>/SKILL.md` rather than
-`isDirectory()`, because skill directories can be symlinks — plus namespaced
-plugin skills from `discoverPlugins` (which pi's own listing misses, since the
-plugins extension exposes those only through the `skill` tool), and themes
-from the package's own directory. The sections render only when
-`quietStartupEnabled()` reads true from pi's settings, so pi's listing and
-ours never both appear.

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

@@ -1,106 +0,0 @@
-# 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

@@ -1,140 +0,0 @@
-# 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

@@ -1,168 +0,0 @@
-# Distribution & dependencies
-
-Part of [Decisions](../decisions.md).
-
-## Two artifacts from one codebase: the app and the package (2026-08-10)
-
-One Code ships two npm packages built from this single repo — **both live on
-npm since 2026-08-10 at 0.1.2** (GitHub release `v0.1.2`):
-
-| npm name | What it is | pi relationship |
-|---|---|---|
-| **`@one-ai/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. The app is scoped under the **`one-ai`** npm org because npm's
-typosquat guard rejects unscoped `one-code` (an existing `onecode` package
-blocks every punctuation variant — discovered only at publish time; a 404 on
-`npm view` does not mean a name is claimable). The *command* the app installs
-is still `one-code`; the extension package stays unscoped so
-`pi install npm:one-code-extension` reads clean, and is attached to the org
-via team access rather than a scope. The npm org (`one-ai`) and the planned
-GitHub org (`oneai-hq` — `one-ai` was taken on GitHub) deliberately differ:
-registry namespaces are independent, install commands only ever cite the npm
-scope, and `repository` fields point at URLs, so the mismatch costs nothing
-beyond a profile cross-link. 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-ai/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).
-
-**Versioning is lockstep.** Both packages share one version per release, even
-when only one changed, and the app pins the extension at exactly its own
-version — so one git tag (`vX.Y.Z`) names the whole release, GitHub Releases
-map one-to-one, and a pin/version mismatch is an instantly visible release
-mistake. Adopted at 0.1.2 (the app skipped 0.1.1 to converge); the cost is an
-occasional republish of an unchanged package. The Homebrew tap is
-`IsuruMaduranga/homebrew-one-ai` — named for the brand umbrella so future
-tools join the same tap — giving `brew install isurumaduranga/one-ai/one-code`
-(two-segment installs are not brew grammar; verified empirically). Two
-release-process facts learned shipping 0.1.2: the formula's `url` + `sha256`
-must be bumped by hand each release until a release workflow automates it,
-and Homebrew's `std_npm_args` passes npm's supply-chain guard
-`--min-release-age=1`, so **the brew install of a release only works ~24h
-after its npm publish** — day-one users get "No matching version found …
-with a date before <now−1d>"; either schedule the formula bump a day after
-the npm publish or accept the gap.
-
-Registering the package also seeds first-run settings (`theme: "one-code"`,
-`quietStartup: true`, and — from 0.1.3 — `tuiMode: "fullscreen"`, the
-alt-screen One Code look per the fullscreen decision in `tui.md`), which
-doubles as skipping pi's stock first-time theme picker — the branded first
-run. Seeded only when no settings file exists, so a user's later changes
-stick. 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)
-
-*(Historical — the release shipped 2026-08-10 as described in the two-artifact
-entry above. The tarball/install checks below were the single-package-era
-method and remain the template for pre-publish verification.)*
-
-`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

@@ -1,64 +0,0 @@
-# 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.