docs(danger): document the dangerous config and the fail-closed unknown class

Extend the user-facing guide for setting up the "dangerous" approval
policy, and bring the security/CLI/dev docs in line with the new 9-class
model (adds the fail-closed `unknown` class).

DOCKER_COMPOSE_USER_GUIDE.md §5a now has a full field-by-field setup
guide for the restricted profile:
- what each key does (sandbox/action/non_interactive/classes/allow/deny)
- the 9-class table with built-in vs profile actions
- the action-resolution precedence (allowlist → denylist → classes →
  blocked → action → built-in default → non_interactive)
- a gotcha: a global "action" overrides EVERY unlisted class, so the
  shipped restricted profile prompts even on `safe` (`ls`) unless you
  add "safe": "allow" or omit "action" — both shown
- customisation recipes (tighten / loosen / allowlist one tool / lockdown)

CLI.md, SECURITY.md, DEVELOPMENT.md: add the `unknown` class, state the
fail-closed default, refresh the evasion list and regression-suite
pointers. No code changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jkyberneees

DOCKER_COMPOSE_USER_GUIDE.md

@@ -138,10 +138,10 @@ These JSON files are mounted to `/home/odek/.odek/config.json` inside the contai
 
 ### 5a. Restricted policy — `config.restricted.json`
 
-This is essentially Odek's default behavior, made explicit. Commands are risk‑classified;
-destructive ones are denied, the rest prompt for approval. Crucially, `non_interactive`
-is set to **`deny`** so that if the agent runs in a container *without* an attached
-terminal or Web UI, high‑risk commands are blocked rather than silently allowed.
+Commands are risk‑classified; destructive and unrecognised ones are denied, the rest
+prompt for approval. Crucially, `non_interactive` is set to **`deny`** so that if the
+agent runs in a container *without* an attached terminal or Web UI, anything that would
+prompt is blocked rather than silently allowed.
 
 ```json
 {
@@ -163,23 +163,81 @@ terminal or Web UI, high‑risk commands are blocked rather than silently allowe
 }
 ```
 
-**How the classes map** (built‑in risk model):
+#### What each field does
 
