docs: Approver + WebSocket approval protocol documentation

SECURITY.md: unified Approver table, Web UI modal docs, non-interactive note
WEBUI.md: approval_request/approval_response WebSocket events + client messages
DEVELOPMENT.md: approver.go + wsapprover.go in source layout

Author: jkyberneees

docs/DEVELOPMENT.md

@@ -43,6 +43,7 @@ internal/
   danger/
     classifier.go             Command/URL classification for security gating
     classifier_test.go        209 tests, 8 risk classes, config overrides
+    approver.go               Approver interface + TTYApprover (CLI /dev/tty)
   memory/
     memory.go                 MemoryManager orchestrator (facts, buffer, episodes)
     facts.go                  FactStore with caps, dedup, substring CRUD
@@ -71,6 +72,7 @@ cmd/kode/
   serve.go                    Web UI server (HTTP + WebSocket)
   subagent.go                 Sub-agent command (--goal, --context, --task, JSON stdout)
   subagent_tool.go            delegate_tasks built-in tool
+  wsapprover.go               WSApprover — WebSocket-based approval for serve mode
   subagent_test.go            Tests (flag parsing, JSON stdout, exit codes, tool schema)
   subagent_contract_test.go   Contract tests (flag parsing, stdout protocol, exit codes)
   subagent_e2e_test.go        E2E tests (16 — KODE_E2E=true, real subprocess spawning)

docs/SECURITY.md

@@ -68,13 +68,22 @@ API keys are read from environment variables or explicit config. kode never logs
 
 ## Dangerous Operations Approval
 
-When running **without** `--sandbox`, kode's shell tool classifies every command by risk level and can prompt for user approval before executing high-risk operations.
+When running **without** `--sandbox`, kode's shell tool and native tools (read_file, write_file, browser, etc.) classify every operation by risk level and can prompt for user approval before executing high-risk operations.
 
-### How it works
+The approval mechanism uses a unified **Approver** interface with two implementations:
+
+| Mode | Approver | How it works |
+|------|----------|-------------|
+| **CLI** (`kode run`, `kode repl`) | `TTYApprover` | Opens `/dev/tty` — the same keypress-based prompt described below |
+| **Web UI** (`kode serve`) | `WSApprover` | Sends `approval_request` via WebSocket — the browser shows a modal with Approve / Deny / Trust buttons |
+
+Both provide the **same three actions**: approve once, deny, or trust for the session. The experience is identical regardless of how you interact with kode.
+
+### How it works (CLI mode)
 
 1. The shell tool receives a command from the agent (JSON with `command` and optional `description`)
 2. The command is tokenized and classified into one of 8 risk classes (see [CLI.md](CLI.md#dangerous-operations))
-3. If the class is configured to `prompt` (default for system_write, network_egress, code_execution, install), the tool opens `/dev/tty` and shows:
+3. If the class is configured to `prompt` (default for system_write, network_egress, code_execution, install), the tool shows:
 
 ```
 ⚠️  Risk: system_write
@@ -114,10 +123,12 @@ When you press `T`, the risk class is cached in memory for the lifetime of the k
 
 ### Non-interactive mode
 
-When `/dev/tty` is not available (piped stdin, CI environments), the configured `non_interactive` action is used:
+When `/dev/tty` is not available (piped stdin, CI environments, or when no custom approver is configured), the configured `non_interactive` action is used:
 - `"allow"` (default) — run all commands without prompting
 - `"deny"` — block all prompted operations
 
+> **Note:** In `kode serve` (Web UI) mode, this fallback is never hit — a WebSocket-based approver (`WSApprover`) is automatically injected, giving you interactive approval dialogs in the browser. The `non_interactive` setting only matters for CLI sessions without a TTY.
+
 ### Allowlist vs Denylist
 
 - **Allowlist** entries (exact command match) bypass all checks — the command runs without prompt even if it would normally be denied

docs/WEBUI.md

@@ -71,11 +71,19 @@ The UI communicates entirely over a single WebSocket at `/ws`. Messages are newl
 ### Client → Server
 
 ```jsonc
+// Prompt — send a task to the agent
 {
   "type": "prompt",
   "content": "What files are in src/?",
   "session_id": "20260519-abc123"  // optional — omit for new session
 }
+
+// Approval response — answer a security prompt
+{
+  "type": "approval_response",
+  "id": "apr-a1b2c3d4",
+  "action": "approve"  // "approve" | "deny" | "trust"
+}
 ```
 
 ### Server → Client
@@ -88,6 +96,7 @@ The UI communicates entirely over a single WebSocket at `/ws`. Messages are newl
 | `tool_result` | Tool returns output | `name`, `output` (truncated to 500 chars) |
 | `done` | Agent finishes | `latency` (seconds) |
 | `error` | Agent or server error | `message` |
+| `approval_request` | Agent needs user approval for dangerous operation | `id`, `risk` (class name), `command` (or resource), `description`, `is_operation` |
 
 Example event sequence: