@globant/coda-darwin-x64 1.0.0 → 1.2.0

package/assets/agents/coda-help.md

@@ -32,6 +32,7 @@ Notation: every entry points to `file.md › § "Exact Heading"`. All files live
 | How do I install / upgrade Coda? | `installation.md` › § "Install CODA", § "Keeping CODA up to date" |
 | What are the requirements? | `installation.md` › § "Requirements" |
 | How do I connect / set up a provider? | `connect-provider.md` › § "Step 1 — Choose how to connect" → § "Step 3 — Authenticate" |
+| Configure a provider non-interactively / from a script / in CI / headless setup (`coda configure`)? | `connect-provider.md` › § "Non-interactive setup (`coda configure`)"; command → `cli-reference.md` › § "Subcommands (run as `coda <command>`)" |
 | OAuth vs API key / switch between them? | `connect-provider.md` › § "Switch a Glob.AI OS provider between OAuth and API key" |
 | Switch the active provider / profile (`/switch-profile`, `/sp`)? | `connect-provider.md` › § "Switch between configured providers"; command → `cli-reference.md` › § "Configuration" |
 | Add / edit / remove a provider (`/providers`)? | `connect-provider.md` › § "Reconfigure"; wizard steps → § "Step 1 — Choose how to connect" |
@@ -44,12 +45,21 @@ Notation: every entry points to `file.md › § "Exact Heading"`. All files live
 | Legacy top-level `provider` / `providers` map (old configs)? | `config-reference.md` › § "providers (runtime client map — legacy)"; `config-json.md` › § "The legacy `providers` map" |
 | Connect to local Ollama? | `config-reference.md` › § "activeProfile and profiles" (`ollama` profiles) |
 | How do I change a setting? Where do settings live? | `configuration.md` › § "Where settings live", § "Common settings to change" |
+| Which shell does CODA use / pick or pin the shell (`bash.shellMode`, `auto`/`bash`/`powershell`/`wsl`)? Why can't I select `wsl`? Why is CODA running a different shell than I configured / "shell unavailable" banner / shell fell back? | `configuration.md` › § "Common settings to change" (Shell); `config-reference.md` › § "bash" |
 | Full annotated config.json / every config block? | `config-json.md` › § "The complete example", § "Common edits, by goal" |
 | What does config key X do / its default? | `config-reference.md` (find the `## <block>` section, e.g. `## bash`, `## checkpoints`, `## skills`) |
 | Where are config / secrets / sessions / logs stored? | `config-reference.md` › § "Config file locations"; `faq.md` › § "Where are my config, sessions, and logs stored?" |
 | Store API keys safely / `${VAR}` / `secretRef` secrets? | `config-json.md` › § "Secrets: keep keys out of the file"; `config-reference.md` › § "Referencing secrets with `${VAR}`" |
 | How do I switch models? | `cli-reference.md` › § "Configuration" (`/switch-model`); `shortcuts.md` › § "Model switching" |
