@globant/coda-darwin-x64 1.0.0 → 1.3.0

package/assets/docs/config-json.md

@@ -10,7 +10,6 @@ For a field-by-field table of the most common keys, see [Configuration Reference
 | --- | --- |
 | `~/.coda/config.json` | Your user-global settings (apply in every project) |
 | `<project>/.coda/config.json` | Project overrides (commit to share with the team) |
-| `<project>/coda.config.ts` | TypeScript config — takes priority over JSON if present |
 
 Settings cascade in priority order: **CLI flags → project config → global config → built-in defaults**. A project file only needs the keys it wants to override; everything else falls back to your global file and then to defaults.
 
@@ -86,15 +85,26 @@ Settings cascade in priority order: **CLI flags → project config → global co
     "tokenRefreshThreshold": 300
   },
 
-  // ── Bash tool approvals ───────────────────────────────────────────────
-  // autoApproveLevel: which risk tier runs WITHOUT asking. "safe" < "low" <
-  // "medium" < "high". Truly destructive commands are never auto-approved.
+  // ── Shell ─────────────────────────────────────────────────────────────
   // shellMode: "auto" | "bash" | "powershell" | "wsl" (or an explicit path).
+  // A mode this host can't run falls back to a working shell with a warning.
   "bash": {
-    "autoApproveLevel": "low",
     "shellMode": "auto"
   },
 
+  // ── Permissions (the authorization engine) ────────────────────────────
+  // defaultMode: the session's starting permission mode.
+  //   "read-only" (reads only) | "default" (asks for risky) | "auto" (hands-off).
+  // allow/ask/deny: rule strings; deny always wins (deny-first).
+  // additionalDirectories: extra roots treated as "in project" for edits/writes.
+  "permissions": {
+    "defaultMode": "default",
+    "allow": ["Bash(git status)", "Bash(npm test)"],
+    "ask": ["Bash(git push:*)"],
+    "deny": ["Bash(rm:*)"],
+    "additionalDirectories": ["../shared"]
+  },
+
   // ── Reasoning (thinking) effort ───────────────────────────────────────
   // effort: "low" | "medium" | "high" | "xhigh" | "max". Per-model support
   // varies. Change live with /effort.
@@ -154,6 +164,19 @@ Settings cascade in priority order: **CLI flags → project config → global co
     "apiKey": "${BRAVE_API_KEY}"
   },
 
+  // ── Web fetch tool ────────────────────────────────────────────────────
+  // Backend priority: the FIRST entry is the primary, the rest are fallbacks.
+  // Default is ["client","anthropic"] — the local fetch first, model backend
+  // (PDFs; requires GEAI webfetch credentials via an active GEAI profile or CODA_WEBFETCH_* env/secrets)
+  // as fallback. Use ["client"] for client-only, ["anthropic"] for model-backend-only, or [] to disable.
+  "webfetch": {
+    "order": ["client", "anthropic"]
+    // "blockedUrls": ["tracker.io", ".pdf"],   // never fetched (client backend)
+    // "allowedHosts": ["docs.internal.example.com"], // strict allowlist
+    // "requireProvenance": true,               // only fetch URLs seen in the chat
+    // "anthropicTimeoutSeconds": 240           // model-backend timeout (PDF parses)
+  },
+
   // ── Extra extensions to load ──────────────────────────────────────────
   // Paths to extension modules (in addition to auto-discovered .coda/extensions).
   "extensions": ["./.coda/extensions/my-tool.ts"],
@@ -266,11 +289,12 @@ The `.secrets` file is never committed and its values are scrubbed from logs bef
 | Add a provider | A new entry under `profiles` (use `/providers`); API-key ones reference a `secretRef` in `.secrets` |
 | Switch which provider is active | `activeProfile` (or `/switch-profile` / `/sp` live) |
 | Switch OAuth ↔ API key | the profile's `auth` block (`{ "method": "oauth" }` vs `{ "method": "apikey", "secretRef": "VAR" }`) |
