one-code-extension 0.1.3 → 0.3.0

package/docs/guide/installation.md

@@ -0,0 +1,124 @@
+# Install One Code
+
+One Code ships as two npm packages from one repository. Choose the one that
+fits how you already work.
+
+| You | Install | What you get |
+|---|---|---|
+| New to this, or you want the simplest setup | `npm install -g @one-ai/one-code` | The bundled app: its own `onecode` command, a pinned version of the pi coding agent inside it, and its state kept in `~/.onecode`. It coexists with any `pi` you already have. |
+| Already running [pi](https://github.com/earendil-works/pi) | `pi install npm:one-code-extension` | The extensions only. They run on your existing pi. One Code's own state still goes to `~/.onecode`; pi's own files stay under your pi agent directory (`~/.pi/agent`). |
+
+## Requirements
+
+- Node.js 22.19 or later. The app refuses to start on older versions,
+  because pi crashes at import time there.
+- macOS or Linux. Windows Subsystem for Linux (WSL) works the same way.
+  Native Windows is untested and unsupported.
+- `git`. Optional: `rg` (ripgrep) for faster search, the GitHub CLI for the
+  pull-request marker in the footer, and a language server for your
+  language (see
+  [Language-server diagnostics](configuration.md#language-server-diagnostics)).
+
+## Install the app with npm
+
+```bash
+npm install -g @one-ai/one-code
+cd your-project
+onecode
+```
+
+On the first run there is no provider yet: the banner shows `model none`.
+Run `/login` inside One Code to connect a provider, or set a provider key
+in your environment before launching. For a free option, see
+[Providers and models](providers-and-models.md).
+
+The first run also seeds pi's settings under `~/.onecode/agent/` with the
+`onecode` theme, quiet startup, and full-screen mode. It never overrides a
+value you change later.
+
+## Install with Homebrew
+
+Homebrew installs Node for you, so this route has no separate Node step:
+
+```bash
+brew install isurumaduranga/one-ai/one-code
+```
+
+The formula is named `one-code`; the command it installs is `onecode`.
+Homebrew refuses npm packages published less than a day ago, so a release
+becomes installable this way about a day after it appears on npm.
+
+## Install the extension on your own pi
+
+If you already run pi, add One Code as an extension:
+
+```bash
+pi install npm:one-code-extension
+```
+
+Use `pi` in place of `onecode` for every command in this guide. The
+extension is tested against pi 0.83 through 0.85 and warns at startup when
+your pi is outside that range. Full-screen mode is opt-in on your own pi;
+see [Full-screen mode and themes](configuration.md#full-screen-mode-and-themes).
+
+A few interface refinements are applied only by the bundled app, because
+they patch pi internals the extension API cannot reach: a clean exit that
+erases the screen in regular mode, and suppression of pi's "Operation
+aborted" line when you interrupt a reply. Everything else is identical.
+
+## Install from source
+
+```bash
+git clone https://github.com/IsuruMaduranga/one-code
+cd one-code
+npm install
+cd ..
+pi install ./one-code
+pi list
+```
+
+Run `npm install` before the path install so the dependencies are present.
+`pi list` confirms the package registered.
+
+## Check the installation
+
+```bash
+onecode --version    # prints the app version and the pi version inside it
+onecode doctor       # prints the setup report; exits 1 when no provider is ready
+```
+
+Inside a session, `/doctor` runs the full checkup. See
+[Check your setup with doctor](doctor.md).
+
+## Update
+
+The bundled app checks npm once a day when a session starts and shows a
+notice with the matching upgrade command when a newer version exists:
+
+```bash
+npm install -g @one-ai/one-code      # npm installs
+brew upgrade one-code                # Homebrew installs
+```
+
+Set `ONECODE_NO_UPDATE_CHECK=1` to skip the check; `--offline` skips it too.
+On your own pi, update with `pi update --extensions`.
+
+Both packages are released together with the same version number.
+
+## Uninstall
+
+```bash
+npm uninstall -g @one-ai/one-code    # or: brew uninstall one-code
+rm -rf ~/.onecode                    # One Code's state, including pi's under the app
+```
+
+On your own pi, run `pi remove one-code-extension` (or remove the package
+entry from pi's settings). Removing `~/.onecode` deletes One Code's
+settings, approvals, plan files, and, under the bundled app, pi's sessions
+and credentials. Memory files stay in `~/.claude/projects/`, because they
+are shared with Claude Code.
+
+## Next step
+
+Connect a provider and choose a model in
+[Providers and models](providers-and-models.md).

package/docs/guide/permissions-modes-and-auto-mode.md

@@ -0,0 +1,450 @@
+# Permissions, modes, and auto mode
+
+Every tool call the model makes passes through One Code's permission gate
+before it runs. This page explains the permission modes, how to switch
+between them, how to write rules, what the approval prompt offers, and how
+plan mode and auto mode change what needs your approval.
+
+For the security guarantees and the known gaps, read
+[A boundary, not a promise](#a-boundary-not-a-promise) at the end of this
+page before you rely on auto mode for unattended work.
+
+## How a decision is made
+
+For each tool call, the gate checks the following in order:
+
+1. **Protected paths.** A write to a protected file or directory (see
+   [Protected paths](#protected-paths)) is never approved automatically. In
+   auto mode it goes to the classifier; in other modes it prompts you.
+   Allow rules do not cover protected paths.
+2. **`deny` rules.** A matching `deny` rule blocks the call. `deny` always
+   wins.
+3. **`ask` rules.** A matching `ask` rule prompts you, even in a mode that
+   would otherwise approve the call.
+4. **`allow` rules.** A matching `allow` rule approves the call without a
+   prompt.
+5. **The mode's default.** Anything no rule covers is decided by the current
+   permission mode.
+
+A handful of tools are always allowed because other tools sit behind them:
+`tool_search`, `skill`, `Agent`, `SendMessage`, `list_agents`, `workflow`,
+`ask_user_question`, `lsp_diagnostics`, `list_mcp_resources`, the task-list
+tools, `schedule_wakeup`, and the plan-mode tools. The tool calls these
+tools make in turn (a subagent's own edits, for example) are still gated.
+
+## Permission rules
+
+One Code reads `allow`, `deny`, and `ask` rules from the same files Claude
+Code uses, plus its own:
+
+| File | Scope |
+|---|---|
+| `~/.claude/settings.json` | Your user-wide Claude Code rules. Read only. |
+| `~/.onecode/settings.json` | Your user-wide One Code rules. `/allow … global` writes here. |
+| `.claude/settings.json` and `.claude/settings.local.json` | The project's rules. Read only. Allow rules from these files need your approval once; see [Trusting a project](#trusting-a-project). |
+| `~/.onecode/projects/<slug>/settings.json` | One Code's per-repository rules. `/allow` writes here. |
+| Managed settings | Organization-wide rules, when present. Read only. |
+
+Rules match tools by name and, optionally, by argument. Claude Code's
+PascalCase tool names (`Bash`, `Read`, `Edit`, `WebFetch`, `Task`, and the
+rest) work in these rules, so a setup you wrote for Claude Code applies as
+it is. For the mapping from Claude Code names to One Code's tool names, see
+[Tools](tools.md#claude-code-tool-names).
+
+A rule naming an MCP server, such as `mcp__github`, covers every tool that
+server provides. A rule naming a single MCP tool, such as
+`mcp__github__create_issue`, covers only that tool.
+
+### Bash rule patterns
+
+Bash rules follow Claude Code's matching rules:
+
+- `Bash(npm test)` matches that exact command line.
+- `Bash(npm test:*)` matches `npm test` and any command that starts with
+  `npm test` followed by a space. It does not match `npm tests` or
+  `npm test:unit`; write `Bash(npm test:unit:*)` for the latter.
+- `Bash(git * --dry-run)` uses `*` as a wildcard anywhere in the line. Write
+  `\*` for a literal asterisk and `\\` for a literal backslash.
+
+`deny` and `ask` rules are matched against every form of a command line, so
+they are hard to sidestep. They apply when they match the raw line, any
+subcommand of a compound line (`&&`, `||`, `;`, `|`, `&`, or a newline), or
+the payload of a wrapper. Wrappers such as `env`, `command`, `nice`,
+`timeout`, and `xargs` are peeled, `sh -c '…'` and the other shells are
+expanded, and the command word is reduced to its lowercased basename, so
+`/bin/rm`, `\rm`, and `RM` all match a rule written for `rm`.
+
+`allow` rules are matched against the literal spelling only, and a compound
+command line is allowed only when an `allow` rule covers every one of its
+subcommands, or when an exact rule matches the whole line. A line that
+contains command substitution (`$(…)` or backticks), `eval`, `exec`, a pipe
+into an interpreter, or a base64 decode is never covered by a prefix or
+wildcard `allow` rule.
+
+### Add a rule during a session
+
+To add an allow rule for the current repository, run:
+
+```
+/allow Bash(npm test:*)
+```
+
+Add `global` at the end to save it for every repository instead:
+
+```
+/allow Bash(npm test:*) global
+```
+
+To review the current mode and every loaded rule, including which project
+rules are trusted and which rules could not be parsed, run `/permissions`.
+
+Rules One Code adds are saved under `~/.onecode`, never under `~/.claude`.
+
+## Permission modes
+
+A mode sets the default answer for actions no rule covers. **Auto is the
+default**, matching Claude Code: a classifier approves routine actions and
+stops risky ones, so you are not prompted for every step.
+
+| Mode | Badge | What it does |
+|---|---|---|
+| Manual | `⏸ manual mode on` | Prompts for anything not already allowed. The `--permission-mode` value is `default`. |
+| Accept edits | `⏵⏵ accept edits on` | File edits inside the working directory run without a prompt. Everything else still prompts. The flag value is `acceptEdits`. |
+| Plan | `⏸ plan mode on` | Read-only investigation plus one plan file. See [Plan mode](#plan-mode). The flag value is `plan`. |
+| Auto | `⏵⏵ auto mode on` | A classifier screens each action. See [Auto mode](#auto-mode). The flag value is `auto`. |
+| Bypass permissions | `⏵⏵ bypass permissions on` | Runs everything without prompts, including writes to protected paths. The flag value is `bypassPermissions`; `--dangerously-skip-permissions` also selects it. |
+| Don't ask | `⏵⏵ don't ask on` | Never prompts. Anything that would have prompted is denied instead. The flag value is `dontAsk`. |
+
+The current badge appears in the banner and is announced when the mode
+changes.
+
+### Cycle modes with ctrl+q
+
+Press **ctrl+q** to cycle through manual, accept edits, plan, and auto.
+Two modes join the cycle only under conditions:
+
+- **Auto** appears only when a model that can run the classifier is
+  available. With no provider connected, the cycle skips it.
+- **Bypass permissions** appears only when the session started in it.
+
+**Don't ask** is never in the cycle; reach it with the `--permission-mode`
+flag or a settings file.
+
+Claude Code cycles modes with shift+tab. One Code cannot use that key
+because pi reserves it for the reasoning-effort dial. On Windows and WSL,
+pi's own default keybindings also use ctrl+q to queue a follow-up message.
+If the two conflict there, change pi's binding in its keybindings file.
+
+### Choose the starting mode
+
+To start one session in a different mode, pass `--permission-mode`:
+
+```bash
+onecode --permission-mode plan
+```
+
+For a reusable shortcut, add an alias to your shell configuration:
+
+```bash
+alias onecode-manual='onecode --permission-mode default'
+```
+
+For a persistent default, One Code reads `permissions.defaultMode` from your
+Claude Code settings files. Merge this into the existing object:
+
+```json
+{
+  "permissions": {
+    "defaultMode": "default"
+  }
+}
+```
+
+The scopes are not equal:
+
+- **User scope** (`~/.claude/settings.json`) and **managed settings** can
+  set any mode.
+- **Project scope** (`.claude/settings.json` and `.claude/settings.local.json`)
+  can set `default`, `acceptEdits`, `plan`, or `dontAsk`. It cannot set
+  `auto` or `bypassPermissions`; a checked-in file must not be able to turn
+  off approvals for whoever clones it.
+- A `defaultMode` in `~/.onecode/settings.json` has no effect.
+
+The `--permission-mode` flag takes precedence over every configured default.
+
+To make bypass mode impossible from any source, set
+`permissions.disableBypassPermissionsMode` to `"disable"` in any scope. One
+Code then refuses bypass whether it was requested by flag or by settings.
+
+The mode you choose during a session persists across `/clear`. A session
+you resume later starts in the configured default, not in the mode it was
+in when it ended.
+
+## The approval prompt
+
+When an action needs your decision, a prompt shows the tool, its arguments,
+and these choices:
+
+- **Yes.** Run it this once.
+- **Yes, and don't ask again … this session.** Approve this action and
+  similar ones until the session ends. The scope of "similar" depends on the
+  action:
+  - A command: only that exact command line, never a pattern.
+  - A file inside the working directory: that tool anywhere in the working
+    directory.
+  - A file outside the working directory: that tool within the file's
+    directory only.
+  - A URL: that host.
+- **No, tell the agent what to do differently.** Deny it, with an optional
+  note that is passed to the model as the reason.
+
+The "don't ask again" option is not offered for protected paths, for writes
+that the auto-mode safety floor caught, or in auto mode. Session grants never
+apply in auto mode and are cleared when the session ends.
+
+In non-interactive runs (`-p` and `--mode json`) nothing can prompt, so an
+action that would have prompted is denied and the model is told why.
+
+## The working directory boundary
+
+Reads and edits are confined to the working directory by default:
+
+- Reading a file inside the working directory is allowed in every mode.
+  Reading outside it prompts in manual mode, goes to the classifier in auto
+  mode, and is denied in don't-ask mode.
+- Accept-edits mode approves edits only inside the working directory.
+- The harness's own session directories count as inside: the auto-memory
+  folder, the session scratchpad, persisted tool output, and the plan file.
+
+Paths are compared after resolving symlinks, so a symlink inside the project
+that points outside it counts as outside.
+
+In auto mode, a shell command that reads outside the working directory, a
+bare `env`, or a `printenv` is never treated as safe by the deterministic
+check and always goes to the classifier.
+
+## Protected paths
+
+Writes to these paths are never approved automatically in any mode other
+than bypass, and allow rules do not cover them.
+
+Protected directories, including everything inside them:
+
+`.git`, `.config/git`, `.vscode`, `.idea`, `.husky`, `.cargo`,
+`.devcontainer`, `.yarn`, `.mvn`, `.claude`, `.onecode`,
+`Library/LaunchAgents`, `.config/fish`, `.local/bin`.
+
+`.claude/worktrees` and `.onecode/plans` are ordinary working space and are
+exempt.
+
+Protected files:
+
+Shell startup files (`.bashrc`, `.bash_profile`, `.bash_login`,
+`.bash_aliases`, `.bash_logout`, `.zshrc`, `.zprofile`, `.zshenv`, `.zlogin`,
+`.zlogout`, `.profile`, `.envrc`), git files (`.gitconfig`, `.gitmodules`),
+package-manager files (`.npmrc`, `.yarnrc`, `.yarnrc.yml`, `.pnp.cjs`,
+`.pnp.loader.mjs`, `.pnpmfile.cjs`, `bunfig.toml`, `.bunfig.toml`), build
+files (`.bazelrc`, `.bazelversion`, `.bazeliskrc`, `gradle-wrapper.properties`,
+`maven-wrapper.properties`), hook runners (`.pre-commit-config.yaml`,
+`lefthook.yml`, `lefthook.yaml`, `.lefthook.yml`, `.lefthook.yaml`), and
+tool configuration (`.devcontainer.json`, `.ripgreprc`, `pyrightconfig.json`,
+`.mcp.json`, `.claude.json`, `managed-settings.json`).
+
+pi's agent directory, Claude Code's configuration directory, and One Code's
+state directory are protected wherever they are, including when relocated
+by an environment variable.
+
+## Trusting a project
+
+Some project-provided configuration can run code or widen permissions, so
+One Code asks you once per project before using it. Each approval is
+remembered under `~/.onecode` together with a hash of the configuration, so
+a change to the configuration asks again. Declining is remembered for the
+current session only.
+
+| What | When you are asked | Stored in |
+|---|---|---|
+| Hooks in `.claude/settings.json` or `.claude/settings.local.json` | At startup: "Run this project's hooks?", listing each command. | `~/.onecode/hooks/project-approvals.json` |
+| MCP servers in `.mcp.json` | At startup, for each new server. See [MCP servers](skills-plugins-and-mcp.md#mcp-servers). | `~/.onecode/mcp/project-approvals.json` |
+| `permissions.allow` rules in the project's settings files | The first time such a rule would decide a call: "Trust this repository's allow rules?" | `~/.onecode/permissions/project-allow-approvals.json` |
+
+`deny` and `ask` rules from a project never prompt; they only tighten the
+gate. Hooks and servers from your user settings, managed settings, or an
+installed plugin never prompt either, because installing them was the
+consent.
+
+## Plan mode
+
+Plan mode lets the model investigate and write a plan without changing your
+code. Only read-only tools and edits to one plan file are available.
+
+- The plan file lives at `~/.onecode/plans/<name>.md`, where the name is a
+  random three-word slug. The same file is reused when you resume the
+  session or switch branches in `/tree`.
+- The model is reminded to explore with the `explore` agent, design with the
+  `plan` agent, and then write the plan.
+- You can read and edit the plan file yourself while the model works.
+
+Enter plan mode by cycling to it with **ctrl+q**, by starting with
+`--permission-mode plan`, or by asking the model to plan first (it can call
+`enter_plan_mode` itself).
+
+When the model finishes, it calls `exit_plan_mode` and an approval dialog
+shows the plan. Nothing runs until you choose. The choices are:
+
+1. **Approve and return to the mode you were in** before planning, when that
+   mode is available.
+2. **Approve into auto mode**, when a classifier model is available.
+3. **Approve into accept-edits mode.**
+4. **Approve into manual mode.**
+5. **Keep planning.** No mode change; the model refines the plan file.
+
+The initial highlight is the option that restores your previous mode, or
+manual mode when that is not offered. It never lands on a more permissive
+option by default. Press the number of a choice to pick it directly, or
+**Esc** to keep planning.
+
+In a non-interactive run there is no one to approve, so `exit_plan_mode`
+refuses and the session stays in plan mode with the plan on disk.
+
+## Auto mode
+
+Auto mode removes routine approval prompts without removing the boundary.
+It combines a deterministic first pass with Claude Code's own two-stage
+classifier.
+
+### What is approved without a classifier call
+
+- Actions a deterministic analysis proves safe. Read-only shell commands
+  inside the working directory are the common case. This analysis can only
+  ever conclude "safe"; anything it cannot parse or recognize goes to the
+  classifier rather than through.
+- Edits and writes to files inside the project that are not credential
+  files, not protected paths, and not files that run code on their own
+  (build wrappers, CI workflows, editor auto-run configuration).
+- Deleting or resetting files inside the project **when git can recover
+  them**. A tracked, committed file can be restored, so removing it is
+  approved. An untracked or modified file cannot, so removing it goes to
+  the classifier. Claude Code trusts the whole project directory here; One
+  Code checks recoverability first.
+
+### What goes to the classifier
+
+Everything else: destructive commands git cannot undo, anything that
+reaches outside the project, network-affecting commands, writes to
+protected paths, and reads outside the working directory.
+
+The classifier is Claude Code's two-stage ruleset, embedded verbatim:
+
+1. **Stage 1** grades harm only, on a 0 to 100 scale. Below 50 the action
+   is allowed and nothing more runs.
+2. **Stage 2** runs when stage 1 scores 50 or above. It weighs the user's
+   stated intent and the allow list, and either approves or blocks with a
+   named rule.
+
+Verdicts are checked before they are acted on. A block must cite a real
+rule from the ruleset. An approval based on intent must quote your own
+words from the conversation. A classifier that cannot be reached, times
+out, or returns something unparseable blocks the action; a gate that cannot
+consult its classifier approves nothing.
+
+A blocked action is reported to the model with the reason so it can choose
+a safer route. You are not prompted per action while auto mode runs. After
+repeated blocks in a row, auto mode pauses and the next action prompts you;
+approving it resumes auto mode.
+
+Allow rules that are broad enough to pre-approve arbitrary execution, such
+as `Bash(*)`, a wildcarded interpreter, or a rule that allows delegation to
+subagents, are suspended in auto mode so they cannot bypass the classifier.
+Session grants from the approval prompt do not apply in auto mode either.
+
+### The classifier model
+
+The classifier runs on a model from the same provider as your session,
+chosen automatically as the cheapest model that is at least as capable as
+the floor: a Sonnet-class model when your session runs a Sonnet-class or
+stronger model, a Haiku-class model otherwise. A weak classifier is a
+measurably weaker boundary; in testing, a Haiku-class classifier scored an
+explicitly requested recursive delete far below the block threshold that a
+Sonnet-class classifier applied to the same command.
+
+To choose the classifier yourself, run `/auto-mode model <provider/model-id>`.
+`/auto-mode model clear` returns to automatic selection. The choice is saved
+to `~/.onecode/settings.json`. When auto mode is active, the banner shows
+the classifier in use.
+
+### The safety floor
+
+A deterministic floor protects the gate's own configuration regardless of
+what the classifier or the model decides. A write to any of these files
+never reaches the classifier; it prompts you in an interactive session and
+is blocked in a non-interactive one:
+
+- `.claude/settings.json` and `.claude/settings.local.json` anywhere
+- `~/.onecode/settings.json` and any `~/.onecode/projects/<slug>/settings.json`
+- `~/.claude.json`
+- Managed settings files
+
+### Configure auto mode
+
+Run `/auto-mode` (or `/auto-mode config`) to see the effective
+configuration: the files it was read from, the environment description,
+any extra rules, and which classifier model is in use.
+
+Run `/auto-mode setup` to have a model draft a configuration for your
+environment. It asks how you use One Code here, offers to scan recent shell
+history for evidence, proposes an environment description and extra rules,
+and saves them to `~/.onecode/settings.json` only when you approve. It also
+audits your allow rules and offers to remove any that are broad enough to
+bypass the classifier.
+
+The configuration keys, under `autoMode`, follow Claude Code's own schema:
+
+| Key | Type | Effect |
+|---|---|---|
+| `environment` | string array | Describes your environment to the classifier, replacing Claude Code's default description. Include `"$defaults"` to keep the defaults and add to them. |
+| `hard_deny` | string array | Extra rules that always block. Appended to Claude Code's built-in list; the built-ins cannot be removed. |
+| `soft_deny` | string array | Extra rules that block unless you explicitly asked for the action. |
+| `allow` | string array | Extra rules that approve. |
+| `classifyAllShell` | boolean | Send every shell command to the classifier, even ones a narrow allow rule covers. |
+| `classifierModel` | string | The classifier model, as `provider/model-id`. |
+| `logDecisions` | boolean | Append every gate decision to `auto-mode-decisions.jsonl` next to the session files. |
+
+One Code reads `autoMode` from `~/.claude/settings.json`,
+`~/.onecode/settings.json`, and managed settings. It never reads `autoMode`
+from a project's `.claude/settings.json` or `.claude/settings.local.json`,
+because a checked-in file must not be able to loosen the classifier for
+whoever clones it. `classifierModel` is read only from `~/.onecode` and
+managed settings.
+
+To see the classifier's verdicts while you work, set `CC_AUTO_MODE_DEBUG=1`
+before launching; each decision is printed to stderr with its stage,
+severity, and rule.
+
+## A boundary, not a promise
+
+One Code's security model is the permission gate plus auto mode, not an
+assumption that the model behaves. Read these facts before you leave a
+session unattended:
+
+- **There is no operating-system sandbox.** The gate decides whether a
+  command runs; nothing constrains what an approved command can touch. For
+  an OS-level wall, run One Code inside a container. The gate and the
+  container work together.
+- **Bypass mode bypasses everything**, including protected paths. Claude
+  Code keeps its protected-path checks active even under
+  `--dangerously-skip-permissions`; One Code does not.
+- **Auto mode is the default without a first-run consent step**, and
+  without the OS sandbox Claude Code pairs its own auto default with.
+- **A weak classifier is a weaker boundary.** Automatic selection applies a
+  floor, but a provider whose catalog has nothing stronger is screened by
+  what it has. One tested model family (GLM-5.3 and GLM-5.3 Flash) approved a
+  request to back up the project to an unnamed outside location, which the
+  ruleset says to block.
+- **A known, accepted gap:** 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 and are never classified. Write a `deny` rule for
+  the write tools too if a path must stay untouched.
+- The license carries an autonomous-execution notice: the permission rules,
+  classifier, and safety checks are best-effort measures, not guarantees.
+  Keep backups and version control of anything you care about.