-| How do I let bash run everything / change approval level? | `permissions.md` › § "Bash approval levels", § "Where to set it"; headless: § "Approvals in headless (batch) mode" |
+| How do I let bash run everything / change approval level / permission mode (`read-only`/`default`/`auto`, Ctrl+P)? | `permissions.md` › § "Permission modes", § "Where to set it"; headless: § "Approvals in headless (batch) mode" |
+| How do I allow / always-allow / never-allow a command (`propose_policy`, "allow pnpm build")? | `permissions.md` › § "The easy way to change permissions: just ask the agent", § "How `propose_policy` works", § "What you actually approve" |
+| Stop CODA suggesting rule changes / disable `propose_policy` (`permissions.proposePolicy`, `CODA_PROPOSE_POLICY`, `disableProposePolicy`)? | `permissions.md` › § "Turning `propose_policy` off"; `config-reference.md` › § "permissions" |
+| Rule syntax / write allow-ask-deny rules by hand / path or command not matching? | `permissions.md` › § "Rule syntax", § "Rules — always-allow / always-ask / always-deny", § "Project-scoped vs. global-scoped rules" |
+| Why was an action denied / precedence / deny-first / order of rules vs mode? | `permissions.md` › § "How decisions are made (precedence)", § "What denial messages look like" |
+| What is the catastrophic floor / what can never be allowed (`rm -rf /`, reading SSH keys, git hooks, `--privileged`)? Answer from the floor sections ONLY — do not describe the retired `bash.autoApproveLevel` as a current control. | `permissions.md` › § "The catastrophic floor — protections that can never be turned off", § "What is never auto-approved" |
+| What permissions do I have right now / what rules apply / where did a rule come from (`/permissions`, `coda permissions`)? | `permissions.md` › § "Seeing what applies right now" |
+| Organization / managed policy / admin lockdown of permissions? | `permissions.md` › § "Managed (organization) policy"; to see what it actually permits on this machine: § "Seeing what applies right now" |
+| Where are permission decisions logged (`authorization.decision`)? | `permissions.md` › § "Every decision is logged" |
 | Is it safe to install skills/plugins/MCP? | `permissions.md` › § "Trust and external code" |
 | How do I connect an MCP server? | `guide-extend.md` › § "Connect external services with MCP" |
 | Where do MCP servers live / session override / disable one? | `guide-extend.md` › § "Connect external services with MCP" ("Where MCP servers are defined") |
@@ -67,6 +77,7 @@ Notation: every entry points to `file.md › § "Exact Heading"`. All files live
 | What is `.codaignore` / what's excluded from snapshots? | `sessions.md` › § "What a snapshot captures (and what it skips)", § "Exclude your own paths with `.codaignore`" |
 | Context % / "Coda forgot something" / compaction? | `how-it-works.md` › § "Compaction: keeping context fresh"; `sessions.md` › § "Watch the context fill level" |
 | Why did a model call retry / fail over? | `how-it-works.md` › § "Error recovery: handling provider hiccups" |
+| Model removed / renamed / auto-healed at startup, or how to stop auto-switching (`strictPin`, `CODA_MODEL_AUTOHEAL`)? | `faq.md` › § "What happens if my model is removed or renamed?"; behavior → `how-it-works.md` › § "Error recovery: handling provider hiccups"; config → `config-reference.md` › § "activeProfile and profiles" (`strictPin`), § "modelResilience" |
 | How do I run Coda headless / in CI? | `guide-automate.md` › § "Basic usage", § "Important flags for automation", § "Authenticating in batch mode"; concept → `cli-vs-batch.md` |
 | What slash command / flag does X? | `cli-reference.md` (pick the section: Session management / Files / Configuration / Tools and extensions / Context / Shell flags / Subcommands) |
 | What keyboard shortcut does X? | `shortcuts.md` (Global / In the chat input / During a turn / Transcript navigation / Model switching) |
@@ -90,6 +101,7 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 
 - Requirements, install (script vs npm), where it installs, upgrading, install troubleshooting → `installation.md` › § "Requirements", § "Install CODA", § "Where CODA installs", § "Keeping CODA up to date", § "Troubleshooting the install"
 - Setup wizard, Glob.AI OS environment, OAuth vs API key, custom/Ollama provider, switch active profile (`/switch-profile`/`/sp`), switch Glob.AI OS project (`/project`), who am I signed in as, reconfigure (`/providers`), OAuth↔API-key switch, OAuth troubleshooting → `connect-provider.md` › § "Step 1 — Choose how to connect", § "Step 2 — Pick a Glob.AI OS environment", § "Step 3 — Authenticate", § "Custom provider", § "Switch between configured providers", § "Switching the active Glob.AI OS project", § "Check who you're signed in as", § "Reconfigure", § "Switch a Glob.AI OS provider between OAuth and API key", § "Troubleshooting"
+- Non-interactive / headless / CI provider setup (`coda configure`), flags, exit codes, key storage → `connect-provider.md` › § "Non-interactive setup (`coda configure`)"; subcommand entry → `cli-reference.md` › § "Subcommands (run as `coda <command>`)"
 - First session in 5 min, starter prompts, `/init`, reviewing/undoing, keeping a session healthy → `quickstart.md` › § "2. Try these prompts", § "3. Review what CODA does", § "4. Undo anything", § "5. Keep the session healthy"
 
 **How it works**