-| Let bash run more without asking | `bash.autoApproveLevel` (e.g. `"high"`) — see [Permissions & Approvals](#permissions) |
+| Let commands run more without asking | `permissions.defaultMode: "auto"`, or add `permissions.allow` rules — see [Permissions & Approvals](#permissions) |
 | Change thinking effort | `reasoning.effort` (or `/effort` live) |
 | Cap or widen parallel agents | `agents.maxConcurrent` (1–10) |
 | Turn off a noisy bundled agent | add its name to `agents.disabledDefinitions` |
 | Use the faster search engine | `tools.grep.backend: "fastgrep"` |
+| Set the web-fetch backend priority | `webfetch.order` — e.g. `["client","anthropic"]` (default) or `["anthropic","client"]`; `[]` disables the tool |
 | Add an MCP server | `mcp.servers` here, or `~/.coda/mcp.json` — see [Tools Reference](#tools-reference) |
 | Quiet or verbose logs | `logging.level` / `logging.levels` |
 | Disable update checks | `autoupdate: false` |
@@ -311,4 +335,4 @@ Each entry accepts per-tier model overrides (`fastModel`, `smartModel`, `deepMod
 - [Configuration](#configuration) — how config works from the UI and how layers cascade.
 - [Configuration Reference](#config-reference) — the field-by-field table.
 - [Connect a Provider](#connect-provider) — setting up providers through the wizard.
-- [Permissions & Approvals](#permissions) — the bash approval levels in detail.
+- [Permissions & Approvals](#permissions) — permission modes, rules, and the floors in detail.

package/assets/docs/config-reference.md

@@ -10,7 +10,6 @@ Reference for the most common configuration options. For how to set these up in
 | `~/.coda/.secrets` | API keys (dotenv format, never commit) |
 | `~/.coda/mcp.json` | Global MCP server definitions |
 | `<project>/.coda/config.json` | Project-level overrides |
-| `<project>/coda.config.ts` | TypeScript config (takes priority) |
 | `<project>/.coda/mcp.json` | Project-level MCP servers |
 
 ## activeProfile and profiles
@@ -53,6 +52,7 @@ Each profile has a `provider` type that determines its shape:
 | `org` / `project` | Selected org and project (written by wizard after login) |
 | `favoriteModels` | Array of model IDs shown as quick-switch options |
 | `fastModel` / `smartModel` / `deepModel` | Model IDs for the `"fast"`, `"smart"`, and `"deep"` agent shortcut tiers |
+| `strictPin` | When `true`, never auto-heal this profile's model if it's retired on the provider — always ask instead (see "modelResilience" below and [How it works](#how-it-works) › "Error recovery"). Default `false`. |
 
 ### `openai-compat` profiles (any OpenAI-compatible API)
 
@@ -172,8 +172,26 @@ You can define [MCP](#tools-reference) servers inline instead of in `mcp.json`:
 
 | Field | Default | Description |
 | --- | --- | --- |
-| `autoApproveLevel` | `"low"` | Risk level auto-approved without confirmation: `"safe"`, `"low"`, `"medium"`, `"high"` |
-| `shellMode` | `"auto"` | Shell to use: `"auto"`, `"bash"`, `"powershell"`, `"wsl"` |
+| `shellMode` | `"auto"` | Shell to use: `"auto"`, `"bash"`, `"powershell"`, `"wsl"`, or an explicit path to a shell binary. Validated against the host: a mode this host can't run falls back to a working shell with a warning (a banner in the TUI, a `stderr` line when headless) rather than failing to start. The settings picker only offers modes your host has. |
+
+(The legacy `bash.autoApproveLevel` is retired — it is migrated to `permissions.defaultMode` on load; see below.)
+
+## permissions
+
+The authorization engine's config. Rule strings use the `Tool(specifier)` form (e.g. `Bash(git status)`, `Bash(rm:*)`); `deny` always wins over `allow`/`ask` (deny-first).
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `defaultMode` | `"default"` | Starting permission mode: `"read-only"` (reads only), `"default"` (asks for risky actions), `"auto"` (hands-off; only the un-relaxable floor + managed deny refuse) |
+| `allow` | `[]` | Rules that always run without asking |
+| `ask` | `[]` | Rules that always prompt |
+| `deny` | `[]` | Rules that are always refused (wins over `allow`) |
+| `additionalDirectories` | `[]` | Extra roots treated as "in project" for edits/writes and the in-tree reversible-mutator allowance |
+| `proposePolicy` | `true` | Lets CODA **propose** a permission change instead of just failing (see [Permissions & Approvals](#permissions)). A change that only *tightens* permissions applies on its own; anything that *widens* them is gated behind your explicit approval of an engine-computed summary of what the rule would actually grant. On by default; opt out with `"proposePolicy": false` (or the admin `disableProposePolicy`). |
+
+Admin-only managed-policy lockdown keys (set in a managed policy, not personal config): `allowManagedRulesOnly`, `allowManagedMcpServersOnly`, `disableAutoMode`, `disableProposePolicy`.
+
+`disableProposePolicy` is one-way: when an administrator sets it, `permissions.proposePolicy` (and the `CODA_PROPOSE_POLICY` override below) cannot switch the feature back on.
 
 ## compaction
 
@@ -188,7 +206,15 @@ You can define [MCP](#tools-reference) servers inline instead of in `mcp.json`:
 | Field | Default | Description |
 | --- | --- | --- |
 | `reasoning.enabled` | `false` | Opt in to sending thinking/reasoning tokens to reasoning-capable models. Off by default. |
-| `reasoning.effort` | `"medium"` | Thinking effort level: `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`. Change it live with `/effort` (see [Commands & Flags](#cli-reference)). Per-model support varies — some models accept only a subset, and some none at all. |
+| `reasoning.effort` | `"medium"` | Thinking effort level: `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`. Change it live with `/effort` (see [Commands & Flags](#cli-reference)). Per-model support varies — some models accept only a subset, and some none at all (support is discovered dynamically for models not in the built-in list). |
+
+## modelResilience
+
+Controls how CODA heals a configured model that's been retired or renamed on the provider (see [How it works](#how-it-works) › "Error recovery"). A retired model is auto-healed to the closest same-provider/family replacement; per-profile `strictPin` (above) opts out.
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `modelResilience.successorMap` | `{}` | Optional explicit `"retiredId": "replacementId"` overrides. A mapped target that is still available wins over the automatic same-family cascade; unmapped models fall back to the cascade. Rarely needed — the heuristic handles known renames. |
 
 ## Other common settings
 
@@ -205,6 +231,7 @@ You can define [MCP](#tools-reference) servers inline instead of in `mcp.json`:
 | `agents.disabledDefinitions` | — | Array of agent definition names to disable without deleting their files |
 | `checkpoints.enabled` | on (interactive) / off (headless) | Master switch for the checkpoints subsystem |
 | `errorHandling.posture` | `balanced` | How aggressively CODA retries on model/provider failures: `conservative` (fewer retries, fail fast), `balanced`, `aggressive` (more retries and failover attempts). See [How CODA Works](#how-it-works). |
+| `errorHandling.streamIdleTimeoutMs` | posture-derived (`240000` for `balanced`) | Streaming inactivity timeout in milliseconds: the max gap between successive stream chunks before the request is aborted. Overrides the posture default. Raise it further (e.g. `360000`) for reasoning-heavy models or large-context turns that legitimately go silent while the model produces its first token. A non-positive value disables the idle timeout. |
 
 ## tools
 
@@ -222,6 +249,20 @@ You can define [MCP](#tools-reference) servers inline instead of in `mcp.json`:
 | --- | --- |
 | `vision.model` | Model used by `examine_images` (Glob.AI OS profiles) |
 
+## webfetch
+
+Configures the `webfetch` tool (fetch a web page by URL). See [Tools Reference](#tools-reference) › "Web fetch" for the full behavior.
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `webfetch.order` | `["client", "anthropic"]` | Backend preference order (first is primary, rest are fallbacks). `"client"` = the local SSRF-hardened fetch (always available); `"anthropic"` = a fixed-model server-side fetch (parses PDFs; needs a Glob.AI OS profile). Use `["client"]`, `["anthropic"]`, or `[]` to **disable** the tool. |
+| `webfetch.blockedUrls` | — | URLs/hosts/extensions never fetched (client backend). Merged with `CODA_FETCH_BLOCKED_URLS`. |
+| `webfetch.allowedHosts` | — | Strict host allowlist (client backend) — when set, only these hosts and subdomains may be fetched. |
+| `webfetch.requireProvenance` | `true` | Only fetch URLs that already appeared in the conversation (your messages / prior tool results), not model-invented ones. Set `false` to opt out. |
+| `webfetch.anthropicTimeoutSeconds` | `240` | Timeout (seconds) for the model backend, decoupled from a request's `timeout` — server-side PDF parsing can take minutes. |
+
+Disable the tool entirely with `webfetch.order: []`, or via a `permissions.deny: ["WebFetch"]` rule (which takes precedence).
+
 ## checkpoints
 
 | Field | Description |
@@ -327,3 +368,8 @@ Keep keys out of `config.json` by storing them in `~/.coda/.secrets` (dotenv for
 | --- | --- | --- |
 | `LOG_LEVEL` | `info` | Log verbosity, Rust-style: a bare token sets the global floor, `service:level` overrides per service (e.g. `info,core.agent:debug`) |
 | `CODA_HOME` | `~/.coda` | Alternative home directory for config, secrets, sessions, logs, and checkpoints |
+| `CODA_PROPOSE_POLICY` | unset | Overrides `permissions.proposePolicy` without editing config (dev/QA). A truthy value (`1`, `true`, `yes`, `on`) forces it **on**; any other set value (e.g. `0`, `false`, `off`) forces it **off** — so it can override in either direction, winning over config. Blank/unset defers to config (default on). An administrator's `disableProposePolicy` still wins over it. |
+| `CODA_MODEL_AUTOHEAL` | unset | In a headless/batch run, set (e.g. `1`) to let CODA auto-heal a retired model to its recommended replacement instead of exiting non-zero. Interactive runs use the picker and ignore this; a `strictPin` profile is never healed. |
+| `CODA_FETCH_BLOCKED_URLS` | unset | Comma-separated URLs/hosts/extensions the `webfetch` client backend must never fetch (e.g. `competitor.com,tracker.io,.pdf`). Merged with `webfetch.blockedUrls`. |
+| `CODA_WEBFETCH_MODEL` | `anthropic/claude-sonnet-4-6` | Fixed model used by the `webfetch` `anthropic` backend (independent of your session model). |
+| `CODA_WEBFETCH_BASE_URL` / `CODA_WEBFETCH_API_KEY` / `CODA_WEBFETCH_PROJECT_ID` | unset | Explicit Glob.AI OS credentials that enable the `webfetch` `anthropic` backend even in a non-GEAI session (e.g. to fetch PDFs). `PROJECT_ID` is optional; the backend is active only when both base URL and API key are set. |

package/assets/docs/configuration.md

@@ -32,7 +32,6 @@ Settings cascade in priority order — project settings override user settings,
 | `~/.coda/config.json` | Your personal defaults — provider, model, theme |
 | `~/.coda/.secrets` | API keys and credentials (never commit this) |
 | `<project>/.coda/config.json` | Project-level overrides (safe to commit if no secrets) |
-| `<project>/coda.config.ts` | TypeScript config — if present, it replaces the project `config.json` (the JSON is ignored) |
 | `~/.coda/mcp.json` | MCP servers available in all your projects |
 | `<project>/.coda/mcp.json` | MCP servers for this project only |
 | `~/.coda/sessions/<id>/mcp.json` | Per-session MCP overrides (written by `/mcp` commands within a session) |
@@ -46,14 +45,9 @@ Some settings can be adjusted from the settings panel. Open it from inside CODA:
 /settings
 ```
 
-**Bash approval level** — open **Bash Tool Preferences** to control how many shell commands CODA can run without asking you first. There are four levels:
+**Permission mode** — how much CODA runs without asking is set by the session's permission mode: **read-only** (reads only), **default** (asks before risky actions), or **auto** (hands-off). Cycle it with **Ctrl+P**, or set the default with `permissions.defaultMode`. See [Permissions & Approvals](#permissions).
 
-- `safe` — only read-only commands run automatically; everything else asks.
-- `low` — the default; a conservative set of safe commands is auto-approved.
-- `medium` — more commands run without prompting.
-- `high` — everything is auto-approved except destructive operations.
-
-The same screen lets you pick the **shell** CODA uses (`auto`, `bash`, `powershell`, or `wsl`).
+**Shell** — pick the **shell** CODA uses (`auto`, `bash`, `powershell`, `wsl`, or an explicit path) under **Bash Tool Preferences**. Only shells your host actually has are offered, so you can't select one that won't run (for example, `wsl` doesn't appear off Windows). If a *configured* shell isn't available on this host — say a `config.json` synced from Windows that asks for `wsl` on macOS — CODA neither fails to start nor silently runs a different shell: it falls back to a working shell and shows a banner naming what it's running instead and why, with a pointer to change it. The banner clears the moment you pick a shell that works. Press **Enter** to confirm and close, **Esc** to step back to the menu.
 
 **Compaction** — to keep context fresh, CODA can automatically condense older conversation before it runs out of room. Tune it under **Context Compaction**:
 
@@ -72,16 +66,16 @@ When the same key is set in more than one place, the most specific wins. From lo
 
 1. **Built-in defaults** — what CODA ships with.
 2. **`~/.coda/config.json`** — your personal, machine-wide settings.
-3. **`<project>/.coda/config.json`** (or `<project>/coda.config.ts`, which replaces it) — project overrides.
-4. **CLI flags** — `--bash-security`, `--model`, `--profile`, and friends, for a single run.
+3. **`<project>/.coda/config.json`** — project overrides.
+4. **CLI flags** — `--model`, `--profile`, `--auto-approve` (headless), and friends, for a single run.
 
-So a project can raise the bash level for everyone who clones it, and you can still override it for one run with `--bash-security` — without editing any file.
+So a project can set the permission mode (`permissions.defaultMode`) for everyone who clones it, and a headless run can override the approval posture with `--auto-approve none|all` — without editing any file.
 
 ## What's safe to commit
 
 - **Commit:** `<project>/.coda/config.json` (no secrets), `<project>/.coda/mcp.json`, `AGENTS.md`, shared skills/agents/workflows.
 - **Never commit:** `~/.coda/.secrets` (it lives in your home directory, not the repo) and your personal `~/.coda/config.json`.
-- **Think twice:** pinning the active `provider` or an elevated `bash.autoApproveLevel` in a project config affects every teammate — see [Collaborate with Your Team](#guide-collaborate).
+- **Think twice:** pinning the active `provider` or an elevated `permissions.defaultMode` (e.g. `"auto"`) in a project config affects every teammate — see [Collaborate with Your Team](#guide-collaborate).
 
 ## A minimal `config.json`
 
@@ -92,7 +86,8 @@ You rarely write this by hand, but it helps to know the shape:
   "activeProfile": "my-corp-profile",
   "model": "claude-sonnet",
   "theme": "modern",
-  "bash": { "autoApproveLevel": "low", "shellMode": "auto" },
+  "bash": { "shellMode": "auto" },
+  "permissions": { "defaultMode": "default" },
   "compaction": { "enabled": true, "threshold": 0.75 },
   "agents": { "enabled": true, "maxConcurrent": 6 }
 }

package/assets/docs/connect-provider.md

@@ -55,6 +55,42 @@ To confirm the current authentication state from inside a session:
 
 It shows the active provider, environment, and — for OAuth — the signed-in identity and selected project. To sign out of a Glob.AI OS session, run `/logout`.
 
+## Non-interactive setup (`coda configure`)
+
+If you need to create or overwrite a provider profile without the interactive TUI — for example in a CI pipeline, a setup script, or when automating machine provisioning — use `coda configure`:
+
+```bash
+# Glob.AI (Clients) — API key read from stdin
+echo "$GEAI_KEY" | coda configure \
+  --provider glob-ai --instance clients \
+  --api-key-stdin --profile-name my-proj
+
+# OpenAI-compatible endpoint
+echo "$API_KEY" | coda configure \
+  --provider openai-compat --base-url api.example.com/v1 \
+  --api-key-stdin --profile-name compat
+
+# Local Ollama (no API key needed)
+coda configure \
+  --provider ollama --base-url http://localhost:11434 \
+  --profile-name local
+```
+
+**Key flags:**
+
+| Flag | Purpose |
+| --- | --- |
+| `--profile-name NAME` | Profile ID in `~/.coda/config.json` (required) |
+| `--provider PROVIDER` | `glob-ai` \| `openai-compat` \| `ollama` (required) |
+| `--instance INSTANCE` | glob-ai only: `clients` \| `corp` \| `saas-europe` (default: `clients`) |
+| `--base-url URL` | Required for `openai-compat`; optional for `ollama` |
+| `--api-key KEY` | Pass key on the command line (appears in shell history — prefer `--api-key-stdin`) |
+| `--api-key-stdin` | Read key from stdin — safe for scripts and CI |
+| `--force` | Overwrite an existing profile and rotate its API key |
+| `--no-activate` | Write the profile without changing `activeProfile` |
+
+API keys are stored in the system keychain (or an encrypted secrets file on systems without a keychain). They are never written in plain text to `config.json`. Run `coda configure --help` for the full reference and exit codes.
+
 ## Reconfigure
 
 To re-authenticate within an active session (e.g. after an OAuth session expires), run `/login` — it re-initiates browser OAuth without reopening the full wizard. For first-time provider setup or editing an existing provider, use `/providers` inside a session (changes take effect after a restart) or `coda --reconfigure` from your terminal. Use `/providers` to switch between configured providers anytime — the provider you configure or select there becomes the **active** one. `coda --reconfigure` edits a provider's settings *without* changing which provider is active.

package/assets/docs/faq.md

@@ -75,13 +75,28 @@ Type `/timeline` (or `/rewind`, or press **Esc** twice) to see all snapshots fro
 
 ### How do I stop CODA from asking me to approve every command?
 
-Raise the bash approval level from `/settings` → **Bash Tool Preferences**. Levels are:
-- `safe` — only truly read-only commands; everything else asks.
-- `low` — the default; a conservative set of safe commands and low-risk writes auto-approve.
-- `medium` — more destructive operations auto-approve.
-- `high` — everything auto-approves except the most destructive operations.
+CODA runs an **authorization engine** that decides `allow` / `ask` / `deny` for every tool call. Two levers control it:
 
-For a single headless run, pass `--bash-security <level>` (e.g. `--bash-security high`) to override the approval level without changing your saved config. See [Configuration](#configuration) for details.
+- **Permission mode** — press `Ctrl+P` to cycle the session's mode: **read-only** (only reads run; writes and commands are refused), **default** (reads run, risky actions like `git commit` ask first, destructive ones are denied unless you add an allow rule), and **auto** (risky actions auto-run for unattended/CI use; only catastrophic ones stay blocked). Set the default in `/settings` or per project in `.coda/config.json` via `permissions.defaultMode`.
+- **Rules** — to always allow or always block a specific command, add `allow` / `ask` / `deny` rules under `permissions` in `config.json` (e.g. `allow Bash(git status)` or `deny Bash(rm:*)`). **Deny always wins**, and a handful of catastrophic actions (`rm -rf /`, `sudo`, a fork bomb) sit behind an un-relaxable floor that no allow rule can override.
+
+The legacy `bash.autoApproveLevel` ("safe"→"high") was replaced by this model; a stored `high` migrates to `auto`.
+
+### How does CODA decide what's safe to run without asking?
+
+It **parses** each command into a syntax tree (not string-matching) and classifies it by capability — read, write, network, destructive, catastrophic — across bash, PowerShell, and cmd. The decision is **deny-first**: explicit deny rules win, then your permission mode fills the gaps, then the un-relaxable floor plus self-protection clamp the dangerous cases. So `cat file` reads freely, `git commit` asks in `default`, `rm -rf /` is refused in every mode, and piping a remote script into a shell (`curl … | sh`) is denied by default. (`rm` and PowerShell `Remove-Item` deny for out-of-tree, absolute, or non-literal targets; an in-tree delete like `rm ./tmp` is auto-allowed in `default`/`auto` as an easily-reverted change, while recursive/absolute forms stay un-relaxable.)
+
+### Will an `awk` / `node -e` / `python -c` one-liner run without asking?
+
+Yes, in `default` and `auto`. An interpreter carrying an **inline-code** flag (`-c`, `-e`, `-p`, `--eval`) — or a named script file, or `awk '<program>' file` — is treated the same as running a script: it's agent-provided code either way, so CODA decides it at the baseline (`allow`), rather than prompting. What still stays at `ask` is a **bare REPL or a stdin program** (`node` alone, `python`, `awk -f -`, reading `/dev/stdin`) — there's no program to attribute. Two things to note: in **read-only** mode every interpreter is refused (running code isn't read-safe, so `python -c 'print(1)'` denies even though it "touches" nothing); and the seam still inspects the surrounding shell — a `$(curl …)` substitution, a `curl … | python -c` pipe, or a redirect onto a secret inside the one-liner is denied regardless. A module-preload path (`node --require ./x.js`) is allowed when the file is in your project and denied (relaxably) when it's outside.
+
+### Can my organization enforce command policies?
+
+Yes. A **managed** (admin) policy can add deny rules everyone inherits, lock the permission mode (for example forbid `auto`), restrict which MCP servers are allowed, and drop non-managed allow rules. Managed rules sit above your personal config and can't be overridden locally.
+
+### `Ctrl+P` doesn't cycle the mode inside my editor's terminal
+
+Some editors capture `Ctrl+P` before CODA sees it. On **Windows/Linux**, VS Code and Cursor bind `Ctrl+P` to "Quick Open," so it never reaches the integrated terminal; on **macOS** Quick Open is `Cmd+P`, so `Ctrl+P` normally passes straight through. Two fixes: run CODA in a **standalone terminal**, or tell the editor to send the key to the terminal — in VS Code/Cursor `settings.json`, add `"terminal.integrated.commandsToSkipShell": ["-workbench.action.quickOpen"]` (the leading `-` lets the key through; the broader `"terminal.integrated.sendKeybindingsToShell": true` forwards most chords but disables editor shortcuts like `Ctrl+F`). Two more reasons it can seem dead: `Ctrl+P` is a no-op until you have an active session, and over the editor (ACP) integration the mode is set from the editor's own permission UI, not `Ctrl+P`.
 
 ### What is AGENTS.md and should I have one?
 
@@ -123,6 +138,15 @@ From inside CODA, open the `/plugin` manager to install, enable, disable, and br
 
 Press `Shift+Tab` to cycle your favorite models, or run `/switch-model` (alias `/sm`) to open the picker — apply it to just this session or save it as your new default. For a single headless run, pass `--model <name>`.
 
+### What happens if my model is removed or renamed?
+
+CODA re-checks your configured model against the provider's live catalog at startup. If it's gone, CODA finds the closest available replacement (same provider and family):
+
+- **Interactive** — the model picker opens pre-selected to the recommendation, naming the retired model. Pick it (this session, or save as the new default) or choose another.
+- **Headless / CI** — set `CODA_MODEL_AUTOHEAL=1` to auto-switch to the replacement (a stderr notice records the change); otherwise the run exits non-zero with a `/switch-model` hint, so nothing changes silently.
+
+To opt out and always be asked, set `"strictPin": true` on the profile (see [Configuration Reference](#config-reference) › "activeProfile and profiles" and "modelResilience"). On a provider without a live catalog (e.g. local Ollama), CODA trusts your id and shows a clear switch-model message if it turns out to be unavailable.
+
 ### Where do I see token usage and cost?
 
 The TUI status bar shows the context fill percentage and running token/cost figures for the session, so you can keep an eye on how much a long session is consuming.

package/assets/docs/glossary.md

@@ -23,8 +23,7 @@ Quick definitions for terms used throughout the docs.
 | **Workflow** | A deterministic script that orchestrates multiple agents — parallel fan-out, multi-stage pipelines, and loops. Authored by the built-in `create-workflow` agent, stored in `.coda/workflows/`, run in the background, and monitored with `/workflows`. |
 | **ACP** | Agent Client Protocol — the integration that lets editors like Zed and JetBrains drive CODA. |
 | **Anti-clobber guard** | The safety check that makes CODA ask before overwriting a file it never read during the current session. |
-| **Approval level** | See *Bash approval level*. The tier (`safe`/`low`/`medium`/`high`) that decides which shell commands run without asking. |
-| **Bash approval level** | The setting (`safe`, `low`, `medium`, `high`) controlling how many shell commands CODA auto-approves. Set from `/settings` → Bash Tool Preferences. |
+| **Permission mode** | The setting that decides how much CODA does without asking — `read-only` (reads only), `default` (asks before risky actions), or `auto` (hands-off). Cycle with **Ctrl+P** or set `permissions.defaultMode` in config. |
 | **`.codaignore`** | A gitignore-syntax file at your project root with glob patterns (and optional `!negation` lines) to exclude from — or forcibly include in — checkpoints. Shares `.gitignore` semantics, so patterns, directory globs, and negations all work. |
 | **Context window** | The amount of conversation CODA can hold at once. The status-bar percentage shows how full it is; compaction frees room as it fills. |
 | **Drift** | Uncaptured changes in your worktree at restore time. CODA stops the restore so you don't lose work; press **F** to force it. |
@@ -32,6 +31,11 @@ Quick definitions for terms used throughout the docs.
 | **`smartModel`** | The model the literal `model: "smart"` shortcut resolves to — the balanced mid-tier for agent runs. Configured under `agents.smartModel` or per-provider. |
 | **`deepModel`** | The model the literal `model: "deep"` shortcut resolves to — the highest-capability, most expensive tier. Configured under `agents.deepModel` or per-provider. |
 | **HITL** | Human-in-the-loop — the approval model where CODA pauses to ask before risky actions. |
+| **Rule** | A string in your `config.json` `permissions` block that targets a specific tool call and assigns an effect (`allow`, `ask`, or `deny`). Usually `ToolName(specifier)` — e.g. `Bash(git log:*)`, `Read(//etc/passwd)` — but a bare tool name (`Bash`, matching *every* call to that tool) and MCP forms (`mcp__server`, `mcp__server__tool`) are also valid. |
+| **`allow` / `ask` / `deny`** | Rule effects. `allow`: always permit without prompting. `ask`: always prompt, even in `auto` mode. `deny`: always block, no override — deny wins over everything else. |
+| **Catastrophic floor** | A fixed set of operations always blocked regardless of any rule, mode, or config — `rm -rf /`, `sudo`, fork bombs, writes to CODA's own config, writes to credential paths, reading the contents of a private key, container-escape flags, and git RCE injection. Cannot be unlocked. |
+| **`propose_policy`** | The built-in tool CODA uses to suggest a permanent permission change (add rule, remove rule, or change mode) for you to approve. Triggered when you ask in plain English (e.g. "allow pnpm build") or after a denial. On by default; a *widening* change always needs your explicit approval. Disable with `permissions.proposePolicy: false`, `CODA_PROPOSE_POLICY`, or the admin `disableProposePolicy`. |
+| **Managed policy** | An organization-level policy set by an administrator that overrides and locks certain permission settings in your personal and project configs (e.g. forbidding `auto` mode, restricting MCP servers). A managed `deny` is final. |
 | **Headless mode** | See *Batch mode*. |
 | **Marketplace** | The catalog of installable plugins, reachable from the `/plugin` manager; Claude Code-ecosystem compatible. |
 | **Redaction** | The always-on scrubbing of secret-looking keys and values from logs before they're written to disk. |

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.