@globant/coda-darwin-x64 1.0.0 → 1.2.0

package/assets/docs/guide-automate.md

@@ -67,9 +67,8 @@ fi
 | `-p` / `--prompt "…"` | The prompt to run |
 | `--prompt-file` / `-pf path` | Read the prompt from a file |
 | `--output text\|json` | Output format. `json` emits newline-delimited events — ideal for parsing in a pipeline |
-| `--auto-approve all\|none` | How to handle approval prompts headlessly. `all` approves everything (needed in CI); `none` denies and aborts on the first request |
+| `--auto-approve all\|none` | How to handle approval prompts headlessly. `all` auto-approves the ask tier (needed in CI — the un-relaxable catastrophic floor still refuses `rm -rf /`, `sudo`, etc.); `none` denies and aborts on the first request |
 | `--timeout ms` | Abort after N milliseconds. Default `0` = no limit. |
-| `--bash-security lvl` | Override the bash auto-approve level for this run (`safe`, `low`, `medium`, `high`). Affects which shell commands auto-run without a prompt. |
 | `--lastsession` | Resume the most recent session for this project (mutually exclusive with `--session-id`). |
 | `--tools default\|all\|*list*` | Limit available tools, e.g. `read,glob,grep` for a read-only run |
 | `--model` / `-m id` | Override the model for this run |
@@ -81,7 +80,9 @@ fi
 | `--base-url url` | Base URL for an ephemeral `openai-compat` / `ollama` run |
 | `--api-key key` | Ephemeral, run-only API key — held in memory, never persisted, redacted in logs |
 