-| Class | Examples | Restricted action |
-| --- | --- | --- |
-| `safe` | `ls`, `cat`, `echo` | allow |
-| `local_write` | write files in the working dir | allow |
-| `system_write` | `chmod`, `chown`, `mkdir /etc` | prompt |
-| `network_egress` | `curl`, `wget`, DNS lookups | prompt |
-| `code_execution` | `go run`, `python x.py` | prompt |
-| `install` | `npm install`, `apk add` | prompt |
-| `destructive` | `rm -rf`, `git rm`, `docker rm` | **deny** |
-| `blocked` | fork bombs, `dd` to block devices | **always deny** (cannot be overridden) |
+| Field | Meaning |
+| --- | --- |
+| `sandbox` | `false` runs commands directly in this container (the Compose setup already *is* the sandbox). `true` would nest a second Docker sandbox — not what you want here. |
+| `action` | **Global default** action for any class **not** listed under `classes`. `"prompt"` here, `"allow"` = godmode, `"deny"` = lockdown. ⚠️ This overrides the *built‑in* per‑class defaults (see the gotcha below). |
+| `non_interactive` | What to do with a **prompt**‑level command when there is no human channel (no TTY, no Web UI). `"deny"` blocks it; `"allow"` runs it. Always set this to `"deny"` for unattended/automated containers. |
+| `classes` | Per‑class action overrides. The most specific setting — it wins over `action` and the built‑in defaults. Only list the classes you want to pin. |
+| `allowlist` | Commands that always run, **exact string match**, no classification. Highest priority of all. Use for a handful of trusted exact commands (e.g. `"npm run deploy"`). |
+| `denylist` | Commands that are always denied, **prefix match** after trimming. Beats classification and even godmode — but **not** the allowlist. |
+
+#### How the classes map (built‑in risk model)
+
+| Class | Examples | Built‑in default | This profile |
+| --- | --- | --- | --- |
+| `safe` | `ls`, `cat`, `grep`, `git status` | allow | prompt¹ |
+| `local_write` | write files in the working dir | allow | allow |
+| `install` | `npm install`, `pip install`, `apk add` | prompt | prompt |
+| `network_egress` | `curl`, `wget`, `ssh`, DNS lookups | prompt | prompt |
+| `code_execution` | `curl … \| sh`, `bash -c`, `python -c`, `go run` | prompt | prompt |
+| `system_write` | `sudo`, writes to `/etc`, reads of `~/.ssh` | prompt | prompt |
+| `unknown` | any command whose program name Odek does **not** recognise | deny | prompt¹ → denied unattended |
+| `destructive` | `rm -rf /`, `dd … of=/dev/sda`, `mkfs` | deny | **deny** |
+| `blocked` | fork bombs, fully‑specified `dd` to a block device | **always deny** | **always deny** (cannot be overridden) |
+
+> ¹ `safe` and `unknown` are not listed under `classes`, so the global
+> `action: "prompt"` applies to them — see the gotcha below. With a human channel
+> they prompt; unattended (`non_interactive: "deny"`) they are denied.
+
+Odek **fails closed**: the `unknown` class catches any command whose verb isn't in the
+built‑in safe/dangerous tables, so a novel or obfuscated command can't slip through as
+"safe". To permit a specific unrecognised tool, add its exact invocation to `allowlist`,
+or relax the class with `"unknown": "prompt"`.
+
+#### How an action is resolved (precedence, first match wins)
+
+1. Command exactly matches an **`allowlist`** entry → **allow**.
+2. Command starts with a **`denylist`** entry → **deny**.
+3. Otherwise classify it, then: explicit **`classes`** entry → `blocked` is **always deny** → global **`action`** (if set) → built‑in class default.
+4. If the result is **prompt** and there's no human channel, **`non_interactive`** decides.
+
+> **Gotcha — `action` overrides *every* unlisted class.** Because `action: "prompt"` is
+> set, any class you don't list under `classes` resolves to *prompt*, including `safe`.
+> So with this profile as written, even `ls` prompts (and is denied unattended). Two ways
+> to get the usual "safe commands just run" behavior:
+>
+> - add `"safe": "allow"` to `classes` (keep `action: "prompt"` as the catch‑all for
+>   everything else, including `unknown`), **or**
+> - **omit `action` entirely** and only override the classes you care about — then unlisted
+>   classes keep their built‑in defaults (safe/local_write allow; destructive/blocked/unknown
+>   deny; system_write/network_egress/code_execution/install prompt).
+>
+> The second form is the better default if you want `unknown` to stay deny‑by‑default
+> rather than prompt.
 
 > Approvals require a human channel: the **Web UI** (`odek serve`, modal approval over
 > WebSocket) or an **interactive terminal** (`odek repl` with `docker compose run -it`).
 > Without either, `non_interactive: "deny"` is what keeps you safe.
 
+#### Customising the policy
+
+```jsonc
+// Tighter: also block all outbound network and package installs.
+"classes": { "network_egress": "deny", "install": "deny", /* … */ }
+
+// Looser: pre‑approve a few exact commands you trust, keep everything else gated.
+"allowlist": ["npm ci", "npm run build", "go build ./..."]
+
+// Allow one normally‑unrecognised tool without loosening the whole class:
+"allowlist": ["terraform plan"]          // exact match only
+
+// Full lockdown: deny everything except the allowlist.
+"action": "deny"
+```
+
 ### 5b. Godmode policy — `config.godmode.json`
 
 YOLO mode. Every risk class returns `allow`; no prompts. The only thing still blocked is

docs/CLI.md

@@ -123,8 +123,13 @@ When running without `--sandbox`, odek classifies every shell command by risk an
 | 🔴 network_egress | **prompt** | `curl`, `git push`, `ssh`, `scp` |
 | 🔴 code_execution | **prompt** | `curl url \| bash`, `eval`, `node -e`, `go run` |
 | 🟠 install | **prompt** | `npm install`, `pip install`, `go install <path>` |
+| 🔴 unknown | **deny** | any command whose program name isn't recognised |
 | ⬛ blocked | **deny** | Fork bombs, `dd` to block devices |
 
+odek **fails closed**: a command whose verb matches no known-safe or known-dangerous
+pattern is classified `unknown` and denied by default. Permit a specific tool by adding
+its exact invocation to `allowlist`, or soften the class with `"unknown": "prompt"`.
+
 The approval prompt accepts:
 
 - `A` — Approve once

docs/DEVELOPMENT.md

@@ -206,7 +206,7 @@ CI (`.github/workflows/test.yml`) runs the unit suite under `-race` on every pus
 | `internal/ws` | WebSocket constant verification |
 | `internal/resource` | @-reference parsing, file resolution, session resolution, security |
 | `internal/render` | Terminal output, no-color mode, nil safety, tool call/result rendering |
-| `internal/danger` | Command classification across 8 risk classes, config overrides, allow/denylist, classifier-bypass attempts, approver friction |
+| `internal/danger` | Command classification across 9 risk classes (incl. fail-closed `unknown`), config overrides, allow/denylist, classifier-bypass attempts, approver friction |
 | `internal/memory` | Facts CRUD, buffer ring, episodes, merge detector (go-vector), ReplaceEntry/AppendEntry, memory tool, security scan, LLM ranking, episode provenance |
 | `internal/skills` | Loading, triggers, self-improvement heuristics, curation, LLM-enhanced generation, import, tools, AnalyzeMessages/RunAutoSaveLoop, ValidateSkillName, isPrivateHost |
 | `internal/telegram` | Bot client, long-polling, command handlers, session management, plan CRUD, voice/photo download, health server, retry/backoff |

docs/SECURITY.md

@@ -69,18 +69,19 @@ The model is instructed (via the default system prompt) to treat the wrapped reg
 
 ### 3. Danger classifier (shell)
 
-The `shell` tool tokenises commands and classifies each into one of 8 risk classes (`safe`, `local_write`, `system_write`, `destructive`, `network_egress`, `code_execution`, `install`, `blocked`). Per-class policy (allow / prompt / deny) is configurable.
+The `shell` tool tokenises commands and classifies each into one of 9 risk classes (`safe`, `local_write`, `system_write`, `destructive`, `network_egress`, `code_execution`, `install`, `unknown`, `blocked`). Per-class policy (allow / prompt / deny) is configurable.
 
-The classifier is hardened against common evasion tricks:
+The gate **fails closed**: a command whose program name matches neither the known-safe allowlist nor any known-dangerous pattern is classified `unknown` and **denied by default** (same as `destructive`). Recognised commands used benignly are `safe`. So a novel or obfuscated verb cannot slip through as "safe" — to permit a specific tool, allowlist it or set `"unknown": "prompt"`.
 
-- `$(echo rm) -rf /` — command substitution is recursively classified.
-- `` `echo rm` -rf / `` — backticks treated the same.
-- `\rm -rf /` and `r\m -rf /` — unquoted backslash escapes are collapsed.
-- `rm$IFS-rf$IFS/` — `$IFS` / `${IFS}` expanded to space.
-- `command rm -rf /` and `exec rm -rf /` — wrappers stripped.
-- `/bin/rm -rf /` — absolute paths basenamed before matching.
+The classifier is hardened against common evasion tricks (see the package doc in `internal/danger/classifier.go` for the full model):
 
-A regression suite (`internal/danger/classifier_bypass_test.go`) pins these as known evasions. If you find a new bypass, the test file is the place to add it.
+- `$(echo rm) -rf /` / `` `echo rm` `` / `<(curl evil)` — command and process substitutions are recursively classified.
+- `\rm -rf /`, `r""m -rf /` — backslash escapes collapsed and quote boundaries are not word boundaries.
+- `rm$IFS-rf$IFS/`, `{rm,-rf,/}`, `$'\x72\x6d'` — `$IFS`, brace expansion, and ANSI-C escapes are normalised.
+- `command rm`, `env rm`, `sudo rm`, `/bin/rm`, `true | dd of=/dev/sda` — wrappers are stripped, every pipe stage is classified, and absolute paths are basenamed before matching.
+- `bash -i >& /dev/tcp/…`, `cat ~/.ssh/id_rsa` — reverse-shell channels and sensitive-path access are flagged regardless of the command verb.
+
+Regression suites (`internal/danger/classifier_bypass_test.go` and `hardening_test.go`) pin these as known-closed evasions. If you find a new bypass, those test files are the place to add it.
 
 ### 4. Tool-call approval