@@ -108,7 +120,7 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 **Tools and safety**
 
 - Built-in tool list, how tools show up, how CODA chooses a tool, what you can configure (incl. env vars), trimmed tools in agent runs → `tools-reference.md` › § "How tools show up", § "Built-in tools", § "How CODA chooses a tool", § "What you can configure", § "Tools inside agent runs"
-- Approvals (HITL), the Question prompt type, bash levels (`safe`/`low`/`medium`/`high`), shell mode, other actions that ask, headless approvals, trust of external code, where to set it → `permissions.md` › § "How approvals work", § "Bash approval levels", § "Choosing the shell", § "Other actions that ask first", § "Approvals in headless (batch) mode", § "Trust and external code", § "Where to set it"
+- Authorization engine (HITL): approvals, permission modes (`read-only`/`default`/`auto`, Ctrl+P, legacy aliases, sub-agent inheritance), plain-English rule changes via `propose_policy` (add/remove rule, change mode, scopes, turning it off), HITL choices, denial messages, rule syntax + gotchas, project vs global scope, precedence (deny-first), catastrophic floor (self-protection, sensitive-path writes, un-relaxable secret reads, git RCE, container escape, redirects), shell mode, other actions that ask, managed policy, headless approvals, decision logging, `bash.autoApproveLevel` migration, trust of external code, where to set it → `permissions.md` › § "How approvals work", § "Permission modes", § "The easy way to change permissions: just ask the agent", § "How `propose_policy` works", § "What you actually approve", § "Turning `propose_policy` off", § "Rules — always-allow / always-ask / always-deny", § "Rule syntax", § "Project-scoped vs. global-scoped rules", § "How decisions are made (precedence)", § "The catastrophic floor — protections that can never be turned off", § "Choosing the shell", § "Other actions that ask first", § "Managed (organization) policy", § "Approvals in headless (batch) mode", § "Every decision is logged", § "Migrating from `bash.autoApproveLevel`", § "Trust and external code", § "Seeing what applies right now" (the read-only `/permissions` and `coda permissions` views: which rules apply, which scope each came from, session grants), § "Where to set it"
 
 **Sessions and checkpoints**
 
@@ -131,7 +143,7 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 **Configuration**
 
 - From the UI: `/providers`, `/settings`, where files live, common settings, cascade, what's safe to commit, minimal example → `configuration.md` › § "Where settings live", § "Common settings to change", § "How settings cascade", § "What's safe to commit", § "A minimal `config.json`"
-- Reference (key-by-key, defaults): locations, `activeProfile`/`profiles` (selection layer), legacy `providers` map, top-level `model`, `auth`, inline `mcp`, `bash`, `compaction`, `reasoning`, `tools`, `vision`, `checkpoints`, `skills`, `logging`, advanced, `${VAR}`, env vars → `config-reference.md` › § "Config file locations", § "activeProfile and profiles", § "providers (runtime client map — legacy)", § "model (top-level)", § "auth (Glob.AI OS login preferences)", § "mcp (inline servers)", § "bash", § "compaction", § "reasoning", § "Other common settings", § "tools", § "vision", § "checkpoints", § "skills", § "logging", § "Advanced blocks", § "Referencing secrets with `${VAR}`", § "Environment variables"
+- Reference (key-by-key, defaults): locations, `activeProfile`/`profiles` (selection layer), legacy `providers` map, top-level `model`, `auth`, inline `mcp`, `bash`, `compaction`, `reasoning`, `tools`, `vision`, `checkpoints`, `skills`, `logging`, advanced, `${VAR}`, env vars → `config-reference.md` › § "Config file locations", § "activeProfile and profiles", § "providers (runtime client map — legacy)", § "model (top-level)", § "auth (Glob.AI OS login preferences)", § "mcp (inline servers)", § "bash", § "compaction", § "reasoning", § "modelResilience", § "Other common settings", § "tools", § "vision", § "checkpoints", § "skills", § "logging", § "Advanced blocks", § "Referencing secrets with `${VAR}`", § "Environment variables"
 - Complete annotated `config.json` (profiles-first) + secrets + legacy providers map + per-goal edits + env vars → `config-json.md` › § "The complete example", § "Secrets: keep keys out of the file", § "Common edits, by goal", § "The legacy `providers` map", § "Environment variables"
 
 **Logging**
@@ -148,7 +160,7 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 - Getting started, installation, and connecting a provider
 - Configuration (providers, models, `config.json`, `.secrets`, cascade, env vars)
 - Built-in tools (read, write, edit, bash, glob, grep, etc.) and how CODA picks them
-- Permissions and approvals (HITL, bash levels, trust of external code)
+- Permissions and approvals (HITL, permission modes, `propose_policy`, rule syntax, precedence, catastrophic floor, managed policy, trust of external code)
 - Agents and subagents (just-ask usage, definitions, `/agents`, `run_agent` family, bundled `coda-help`/`explore`)
 - Workflows (creating, running, `/workflows`, `create-workflow`, what a run produces)
 - Skills, extensions, plugins, and MCP servers (creating, loading, managing)

package/assets/docs/agents.md

@@ -72,6 +72,7 @@ You are a codebase exploration specialist. Given an area or question:
 | `tools` / `disallowedTools` | Allow-list or deny-list the tools the agent may use — handy for a read-only reviewer. |
 | `background` | Default this agent to background (non-blocking) runs. |
 | `color` | A label color in the `/agents` UI. |
+| `permissionMode` | The permission mode for this agent's run. Enforced: a sub-agent can only **tighten** (never widen) the parent's mode. |
 
 **Parsed for forward-compatibility (not yet enforced):** the following fields are accepted in frontmatter but currently have no runtime effect — they are read into the agent definition and reserved for future releases. Setting them today does nothing:
 
@@ -79,7 +80,6 @@ You are a codebase exploration specialist. Given an area or question:
 | --- | --- | --- |
 | `maxTurns` | Cap the number of turns the agent may take. | number |
 | `effort` | Effort-level hint for the model (e.g. `low`, `medium`, `high`). | string |
-| `permissionMode` | Override the permission mode for this agent's run. | string |
 | `skills` | Skill names to load for this agent. | string[] |
 | `memory` | Toggle memory for this agent. | boolean |
 | `isolation` | Isolation setting for this agent's run. | string |

package/assets/docs/cli-reference.md

@@ -1,41 +1,41 @@
 # Commands & Flags
 
-Reference for the slash commands available in the interactive TUI, plus the shell flags you pass when launching CODA from the terminal. Type `/help` inside CODA at any time to see the current list (extensions may add more).
-
-## Session management
-
-| Command | What it does |
-| --- | --- |
-| `/sessions` | Browse, resume, rename, and delete saved sessions |
-| `/new` | Start a fresh session (old one is saved) |
-| `/exit` (alias `/quit`) | Exit CODA; prints `coda --session-id <id>` so you can resume later |
-| `/clear` | Permanently wipe the current session's message history (the session itself stays) |
-
-## Files and changes
-
-| Command | What it does |
-| --- | --- |
-| `/timeline` (alias `/rewind`) | Open the timeline picker to view and restore checkpoints from this session |
-| `/init` | Analyze the project and generate an `AGENTS.md` file |
-| `/project` | Switch the active Glob.AI OS project (Glob.AI OS OAuth only) |
-
-## Configuration
-
-| Command | What it does |
-| --- | --- |
+Reference for the slash commands available in the interactive TUI, plus the shell flags you pass when launching CODA from the terminal. Type `/help` inside CODA at any time to see the current list (extensions may add more).
+
+## Session management
+
+| Command | What it does |
+| --- | --- |
+| `/sessions` | Browse, resume, rename, and delete saved sessions |
+| `/new` | Start a fresh session (old one is saved) |
+| `/exit` (alias `/quit`) | Exit CODA; prints `coda --session-id <id>` so you can resume later |
+| `/clear` | Permanently wipe the current session's message history (the session itself stays) |
+
+## Files and changes
+
+| Command | What it does |
+| --- | --- |
+| `/timeline` (alias `/rewind`) | Open the timeline picker to view and restore checkpoints from this session |
+| `/init` | Analyze the project and generate an `AGENTS.md` file |
+| `/project` | Switch the active Glob.AI OS project (Glob.AI OS OAuth only) |
+
+## Configuration
+
+| Command | What it does |
+| --- | --- |
 | `/providers` | Connect, add, update, or remove providers (the setup wizard; same as `--reconfigure`; restart required) |
 | `/switch-profile` (alias `/sp`) | Switch the active provider profile among the ones you've already configured. With no argument it opens the profile picker; `/switch-profile <profile-id>` selects one directly. The change is saved as `activeProfile` and applies on the next launch |
 | `/switch-model` (alias `/sm`) | Open the model picker. `/switch-model <provider/model>` applies for this session; `/switch-model save <provider/model>` also saves it as the default for new sessions |
 | `/login` | Authenticate with Glob.AI OS via browser (OAuth PKCE) when `auth` is configured |
 | `/effort [<level>]` | Set the model's thinking (reasoning) effort — `low`, `medium`, `high`, `xhigh`, `max`. With no level, pick from the levels the current model supports; some models don't support effort at all |
 | `/logout` | Sign out of your Glob.AI OS session |