-> **Approvals in CI.** In headless mode `--auto-approve` defaults to `all`, so CODA runs without stopping for prompts. Pass `--auto-approve none` if you instead want it to refuse anything that would need approval and abort on the first such request. For finer control over which shell commands run, also set `bash.autoApproveLevel` in `config.json` (it defaults to `high` in headless mode).
+> **Approvals in CI.** In headless mode `--auto-approve` defaults to `all`, so CODA runs without stopping for prompts. Pass `--auto-approve none` if you instead want it to refuse anything that would need approval and abort on the first such request. Headless runs default to the `auto` permission mode; set `permissions.defaultMode` in `config.json` to change it.
+
+> **A retired model in CI.** If the configured model has been removed or renamed on the provider, a headless run exits non-zero with a `/switch-model` hint rather than guessing. Set `CODA_MODEL_AUTOHEAL=1` to let it auto-switch to the closest available replacement (same provider/family; recorded on stderr) and keep running; a profile with `strictPin: true` is never auto-healed. See [FAQ](#faq) › "What happens if my model is removed or renamed?".
 
 ## Authenticating in batch mode
 
@@ -121,7 +122,7 @@ Always check the **exit code**: a non-zero status means the run failed (an error
 Unattended runs are safest when you limit what the agent can touch:
 
 - **Restrict tools** with `--tools` — e.g. `--tools read,glob,grep` for a read-only review that can't edit or run commands.
-- **Tune bash** with `--bash-security` (or `bash.autoApproveLevel` in config) so even an auto-approved run won't run beyond the tier you set.
+- **Set the permission mode** with `permissions.defaultMode` (or `--auto-approve` for a headless run) so an unattended run stays within the posture you choose.
 - **Cap runtime** with `--timeout` so a stuck run can't hang the pipeline.
 
 ## What batch mode can't do

package/assets/docs/guide-changes.md

@@ -14,14 +14,13 @@ For how checkpoints work in detail — the shadow repo, Git requirements, and ho
 
 When CODA wants to run a shell command, it shows you what it's about to execute and waits for your approval — press **Y** to allow it or **N** to skip it. By default, CODA auto-approves low-risk commands (like `git status` or `cat`) and asks before anything that writes or deletes files.
 
-How much runs without asking depends on your **bash approval level**, which you set from `/settings` → **Bash Tool Preferences**:
+How much runs without asking depends on your **permission mode**, which you cycle with **Ctrl+P** or set via `permissions.defaultMode`:
 
-| Level | What it auto-approves |
+| Mode | What it allows |
 | --- | --- |
-| `safe` | Read-only commands only (`ls`, `cat`, `git status`) |
-| `low` | Safe commands plus low-risk writes — `mkdir`/`touch`/`cp`, package installs/tests, `git add`/`commit`/`checkout`/`stash`/`switch`/`restore` (**default**) |
-| `medium` | Adds riskier operations — `mv`/`rm`, `git push`/`pull`/`merge`/`rebase`/`reset`, `chmod`/`chown` |
-| `high` | Everything except clearly destructive operations (`rm -rf /`, disk format) |
+| `read-only` | Reads only — file reads and searches; no edits and no commands that change anything |
+| `default` | Auto-approves safe reads and in-`cwd` edits, but asks before risky actions — `git commit`, edits outside the working directory, and overwriting a file it never read this session (**default**) |
+| `auto` | Hands-off — runs without asking; only the un-relaxable catastrophic floor (`rm -rf /`, `sudo`, fork bombs) and managed-policy denials still refuse |
 
 See [Configuration](#configuration) for more on adjusting this per project.
 
@@ -97,5 +96,5 @@ If your project has an `AGENTS.md` with a "quality gate" section, CODA follows i
 ## See also
 
 - [Sessions & Checkpoints](#sessions) — the shadow repo, drift detection, and what a snapshot captures.
-- [Permissions & Approvals](#permissions) — bash approval levels and the anti-clobber guard in depth.
-- [Configuration](#configuration) — set your default approval level and composer behavior.
+- [Permissions & Approvals](#permissions) — permission modes and the anti-clobber guard in depth.
+- [Configuration](#configuration) — set your default permission mode and composer behavior.

package/assets/docs/guide-collaborate.md

@@ -64,7 +64,7 @@ The most valuable things to share live in the repo and apply to everyone who clo
 A project-level `<project>/.coda/config.json` is also **safe to commit** — it never holds secrets (those live in `~/.coda/.secrets`, which is never committed). But be selective about what you put there:
 
 - **Don't commit the active provider.** Which provider you use (a specific Glob.AI OS instance, or a local Ollama) is a personal, machine-specific choice, and provider profiles are defined in each developer's own global config. Pinning it in the repo can break teammates who don't have that profile.
-- **Think twice before committing an elevated bash approval level.** Raising `autoApproveLevel` for the whole project means everyone who clones the repo runs more commands without being asked — a safety trade-off your team should agree on first.
+- **Think twice before committing an elevated permission mode.** Setting `permissions.defaultMode: "auto"` in the project's `.coda/config.json` means everyone who clones the repo runs more commands without being asked — a safety trade-off your team should agree on first.
 
 In short: share **conventions and workflows**, keep **personal and security preferences** local.
 

package/assets/docs/how-it-works.md

@@ -21,7 +21,7 @@ CODA picks which tools to use automatically based on the task. You don't need to
 
 Each turn runs a loop: CODA reads your message, decides on the next action, calls one or more tools, observes the results, and repeats — until the task is done or it needs your input. A few properties of this loop are worth knowing:
 
-- **It pauses for approval** before risky actions (shell commands above your level, overwriting an unread file). See [Permissions & Approvals](#permissions).
+- **It pauses for approval** before risky actions (shell commands your permission mode or rules gate to `ask`, overwriting an unread file). See [Permissions & Approvals](#permissions).
 - **It has a step budget.** A single turn is capped at a maximum number of loop steps (`maxSteps`, default 300) so a runaway turn can't loop forever. You'll rarely hit this in normal use.
 - **You can interrupt it.** Press **Esc** to stop the loop mid-turn and redirect.
 - **It can delegate.** For big or parallelizable work, the loop can spawn child [agents](#agents) or a [workflow](#workflows) instead of doing everything inline.
@@ -68,6 +68,7 @@ Model calls don't always succeed — providers rate-limit, time out, or return t
 - **Retries with guidance** when the model can fix it — for example, telling it exactly which tool arguments were wrong — and **backs off with jitter** (honoring any `Retry-After`) within a bounded per-turn budget.
 - **Continues a truncated answer** that hit the output-length cap, resuming where it stopped.
 - **Fails over** to your configured `fallback` model when a provider keeps failing, with a circuit breaker so it stops hammering a service that's down.
-- **Escalates immediately** for problems retrying can't fix — auth failures, content-policy blocks, hard quota/billing limits, and model-unavailable errors (when the model has been removed or renamed on the provider) — surfacing a clear classified message.
+- **Heals a retired model** — if your configured model has been removed or renamed on the provider, CODA finds the closest available replacement (same provider and family) instead of just failing. Interactively it opens the model picker pre-selected to the recommendation, naming the retired id; a headless run auto-heals only when you set `CODA_MODEL_AUTOHEAL` (otherwise it exits non-zero with a `/switch-model` hint, so nothing changes silently). Pin a profile with `strictPin: true` to opt out and always be asked. On a provider without a live catalog (e.g. local Ollama), or when nothing suitable exists, you get a clear switch-model message. See [Configuration Reference](#config-reference) › "modelResilience".
+- **Escalates immediately** for problems retrying can't fix — auth failures, content-policy blocks, and hard quota/billing limits — surfacing a clear classified message.
 
 In the TUI you'll see a live row like `↻ Backing off… / Failing over… / Continuing…` while this happens. You can tune how aggressively CODA retries with `errorHandling.posture` (`conservative` / `balanced` / `aggressive`) and set `fallback.enabled: true` along with `fallback.provider` (and optionally `fallback.model`) to opt in to failover — see [Configuration Reference](#config-reference).

package/assets/docs/index.md

@@ -29,7 +29,7 @@ If you are brand new, read these in order:
 - [Commands & Flags](#cli-reference) — every slash command and shell flag.
 - [Keyboard Shortcuts](#shortcuts) — TUI key bindings.
 - [Tools Reference](#tools-reference) — the built-in tools the agent can call.
-- [Permissions & Approvals](#permissions) — the human-in-the-loop model and bash approval levels.
+- [Permissions & Approvals](#permissions) — the human-in-the-loop model and permission modes.
 - [Sessions & Checkpoints](#sessions) — resuming work and undoing changes.
 
 ### Task guides

package/assets/docs/overview.md

@@ -65,7 +65,7 @@ Every turn follows the same shape. Understanding it makes CODA predictable:
 1. **You send a message.** CODA snapshots your files (a checkpoint) before doing anything.
 2. **It reasons and plans.** For non-trivial work it sketches the steps first.
 3. **It calls tools.** Reading files, searching, editing, running shell commands — one or more at a time.
-4. **It pauses for approval** before anything risky (a shell command above your approval level, or overwriting a file it never read). You answer with a single key.
+4. **It pauses for approval** before anything risky (a shell command your permission mode or rules gate to `ask`, or overwriting a file it never read). You answer with a single key.
 5. **It summarizes** what changed and why, then hands the turn back to you.
 
 At any point you can press **Esc** to interrupt and redirect — that is almost always faster than letting it finish and undoing the result.

package/assets/docs/permissions.md

@@ -1,6 +1,8 @@
 # Permissions & Approvals
 
-CODA can read files, run shell commands, and edit your code — but it asks before doing anything risky. This human-in-the-loop (HITL) design keeps you in control: CODA proposes an action, you approve or skip it, and nothing irreversible happens behind your back.
+CODA can read files, run shell commands, and edit your code — but it asks before doing anything risky. Every tool call goes through an always-on **authorization engine** that decides `allow` / `ask` / `deny`. This human-in-the-loop (HITL) design keeps you in control: CODA proposes an action, you approve or skip it, and nothing irreversible happens behind your back.
+
+Rules and modes combine to form a layered safety net — you stay in control even when the agent runs largely on its own. This page covers the permission modes, the easy plain-English way to change permissions (`propose_policy`), the rule syntax the agent writes for you, how decisions are made, and the un-relaxable catastrophic floor.
 
 ## How approvals work
 
@@ -11,65 +13,267 @@ When CODA wants to do something that could change your system, it pauses and sho
 
 Some prompts are **questions** rather than yes/no approvals — for example when a tool needs you to pick from a numbered list or type a short answer. There you type your choice (or the number) and press **Enter**.
 
-How often CODA stops to ask depends on your settings. The goal is to auto-approve the safe, routine things (reading files, listing directories) and pause on the things that write, delete, or reach outside your project.
+How often CODA stops to ask depends on your **permission mode** and your **rules** (below). The goal is to auto-approve the safe, routine things (reading files, listing directories) and pause on the things that write, delete, or reach outside your project.
+
+## Permission modes
+
+The main approval control is the **permission mode** — the master dial that sets the agent's default level of autonomy. Press **Ctrl+P** to cycle the session between three modes; set the default with `permissions.defaultMode` in your config (globally in `~/.coda/config.json`, or per project in `.coda/config.json`).
+
+The three valid values are `"read-only"`, `"default"`, and `"auto"`.
+
+| Mode | What runs without asking | What asks | What's refused |
+| --- | --- | --- | --- |
+| **read-only** | Reads & inspections only (`cat`, `ls`, `git log`, `grep`, `Get-Content`, `dir` …) | — | Everything that changes state — writes, mutators, **and code-exec/build** (`python -c`, `node -e`, `cargo build`) |
+| **default** | Reads, plus edits **inside your project** (`Edit`/`Write` in the cwd) | Risky commands (`git commit`, out-of-cwd edits, overwriting an unread file), MCP tools not covered by a rule | Destructive ones — unless you add an `allow` rule |
+| **auto** | Reads, edits, and risky commands — for unattended / CI runs | — | Only catastrophic actions (the un-relaxable floor, below) |
+
+- **read-only** allows a command *iff* it is positively classified read-safe (a curated read or inspector), on bash, PowerShell, **and** cmd alike. Interpreters, build/test verbs (`cargo build`, `tsc`, `go test`), and mutators are **not** read-safe — they are refused, even though a build isn't a "write."
+- **default** is the shipped mode. It auto-approves an in-project `Edit`/`Write` (as long as the file was read this session, or is brand new) but still asks for edits outside the cwd, risky bash, overwriting a file it hasn't read this session, and MCP calls with no explicit allow rule.
+- **auto** relaxes the `ask` tier to `allow` for hands-off runs — but the un-relaxable floor, managed policy, your own `deny`/`ask` rules, and sensitive-path protections still bite.
+
+> **Legacy mode aliases:** `"plan"` → `read-only`, `"acceptEdits"` → `default`, `"bypassPermissions"` or `"bypass"` → `auto`. These still work but the new names are preferred.
+
+**Mode is the fallback baseline** — explicit rules always take priority over it (see [precedence](#how-decisions-are-made-precedence)).
+
+### Sub-agents and mode inheritance
+
+When CODA spawns a sub-agent (for example to run a workflow), the sub-agent's mode can only be **equal to or more restrictive** than the parent's. A sub-agent can never widen the autonomy the parent runs under.
+
+## The easy way to change permissions: just ask the agent
 
-## Bash approval levels
+You rarely need to hand-edit `config.json` to change what the agent can do. The everyday way to loosen (or tighten) a permission is to **tell the agent in plain English**, right in the chat:
 
-The most common approval control is the **bash approval level** — it decides how many shell commands CODA can run without asking. Set it from `/settings` → **Bash Tool Preferences**:
+```
+Allow running pnpm commands
+Always allow git push to origin main
+Never allow rm -rf
+```
+
+CODA recognizes this as a request to change your permissions and calls its built-in **`propose_policy`** tool to draft the exact rule, then shows you the resulting change for approval before writing anything to disk. You don't need to know the rule-string syntax up front — the agent writes it for you (see [Rule syntax](#rule-syntax) if you'd rather write rules by hand).
 
-| Level | What it auto-approves |
+### When the agent needs permission it doesn't have
+
+When CODA tries to run something not covered by your policy, it pauses and shows a **HITL prompt** (e.g. `Allow bash: git push origin main?`). Your choices:
+
+| Choice | What it does |
 | --- | --- |
-| `safe` | Read-only commands only (`ls`, `cat`, `git status`) |
-| `low` | Safe commands plus low-risk writes — **default** |
-| `medium` | Most file operations and git commits |
-| `high` | Everything except clearly destructive operations (`rm -rf`, disk formatting) |
+| **Allow** (once) | Permits this single call. You'll be asked again next time. |
+| **Allow always** | Writes a permanent allow rule to your project config and proceeds. Shows a confirmation screen first. |
+| **Reject** | Blocks this specific call. The agent is told it was denied. |
+
+> **In headless / non-interactive mode:** any action that would trigger a prompt is automatically denied — you'll see `Denied — approval is required, but no operator is present`.
+
+### What denial messages look like
+
+When an action is blocked, CODA shows a structured reason:
+
+| Message | Cause |
+| --- | --- |
+| `Denied by rule policy` | An explicit `deny` rule matched |
+| `Denied — read-only mode does not allow this action` | The current mode blocks it |
+| `Denied — rm -rf / is a destructive system operation (cannot be overridden)` | A catastrophic floor block |
+| `Denied — git push --force is an irreversible git operation (data loss)` | Reversibility floor |
+| `Denied — writing to ~/.ssh/id_rsa (a credential / persistence path)` | Sensitive-path protection |
+| `Denied by a PreToolUse hook` | A lifecycle hook you configured rejected the call |
+| `Denied — this MCP server is not in the managed allowlist` | Organization managed policy block |
+
+CODA may also suggest up to 3 alternatives drawn from your existing allow rules — for example, if `git push` is denied it might suggest `git status` or `git log`.
 
-Even at `high`, commands that match CODA's blocked patterns still require explicit approval. Lowering the level is the safest choice when you're working in an unfamiliar or sensitive repo.
+### How `propose_policy` works
+
+Instead of just failing, the agent can proactively ask you to make a permanent permission change — either because you asked in plain English, or on its own initiative after being denied. It can propose:
+
+- **Add a rule** — e.g. always allow `git push origin main`, or always ask before `npm publish`.
+- **Remove a rule** — take away a previously added allow or deny rule.
+- **Change the permission mode** — switch between `read-only`, `default`, and `auto`.
+
+Every proposal has a **scope**: `project` (this repo only) or `global` (all your projects).
+
+The **direction** of the change decides what happens next:
+
+- **Tightening** (adding a `deny`, lowering the mode) applies on its own. It only ever removes capability, so there is nothing to approve.
+- **Widening** (an `allow`/`ask` rule, removing *any* existing rule, raising the mode) **always asks you first** — there is no mode, including `auto`, in which it applies by itself. The prompt may carry warning bullets such as `- Unlocks many commands`, `- Broader than what you asked about`, `- Targets a path outside your workspace`, or `- Won't take effect` (the rule can't override a hard floor).
+
+After you approve, the rule is written to your config and takes effect immediately in the running session.
+
+### What you actually approve
+
+The approval prompt does not repeat CODA's argument for the change; it shows a summary the engine computes from the rule itself:
+
+- what the rule would really let it do (a `Write(package.json)` grant reads as **create/overwrite**, not a vague "access"),
+- how broad it is, and which project or global config it lands in,
+- warnings for the risky shapes — unbounded grants, reaching outside your project, rules that apply in *all* your projects, or a look-alike command name using confusable characters,
+- and that the change is **permanent** — it is written to your config and applies in future sessions.
+
+So you are approving the *effect*, not the pitch. If the summary and the explanation disagree, trust the summary.
+
+A few limits worth knowing:
+
+- **You can say no.** Declining changes nothing, and CODA carries on with the action still blocked.
+- **Headless runs never auto-approve.** With no one to ask, a widening is simply refused (see [Approvals in headless (batch) mode](#permissions)).
+- **A repository can't grant itself more autonomy.** A project-scoped request to raise the permission mode is rejected outright, not offered to you.
+- **The protected set stays protected.** Proposing cannot reach the un-relaxable floor below, your organization's managed policy, or CODA's own control-plane files.
+
+Every proposal — applied, declined, or refused — is recorded in the authorization log, marked as agent-proposed.
+
+### Turning `propose_policy` off
+
+It is **on by default**. To stop the agent from ever suggesting permanent rule changes:
+
+| How | Effect |
+| --- | --- |
+| `"proposePolicy": false` under `permissions` in `config.json` | Off for that config's scope (global or project) |
+| `CODA_PROPOSE_POLICY` env var | Overrides config either way for one run: a truthy value (`1`, `true`, `yes`, `on`) forces it **on**; any other set value (`0`, `false`, `off`, …) forces it **off**. Blank/unset defers to config. |
+| Admin managed `disableProposePolicy` | Off fleet-wide, and **one-way** — neither `permissions.proposePolicy` nor `CODA_PROPOSE_POLICY` can switch it back on |
+
+## Rules — always-allow / always-ask / always-deny
+
+To pin a specific command regardless of mode, add rules under `permissions` in `config.json`:
+
+```jsonc
+"permissions": {
+  "defaultMode": "default",
+  "allow": ["Bash(git status)", "Bash(npm test)"],
+  "ask":   ["Bash(git push:*)"],
+  "deny":  ["Bash(rm:*)"]
+}
+```
 
-**Which level should I pick?**
+The engine is **deny-first**: an explicit `deny` always wins, then your `ask`, then your `allow` rules fill the gaps, then the permission mode decides everything else. So `cat file` reads freely, `git commit` asks in `default`, and an `allow Bash(git push:*)` lets pushes through without a prompt.
 
-- `safe` — auditing or read-only review, or any repo you don't fully trust yet.
-- `low` (default) — everyday development; CODA runs safe reads and low-risk writes (creating files, package installs, `git add`/`commit`) but asks before anything that moves or deletes.
-- `medium` — you're moving fast in a repo you know and are comfortable auto-approving `mv`/`rm`, `git push`/`reset`, and permission changes.
-- `high` — trusted, recoverable environments where you want minimal interruptions; still stops on clearly destructive commands.
+### Rule syntax
 
-**What is never auto-approved.** Regardless of level, commands matching CODA's blocked patterns — things like `rm -rf /`, disk formatting, or piping a remote script straight into a shell — always require an explicit **Y**. The approval level controls the *gray area*; the hard-block list is not negotiable by config.
+Most rules take the form `ToolName(subcommand-or-identifier:argument-pattern)`, but the grammar also accepts a **bare tool name** (no parentheses) and **MCP server/tool** rules. This is the same syntax `propose_policy` writes for you.
+
+| Rule string | Meaning |
+| --- | --- |
+| `Bash(git log:*)` | Any `git log` command (any arguments) |
+| `Bash(git push origin main)` | Exact match — only that command, no other arguments |
+| `Bash(npm:*)` | Any command starting with `npm` |
+| `Bash(npm install:*)` | Only commands starting with `npm install` |
+| `Bash(*)` | Any bash command at all |
+| `Bash` | **Bare tool name** — the whole tool, i.e. *every* command it can run. A bare `deny Bash` also removes the tool from the agent's tool list entirely. |
+| `Read(//etc/passwd)` | The absolute system path `/etc/passwd` |
+| `mcp__filesystem` | Any call to the `filesystem` MCP server |
+| `mcp__filesystem__read_file` | Only that one tool on that server |
+
+A bare tool name is the broadest possible rule for that tool — use it deliberately. It is most useful as a `deny` (`deny: ["Bash"]` turns bash off completely); as an `allow` it is a blanket grant.
+
+Beyond `Bash`, command rules can name a PowerShell dialect (`pwsh(...)`, `powershell(...)`) and file tools take glob specifiers (`Read`, `Edit`, `Write`, `Glob`, `Grep`, `MultiEdit`, `NotebookEdit`).
+
+Effect types: `allow` (permit, no prompt), `ask` (always prompt, even in `auto`), `deny` (always block, no exceptions). An invalid rule string is rejected at startup rather than silently ignored.
+
+> **Path gotcha:** a *single* leading slash in a file rule (`Read(/etc/passwd)`) is treated as *relative to your project root* (matching `<project>/etc/passwd`), **not** the real `/etc/passwd`. Use a **double slash** (`Read(//etc/passwd)`) for absolute filesystem paths. CODA warns when it detects this likely mistake on a `deny` rule.
+>
+> **Command gotcha — rules match the command name exactly as written.** `Bash(curl:*)` matches `curl` but **not** `/usr/bin/curl`. This holds for *both* directions, and it cuts differently for each:
+>
+> - As an **`allow`**, exactness is a safety property: `allow Bash(rm:*)` cannot be abused to run some other `rm` further up a path (`/tmp/evil/rm`).
+> - As a **`deny`**, it is a limitation you need to know about: `deny Bash(mytool:*)` does **not** block `/usr/local/bin/mytool` or `./sub/mytool`. A `deny` rule is a policy pin for the spelling you wrote, not an escape-proof block. If you need one command name blocked in every spelling, deny the paths too, or rely on the floor for the genuinely dangerous ones.
+>
+> The catastrophic floor and the built-in danger lists are **not** subject to this: they fold a command down to its base name, so `/bin/rm -rf /` is caught exactly like `rm -rf /`, however it is spelled.
+
+### Project-scoped vs. global-scoped rules
+
+| Scope | Config file written | Who it affects |
+| --- | --- | --- |
+| **project** | `<your-project>/.coda/config.json` | Only CODA sessions inside this repository |
+| **global** | `~/.coda/config.json` | Every CODA session you run, in any project |
+
+A project-scoped rule committed to the repo means teammates see the same rules. A project config can only make the permission mode **more** restrictive than your global or managed policy — never more permissive.
+
+## How decisions are made (precedence)
+
+When the agent wants to run a tool or command, CODA evaluates rules and mode in this strict order:
+
+1. **Explicit `deny` rules win first** — a `deny` in any config (global or project) blocks the call outright. `deny` rules from both files are *unioned*; nothing can override a deny.
+2. **Explicit `ask` rules** — if no deny matched, a matching `ask` prompts you before proceeding.
+3. **Explicit `allow` rules** — a match here proceeds without prompting.
+4. **The active mode** fills in anything not covered by a rule.
+5. **The catastrophic floor** clamps down last, unconditionally — it is applied *after* rules and mode precisely so that no `allow` rule and no mode (not even `auto`) can relax it. When several things in one command line disagree, the **most restrictive** outcome wins.
+
+```
+Incoming action
+  ↓
+[Deny rule matches?]   → YES → Blocked
+  ↓ NO
+[Ask rule matches?]    → YES → Prompt user
+  ↓ NO
+[Allow rule matches?]  → YES → Proceed
+  ↓ NO
+[Mode baseline]        → allow / ask / deny based on action type
+  ↓
+[Catastrophic floor]   → Always blocks certain dangerous actions
+```
+
+## The catastrophic floor — protections that can never be turned off
+
+Below every rule and every mode sits a fixed floor. These protections are **un-relaxable**: no `allow` rule, no `auto` mode, and no `--auto-approve all` can unlock them, and `propose_policy` cannot reach them either.
+
+> **A broad `allow` is a real grant — scope it tightly.** Allowing a command that reaches another machine hands over that capability in full. In particular, `allow Bash(ssh:*)` grants the agent **arbitrary command execution on the remote host**: CODA mediates only what runs *locally* (it still blocks reading your private key or exfiltrating a secret), but it cannot police what happens on the far side of an `ssh` session. Prefer specific rules (`Bash(ssh deploy@host:*)`) over blanket ones.
+
+### What is never auto-approved
+
+- **Self-protection** — writes to CODA's own control-plane files (`~/.coda/config.json`, project `.coda/config.json`, extension scripts) are blocked by shell command, file-write tool, redirect, or MCP call. The agent can't quietly widen its own permissions.
+- **Sensitive-path writes** — writing to credential/system paths (`~/.ssh/`, `authorized_keys`, `/etc/`, `.gitconfig`, `.git/config`, `.git/hooks/`) is always blocked.
+- **Secret reads (exfiltration)** — reading the *contents* of a private key or credential file (`cat ~/.ssh/id_rsa`, `cp ~/.aws/credentials …`, `Get-Content` on the same) is always blocked, and **not** relaxable — a broad `allow Bash(cat:*)` does not unlock it. Ordinary *config* files are unaffected: reading `~/.ssh/config`, `.bashrc`, or a project `.env` stays allowed, as do name/metadata-only checks like `test -f ~/.ssh/known_hosts`.
+- **Git remote code execution** — config injection that makes git silently run code (`git config core.hooksPath …`, `core.sshCommand`, `git rebase -x '… | sh'`, `git fetch ext::…`) is always blocked.
+- **Container escape** — flags that grant a container host access (`--privileged`, `-v /:/host`, mounting the Docker socket, `--pid=host`, `--cap-add SYS_ADMIN`/`ALL`) are always blocked. A plain `docker run` follows normal ask/allow logic.
+- **Shell-redirect abuse** — using `>`/`>>` to write into credential or system paths is always blocked, even with a broad allow rule.
+- **Catastrophic commands** — `rm -rf /`, disk formatting, `sudo`, fork bombs, `curl … | sh`, writes to raw devices, and their PowerShell/cmd equivalents.
+
+| Protection | Relaxable with a rule? | Blocked example |
+| --- | --- | --- |
+| Self-protection (permission config files) | **No** | `cp evil.json ~/.coda/config.json` |
+| Sensitive-path *writes* | **No** | `cp malicious .git/hooks/pre-commit` |
+| Secret / private-key *reads* | **No** | `cat ~/.ssh/id_rsa` |
+| Git RCE injection | **No** | `git config core.hooksPath /tmp/evil` |
+| Git irreversible history ops (`--force`, `reset --hard`) | Yes — with an explicit allow rule | `git push --force` |
+| Container escape flags | **No** | `docker run --privileged ubuntu` |
+| Credential redirect | **No** | `echo key >> ~/.ssh/authorized_keys` |
 
 ## Choosing the shell
 
-CODA runs bash commands through a shell you can pick from the same `/settings` → **Bash Tool Preferences** screen. The **shell mode** can be `auto` (let CODA detect the best option), or you can pin it to `bash`, `powershell`, or `wsl` — handy on Windows where the default isn't always what you want.
+CODA runs bash commands through a shell you can pick from `/settings`. The **shell mode** can be `auto` (let CODA detect the best option), or you can pin it to `bash`, `powershell`, or `wsl` — handy on Windows. The engine parses and classifies commands in whichever dialect actually runs them, so a decision on one shell matches the equivalent command on another.
 
 ## Other actions that ask first
 
-Bash isn't the only thing gated by approvals. CODA also pauses before:
+Bash isn't the only thing gated by approvals. In `default` mode CODA also pauses before:
 
-- **Overwriting a file it never read this session** — an anti-clobber guard. If CODA didn't read a file before writing to it, it asks first so it can't silently clobber work it hasn't seen.
-- **Consolidating memory** — when CODA rewrites its `MEMORY.md` notes, it asks before replacing them.
-- **MCP and other tools** — external tools you've connected may run their own approval logic; CODA always routes them through your MCP configuration.
+- **Overwriting a file it never read this session** — an anti-clobber guard, so it can't silently clobber work it hasn't seen.
+- **MCP and other tools** — external tools you've connected route through your MCP configuration and your rules; a managed policy can restrict which MCP servers are allowed at all.
+
+(Its own `memory` notes are always allowed — that's the agent's own state, not a change to your system.)
+
+## Managed (organization) policy
+
+Admins can ship a **managed policy** that everyone inherits: extra `deny` rules that can't be overridden locally, a locked permission mode (e.g. forbid `auto` via `disableAutoMode`), a restricted set of allowed MCP servers (`allowManagedMcpServersOnly`), a lockdown that drops non-managed `allow` rules (`allowManagedRulesOnly`), and a switch that turns off rule proposals entirely (`disableProposePolicy`). Managed rules sit above your personal config — a managed `deny` is final, and a managed `disableProposePolicy` cannot be switched back on by your config or by `CODA_PROPOSE_POLICY`.
 
 ## Approvals in headless (batch) mode
 
 Headless runs can't show you a prompt, so the rules are stricter and more autonomous by design:
 
-- The **`ask_user`** tool isn't available — there's no one to answer.
-- Bash defaults to a higher auto-approval tier so scripts don't hang waiting on input.
+- The **`ask_user`** tool isn't available — there's no one to answer, so it fails closed.
+- Any residual `ask` (something the mode would have prompted for) becomes a **`deny`** — a headless run never silently auto-approves an `ask`.
 
-You control this from the command line when you launch a batch run:
+You control the headless posture from the command line:
 
 ```bash
-# Set the bash approval level for this run
-coda -p "Run the test suite and report failures" --bash-security high
-
-# Auto-approve everything for a fully unattended run (this is the default when --auto-approve is omitted)
+# Auto-approve the ask tier for a fully unattended run (this is the default — maps to `auto`)
 coda -p "Format the codebase" --auto-approve all
 
-# Block all HITL requests — run fails immediately if any approval is needed
+# Fail-closed: any pending approval immediately aborts the run — useful for CI
 coda -p "Run the test suite and report failures" --auto-approve none
 ```
 
-When `--auto-approve` is omitted, headless runs default to `all`, meaning every HITL request is auto-approved. Pass `--auto-approve none` to do the opposite: any pending approval request immediately aborts the run with an error — useful for CI pipelines where silent auto-approval is unacceptable.
+When `--auto-approve` is omitted, headless defaults to `all` (→ `auto`). Even so, `--auto-approve all` does **not** run *everything*: the un-relaxable catastrophic floor, self-protection, sensitive-path protections, and managed `deny` rules still refuse `rm -rf /`, `sudo`, fork bombs, and the like. Pass `--auto-approve none` (→ `default`, fail-closed) when silent auto-approval is unacceptable.
+
+## Every decision is logged
+
+Every authorization decision — allowed, prompted, or denied — is recorded in CODA's structured log as an `authorization.decision` entry, including the tool name, the decision, the matched rule (if any), the active mode, and the denial category. Proposed policy changes are logged separately, capturing whether they were approved, rejected, or declined. Review these to understand every permission decision made during a session (see [View & Share Logs](#logging)).
 
-Use a high auto-approval tier only when you trust the prompt and the repo — an unattended run with `--auto-approve all` will not stop to ask, even for destructive commands.
+## Migrating from `bash.autoApproveLevel`
+
+Older configs used a `bash.autoApproveLevel` (`safe` / `low` / `medium` / `high`). That per-command risk tier is **retired** in favor of permission modes. On startup CODA migrates it once, in place: `high` → `permissions.defaultMode: "auto"`, and the more cautious `safe`/`low`/`medium` → `"default"`. You'll see a one-time note confirming the rewrite; after that the field is gone. (If your config has comments, CODA leaves it untouched and asks you to set `permissions.defaultMode` by hand.)
 
 ## Trust and external code
 
@@ -80,14 +284,55 @@ Approvals protect you from CODA's *own* actions. A separate concern is the **cod
 - **Keep approvals on** (don't blanket `--auto-approve all`) when running with untrusted extensions or MCP servers active.
 - **Don't put secrets into prompts or project files** that an untrusted extension could read.
 
+## Seeing what applies right now
+
+The rest of this page describes how permissions *work*. To see what is actually in
+force for you, in this project, run:
+
+```
+/permissions
+```
+
+It lists every allow / ask / deny rule and **where each one comes from** — your
+`~/.coda/config.json`, the project's `.coda/config.json`, or a managed policy your
+organization deployed — plus the current permission mode, any organization locks,
+and any "don't ask again" grants you approved in this session.
+
+Outside an interactive session — in CI, or to check a machine's policy without
+starting the agent — the same view is available as a command:
+
+```
+coda permissions
+```
+
+This is the right way to confirm what a **managed policy** actually permits on a
+given machine: it reads the same configuration a session would, so what it prints is
+what a session started in that directory would enforce.
+
+Both views are **read-only**. To change a rule, ask the agent (see the section
+"The easy way to change permissions: just ask the agent" above) or edit the config
+files described in "Where to set it" below.
+
+Two things to know when reading the output:
+
+- **Rules are only part of the policy.** The permission mode's baseline, the
+  per-command shell policy, and the catastrophic floor also apply to every call, and
+  are not rules that can be listed. The output says so explicitly — an empty rule
+  list does **not** mean "everything is allowed".
+- **A rule set in two places is listed once**, under the more authoritative one, with
+  a note like `(also set in your config)`.
+
 ## Where to set it
 
-- **From inside CODA:** `/settings` → **Bash Tool Preferences** (applies globally or per project).
-- **Per project:** project-level config overrides your personal defaults — see [Configuration](#configuration).
-- **For a single run:** the `--bash-security` and `--auto-approve` flags (see [Commands & Flags](#cli-reference)).
+- **See what applies first:** run `/permissions` (or `coda permissions` outside a session) — see the section "Seeing what applies right now" above.
+- **In the session:** press **Ctrl+P** to cycle the permission mode.
+- **Just ask:** tell the agent in plain English (`allow pnpm build`, `never allow rm -rf`) and it drafts the rule via `propose_policy` for your approval.
+- **Default / per project:** `permissions.defaultMode` and `permissions.allow`/`ask`/`deny` in `~/.coda/config.json` or a project's `.coda/config.json` (project config overrides your personal default) — see [Configuration](#configuration).
+- **For a headless run:** the `--auto-approve none|all` flag (see [Commands & Flags](#cli-reference)).
 
 ## See also
 
 - [Make Changes Safely](#guide-changes) — staying in control while CODA edits code.
 - [How CODA Works](#how-it-works) — tools, memory, and the agent loop.
 - [Configuration](#configuration) — where settings live and how they cascade.
+- [Tools Reference](#tools-reference) — the built-in tools the engine gates.

package/assets/docs/shortcuts.md

@@ -18,7 +18,6 @@ These shortcuts work inside the interactive TUI. Type `?` at any time to open th
 | `Ctrl+J` | Insert a newline without sending |
 | `↑` / `↓` | Navigate input history |
 | `/` | Open the slash command palette |
-| `@` | Attach a file — opens the file-path browser |
 | `?` | Open the keyboard-shortcuts overlay |
 
 > **Tip — attach screenshots.** Paste a path to an image file (or paste the image itself where your terminal supports it) and CODA picks it up as visual context — it shows a short `[Image N]` marker so you know it'll be sent. Useful for sharing a screenshot of an error or a UI mockup.
@@ -45,6 +44,11 @@ These shortcuts work inside the interactive TUI. Type `?` at any time to open th
 | Shortcut | Action |
 | --- | --- |
 | `Shift+Tab` | Cycle through favorite models |
+| `Ctrl+R` | Refresh the model catalog (inside the `/switch-model` picker) |
+
+The picker shows the catalog CODA loaded at startup. If you have just added or
+retired a model on your provider and want the list re-read from the server
+rather than from CODA's cache, press `Ctrl+R` while the picker is open.
 
 Mark models as favorites from the `/switch-model` picker; `Shift+Tab` then rotates through just that shortlist, so you can flip between (say) a strong reasoning model and a cheaper everyday one without opening a menu.
 

package/assets/docs/tools-reference.md

@@ -11,7 +11,7 @@ CODA builds a **tool registry** for each session. Which tools are available depe
 - **Agents** — delegation tools appear only when agents are enabled.
 - **Extensions and plugins** — these can register additional tools.
 
-Some tools pause for **approval** before doing something risky — see [Permissions & Approvals](#permissions). Headless runs use a stricter set: the `ask_user` tool isn't available, and bash defaults to a higher auto-approval tier.
+Some tools pause for **approval** before doing something risky — see [Permissions & Approvals](#permissions). Headless runs use a stricter set: the `ask_user` tool isn't available, and bash runs under the `auto` permission mode.
 
 To limit which tools a single run may use, pass `coda --tools …` (see [Commands & Flags](#cli-reference)).
 
@@ -22,13 +22,14 @@ To limit which tools a single run may use, pass `coda --tools …` (see [Command
 | `read` | Read file contents, with pagination and encoding handling |
 | `write` | Create or overwrite files; asks before overwriting a file it never read this session |
 | `edit` | Apply structured search-and-replace edits to existing files |
-| `bash` | Run shell commands, gated by risk tiers and approval prompts |
+| `bash` | Run shell commands, classified by capability and gated by your permission mode |
 | `glob` | Find files by path pattern (fast file finder) |
 | `grep` | Search file contents (powered by ripgrep) |
 | `think` | A lightweight scratchpad step the model can use to reason |
 | `memory` | Read or update `MEMORY.md` notes; consolidating can ask for approval |
 | `ask_user` | Ask you a question in the UI (interactive sessions only) |
 | `web_search` | Search the web (Glob.AI OS profiles with search configured) |
+| `webfetch` | Fetch a web page by URL and return it as markdown, plain text, or raw HTML |
 | `examine_images` | Analyze image files with a vision model (Glob.AI OS) |
 | `omni_parser` | Extract text and data from documents and media (Glob.AI OS) |
 | `mcp_execute` | Call a tool on an MCP server you've connected |
@@ -46,7 +47,7 @@ You never name a tool — CODA picks based on the task. A few patterns are worth
 - **To find text inside files**, it uses `grep` (ripgrep) rather than reading file after file.
 - **To read a known file**, it uses `read`, often with an offset/limit on large files.
 - **To change a file**, it prefers `edit` (surgical search-and-replace) over `write` (whole-file overwrite), and `write` asks before clobbering a file it never read this session.
-- **To run anything in your shell** — tests, linters, git — it uses `bash`, gated by your approval level.
+- **To run anything in your shell** — tests, linters, git — it uses `bash`, gated by your permission mode.
 - **For big or parallel work**, it may delegate with `run_agent` (see [Agents](#agents)) instead of doing it all inline.
 
 The search tools deserve special mention because they're the backbone of fast, accurate work: `glob` and `grep` let CODA locate the right code without loading the whole repo into context.
@@ -57,14 +58,55 @@ Tool behavior is configured in a few different places — some from the `/settin
 
 | Area | What you control | Where |
 | --- | --- | --- |
-| **Bash** | Approval level and shell mode — how often CODA asks before running commands, and which shell it uses. See [Permissions & Approvals](#permissions). | `/settings` → Bash Tool Preferences |
+| **Bash** | Permission mode (Ctrl+P / `permissions.defaultMode`) and shell mode — how often CODA asks before running commands, and which shell it uses. See [Permissions & Approvals](#permissions). | `Ctrl+P` / config (`permissions.defaultMode`) |
 | **Search** | Enable or disable `glob` and `grep`, the `grep` backend (ripgrep or fastgrep), and result limits. Ripgrep ships bundled — no separate install needed. | Config file (`tools.glob`, `tools.grep`) |
 | **Vision** | The model used by `examine_images`. | Config file (`vision.model`) |
 | **Web search** | The model used for web search (Glob.AI OS). | `CODA_WEBSEARCH_MODEL` env var (falls back to the built-in default) |
+| **Web fetch** | Backend order, URL blocklist/allowlist, provenance, and the model-backend timeout for `webfetch`. Disable it entirely, or deny it via a permission rule. See [Web fetch](#web-fetch) below. | Config file (`webfetch.*`) / `permissions.deny: ["WebFetch"]` |
 | **OmniParser** | How much extracted document text is inlined in a result vs written to `.coda/omni-parser/`. | `CODA_OMNI_PARSER_INLINE_THRESHOLD_CHARS` env var |
 | **MCP** | Which servers load — which in turn decides whether `mcp_execute` is useful. | The `/mcp` manager |
 | **Agents** | Whether the delegation tools exist, and how runs behave. See [Agents](#agents). | Config (`agents.*`) + the `/agents` manager |
 
+## Web fetch
+
+The `webfetch` tool retrieves the contents of an `http(s)` URL and hands it back as **markdown** (default), **plain text**, or **raw HTML**. It's a single, visible, permission-gated tool — one tool call, one approval prompt — with **two selectable backends** chosen by a preference order (`webfetch.order`), with automatic **runtime fallback** (if the first backend fails, the next available one runs):
+
+- **`client`** — a fetch CODA controls end-to-end, with SSRF protection (it pins the connection to the validated IP so a hostname can't rebind to a private/metadata address), a URL blocklist/allowlist, main-content extraction that strips nav/sidebar/footer chrome (with a guard that keeps the **whole page** for link-rich homepages and index pages), and HTML→Markdown conversion. Always available; no model call. This is the **default primary** backend.
+- **`anthropic`** — makes a call to a fixed model that runs the provider's server-side web-fetch tool and returns the parsed page. It handles content the client backend can't parse (notably **PDFs**), and is available only when a Glob.AI OS (GEAI) profile is configured. Used as the fallback by default.
+
+The default order is **`["client", "anthropic"]`**: fetch locally first, fall back to the model backend (e.g. for a PDF) when it's available. Without a Glob.AI OS profile, the order simply falls through to `client`, and a PDF returns a short "can't fetch this here" message.
+
+There is **no headless-browser rendering** — CODA deliberately does not bundle or require a browser. A client-rendered single-page app that ships little server-side content gets an actionable notice (try the model backend or a direct content URL) rather than being rendered.
+
+### Configuring web fetch
+
+Set the backend priority (and other options) with a `webfetch` block in your config file — the **first** entry in `order` is the primary, the rest are fallbacks:
+
+```jsonc
+{
+  // ... other config ...
+  "webfetch": {
+    "order": ["client", "anthropic"]
+  }
+}
+```
+
+All settings live under `webfetch` (all optional):
+
+| Field | Default | What it does |
+| --- | --- | --- |
+| `webfetch.order` | `["client", "anthropic"]` | Backend preference order. First entry is the primary; the rest are fallbacks. Use `["client"]` for client-only, `["anthropic"]` for model-backend-only, or `[]` to **disable** the tool. |
+| `webfetch.blockedUrls` | — | URLs/hosts/extensions the tool must never fetch (client backend). Merged with the `CODA_FETCH_BLOCKED_URLS` env var. |
+| `webfetch.allowedHosts` | — | Strict allowlist (client backend) — when set, only these hosts and their subdomains may be fetched. |
+| `webfetch.requireProvenance` | `true` | Anti-exfiltration: only fetch URLs that already appeared in the conversation (your messages or prior tool results), never model-invented URLs. Set `false` to allow model-composed URLs. |
+| `webfetch.anthropicTimeoutSeconds` | `240` | Timeout budget for the model backend, decoupled from a request's own `timeout` — a server-side parse of a large PDF can take minutes. Raise it if large PDFs still time out. |
+
+You can also disable the tool through the authorization engine with a `permissions.deny: ["WebFetch"]` rule (see [Permissions & Approvals](#permissions)), which takes precedence over `webfetch.order`.
+
+The tool can also write a fetched page straight to a file (always confined to `.coda/docs`) instead of returning it inline — useful for large pages you want to keep without spending tokens.
+
+`webfetch` is **main-agent-only** — it is not available inside delegated agent runs or workflows.
+
 ## Tools inside agent runs
 
 When a delegated [agent](#agents) run executes, it uses a trimmed tool set. Two categories are removed from every child session: