one-code-extension 0.1.0

package/docs/decisions/memory-state.md

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

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

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

package/docs/decisions/skills-plugins.md

@@ -0,0 +1,56 @@
+# Skills & plugins
+
+Part of [Decisions](../decisions.md).
+
+## Skills and plugins
+
+**The `skill` tool.** pi's own skill mechanism lists skills in the system prompt
+and expects the model to `read` the SKILL.md path. Claude Code instead exposes a
+`Skill` tool that returns the instructions as a tool result, which is what makes
+`/skill-name` invocation work. `extensions/skill/` adds that: it indexes what pi
+already discovered (via `before_agent_start`'s `systemPromptOptions.skills`,
+rather than rediscovering) plus plugin skills, and returns the body with the
+skill's own path so relative `references/` and `scripts/` remain readable.
+
+**Plugins.** `extensions/plugins/` reads `~/.claude/plugins/installed_plugins.json`
+and wires each plugin's resources in, namespaced the way Claude Code namespaces
+them so two plugins can both ship a `commit`:
+
+| Plugin directory | Becomes |
+|---|---|
+| `agents/*.md` | subagents, as `<plugin>:<agent>` |
+| `skills/<name>/SKILL.md` | skills, as `<plugin>:<skill>` |
+| `commands/*.md` | slash commands, as `/<plugin>:<command>` |
+| `.mcp.json` | MCP servers |
+
+Command templates get full Claude Code expansion: `$ARGUMENTS`, `$@`, positional
+`$1`, and **`` !`command` `` substitution**, which is what makes plugin commands
+like `commit` work — the template gathers `git status` and `git diff` before the
+model sees the prompt. The expanded text is delivered as a user turn.
+
+Verified against a real installation (7 plugins): 7 namespaced agents, 3 skills
+listed and invocable, 7 commands registered, 2 MCP configs picked up, and
+`/commit-commands:commit` expanded with live git output embedded.
+
+Three findings from this work, each of which had been silently wrong:
+
+1. **Module state is not shared between extension files.** Under jiti each
+   extension gets its own module instance, so a shared registry singleton written
+   by one extension reads as *empty* in another — no error, just nothing. The
+   deferred-tool registry only worked because its data crossed via the event bus.
+   Plugin discovery is therefore a function each consumer calls for itself
+   (`discoverPlugins`, memoised per module).
+2. **Real frontmatter is not always valid YAML.** pi's parser threw
+   "Nested mappings are not allowed in compact mappings" on a genuine plugin
+   agent whose unquoted `description:` contained `: `, and our `catch` dropped the
+   whole definition — the file lost this way was, aptly,
+   `silent-failure-hunter.md`. `parseAgentFile` now falls back to line-wise
+   extraction. Also: `model: inherit` means "use the session model", not a model
+   id.
+3. **Never gate a loader behind a permission prompt.** The `skill` tool was
+   blocked by our own permission system in non-interactive runs, and the same
+   applied to `tool_search` — which would have made every deferred tool
+   unreachable by default. Both are now auto-allowed along with `lsp_diagnostics`
+   and `list_mcp_resources`; network egress and MCP calls still ask. This class of
+   bug was invisible because earlier end-to-end tests all ran with
+   `--dangerously-skip-permissions`.