-| `/settings` | Open the settings panel: UI theme, bash approval, compaction |
-| `/auth-status` (alias `/whoami`) | Show the current authentication status |
-
-## Tools and extensions
-
-| Command | What it does |
-| --- | --- |
+| `/settings` | Open the settings panel: UI theme, permission mode, compaction |
+| `/auth-status` (alias `/whoami`) | Show the current authentication status |
+
+## Tools and extensions
+
+| Command | What it does |
+| --- | --- |
 | `/mcp` | Open the MCP manager — add a server, edit `mcp.json`, list servers, view tools, reload |
 | `/mcp status` | Show each server's connection status |
 | `/mcp list-tools [server]` | List the tools a server exposes |
@@ -45,9 +45,9 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `/skills enable <name>` / `/skills disable <name>` | Toggle a skill |
 | `/skills add <url> [project\|global]` | Install a skill from GitHub |
 | `/skills refresh` | Re-scan the skill directories |
-| `/extensions` | Manage loaded extensions (`list`, `guide`) |
-| `/plugin` | Install, enable, disable, and list plugins |
-| `/reload-plugins` | Reload plugins after you change them on disk |
+| `/extensions` | Manage loaded extensions (`list`, `guide`) |
+| `/plugin` | Install, enable, disable, and list plugins |
+| `/reload-plugins` | Reload plugins after you change them on disk |
 | `/agents` | Open the Agents overlay — browse definitions and active runs |
 | `/agents overview` (or `/agents runs`) | Show recent runs and the agent library in chat |
 | `/agents library` | List reusable agent definitions only |
@@ -59,33 +59,32 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `/agents open <id>` | Inspect a specific run’s details and recent activity |
 | `/agents transcript <id>` | Switch to the child session’s transcript |
 | `/workflows` | Open the workflow dashboard (live run → phase → agent tree and history) |
-| `/workflows stop [runId]` | Stop a workflow run; omit the id to stop all in-flight runs |
-
-## Context
-
-| Command | What it does |
-| --- | --- |
-| `/compact` | Manually condense conversation history to free up context |
-| `/upgrade` | Check for a newer version and open the update dialog |
-| `/help` | Print the full list of available commands |
-
-## Shell flags (run before opening CODA)
-
-| Flag | What it does |
-| --- | --- |
-| `coda --help` / `-h` | Print CLI usage and exit |
-| `coda --version` / `-v` | Print the installed version |
-| `coda --reconfigure` | Open the provider setup wizard (interactive terminal only) |
-| `coda --lastsession` | Resume the most recent session for this project |
-| `coda --session-id <id>` / `-s` | Resume (or create) a specific session |
-| `coda -p "prompt"` / `--prompt` | Run in batch (headless) mode |
-| `coda --prompt-file <path>` / `-pf` | Read the headless prompt from a file |
-| `coda --output text\|json` | Output format for headless runs (`json` emits structured events) |
-| `coda --auto-approve all\|none` | Headless approval handling (use `all` in CI) |
-| `coda --tools <list>` / `-t` | Limit which tools are available for the run |
-| `coda --timeout <ms>` | Abort a headless run after the given time |
-| `coda --checkpoints[=true\|false]` | Force checkpoints on or off for this run |
-| `coda --bash-security <level>` | Set the bash approval level for this run |
+| `/workflows stop [runId]` | Stop a workflow run; omit the id to stop all in-flight runs |
+
+## Context
+
+| Command | What it does |
+| --- | --- |
+| `/compact` | Manually condense conversation history to free up context |
+| `/upgrade` | Check for a newer version and open the update dialog |
+| `/help` | Print the full list of available commands |
+
+## Shell flags (run before opening CODA)
+
+| Flag | What it does |
+| --- | --- |
+| `coda --help` / `-h` | Print CLI usage and exit |
+| `coda --version` / `-v` | Print the installed version |
+| `coda --reconfigure` | Open the provider setup wizard (interactive terminal only) |
+| `coda --lastsession` | Resume the most recent session for this project |
+| `coda --session-id <id>` / `-s` | Resume (or create) a specific session |
+| `coda -p "prompt"` / `--prompt` | Run in batch (headless) mode |
+| `coda --prompt-file <path>` / `-pf` | Read the headless prompt from a file |
+| `coda --output text\|json` | Output format for headless runs (`json` emits structured events) |
+| `coda --auto-approve all\|none` | Headless approval handling (use `all` in CI) |
+| `coda --tools <list>` / `-t` | Limit which tools are available for the run |
+| `coda --timeout <ms>` | Abort a headless run after the given time |
+| `coda --checkpoints[=true\|false]` | Force checkpoints on or off for this run |
 | `coda --model <name>` / `-m` | Use a specific model for this run |
 | `coda -e <path>` | Load an extra extension file for this run |
 | `coda --mcp-config <path>` | Point at a specific `mcp.json` for this run |
@@ -105,6 +104,7 @@ Beyond launching a session, `coda` exposes a few standalone subcommands:
 
 | Command | What it does |
 | --- | --- |
+| `coda configure` | Create or overwrite a persisted provider profile non-interactively (CI-friendly). Run `coda configure --help` for the full flag reference |
 | `coda install` | Add the coda binary directory to `PATH` (macOS/Linux: updates shell rc files; Windows: updates user Path env var) |
 | `coda upgrade` | Download and install the platform-native CODA binary from the release feed |
 | `coda logs` | Open the log viewer (or stream when piped); supports filters and `--follow` |
@@ -128,4 +128,4 @@ coda -p "Run the test suite and summarize failures" \
      --output json \
      --tools read,glob,grep,bash \
      --timeout 600000
-```
+```

package/assets/docs/cli-vs-batch.md

@@ -43,7 +43,6 @@ Batch runs a **single turn** — one prompt in, one result out — then exits. T
 | `--auto-approve none` | Refuse any action that needs approval (fail fast; useful for safety checks) |
 | `--timeout MS` | Abort the run after the given milliseconds and exit non-zero |
 | `--tools LIST` | Limit which tools are available (e.g. `read,glob,grep`) |
-| `--bash-security LVL` | Override the bash auto-approve tier for this run |
 | `-s / --session-id ID` | Resume an existing session in headless mode |
 | `--lastsession` | Resume the most recent session in headless mode |
 | `--checkpoints` | Enable checkpoint creation (no TUI restore, but useful for diff workflows) |

package/assets/docs/config-json.md

@@ -86,15 +86,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 +165,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 +290,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 +336,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

@@ -53,6 +53,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 +173,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 +207,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
 
@@ -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

@@ -46,14 +46,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**:
 
@@ -73,15 +68,15 @@ 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.
+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 +87,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. |