docs: document default_action and the defer verdict; fix stale empty-stdout claim

Signed-off-by: Leonardo Grasso <me@leonardograsso.com>

Author: leogr

CLAUDE.md

@@ -29,7 +29,7 @@ The project targets **Claude Code** as its primary integration on **Linux, macOS
 2. **Event delivery** — The interceptor sends the event to the plugin's embedded broker via Unix domain socket.
 3. **Rule evaluation** — The plugin feeds the event to Falco's rule engine via the source plugin API (`next_batch`). Falco evaluates all loaded rules.
 4. **Alert feedback** — Matching rules generate alerts. Falco delivers them back to the plugin's embedded broker via `http_output` (localhost).
-5. **Verdict resolution** — The broker determines the verdict from rule tags (`deny`, `ask`, or allow-by-default) and responds to the interceptor.
+5. **Verdict resolution** — The broker determines the verdict from rule tags (`deny`, `ask`, or the no-match floor `allow`/`defer` per `default_action`) and responds to the interceptor.
 6. **Verdict delivery** — The interceptor communicates the verdict to the coding agent using the standard hook response format.
 
 ### Components
@@ -57,11 +57,11 @@ Rule verdicts are encoded in the `tags:` field of Falco rules, not in the `outpu
 
 - `tags: [coding_agent_deny]` — block the tool call
 - `tags: [coding_agent_ask]` — require user confirmation
-- No deny/ask tag — allow (no explicit allow tag needed)
+- No deny/ask tag — the **no-rule-match floor** (`default_action`, see "Operational modes"): `allow` (default; Prempti approves) or `defer` (Prempti steps aside)
 
-There is no allow tag because the absence of a verdict IS the allow verdict. Rules only fire when their condition matches — a tool call that doesn't match any deny or ask rule simply produces no deny/ask alert, and the broker resolves it as allow via batch-completion.
+There is no allow tag because the absence of a deny/ask verdict IS the floor. Rules only fire when their condition matches — a tool call that doesn't match any deny or ask rule simply produces no deny/ask alert, and the broker resolves it via batch-completion with the configured floor (`allow` or `defer`).
 
-The broker parses the `tags` array from Falco's JSON alert output. Verdict escalation applies when multiple rules match: deny > ask > allow.
+The broker parses the `tags` array from Falco's JSON alert output. Verdict escalation applies when multiple rules match: deny > ask > {allow | defer} (the floor is uniform per plugin instance, so allow and defer never compete).
 
 ### Catch-all seen rule + HTTP verdict resolution
 
@@ -174,12 +174,16 @@ Note: Falco's alert delivery is asynchronous — alerts are pushed to an interna
 ### Operational modes
 
 Three plugin modes, switchable without reinstallation via `premptictl mode <guardrails|monitor|passthrough>`:
-- **Guardrails** (default) — verdicts enforced (deny/ask/allow).
-- **Monitor** — rules evaluated and logged, but all verdicts resolve to allow after the synchronous rule-eval wait. Would-deny / would-ask log lines still fire.
-- **Passthrough** (Experimental, embedding-only) — every interceptor request is resolved as `allow` immediately at register, without waiting for rule evaluation. Events are still enqueued for Falco, so alerts continue to flow through `http_output` / `falco.log` and any observability pipeline hanging off them. No would-deny / would-ask log lines, because rule evaluation is decoupled from the verdict. Use only when embedding Prempti inside a host agent that has its own alert pipeline and does not want the hook's latency tied to Falco's rule loop.
+- **Guardrails** (default) — verdicts enforced (deny / ask / floor). The no-rule-match floor is `default_action` (below).
+- **Monitor** — rules evaluated and logged, but all verdicts resolve to `defer` after the synchronous rule-eval wait (Prempti steps aside; would-deny / would-ask log lines still fire). `default_action` is ignored.
+- **Passthrough** (Experimental, embedding-only) — every interceptor request is resolved as `defer` immediately at register, without waiting for rule evaluation. Events are still enqueued for Falco, so alerts continue to flow through `http_output` / `falco.log` and any observability pipeline hanging off them. No would-deny / would-ask log lines, because rule evaluation is decoupled from the verdict. `default_action` is ignored. Use only when embedding Prempti inside a host agent that has its own alert pipeline and does not want the hook's latency tied to Falco's rule loop.
 
 The three modes are mutually exclusive — `mode:` is a single string, so only one is active at a time.
 
+**No-rule-match floor (`default_action`)** — orthogonal to mode, switchable via `premptictl default-action <allow|defer>`. It governs how the broker resolves an event that matches **no** deny/ask rule, in **guardrails mode only**:
+- `allow` (default) — Prempti actively approves: Claude Code gets `permissionDecision: "allow"` (skips its own prompt); Codex gets `{"behavior":"allow"}` at `PermissionRequest`. No regression from prior releases.
+- `defer` — Prempti steps aside: Claude Code gets empty stdout + exit 0 (its normal permission flow applies, prompting if it normally would); Codex's `PermissionRequest` gets no output (its own approval flow decides). This is also what `monitor` and `passthrough` always emit, which keeps the active-approval shape confined to guardrails mode. `defer` is a fourth wire verdict alongside `allow`/`deny`/`ask`; deny/ask are unaffected by `default_action`. Note `defer` is **not** rendered as Claude's `permissionDecision: "defer"` (a `-p`/Agent-SDK value that pauses the call for resume) — empty stdout is the documented "let the agent's own permission system decide" path.
+
 Mode changes are applied via an explicit service restart driven by `ctl mode`: it rewrites the plugin config fragment, stops the service, re-registers the interceptor hook (so the brief restart window stays fail-closed rather than passing tool calls through unchecked), and starts the service again. Behavior is identical on Linux, macOS, and Windows. The same flow applies to any other config edit: edits made directly to `falco.yaml` or any included config / rule file take effect on the next `ctl start` (or `ctl mode`) — Falco's own `watch_config_files` is disabled deliberately because it is Linux-only upstream.
 
 `ctl restart` exposes the same stop → re-add hook → start cycle as a standalone command for users who edit config files directly.
@@ -313,7 +317,7 @@ Windows has no user-level systemd or launchd equivalent, so Prempti uses a **Pow
 | `disable` | `systemctl --user disable` | `launchctl unload -w <plist>` | `reg delete <Run key>` |
 | `status` | `systemctl --user status` | `launchctl list <label>` | `tasklist /FI "IMAGENAME eq falco.exe"` |
 
-All three platforms share `ctl health` (synthetic event through the full pipeline), `ctl hook add / remove / status`, `ctl mode`, and `ctl logs` with per-OS tail implementations (`tail -n N [-f]` on Linux/macOS vs `Get-Content -Tail N [-Wait]` on Windows). `--tail` defaults to 100 lines; pass an explicit value to override.
+All three platforms share `ctl health` (synthetic event through the full pipeline), `ctl hook add / remove / status`, `ctl mode`, `ctl default-action`, and `ctl logs` with per-OS tail implementations (`tail -n N [-f]` on Linux/macOS vs `Get-Content -Tail N [-Wait]` on Windows). `--tail` defaults to 100 lines; pass an explicit value to override.
 
 ## Technology Stack
 

configs/README.md

@@ -20,25 +20,34 @@ Key settings:
 Plugin-specific configuration fragment. Merged into `falco.yaml` via `config_files` (append strategy).
 
 Contains:
-- Plugin definition (`coding_agent`) with `init_config` (mode, socket path, HTTP port, verdict tags)
+- Plugin definition (`coding_agent`) with `init_config` (mode, `default_action`, socket path, HTTP port, verdict tags)
 - `load_plugins` list
 - `rules_files` (default rules → user rules → seen rule)
 - `http_output` configuration
 
+#### `default_action` (no-rule-match floor)
+
+In `guardrails` mode, an event matching no deny/ask rule resolves with the
+`default_action` floor: `allow` (default — Prempti approves, skipping the
+agent's own prompt) or `defer` (Prempti steps aside; the agent's own
+permission system decides). deny/ask verdicts are unaffected. Change it via
+`premptictl default-action <allow|defer>`. Ignored in `monitor`/`passthrough`
+(those always defer).
+
 #### `mode: passthrough` (Experimental)
 
 Embedding-only mode. When `mode: passthrough` is set, all interceptor
-requests are resolved as `allow` immediately at register, without
+requests are resolved as `defer` immediately at register, without
 waiting for rule evaluation. Events are still enqueued for Falco so
 observability via `http_output` and `falco.log` is preserved.
 
 Use only when embedding Prempti inside a host agent that handles
 alerts via its own pipeline.
 
 This is distinct from `mode: monitor`: monitor waits for rule
-evaluation and then forces an `allow` verdict (synchronous, so
+evaluation and then resolves as `defer` (synchronous, so
 would-deny/would-ask log lines fire), while passthrough short-circuits
-at register and skips the wait entirely.
+at register and skips the wait entirely. Both ignore `default_action`.
 
 ## Path Expansion
 

docs/hooks/claude-code/SPEC.md

@@ -8,7 +8,7 @@
 
 ## Overview
 
-The Claude Code interceptor is a stateless CLI binary invoked by Claude Code's `PreToolUse` hook on every tool call. It reads the hook JSON from stdin, wraps it in a wire-protocol envelope, sends it to the plugin broker via Unix domain socket, receives a verdict (allow/deny/ask), and writes the hook response to stdout.
+The Claude Code interceptor is a stateless CLI binary invoked by Claude Code's `PreToolUse` hook on every tool call. It reads the hook JSON from stdin, wraps it in a wire-protocol envelope, sends it to the plugin broker via Unix domain socket, receives a verdict (allow/deny/ask/defer), and writes the hook response to stdout.
 
 The interceptor is a **thin passthrough** — it does not interpret tool call content, extract fields, or evaluate policies. All semantic processing (field extraction, path resolution, policy evaluation) happens in the plugin broker. This design keeps the interceptor simple, agent-agnostic, and easy to maintain.
 
@@ -60,7 +60,7 @@ The interceptor reads `tool_use_id` for correlation and passes the entire JSON a
 
 ### Output (stdout)
 
-The interceptor writes a single JSON line to stdout:
+For an `allow`, `deny`, or `ask` verdict the interceptor writes a single JSON line to stdout:
 
 ```json
 {
@@ -72,13 +72,15 @@ The interceptor writes a single JSON line to stdout:
 }
 ```
 
-**Critical invariant**: The interceptor must ALWAYS produce valid JSON on stdout when exiting with code 0. Empty stdout with exit 0 causes Claude Code to silently allow the tool call.
+For a `defer` verdict — the no-rule-match floor when the plugin's `default_action` is `defer`, and the resolution under `monitor` / `passthrough` modes — the interceptor writes **nothing** and exits 0. Claude Code treats exit 0 with no output as "no decision; the normal permission flow applies" (its allowlist/settings decide and it prompts if it normally would). This is deliberately **not** `permissionDecision: "defer"`: per the Claude Code hooks docs that value is a `-p` / Agent SDK feature that pauses the tool call for a wrapper to resume, which would hang an interactive session.
+
+**Critical invariant**: On a broker *error* the interceptor fails closed — it emits an explicit `deny` (unless `PREMPTI_FAIL_OPEN=1`), never empty stdout. The only path that intentionally emits empty stdout is the `defer` verdict above. Empty stdout is **not** a silent allow: per the Claude Code hooks docs, exit 0 with no output continues through the normal permission flow (deny rules still apply, ask rules still prompt).
 
 ### Exit Codes
 
 | Code | Meaning | Claude Code behavior |
 |------|---------|---------------------|
-| 0    | Success | Parse stdout JSON for verdict |
+| 0    | Success | Parse stdout JSON for verdict; empty stdout = no decision (normal permission flow) |
 | 2    | Blocking error | Block tool call, feed stderr to Claude as feedback |
 | Other | Non-blocking error | Log to verbose output, allow tool call |
 
@@ -131,14 +133,14 @@ The `event` field contains the entire Claude Code hook input verbatim. The broke
 ```json
 {
   "id": "<tool_use_id>",
-  "decision": "allow|deny|ask",
+  "decision": "allow|deny|ask|defer",
   "reason": "optional explanation"
 }
 ```
 
 **Validation**: The interceptor verifies that:
 - `id` matches the request's correlation ID
-- `decision` is one of `allow`, `deny`, `ask`
+- `decision` is one of `allow`, `deny`, `ask`, `defer` (`defer` renders as empty stdout — see [Output](#output-stdout))
 
 Failures trigger `verdict_on_error` (fail-closed by default: deny).