one-code-extension 0.1.3 → 0.3.0

package/docs/decisions/lsp.md

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

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

package/docs/decisions/memory-state.md

@@ -1,170 +0,0 @@
-# Memory & session state
-
-Part of [Decisions](../decisions.md).
-
-## Memory: own file-based implementation
-
-The original plan scoped memory out as "Anthropic-hosted", but the memory
-system Claude Code actually runs on is machine-local plain files the model
-manages itself with ordinary file tools: one fact per markdown file under
-`~/.claude/projects/<slug>/memory/`, a `MEMORY.md` index, a `# Memory` system
-prompt section describing the format, and the index injected into the first
-turn. All of that is local, so we implement it (`extensions/lib/memory.ts` +
-`extensions/memory/`) rather than depend on `pi-memory`, whose model differs
-(its own tools and storage format) and would not read or write Claude Code's
-existing memory directories.
-
-Fidelity details confirmed against the official memory doc
-(<https://code.claude.com/docs/en/memory>), `payload.json`, and a live Claude
-Code context:
-
-- **Slug is keyed by git root, not cwd** — all worktrees and subdirectories of
-  a repo share one memory directory; outside a repo the cwd is used. We resolve
-  with `findGitRoot` (now in `lib/git.ts`).
-- **Only the first 200 lines or 25KB of MEMORY.md load**; `truncateIndex`
-  mirrors that. Topic files are never startup-loaded — the model reads them on
-  demand.
-- **Placement**: Claude Code nests the index inside the first-turn claudeMd
-  `<system-reminder>` ("Contents of … (user's auto-memory, persists across
-  conversations):"). We reuse that exact framing but emit a standalone
-  reminder, because our CLAUDE.md equivalent travels through pi's
-  `contextFiles` into the system prompt instead of a first-turn reminder.
-- **Write-time frontmatter stamping** (found by diffing a real session
-  transcript's Write inputs against the files on disk): Claude Code enriches a
-  memory file's `metadata:` at write time with `node_type: memory`,
-  `originSessionId`, and a `modified` ISO timestamp — and never adds
-  frontmatter to a file that has none, which keeps MEMORY.md unstamped. We
-  stamp by mutating the `write` tool's input in `tool_call`, *before*
-  execution, so the file lands stamped and file-tracker observes the same
-  bytes that hit disk (stamping after its `tool_result` observation would make
-  every memory write look externally modified).
-- **Write-time index limit guard**: after a write/edit of MEMORY.md, Claude
-  Code measures the loadable content against the 200-line/25KB limits —
-  near-limit it reminds the model to shorten the index; over-limit the write
-  succeeds but the result is an error telling the model to rewrite. Replicated
-  via the reminder queue and pi's rewritable `tool_result`.
-
-Not replicated: relevance-based mid-session recall of individual memory files.
-Its selection mechanism is undocumented client internals (the frontmatter
-`description` is "used to decide relevance during recall", and the UI shows
-"Recalled N memories"), and no recalled-memory block has been
-observed in practice — including in a long live session working on this very
-project with a relevant memory on file. There is nothing observable to copy;
-the injected index is the entry point and the model follows links from there.
-
-Split follows the house pattern: pure helpers (slug, paths, truncation,
-prompt/reminder text) in `lib/memory.ts`; the `memory` extension does mkdir +
-first-turn reminder over the queue; `system-prompt` re-derives the directory
-for its section (no shared module state — jiti). Using Claude Code's exact
-slug and layout means memories written by real Claude Code sessions are picked
-up unchanged, and vice versa.
-
-Verified live via tmux + `debug-capture.ts` (the sandboxed shell can't run pi
-directly): the `# Memory` section lands just before `# Environment`, the
-directory is created with the expected slug on session start (from a
-subdirectory of a git repo it resolves to the repo root), and a planted
-`MEMORY.md` arrives as a `<system-reminder>` on the first user message.
-Stamping was verified end-to-end with a real model run through the permission
-gate (allow rules, no bypass flag): the model wrote plain frontmatter and the
-file landed with `node_type`/`originSessionId`/`modified` in Claude Code's
-field order, while MEMORY.md stayed unstamped.
-
-## The memory dir is harness-designated working space, like the plan file
-
-Auto mode blocked the auto-memory feature it ships next to: the system prompt
-instructs the model to write memories into `~/.claude/projects/<slug>/memory`,
-which is both outside the working directory and under the protected `.claude`
-dir, so every memory write went to the classifier and its out-of-project rule
-(correctly, per its own text) blocked it. The harness was flagging its own
-instruction.
-
-The fix follows the plan-file precedent exactly: `decide()` takes a
-`memoryDirPath` and deterministically allows *writing-tool* calls that land
-inside it, with cause `memory-dir`. Scope notes, since this punches through
-the protected-path check:
-
-- Deny rules and explicit ask rules still win — an ask rule is the user's
-  stated intent to be prompted, and the check sits after both.
-- Only the exact per-project dir clears. Another project's memory dir, and
-  everything else under `.claude`, still hits the protected-path check.
-- The check judges `resolvedSubject` when available — where the write actually
-  *lands* — so a symlink planted inside the memory dir cannot convert the
-  allow into a write elsewhere; `resolve()` normalises `..` traversals for the
-  same reason. Bash writes into the dir are not cleared, only the write tools.
-- The permissions extension re-derives the dir (`memoryDir` + `findGitRoot`)
-  rather than sharing state with the memory extension, per the jiti
-  module-isolation rule. The workflow permission gate does the same, since
-  memory writes inside `agent()` calls previously died on "needs interactive
-  approval".
-- Plan mode still denies memory writes (unchanged); the auto-mode safety floor
-  is unaffected — it deliberately targets exact settings files and already
-  documents that `~/.claude` holds memory the agent writes routinely.
-- Trap, caught live: `resolveForContainment` returns a *case-folded* path, so
-  any prefix/equality check against it must case-fold both sides (as
-  `isProtectedPath` does). The first cut compared case-sensitively, matched
-  nothing on macOS, and every memory write silently fell through to the
-  protected-path check — visible only because the live run was checked before
-  committing.
-
-## Session scratchpad, Claude Code-style
-
-Claude Code gives every session a scratchpad
-(`<tmp>/claude-<uid>/<project-slug>/<session-id>/scratchpad`) via a system
-prompt section and lets it be used "generally without permission prompts";
-One Code had nothing, so temp files landed in `/tmp` or the project — and in
-auto mode, `/tmp` writes are exactly the out-of-project pattern the classifier
-flags. Same failure family as the memory-dir block, fixed with the same
-mechanism:
-
-- `lib/scratchpad.ts` derives the path (pure core + `sessionScratchpadDir`
-  re-derived by every consumer, per the jiti module-isolation rule) and
-  carries the prompt section verbatim from `payload.json`. `/tmp` is resolved
-  through its symlink up front so the prompt, the permission comparison, and
-  the case-folded resolved subject all name one real location.
-- The system-prompt extension mkdirs it at `session_start` and renders the
-  section. The path embeds the session id, so it deliberately lives *outside*
-  the (cwd, model)-cached environment block — constant within a session, which
-  is all provider prompt caching needs. An unwritable tmp drops the section
-  rather than promising a directory writes will error on.
-- `decide()` grew a `scratchpadDirPath` beside `memoryDirPath` — one shared
-  `isInsideDir` check (resolved subject, case-folded, traversal-safe), deny
-  and ask rules still winning, other sessions' scratchpads and bare `/tmp`
-  not cleared. The workflow gate derives the *child's* scratchpad lazily from
-  its first tool call, since the child session id does not exist when the
-  gate is constructed.
-- The write tools get the deterministic allow; bash into the scratchpad still
-  goes to the classifier, so the outside-cwd default rule now names the
-  harness's designated directories (scratchpad, auto-memory) as clearing it.
-
-Verified live without `--dangerously-skip-permissions`: a plain `-p` session
-was asked for "a temporary file in the right place per your instructions",
-wrote `notes.txt` into its own session scratchpad path, and the file was on
-disk — no prompt, correct slug and session id. Typecheck and 711 unit tests
-pass.
-
-## Own state, borrowed config: `.claude` is read-only, One Code writes to `~/.one-code`
-
-One Code sat in a three-way namespace muddle: pi owns `~/.pi` (sessions,
-models.json — harness plumbing, invisible, and untouchable without forking),
-`.claude` is Claude Code's directory, and One Code had started *generating*
-state into the latter (plan files at first; memory was already there at
-`~/.claude/projects/<slug>/memory`). Reading `.claude` deeply is the product —
-"your Claude Code setup works on any model" is the pitch, so settings, skills,
-commands, agents, plugins, and CLAUDE.md stay read-from-`.claude` forever. But
-*writing* into a namespace another product owns invites collisions: Claude
-Code also writes under `~/.claude/projects/<slug>/` and evolves that layout
-without notice, and a user auditing "what did Claude Code do" finds artifacts
-it didn't make.
-
-The policy, in one line: **`.claude` is a read-only compat surface; everything
-One Code generates goes to `~/.one-code`.** `extensions/lib/paths.ts` centralises
-both roots — `claudeConfigDir()` (honouring `CLAUDE_CONFIG_DIR`, which Claude
-Code itself supports and One Code previously ignored) and `oneCodeStateDir()`
-(honouring `ONE_CODE_STATE_DIR`). Plan files moved to `~/.one-code/plans`
-immediately, while the feature was a day old. `.one-code` joined the protected
-dirs (the gate's own namespace must be as guarded in its new home as in the
-old), with `.one-code/plans` excepted as working space. Deliberately *not* done:
-a One Code-native settings schema (no demand yet — compat reads suffice), and
-the memory-dir migration, which has a real tradeoff (sharing memory with
-Claude Code on the same repo is arguably a feature) and waits on its own
-decision.

package/docs/decisions/model-policy.md

@@ -1,126 +0,0 @@
-# Model policy
-
-Part of [Decisions](../decisions.md).
-
-## Shared role profiles: smaller classifiers and delegated workers by default
-
-A real OpenAI Codex session exposed two different defaults with the same costly
-result: selecting `gpt-5.6-sol` made the banner read `classifier 5.6-sol
-(planned)` and `subagents 5.6-sol (session)`. The classifier's provider table
-predated Luna and 5.4 Mini, so its deliberate "session before anything chosen
-only by price" fallback did exactly what it should. Subagents had a separate,
-intentional session-model default. Workflow `agent()` had a third path: it
-always received `ctx.model`, so it did not actually honour `/subagent` despite
-the command and reminder saying it did.
-
-The fix is one pure policy layer (`extensions/lib/model-policy.ts`) shared by
-both selectors, but **not one shared capability rule**:
-
-- classifier profiles contain only reviewed small-but-capable families; price
-  alone can never promote a model into the security boundary;
-- subagent profiles prefer economical coding/reasoning models, then may use a
-  cheaper price-ranked model when the provider policy says containment is
-  knowable;
-- explicit classifier, per-call, agent-frontmatter, and `/subagent` choices
-  retain their old precedence and may cross providers because naming one is
-  choosing it; `inherit` explicitly suppresses automatic selection;
-- both roles finish at the session model rather than breaking the feature.
-
-Automatic subagent selection is a *cost optimisation*, and review tightened it
-to demand cost evidence: it engages only when both the session model and the
-candidate carry real prices and the candidate is strictly cheaper. Without that
-rule an unpriced catalog let the profile's order silently *upgrade* a haiku
-session to sonnet-class. The price-ranked fallback (for when the profile has
-gone stale) additionally requires one of the known small-model name words and
-ranks those tiers ahead of raw price — otherwise the absolute cheapest
-contained model became the default coding worker, which on a mainstream catalog
-is nano/lite-tier or something wholly unknown. And once any *explicit* choice
-(agent frontmatter or configured default) fails to resolve, automatic selection
-stays out of it: substituting a cheaper vetted model for a model somebody named
-is a model nobody described, so the remaining chain and then the session model
-serve.
-
-The profile inventory was checked on 2026-08-06 against pi 0.84.0's generated
-catalog and official model pages: [Anthropic](https://platform.claude.com/docs/en/about-claude/models/overview),
-[OpenAI](https://developers.openai.com/api/docs/models),
-[Google](https://ai.google.dev/gemini-api/docs/models),
-[xAI](https://docs.x.ai/developers/models),
-[Mistral](https://docs.mistral.ai/getting-started/models/models_overview/),
-[DeepSeek](https://api-docs.deepseek.com/quick_start/pricing),
-[Z.AI](https://docs.z.ai/), [Qwen Coding Plan](https://help.aliyun.com/en/model-studio/coding-plan),
-[Kimi](https://platform.kimi.ai/docs/models),
-[MiniMax](https://platform.minimax.io/docs/guides/models-intro),
-[Xiaomi](https://mimo.mi.com/docs/quick-start/summary/model), and
-[Ant Ling](https://developer.ant-ling.com/en/docs/models/ling/). Hosted-profile
-IDs came from the official catalogs for [NVIDIA NIM](https://build.nvidia.com/models),
-[Groq](https://console.groq.com/docs/models),
-[Cerebras](https://inference-docs.cerebras.ai/models/overview),
-[Fireworks](https://fireworks.ai/models),
-[Together](https://docs.together.ai/docs/serverless/models),
-[Baseten](https://www.baseten.co/products/model-apis/), and
-[Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/models/).
-The lists are intentionally short prefixes applied to the *live authenticated
-catalog*, not copied catalogs; unavailable entries simply fall through.
-
-All 39 built-in pi language-model provider IDs have an explicit policy. Direct
-vendors contain to the provider. Stable hosted inference services such as Groq
-and NVIDIA contain to that host even when IDs carry publisher-like prefixes.
-Gateways require more care:
-
-- OpenRouter's `creator/model` prefix identifies a model namespace, **not the
-  serving inference provider**; automatic switching stays in that namespace and
-  reuses its direct-family profile, but One Code cannot claim processor
-  containment because pi exposes none of OpenRouter's provider-routing options
-  ([official routing semantics](https://openrouter.ai/docs/guides/routing/provider-selection)).
-- Vercel likewise separates creator IDs from serving providers; profile reuse
-  stays in the creator namespace ([provider options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options)).
-- Cloudflare's generated pi catalog strips some upstream prefixes, so route
-  identity comes from API/base transport rather than slash parsing
-  ([provider integrations](https://developers.cloudflare.com/ai-gateway/providers/)).
-- Bedrock containment includes geography plus family: an automatic choice may
-  not move from `us.` to `eu.` or `global.`. Opaque application-profile ARNs
-  stay on the session model ([model IDs](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html)).
-- Hugging Face, Radius, OpenCode Zen, OpenCode Go, unknown aliases, and custom
-  providers whose route cannot be established are session-only automatically.
-  Hugging Face repository IDs in particular do not name the serving inference
-  provider unless a provider suffix is pinned
-  ([routing docs](https://huggingface.co/docs/inference-providers/en/index)).
-
-With no explicit default, an OpenAI Codex Sol session now plans both its
-classifier and delegated workers on Luna. The banner labels the latter `(auto)`
-rather than implying it came from settings. `workflow/index.ts` passes the same
-user/managed default into `AgentRunner`, and workflow calls no longer bypass
-the automatic resolver when `model` is omitted.
-
-Verified against fresh pi processes: the TUI banner showed `model 5.6-sol ·
-subagents 5.6-luna (auto)`; an omitted-model foreground subagent recorded
-`openai-codex/gpt-5.6-luna`; and an omitted-model synchronous workflow completed
-on the same low-cost path. Luna's classifier was exercised in both directions
-without `--dangerously-skip-permissions`: an exact user-named `/tmp` write was
-allowed by verified intent, while a delegated outside-project backup path was
-blocked under S5. Typecheck and all 682 unit tests passed.
-
-## Upward cost pressure: an informational warning and a per-call gate
-
-Automatic selection only ever moves cost *down*, but two paths still let a
-subagent run on something pricier than the session model: a configured default
-(deliberate cheap-driver/strong-worker setups exist) and the per-call `model`
-field (chosen by the main model itself). Those get different treatment because
-their authors differ:
-
-- **Configured default pricier than the session model** → one informational
-  line in the every-turn reminder, with both prices. It suggests a cheaper
-  listed model for routine tasks but does not tell the model to override the
-  user's knob — the user set it, and second-guessing a user setting from the
-  reminder would invert authority.
-- **Per-call `model` pricier than the session model** → the subagent tool
-  errors with both prices and the menu, and workflow `agent()` throws, unless
-  the call sets `allow_expensive: true` (`allowExpensive` in agent() opts). The
-  schema tells the model to set it only when the user explicitly asked for that
-  model. Only `source: "call"` resolutions are gated: `subagentModel`, the env
-  var, agent-file frontmatter, and `inherit` are user-installed choices, and
-  the codebase rule is that naming a model is choosing it.
-
-The gate opens when either price is unknown — a cost gate that fails closed on
-an unpriced catalog blocks the feature outright, the same failure shape as
-gating a tool other tools sit behind.

package/docs/decisions/modes.md

@@ -1,178 +0,0 @@
-# Modes & keybindings
-
-Part of [Decisions](../decisions.md).
-
-## `/effort`, and ultracode as a standing mode
-
-Claude Code exposes reasoning effort as a Faster→Smarter slider whose last stop,
-past `max` and behind a divider, is `ultracode` — subtitled "xhigh + workflows".
-The divider is the whole point: every other stop buys more thinking, while that
-one also changes *how the model works*, arming multi-agent orchestration on every
-turn instead of the single turn the keyword arms. One Code now has the same
-command, and the same two-tier opt-in: the keyword in a message for one turn
-(`extensions/workflow`), `/effort ultracode` for a standing mode that persists
-until switched off.
-
-The mode is implemented the way the permissions extension implements plan mode —
-an `every-turn` reminder on `one-code:system-reminder` under a key, withdrawn with
-`{remove: true}` when leaving — plus `ctx.ui.setStatus` for a `✦ ultracode`
-footer indicator. Its standing text is deliberately stronger than the keyword's
-one-turn nudge: orchestrate substantive work *by default* and verify
-adversarially, with trivial and conversational turns carved out so the mode does
-not spawn a fleet to rename a variable.
-
-The slider itself is a hand-rolled `Component` passed to `ctx.ui.custom()`,
-following branding's precedent of implementing pi-tui's interface inline. That is
-not stylistic: `@earendil-works/pi-tui` is a regular dependency of
-pi-coding-agent rather than a peer, so it is unhoisted and unresolvable from this
-package — pi's own thinking picker is a vertical `SelectList`, which we cannot
-import and which is the wrong shape anyway. The cost is decoding keys from raw
-bytes (`handleInput` hands over terminal data, not key names) and owning the
-layout, so the marker row, labels, and track are laid out against measured
-column positions and collapse to a single line rather than wrapping when the pane
-is too narrow.
-
-One live finding shaped the design. `setThinkingLevel` **clamps to model
-capability silently** — no throw, no warning, and `thinking_level_select` fires
-after the fact without a veto — so asking for xhigh on haiku-4-5 quietly yields
-`high`. Rather than report a level the model never accepted, the command sets,
-reads back, and says so: "Effort: ultracode — high reasoning, workflows armed
-every turn (this model caps reasoning at high)". That also fixed a subtler bug:
-the shift+tab hygiene (drop the mode when the user cycles thinking away, so the
-footer cannot lie) originally compared against xhigh, which on a clamping model
-would have made ultracode cancel itself the moment anything re-announced the
-clamped level. It compares against the level the mode actually settled on.
-
-Verified: 19 unit tests over the pure slider (choice/level mapping, both arrow
-encodings, clamped movement, marker alignment under the selected label, the
-ultracode subtitle appearing only when selected, narrow-pane degradation) and a
-live tmux TUI run — the slider opened preselected at the current level, arrow
-keys moved the marker, `ultracode` revealed its subtitle, Enter applied it with
-the clamp reported honestly, `✦ ultracode` appeared in the footer, and a
-`CC_E2E_LOG` capture confirmed the standing reminder in **both** subsequent
-turns' payloads rather than just the first.
-
-## Aligning `/effort` with shift+tab
-
-The first cut left two dials disagreeing: shift+tab cycled pi's seven thinking
-levels and called it "thinking", while `/effort` showed Claude Code's five plus
-ultracode and called it "effort". Same underlying number, two names, two sets.
-
-Taking over the key is not available: `app.thinking.cycle` is on pi's
-`RESERVED_KEYBINDINGS_FOR_EXTENSION_CONFLICTS` list, so `registerShortcut` on
-shift+tab is skipped with a warning rather than honoured, and no extension API
-unbinds or retargets a reserved key (only the user's own keybindings config can).
-Disabling it was therefore off the table too, which settles the direction:
-conform to the key rather than compete with it. The slider shows the full `off`→
-`max` ladder plus `ultracode` past the divider, but **enables only the stops the
-active model can reach**: pi filters shift+tab's own cycle through
-`getSupportedThinkingLevels(model)` (a per-model set derived from the model's
-`thinkingLevelMap`, see findings §3), so a fixed seven-stop ladder disagreed with
-shift+tab on every model that doesn't support all of them. Unsupported stops stay
-on the track dimmed and are skipped by navigation, with a `dimmed = unsupported by
-<model>` note; everything we write calls the dial "effort" (banner hint included;
-pi's own footer still says what it says), and the footer names shift+tab as the
-shortcut for the plain stops, so the two read as one control with two entry points
-rather than two competing settings.
-
-Building the slider from the fixed ladder rather than the model's set was a live
-bug: on `deepseek-v4-flash` (supported levels `{high, max}`) picking `low` made
-pi's `clampThinkingLevel` snap *upward* to `high`, which the old code mislabelled
-"caps reasoning at high". A downward clamp (the model genuinely can't reach the
-requested level) is now the only thing flagged — "tops out at" — and the typed
-path (`/effort low`) refuses an unreachable level, naming what the model does
-support, instead of silently rerouting it. Verified live against
-`deepseek-v4-flash`.
-
-Widening the track from six stops to eight is what exposed a latent bug: the
-layout only checked whether the *track* fit the pane, so the longer hint line
-overflowed at 80 columns. Width is now measured on the unstyled text of every row
-(escape codes would inflate the count), and anything that does not fit collapses
-to a clipped one-line stop list — verified by a test that walks every stop at
-widths from 200 down to 10.
-
-## Permission-mode cycling on ctrl+q, not shift+tab, ctrl+m, or alt+m
-
-Claude Code cycles permission modes with shift+tab; typing
-`/permission-mode acceptEdits` for the same switch was friction worth removing.
-The obvious key is taken: pi reserves shift+tab for `app.thinking.cycle` (see
-"Aligning `/effort` with shift+tab" above), and freeing it would mean writing
-`app.thinking.cycle: []` into the user's `~/.pi/agent/keybindings.json` — a
-package silently editing user config to defeat a deliberate reservation. That
-was prototyped and rejected in favour of keeping pi's default: shift+tab stays
-the effort dial.
-
-ctrl+m was considered next and is impossible at the protocol level: ctrl+m *is*
-carriage return (0x0D) in terminal encoding, so outside kitty-protocol
-terminals `matchesKey("\r", "ctrl+m")` is true and every Enter press would
-cycle the mode. pi-tui's `rawCtrlChar` confirms there is no special-casing.
-alt+m — Claude Code's own documented fallback binding, used on Windows when VT
-input is unavailable — shipped briefly and was rejected for macOS ergonomics:
-option+m types "µ" unless the terminal is configured to send option as Meta,
-which is off by default everywhere and not a setting to ask users for.
-
-That leaves the ctrl+letters, and pi plus the terminal claim nearly all of
-them: a/b/e/f/k/u/w/y (editor), c/d/z (clear/exit/suspend), g/l/n/o/p/t/v/x
-(pi app keys), r/s (session picker), and h/i/j/m are Backspace/Tab/LF/CR at
-the byte level. **ctrl+q** is the one left standing — historically XON flow
-control, but pi's raw-mode TUI disables IXON so it arrives everywhere,
-macOS included, with no configuration.
-
-The modes themselves follow Claude Code v2.1 (verified against
-code.claude.com/docs/en/permission-modes.md): `default` is displayed as
-"manual" and `manual` is accepted as an alias everywhere a mode is named; the
-cycle is manual → acceptEdits → plan, with bypassPermissions joining only when
-the session started with it; `dontAsk` (deny instead of prompting; never in
-the cycle) is accepted via flag/settings; footer badges use Claude Code's
-exact strings (`⏸ manual mode on`, `⏵⏵ accept edits on`, …) via
-`ctx.ui.setStatus`. Claude Code's `auto` mode is deliberately not implemented:
-it is gated on a server-side approval classifier we have no equivalent of, and
-Claude Code itself drops it from the cycle when unavailable, so its absence is
-faithful rather than a gap. `/permission-mode` is gone; mode-change reminders
-are keyed so cycling through several modes announces only the one settled on.
-Verified in a live tmux TUI: badge at startup, three-stop cycle, bypass
-joining under `--dangerously-skip-permissions`, and `/permission` completing
-to only `/permissions`.
-
-## Plan mode is file-based, like current Claude Code
-
-Claude Code moved plan mode from "pass the plan as an ExitPlanMode parameter"
-to a **plan file**: entering plan mode allocates `~/.one-code/plans/<slug>.md`,
-a per-turn system message names it as the one writable path and prescribes an
-explore→design→review→write→approve workflow, and ExitPlanMode takes no
-parameters — it reads the file. Observed live in Claude Code and mirrored here: the plan
-survives compaction, the user can open/edit it, and long plans stop bloating
-tool calls and `ui.select` titles.
-
-**Who owns what.** Mode stays with `permissions`; the file belongs to
-`plan-mode`. Allocation happens in `before_agent_start` — the one hook that
-covers all three entry points (tool, ctrl+q, `defaultMode: "plan"`) and runs
-after every extension's `session_start`, so restoring the branch's previous
-path (a `plan-mode-file` custom entry, read via `getBranch()` like tasks/todo)
-can never race a fresh allocation. The path crosses to the matcher over a new
-`one-code:plan-file-path` channel, mirroring `one-code:set-permission-mode` in the
-other direction; `plan-mode` learns the mode from the existing
-`one-code:permission-status` channel rather than a shared module (jiti).
-
-**The reminder key moved.** `setMode` no longer emits plan mode's reminder;
-`plan-mode` re-emits under the same `"permission-mode"` key every turn, with
-`existsSync` flipping "create it at …" to "continue building …" the turn after
-the file appears. Every-turn re-emits replace by key, so nothing accumulates.
-
-**The carve-out allows outright.** In plan mode a write whose subject (or
-symlink-resolved subject) is the plan file returns `allow`, and everything
-else keeps denying. Outside plan mode the file has no special status, matching
-Claude Code. Deny rules still beat the carve-out. (`.one-code` itself is a
-protected dir like `.claude`; `.one-code/plans` is excepted as working space —
-plan documents are rendered to the user, never executed.)
-
-**Slug fidelity note.** Claude Code's real slugs start with the user's opening
-words plus two random words (`we-are-going-to-async-turtle.md`); One Code uses
-three random words. Deriving from the prompt was skipped — the slug is
-allocated before any user text is guaranteed to exist (ctrl+q, defaultMode).
-
-Verified live: an RPC run (no `--dangerously-skip-permissions`) showed a
-blocked ordinary write and an unprompted plan-file write in plan mode; a tmux
-TUI run exercised the scrollable approval viewer (scroll, choice switch,
-reject→stay-planning, Enter→approve→manual mode) and ctrl+q entry reusing the
-session's existing file.