one-code-extension 0.1.3 → 0.3.0

package/docs/guide/bring-your-claude-code-setup.md

@@ -0,0 +1,126 @@
+# Bring your Claude Code setup
+
+One Code reads the same configuration files as Claude Code, so your
+existing setup works without changes. There is no import step and nothing
+to convert. Open a project that already has a `.claude/` directory, and One
+Code picks up each of the following as it is.
+
+## Project instructions: CLAUDE.md
+
+One Code loads `CLAUDE.md` files and includes them in the model's context
+exactly as Claude Code does: your global `~/.claude/CLAUDE.md`, then the
+`CLAUDE.md` in every directory from the filesystem root down to the working
+directory, plus any `CLAUDE.local.md` beside them for private instructions.
+`@path` imports are expanded in place.
+
+If a directory has no `CLAUDE.md`, One Code uses its `AGENTS.md` instead, so
+a repository that standardized on `AGENTS.md` works too. A `CLAUDE.md` takes
+precedence over an `AGENTS.md` in the same directory.
+
+To give One Code instructions that Claude Code should not read, add an
+`ONECODE.md`. See [ONECODE.md](sessions-and-context.md#onecodemd).
+
+To generate a `CLAUDE.md` for a project that lacks one, run `/init`. It has
+the model survey the project (build, test, and lint commands, layout,
+existing AI-tool configuration), ask you about what the code cannot answer,
+and write the file. It never overwrites an existing `CLAUDE.md` silently.
+
+## Skills, commands, and agents
+
+| Directory | Becomes |
+|---|---|
+| `.claude/skills/`, `~/.claude/skills/`, `~/.agents/skills/` | Skills the model can call and you can run as `/<name>`. `/skills` manages them. |
+| `.claude/commands/`, `~/.claude/commands/` | Slash commands with the same names, with `$ARGUMENTS` substitution. |
+| `.claude/agents/`, `~/.claude/agents/` | Subagent definitions with their model, tools, and instructions. `/agents` lists them. |
+| `.claude/workflows/`, `~/.claude/workflows/` | Saved `ultracode` workflow scripts. |
+
+See [Skills, plugins, and MCP](skills-plugins-and-mcp.md) and
+[Subagents and workflows](subagents-and-workflows.md).
+
+## Plugins
+
+Plugins installed under `~/.claude/plugins` are picked up, with their
+agents, skills, commands, hooks, MCP servers, and language-server
+configuration, each namespaced by plugin. The `enabledPlugins` key in your
+settings files is honored. `/plugins` browses and installs more; anything
+One Code installs goes to its own plugin directory. See
+[Plugins](skills-plugins-and-mcp.md#plugins).
+
+## MCP servers
+
+Servers in `.mcp.json`, in `~/.claude.json`, and in
+`.claude/settings.local.json` are connected at startup, after a one-time
+approval for project servers. Only the `mcpServers` key of `~/.claude.json`
+is read; the rest of that file is left alone. See
+[MCP servers](skills-plugins-and-mcp.md#mcp-servers).
+
+## Settings files
+
+One Code reads these Claude Code files and never writes them:
+
+| File | Scope |
+|---|---|
+| `~/.claude/settings.json` | User |
+| `.claude/settings.json` | Project |
+| `.claude/settings.local.json` | Project, local |
+| Managed settings (`/Library/Application Support/ClaudeCode/managed-settings.json` on macOS, the Linux equivalent elsewhere) | Organization |
+| `~/.claude.json` | User, `mcpServers` only |
+
+`CLAUDE_CONFIG_DIR` relocates the user-scope files, as it does in Claude
+Code.
+
+The keys One Code honors:
+
+| Key | Scopes | Notes |
+|---|---|---|
+| `permissions.allow`, `permissions.deny`, `permissions.ask` | All | Project allow rules need one-time approval. See [Permissions](permissions-modes-and-auto-mode.md#permission-rules). |
+| `permissions.defaultMode` | All | A project file cannot select `auto` or `bypassPermissions`. |
+| `permissions.disableBypassPermissionsMode` | All | `"disable"` refuses bypass mode from any source. |
+| `autoMode.*` | User, managed | Never read from project files. See [Configure auto mode](permissions-modes-and-auto-mode.md#configure-auto-mode). |
+| `hooks` | All | Project hooks need one-time approval. See [Hooks](hooks.md). |
+| `env.CLAUDE_CODE_SUBAGENT_MODEL` | User, managed | The only `env` key read. |
+| `enabledPlugins` | All | Later scope wins per plugin. |
+| `enabledMcpjsonServers`, `disabledMcpjsonServers`, `enableAllProjectMcpServers` | User, untracked local | Never from a checked-in project file. |
+| `mcpServers` | `~/.claude.json`, `.claude/settings.local.json` | |
+
+Not honored: `permissions.additionalDirectories`, other `env` keys,
+`includeCoAuthoredBy`, `apiKeyHelper`, `forceLoginMethod`,
+`cleanupPeriodDays`, and `spinnerTipsEnabled`. Run `/doctor report` to see,
+for every file found, which keys were used, ignored, or refused.
+
+## Permission rules
+
+The `allow`, `deny`, and `ask` rules in your settings drive the permission
+gate, with `deny` always winning. Claude Code's PascalCase tool names
+(`Read`, `Bash`, `Edit`, `Task`, `WebFetch`, and the rest) are accepted
+verbatim and mapped to the matching tool. See
+[Permissions, modes, and auto mode](permissions-modes-and-auto-mode.md).
+
+## Hooks
+
+Claude Code command hooks run unchanged, with the same standard-input JSON,
+exit-code meaning, and output format. Eight events are supported. A
+project's hooks run only after you approve them once. See [Hooks](hooks.md).
+
+## Memory
+
+One Code keeps per-repository memory in Claude Code's own folder,
+`~/.claude/projects/<slug>/memory/`, so both tools read and write the same
+memories. This is the one place One Code writes under `~/.claude`. Run
+`/memory` to open memory and instruction files. See
+[Memory](sessions-and-context.md#memory).
+
+## What stays separate
+
+One Code's own state lives in `~/.onecode`. Everything it saves (a chosen
+subagent model, auto-mode options, rules added with `/allow`, disabled MCP
+servers, project approvals, plan files, OAuth tokens) goes there or to a
+per-repository file under it, never into your Claude Code configuration.
+See [Where settings live](configuration.md#where-settings-live).
+
+## What does not carry over
+
+Features that need Claude Code's own hosted or desktop services are not
+available. For the full list of tools, commands, and skills that are
+missing or different, see
+[Differences from Claude Code](differences-from-claude-code.md).

package/docs/guide/configuration.md

@@ -0,0 +1,171 @@
+# Configure One Code
+
+Use this page to find the right settings file, learn what One Code stores
+and where, change the terminal appearance, and set up language-server
+diagnostics. Provider keys are covered in
+[Providers and models](providers-and-models.md); permission rules in
+[Permissions, modes, and auto mode](permissions-modes-and-auto-mode.md).
+
+## Where settings live
+
+Three kinds of files are involved: pi's own settings (terminal, theme,
+default model), One Code's settings, and Claude Code's settings, which One
+Code reads but never writes.
+
+| What you want to change | File |
+|---|---|
+| Theme, full-screen mode, and other pi settings, in the `onecode` app | `~/.onecode/agent/settings.json` |
+| The same, on your own pi installation | `~/.pi/agent/settings.json` |
+| One Code's user-wide settings: subagent model, auto-mode configuration, global allow rules, web-search keys, disabled MCP servers | `~/.onecode/settings.json` |
+| One Code's per-repository settings: allow rules and disabled MCP servers for one repository | `~/.onecode/projects/<slug>/settings.json` |
+| Claude Code user configuration that One Code reads | `~/.claude/settings.json` |
+| Claude Code project configuration that One Code reads | `.claude/settings.json`, `.claude/settings.local.json` |
+
+The per-repository slug is derived from the repository root, so worktrees
+and subdirectories of one repository share one file.
+
+Commands such as `/allow`, `/subagent`, `/auto-mode model`, and the
+`/mcp` panel write to One Code's files. Both One Code files are written
+atomically; a malformed file is reported rather than overwritten.
+
+### Relocating directories
+
+| Variable | Moves |
+|---|---|
+| `ONECODE_STATE_DIR` | One Code's state (default `~/.onecode`). |
+| `PI_CODING_AGENT_DIR` | pi's agent directory. The bundled app sets it to `~/.onecode/agent`. |
+| `CLAUDE_CONFIG_DIR` | Where Claude Code's user configuration is read from (default `~/.claude`). |
+
+Setting one does not move the others.
+
+## What is stored under ~/.onecode
+
+| Path | Contents |
+|---|---|
+| `settings.json` | User-wide One Code settings. |
+| `projects/<slug>/settings.json` | Per-repository settings. |
+| `agent/` | pi's own state under the bundled app: credentials, model catalog, sessions, pi's settings, and One Code's plugin directory (`agent/plugins/`). |
+| `plans/<name>.md` | Plan files from plan mode. |
+| `hooks/project-approvals.json` | Which projects' hooks you approved. |
+| `mcp/project-approvals.json` | Which projects' MCP servers you approved. |
+| `permissions/project-allow-approvals.json` | Which projects' allow rules you trusted. |
+| `mcp-auth/<server>.json` | OAuth tokens for MCP servers, owner-readable only. |
+| `cache/artificial-analysis.json` | The cached model-capability snapshot, when a key is set. |
+| `hooks/hooks-decisions.jsonl` | A hook decision log, written only while `CC_HOOKS_DEBUG` is set. |
+
+The bundled app also keeps a timestamp of its last update check at
+`agent/last-update-check`.
+
+## Settings reference
+
+Keys in `~/.onecode/settings.json`. Keys marked "per repository" may also
+appear in `projects/<slug>/settings.json`.
+
+| Key | Type | Set by | Effect |
+|---|---|---|---|
+| `subagentModel` | string | `/subagent` | Default model for subagents and workflow agents: `provider/model-id`, a short alias, or `inherit`. |
+| `permissions.allow` | string array | `/allow` (per repository) or `/allow … global` | Allow rules in Claude Code's format. |
+| `autoMode.environment` | string array | `/auto-mode setup` | Describes your environment to the classifier. |
+| `autoMode.hard_deny`, `autoMode.soft_deny`, `autoMode.allow` | string array | `/auto-mode setup` | Extra classifier rules, appended to the built-ins. |
+| `autoMode.classifierModel` | string | `/auto-mode model` | The classifier model. |
+| `autoMode.classifyAllShell` | boolean | By hand | Send every shell command to the classifier. |
+| `autoMode.logDecisions` | boolean | By hand | Log every gate decision next to the session files. |
+| `webSearch.apiKeys.brave`, `webSearch.apiKeys.tavily` | string | By hand | Search keys when the environment variables are not set. |
+| `webSearch.order` | string array | By hand | Order of the fallback search backends: `brave`, `tavily`, `exa-free`. |
+| `capabilityIndex.artificialAnalysisApiKey` | string | By hand | Artificial Analysis key for measured model selection. |
+| `disabledMcpServers` | string array | `/mcp` (user or per repository) | MCP servers kept disabled. |
+
+Two keys are stamped alongside model choices (`subagentModelSetFor`,
+`autoMode.classifierModelSetFor`) to record the provider a choice was made
+on; leave them alone.
+
+The main model chosen with `/model` is saved in pi's own settings file as
+`defaultProvider` and `defaultModel`, not in One Code's.
+
+## Full-screen mode and themes
+
+The bundled app starts in full-screen mode with the `onecode` theme and
+quiet startup. It sets these on first run in pi's settings and never
+overrides a value you change later.
+
+On your own pi, to use full-screen mode for one session:
+
+```bash
+pi --tui-mode fullscreen
+```
+
+For a persistent setting, merge these keys into pi's settings file (the
+first two rows of the table under [Where settings live](#where-settings-live)),
+preserving its other keys such as `packages`:
+
+```json
+{
+  "tuiMode": "fullscreen",
+  "theme": "onecode",
+  "quietStartup": true
+}
+```
+
+Use `"theme": "onecode-light"` for the light theme. Full-screen mode uses
+the terminal's alternate screen and restores your terminal on exit.
+
+One Code also works with other pi extensions, themes, and settings; see pi's
+own documentation for those.
+
+## Main and subagent models
+
+Connect providers with `/login` and choose the main model with `/model`.
+Set the subagent default with `/subagent`, or apply a preset with
+`/doctor preset <economical|balanced|quality>`. See
+[Providers and models](providers-and-models.md) and
+[Choose the subagent model](subagents-and-workflows.md#choose-the-subagent-model).
+
+## Permission settings
+
+`/permissions` shows the mode and rules, `/allow` adds a rule, and
+`/auto-mode setup` configures the classifier. **ctrl+q** cycles modes. To
+start a session in a given mode:
+
+```bash
+onecode --permission-mode plan
+```
+
+A persistent default goes in a Claude Code settings file, not in
+`~/.onecode/settings.json`. See
+[Choose the starting mode](permissions-modes-and-auto-mode.md#choose-the-starting-mode).
+
+## Language-server diagnostics
+
+One Code runs a language server for each language it detects in the
+project and reports diagnostics to the model after edits. The server must
+be installed and on the `PATH` used to launch One Code.
+
+| Language | Server | Install |
+|---|---|---|
+| TypeScript, JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` |
+| Python | `pyright-langserver` | `npm install -g pyright` |
+| Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |
+| Rust | `rust-analyzer` | `rustup component add rust-analyzer` |
+| Java | `jdtls` | `brew install jdtls` |
+
+A server is started for a language the first time the model touches one of
+its files, from the nearest directory that has a project marker such as
+`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, or `pom.xml`. A
+server that crashes is restarted twice, then disabled for the session.
+
+If the project's TypeScript installation lacks `lib/tsserver.js`
+(TypeScript 7's native compiler), the server cannot start; One Code
+reports this. Install a TypeScript 5.x development dependency in that
+project.
+
+Plugins can add servers through a `.lsp.json` file. A plugin's server takes
+precedence over the built-in table for the file extensions it claims.
+
+Run `/lsp` to see each server's status and diagnostic count, start
+failures, and plugin configuration problems. `/doctor report` lists the
+servers your project needs and whether they are installed.
+
+## Environment variables
+
+Every toggle is listed in the
+[environment-variable reference](reference.md#environment-variables).

package/docs/guide/differences-from-claude-code.md

@@ -0,0 +1,150 @@
+# Differences from Claude Code
+
+One Code recreates Claude Code's workflow on the pi agent harness with your
+choice of model. Most of what you know carries over. This page lists what
+is deliberately different, what is not provided, and the known limitations,
+so nothing surprises you.
+
+## What is the same
+
+- Your `CLAUDE.md`, skills, commands, agents, plugins, hooks, permission
+  rules, and MCP configuration are read from the same files, in the same
+  formats. See [Bring your Claude Code setup](bring-your-claude-code-setup.md).
+- The system prompt, the context block, the compaction instruction, the
+  auto-mode classifier ruleset, and the recap prompt are Claude Code's own,
+  adapted where a provider requires it.
+- Memory lives in Claude Code's own folder, so both tools share it.
+- Auto mode is the default permission mode, with Claude Code's two-stage
+  classifier.
+- Subagents, forks, worktree isolation, plan mode, structured tasks,
+  background shells, and `ultracode` workflows behave as they do in Claude
+  Code.
+
+## What is different by design
+
+| Area | Claude Code | One Code |
+|---|---|---|
+| Models | Anthropic models. | Any provider pi supports, switchable mid-session, with a different model per role. |
+| Tool names on the wire | PascalCase (`Read`, `Bash`). | snake_case (`read`, `bash`); `Agent` and `SendMessage` keep their names. Claude Code names still work in rules and hook matchers. |
+| Permission-mode key | shift+tab. | ctrl+q. pi reserves shift+tab for the reasoning-effort dial. |
+| Task-list key | ctrl+t. | `/tasks show` and `/tasks hide`. pi reserves ctrl+t for thinking blocks. |
+| Deleting files in auto mode | The whole project directory is trusted. | A delete is approved only when git can recover the file; otherwise the classifier decides. |
+| Bypass mode | Protected paths stay protected. | Bypass mode bypasses everything, including protected paths. |
+| First-run consent for auto mode | Asked once. | Not asked. Auto mode is on from the first session. |
+| OS sandbox | Paired with auto mode. | None. Run One Code in a container for OS-level isolation. |
+| Cost display | Main conversation. | All-in: subagents, classifier, reader, and recap calls included. |
+| Web search | Anthropic's search. | The provider's own search when it has one, else Brave, Tavily, or a keyless fallback. |
+| Reasoning effort | Fixed per model. | A slider from `off` to `max`, plus `ultracode`. |
+| Session storage | `~/.claude`. | `~/.onecode` for One Code's state and the bundled app's pi state. `~/.claude` is read-only except for memory. |
+| Update command | `/upgrade`. | A daily check that shows an install-aware upgrade hint. |
+| Config editing | `/config`, `/hooks`, `/statusline`. | Settings files, plus `/doctor` to see what is in effect. |
+
+## Tools that are not provided
+
+These Claude Code tools depend on Anthropic-hosted or desktop services and
+have no equivalent here: `Artifact`, `ReportFindings`,
+`ShareOnboardingGuide`, `PushNotification`, `RemoteTrigger`, `DesignSync`,
+`CronCreate`, `CronList`, `CronDelete`, `EndConversation`, and
+`SendFeedback`. Scheduling within a session is available through `/loop`
+and `schedule_wakeup`; scheduled cloud sessions are not.
+
+The `Agent` tool's remote isolation option is not implemented.
+
+## Commands that are not provided
+
+Claude Code commands with no One Code or pi counterpart: `/cost` (the
+footer shows cost instead), `/status`, `/vim`, `/terminal-setup`, `/bug`,
+`/help`, `/rewind`, `/add-dir`, `/hooks`, `/ide`, `/install-github-app`,
+`/statusline`, `/privacy-settings`, and `/upgrade`. pi's `/changelog` and
+`/settings` cover part of `/release-notes` and `/config`. `/review` is
+available through the `commit-commands` plugin when installed.
+
+## Skills that are not bundled
+
+One Code bundles four of Claude Code's built-in skills: `simplify`,
+`code-review`, `security-review`, and `fewer-permission-prompts`. It does
+not bundle the skills that need Claude Code's hosted or desktop surfaces
+(`design`, `dataviz`, the `artifact-*` guides, and the publishers), the
+account and desktop skills (`update-config`, `keybindings-help`,
+`claude-in-chrome`, `debug`, `usage`, `schedule`, `batch`,
+`claude-code-guide`), the run-skill generators, or the `claude-api`
+reference. See
+[Skills not bundled](skills-plugins-and-mcp.md#skills-not-bundled).
+
+## Hooks
+
+Eight events are supported: `PreToolUse`, `PostToolUse`,
+`UserPromptSubmit`, `Stop`, `SessionStart`, `SessionEnd`, `PreCompact`, and
+`PostCompact`. `Notification`, `SubagentStop`, and `PermissionRequest` are
+not. Hook types other than `command` are skipped. A hook can block an
+action but never pre-approve one. See [Hooks](hooks.md).
+
+## Settings keys that are ignored
+
+`permissions.additionalDirectories` is not honored. The `env` block is read
+only for `CLAUDE_CODE_SUBAGENT_MODEL`, and only from user and managed
+scope. `includeCoAuthoredBy`, `apiKeyHelper`, `forceLoginMethod`,
+`cleanupPeriodDays`, and `spinnerTipsEnabled` are not read. Run
+`/doctor report` to see, per file, which keys were used, ignored, or
+refused.
+
+## Prompt layout on Anthropic models
+
+Claude Code delivers part of its reminder stack to Opus and Sonnet as a
+system-role message after the first user message. pi's message model cannot
+express that, so One Code uses the layout Claude Code uses for Haiku on
+every model. The content is the same; only the placement differs.
+
+## Platform support
+
+- **macOS and Linux** are developed and verified. **WSL** works the same
+  way.
+- **Native Windows** is untested and unsupported. Hooks run through
+  `/bin/sh`, background shells fall back to it when `SHELL` is unset, and
+  no PowerShell tool exists. Use WSL.
+
+## Provider notes
+
+- End-to-end verification has focused on Anthropic, OpenAI, and OpenRouter.
+  Other providers are less exercised.
+- Some models reject options that others accept. One Code sends minimal
+  options to its side calls (classifier, recap, reader) for this reason. A
+  provider incompatibility in a side call fails closed: a classifier that
+  cannot answer blocks the action.
+- Prompt-cache lifetime and pricing are the provider's. The extended
+  one-hour cache applies to Anthropic; other providers use their own
+  values.
+
+## Known issues
+
+- A write or edit tool can reach a file that only a `Bash` deny rule
+  protects, because in-project writes take the deterministic fast path in
+  auto mode and are not classified. Write `deny` rules for the write tools
+  as well. This is documented and accepted rather than fixed.
+- GLM-5.3 and GLM-5.3 Flash, used as the classifier, approve a request to
+  back up the project to an unnamed outside location that the ruleset says
+  to block.
+- Running a skill in a one-shot run (`-p '/simplify'`) delivers the skill
+  but starts no model turn, so the process exits without doing anything.
+  Interactive sessions are unaffected.
+- The reasoning effort set with `/effort` does not persist across
+  restarts; the model chosen with `/model` does. To save a level, open
+  pi's `/thinking` picker and press **ctrl+s**, or pass `--thinking`.
+- A subagent spawn that is blocked before it starts can leave its requested
+  run name reserved; a retry with the same name is renamed automatically.
+- Under pi's RPC transport, `SessionStart` hooks fire twice per `/clear`.
+- A background subagent started before `/clear` can report its cost into
+  the new session's footer total.
+- `/lsp` diagnostics from a subagent's edits surface in the parent's
+  context, not the subagent's. This matches Claude Code.
+- Subagents run in-process. A subagent that stops responding is stopped
+  after 30 minutes, and an out-of-memory condition affects the whole
+  process.
+- MCP servers that use server-sent events (`type: "sse"`) are untested.
+  Stdio and HTTP transports are verified. The OAuth flow is implemented but
+  has had limited live testing.
+- Plugin marketplaces support git and local sources only; npm and pip
+  sources, version pinning, dependency resolution, and enterprise
+  blocklists are not implemented.
+
+Open work is tracked in the project's issue tracker on GitHub.

package/docs/guide/doctor.md

@@ -0,0 +1,86 @@
+# Check your setup with doctor
+
+`/doctor` is One Code's health check, modelled on Claude Code's. It measures
+your setup, reports what a session will use, and can have the model repair
+the findings.
+
+## The three forms
+
+| Command | What it does |
+|---|---|
+| `/doctor` | The checkup. One Code builds the report and hands it to the model, which reviews the findings and proposes or applies fixes. With no model available, it falls back to showing the report. |
+| `/doctor report` | The report alone, in a scrollable panel, with no model call. Includes a network check for a newer version. |
+| `onecode doctor` | The report from the shell, without starting a session. Bundled app only. |
+
+`/doctor presets` and `/doctor preset <name>` are described in
+[Model presets](#model-presets).
+
+## What the report contains
+
+1. **Installation.** Whether you run the bundled app or the extension on
+   your own pi, the pi version and whether it is in the tested range, the
+   Node version and platform, pi's agent directory, One Code's state
+   directory, where Claude Code configuration is read from, and whether a
+   newer One Code is available.
+2. **Providers.** Each provider with credentials, how many models it
+   offers, and where the credential came from. An error when none is
+   ready, with the free options named.
+3. **Models.** The main model with its price and context window, the
+   prompt tier it gets, the reasoning effort, the subagent model and how it
+   was chosen, the auto-mode classifier model, the reader model used by
+   web fetch and recaps, capability verdicts for each role when an
+   Artificial Analysis key is set, and the permission mode.
+4. **Presets.** The three model presets for your provider and the model
+   each role would get under each.
+5. **Imported configuration.** Every settings file found, with the keys One
+   Code uses, ignores, and refuses; the instruction files in context with
+   their sizes; the memory folder; agents, skills, and commands by origin;
+   plugins; and hooks.
+6. **MCP servers.** Each configured server, its source, and its connection
+   status.
+7. **Dependencies.** `git` (required), `rg` (optional), the language
+   servers for the languages detected in the project, the commands MCP
+   servers need, and the route web search would take. Missing programs
+   come with install hints.
+
+Findings are listed first, errors before warnings, each with a suggested
+fix. The report is "ready" when at least one provider works, a model is
+selected, and there are no errors.
+
+In the panel, press **f** to run the checkup on the report you are reading.
+
+## Model presets
+
+A preset sets the main model, the subagent model, and the classifier model
+together, from the provider you are connected to. Only current-generation,
+priced models that support tool calls are considered.
+
+| Preset | Main model | Subagents | Classifier |
+|---|---|---|---|
+| `economical` | The cheapest small model. | Inherit the main model. | Automatic. |
+| `balanced` | The cheapest Sonnet-class model. | Chosen automatically (a cheaper Sonnet-class model when one exists, else the main model). | Automatic. |
+| `quality` | The most capable model available. | Inherit the main model. | Automatic. |
+
+`/doctor presets` shows what each preset would pick. `/doctor preset balanced`
+applies one; the aliases `economy`, `cheap`, `balance`, `max`, `maximum`,
+and `best` also work. Applying a preset writes the subagent and classifier
+choices to `~/.onecode/settings.json` and remembers the main model as pi's
+default. Undo any part with `/model`, `/subagent clear`, or
+`/auto-mode model clear`.
+
+## The command-line form
+
+```bash
+onecode doctor
+```
+
+This prints the same report as text. It exits with:
+
+| Code | Meaning |
+|---|---|
+| 0 | No errors. |
+| 1 | At least one error-level finding, such as no provider ready. |
+| 2 | The doctor itself failed to run. |
+
+Because it registers the extension package in the isolated agent directory
+before reporting, the result matches what a real session would see.

package/docs/guide/hooks.md

@@ -0,0 +1,109 @@
+# Hooks
+
+Hooks are shell commands that run at fixed points in a session. One Code
+runs Claude Code's command hooks from your existing settings files, with
+the same input, output, and exit-code contract, so hooks you wrote for
+Claude Code work unchanged.
+
+## Where hooks come from
+
+Hooks are read from the `hooks` block of these files:
+
+- `~/.claude/settings.json` (user scope)
+- Managed settings
+- `.claude/settings.json` (project scope)
+- `.claude/settings.local.json` (project scope)
+- Installed plugins
+
+A project's hooks can run arbitrary code, so they run only after you
+approve them once. At startup One Code lists each command from the
+project's files and asks "Run this project's hooks?". The approval is
+stored in `~/.onecode/hooks/project-approvals.json` with a hash of the hook
+configuration, so any change asks again. Declining is remembered for the
+session only. User, managed, and plugin hooks never prompt.
+
+Only command hooks are supported. Hook entries of type `http`, `prompt`, or
+`agent` are skipped with a diagnostic.
+
+## Supported events
+
+| Event | When it runs |
+|---|---|
+| `PreToolUse` | Before a tool runs. Can block the call or rewrite its input. |
+| `PostToolUse` | After a tool returns. Can replace the result or add context. |
+| `UserPromptSubmit` | When you submit a prompt. Can block it or add context. |
+| `Stop` | When the model finishes a turn. |
+| `SessionStart` | When a session starts, resumes, clears, or compacts. |
+| `SessionEnd` | When a session ends. |
+| `PreCompact` | Before context compaction. |
+| `PostCompact` | After context compaction, with the summary. |
+
+Claude Code's `Notification`, `SubagentStop`, and `PermissionRequest`
+events are not supported. pi has no event that carries the notification
+concept, and the other two are not implemented.
+
+Hooks also run inside subagents: a `PreToolUse` hook that blocks a command
+blocks it in a subagent too.
+
+Under pi's RPC transport, `SessionStart` fires twice per `/clear`. This is
+a pi behavior.
+
+## What a hook receives
+
+The hook's standard input is a JSON object with these fields:
+
+| Field | Present | Meaning |
+|---|---|---|
+| `session_id` | Always | The session id. |
+| `transcript_path` | Always | The session file, or an empty string when there is none. |
+| `cwd` | Always | The working directory. |
+| `hook_event_name` | Always | The event name from the table. |
+| `tool_name`, `tool_input` | Tool events | The tool and its arguments. Tool names are One Code's names; see [Claude Code tool names](tools.md#claude-code-tool-names). |
+| `tool_response` | `PostToolUse` | `{ content, is_error }`. |
+| `prompt` | `UserPromptSubmit` | The submitted text. |
+| `stop_hook_active` | `Stop` | Whether a Stop hook is already running. |
+| `trigger` | Compaction events | `manual` or `auto`. |
+| `custom_instructions` | `PreCompact` | Instructions passed to `/compact`. |
+| `compact_summary` | `PostCompact` | The summary that replaced the context. |
+| `source` | `SessionStart` | `startup`, `resume`, `clear`, or `compact`. |
+| `reason` | `SessionEnd` | `clear`, `logout`, `prompt_input_exit`, or `other`. |
+| `agent_id`, `agent_type` | Inside a subagent | Identify the subagent making the call. |
+
+The hook's environment also carries `CLAUDE_PROJECT_DIR`.
+
+Hook matchers match on the tool name. Claude Code's PascalCase names work.
+
+## How a hook's result is read
+
+| Outcome | Effect |
+|---|---|
+| Exit code 0 with JSON on stdout | The JSON is read as an envelope; see the following table. |
+| Exit code 0 with other output | The hook passes. For `UserPromptSubmit` and `SessionStart`, the output is added to the model's context. |
+| Exit code 2 | The action is blocked. Standard error is the reason. |
+| Any other exit code | The hook passes and its output is ignored. |
+| Timeout | `PreToolUse` and `UserPromptSubmit` block (fail closed). Other events pass. |
+| The command could not be started | The hook passes; this is an environment problem, not a verdict. |
+
+Envelope fields honored in a JSON result:
+
+| Field | Effect |
+|---|---|
+| `continue: false` | Blocks, with `stopReason` as the reason. |
+| `decision: "block"` | Blocks, with `reason` as the reason. |
+| `hookSpecificOutput.permissionDecision` | `"deny"` and `"ask"` both block, with `permissionDecisionReason`. `"allow"` is read but never honored; a hook cannot pre-approve an action, and the permission gate still runs. |
+| `hookSpecificOutput.updatedInput` | Replaces the tool's input (`PreToolUse`). |
+| `hookSpecificOutput.updatedToolResult` | Replaces the tool's result (`PostToolUse`). |
+| `hookSpecificOutput.additionalContext` | Adds text to the model's context. |
+| `systemMessage` | Shown to you. |
+
+A `PreToolUse` block stops the call before the permission gate runs, so no
+approval prompt appears for a hook-blocked call.
+
+## Debugging hooks
+
+Set `CC_HOOKS_DEBUG=1` before launching to print each hook dispatch and its
+outcome to stderr. Decisions are also appended to
+`~/.onecode/hooks/hooks-decisions.jsonl` while the variable is set.
+
+Hooks run through `/bin/sh`. On native Windows this path does not exist,
+which is one reason native Windows is unsupported; use WSL.