docs(codex): default to daemon-backed enforcement

Author: Su Fu

clients/gmail-mcp/README.md

@@ -1,22 +1,30 @@
 # permit0-gmail-mcp
 
-MCP server that exposes Gmail tools (Gmail API v1) to Claude Code, **each
-call gated by permit0**. Mirrors `clients/outlook-mcp` — same 13 tools, same
-norm actions, same risk rules.
+MCP server that exposes Gmail tools (Gmail API v1) to agent hosts. With
+Codex, permit0 enforcement happens at the Codex `PreToolUse` hook layer:
+Codex proposes `mcp__permit0-gmail__gmail_send`, the permit0 hook sends it
+to the daemon, and the Gmail API call only runs when the hook allows it.
+Mirrors `clients/outlook-mcp` — same 13 tools, same norm actions, same
+risk rules.
 
 ## Architecture
 
+For Codex:
+
 ```
-Claude Code  ──MCP/stdio──▶  permit0-gmail-mcp
-                               │
-                               ├─▶ @permit0.guard("email.X")
-                               │    └─ POST /api/v1/check_action ──▶ permit0 daemon
-                               │                                       (allow/deny/human)
-                               │
-                               └─▶ Gmail API (gmail.googleapis.com/gmail/v1)
-                                    (only on allow)
+Codex ──PreToolUse hook──▶ permit0 hook --client codex --remote :9090
+   │                              │
+   │                              └─▶ permit0 daemon/dashboard
+   │                                    (allow/deny/human)
+   │
+   └─MCP/stdio, only if allowed──▶ permit0-gmail-mcp
+                                      └─▶ Gmail API
 ```
 
+For hosts without a hook layer, add an equivalent pre-tool gate before
+starting this MCP server. The server itself is plain MCP and does not
+call permit0 internally.
+
 ## Tools exposed
 
 Same 13 tools as outlook-mcp — same parameters, same norm actions:
@@ -72,28 +80,49 @@ and silent-refreshes after that.
 python -c "from permit0_gmail_mcp.auth import get_token; print(bool(get_token()))"
 ```
 
-### 4. Wire into Claude Code
+### 4. Wire into Codex
+
+Start the permit0 daemon and install the Codex hook in remote mode:
+
+```bash
+cd /path/to/permit0
+cargo run -p permit0-cli -- serve --ui --port 9090
+PERMIT0_URL=http://127.0.0.1:9090 bash integrations/permit0-codex/examples/install-managed-prefs.sh
+```
+
+Add the Gmail MCP server to your Codex config:
+
+```toml
+[mcp_servers.permit0-gmail]
+command = "/absolute/path/to/permit0-gmail-mcp"
+```
+
+Restart Codex. The 13 `gmail_*` tools appear, and every Gmail MCP tool
+call is enforced by the daemon-backed Codex hook before the MCP server
+is called.
+
+### Claude Code
 
-Add to `~/.claude.json` under top-level `mcpServers`:
+If you are using Claude Code, wire the server under top-level
+`mcpServers`:
 
 ```json
 {
   "mcpServers": {
     "permit0-gmail": {
-      "command": "permit0-gmail-mcp",
-      "env": {
-        "PERMIT0_URL": "http://localhost:9090"
-      }
+      "command": "permit0-gmail-mcp"
     }
   }
 }
 ```
 
-Restart Claude Code. The 13 `gmail_*` tools appear.
+Then configure a pre-tool permit0 hook for Claude Code so the MCP call is
+gated before it reaches Gmail.
 
 You can have **both** `permit0-outlook` and `permit0-gmail` configured at
-the same time — both gate through the same permit0 daemon, both lower to
-the same `email.*` norm actions, same risk rules.
+the same time. With the host's permit0 hook configured, both lower to the
+same `email.*` norm actions and are evaluated by the same daemon, using
+the same risk rules.
 
 ## Try it
 
@@ -102,7 +131,8 @@ In Claude Code:
 > Search my Gmail for "newsletter" emails from the past 7 days and archive all results.
 
 Claude Code will call `gmail_search(query="newsletter newer_than:7d")` →
-permit0 evaluates each result's `gmail_archive(message_id=...)`.
+the host hook evaluates each `gmail_archive(message_id=...)` before it
+reaches the MCP server.
 
 > Read that entire thread.
 
@@ -123,12 +153,12 @@ conversationId stitching needed).
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
-| `PERMIT0_URL` | `http://localhost:9090` | permit0 daemon URL |
 | `GMAIL_CREDENTIALS` | `~/.permit0/gmail_credentials.json` | OAuth app credentials |
 
 ## Cross-backend invariant
 
-If you have both Gmail and Outlook MCP servers configured, **both** lower
-to the same `email.*` norm actions. permit0 sees one unified IR. The
-dashboard's audit log shows `channel=gmail` vs `channel=outlook`, but the
-risk rule and the human reviewer's decision applies regardless.
+If you have both Gmail and Outlook MCP servers configured behind a
+permit0 hook, **both** lower to the same `email.*` norm actions. permit0
+sees one unified IR. The dashboard's audit log shows `channel=gmail` vs
+`channel=outlook`, but the risk rule and the human reviewer's decision
+applies regardless.

clients/outlook-mcp/README.md

@@ -1,21 +1,26 @@
 # permit0-outlook-mcp
 
-MCP server that exposes Outlook tools (Microsoft Graph) to Claude Code, **each
-call gated by permit0** so policy is enforced before any email is sent, moved,
-or deleted.
+MCP server that exposes Outlook tools (Microsoft Graph) to agent hosts.
+With Codex and Claude Code, permit0 enforcement happens at the host
+`PreToolUse` hook layer: the host proposes
+`mcp__permit0-outlook__outlook_send`, the permit0 hook sends it to the
+daemon, and the Graph API call only runs when the hook allows it.
 
 ## Architecture
 
+```text
+Agent host ──PreToolUse hook──▶ permit0 hook --client <host> --remote :9090
+   │                                  │
+   │                                  └─▶ permit0 daemon/dashboard
+   │                                        (allow/deny/human)
+   │
+   └─MCP/stdio, only if allowed──────▶ permit0-outlook-mcp
+                                          └─▶ Microsoft Graph API
 ```
-Claude Code  ──MCP/stdio──▶  permit0-outlook-mcp
-                               │
-                               ├─▶ @permit0.guard("email.X")
-                               │    └─ POST /api/v1/check_action ──▶ permit0 daemon
-                               │                                       (allow/deny/human)
-                               │
-                               └─▶ Microsoft Graph API
-                                    (only on allow)
-```
+
+For hosts without a hook layer, add an equivalent pre-tool gate before
+starting this MCP server. The server itself is plain MCP and does not
+call permit0 internally.
 
 ## Tools exposed
 
@@ -33,13 +38,19 @@ Claude Code  ──MCP/stdio──▶  permit0-outlook-mcp
 
 ## Setup
 
-### 1. Make sure the permit0 daemon is running
+### 1. Make sure the permit0 daemon and host hook are running
 
 ```bash
 cd /path/to/permit0
 cargo run -p permit0-cli -- serve --ui --port 9090
 ```
 
+For Codex, install the daemon-backed hook:
+
+```bash
+PERMIT0_URL=http://127.0.0.1:9090 bash integrations/permit0-codex/examples/install-managed-prefs.sh
+```
+
 ### 2. Install this MCP server + the Python SDK
 
 ```bash
@@ -61,43 +72,49 @@ Visit the Microsoft device-login URL it prints, sign in with your personal
 Outlook account, approve `Mail.ReadWrite` + `Mail.Send`. Token caches to
 `~/.permit0/outlook_token.json` and is reused by this MCP server.
 
-### 4. Wire into Claude Code
+### 4. Wire into your host
+
+For Codex, add the Outlook MCP server to your Codex config:
+
+```toml
+[mcp_servers.permit0-outlook]
+command = "/absolute/path/to/permit0-outlook-mcp"
+```
 
-Add to your Claude Code config (typically `~/.claude.json` or a project-local
-`.mcp.json`):
+For Claude Code, add it to `~/.claude.json` or project-local `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "permit0-outlook": {
-      "command": "permit0-outlook-mcp",
-      "env": {
-        "PERMIT0_URL": "http://localhost:9090"
-      }
+      "command": "permit0-outlook-mcp"
     }
   }
 }
 ```
 
-Restart Claude Code. The 9 tools above appear in its tool list.
+Restart the host. The 9 tools above appear in its tool list, and each
+mutating Outlook MCP call is enforced by the daemon-backed host hook
+before the MCP server is called.
 
 ## Try it
 
-In Claude Code:
+In your agent host:
 
 > List the 5 most recent emails in my inbox and archive all promotional emails from last week.
 
-Claude Code will call `outlook_list` (no permit0 check), then for each
-candidate message, call `outlook_archive(message_id=...)`. Each archive call
-hits permit0 — you'll see the decisions live in the dashboard at
-http://localhost:9090/ui/ under the **Audit** tab.
+The host will call `outlook_search` or `outlook_list`, then for each
+candidate message, call `outlook_archive(message_id=...)`. Each archive
+call is evaluated by the hook before it reaches the MCP server; you'll
+see the decisions live in the dashboard at <http://localhost:9090/ui/>.
 
 > Send an email to bob@example.com with subject "test" and body "hi".
 
-Claude Code calls `outlook_send(to=..., subject=..., body=...)`. permit0
-evaluates `email.send` against its risk rule. A clean send → ALLOW. Embedding
-something like `password is hunter2` in the body → DENY (the SDK raises
-`permit0.Denied`, the MCP layer reports the block to Claude Code).
+The host calls `outlook_send(to=..., subject=..., body=...)`. permit0
+evaluates `email.send` against its risk rule. A clean send can run.
+Sensitive content or risky recipients return a deny envelope from the
+hook, so the host blocks the tool call before the MCP layer reaches
+Microsoft Graph.
 
 ## Combining with shadow mode
 
@@ -107,16 +124,14 @@ If you want to **observe** without enforcement while you tune the risk rules:
 export PERMIT0_SHADOW=1   # for `permit0 hook` use
 ```
 
-Note: this env var is read by the **`permit0 hook`** subcommand
-(Claude Code PreToolUse). The MCP server itself enforces directly via
-`@permit0.guard` — there's no built-in shadow flag yet. If you want shadow
-mode for MCP tools too, ask and we'll add it.
+Note: this env var is read by the **`permit0 hook`** subcommand. The MCP
+server itself is plain MCP, so shadow/enforcement behavior is controlled
+by the host hook command.
 
 ## Configuration
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
-| `PERMIT0_URL` | `http://localhost:9090` | permit0 daemon URL |
 | `MSGRAPH_CLIENT_ID` | Microsoft Graph PowerShell public client | Override with your own Azure App reg |
 
 ## What this is NOT

clients/outlook-mcp/permit0_outlook_mcp/__init__.py

@@ -1,3 +1,3 @@
-"""permit0-outlook-mcp: MCP server exposing Outlook tools, each gated by permit0."""
+"""permit0-outlook-mcp: plain MCP server exposing Outlook tools."""
 
 __version__ = "0.1.0"

clients/outlook-mcp/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "permit0-outlook-mcp"
 version = "0.1.0"
-description = "MCP server exposing Outlook (Microsoft Graph) tools, each gated by permit0"
+description = "Plain MCP server exposing Outlook (Microsoft Graph) tools for host-level permit0 hooks"
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}

integrations/permit0-codex/README.md

@@ -15,8 +15,9 @@ Model proposes a tool call (Bash, apply_patch, mcp__<server>__<tool>)
    ↓
 Codex fires PreToolUse hook → spawns `permit0 hook --client codex`
    ↓
-permit0 normalizes the tool call through packs, scores it, returns
-either empty stdout (no objection) or a deny envelope
+permit0 forwards the tool call to the daemon, which normalizes it
+through packs, scores it, records the decision for the dashboard, and
+returns either empty stdout (no objection) or a deny envelope
    ↓
 Codex either runs the tool or blocks it with permit0's reason
 ```
@@ -34,9 +35,20 @@ Codex either runs the tool or blocks it with permit0's reason
   # produces ./target/release/permit0
   ```
 
-## Setup (production-ish)
+## Setup (dashboard-visible enforcement)
 
-Add the hook to your Codex config and trust it once via the TUI.
+Start the permit0 daemon, then add the hook to your Codex config and
+trust it once via the TUI. Remote daemon mode is the recommended setup:
+it gives one enforcement point, one approval flow, and one dashboard
+record for every Codex tool decision.
+
+0. Start the daemon:
+
+   ```bash
+   cargo run -p permit0-cli -- serve --ui --port 9090
+   ```
+
+   Open <http://127.0.0.1:9090/ui/> to watch decisions and approvals.
 
 1. Append this block to `~/.codex/config.toml`:
 
@@ -49,7 +61,7 @@ Add the hook to your Codex config and trust it once via the TUI.
 
    [[hooks.PreToolUse.hooks]]
    type = "command"
-   command = "/absolute/path/to/permit0/target/release/permit0 hook --client codex --packs-dir /absolute/path/to/permit0/packs --unknown defer"
+   command = "/absolute/path/to/permit0/target/release/permit0 hook --client codex --remote http://127.0.0.1:9090 --unknown deny"
    timeout = 30
    statusMessage = "permit0 safety check"
    ```
@@ -70,24 +82,33 @@ Add the hook to your Codex config and trust it once via the TUI.
    Exit Codex.
 
 3. From now on every `codex` and `codex exec` session fires permit0 on
-   every tool call. Re-trust is required if you edit the hook command
+   every tool call. If the daemon is down, remote mode fails closed and
+   blocks the tool. Re-trust is required if you edit the hook command
    (Codex tracks a content hash).
 
+Local hook mode (`--packs-dir ...`) still exists for offline development
+and synthetic smoke tests, but it evaluates in the hook process and does
+not write decisions to the daemon dashboard. Do not use local mode when
+you expect dashboard-visible enforcement.
+
 ## Setup (unattended — macOS auto-trust)
 
 For CI, scripts, or anywhere you can't open the TUI: install the hook
 via macOS managed preferences. Codex treats these as MDM-sourced =
 always trusted, no review needed.
 
 ```bash
+cargo run -p permit0-cli -- serve --ui --port 9090
 bash integrations/permit0-codex/examples/install-managed-prefs.sh
 ```
 
 The script reads the same TOML config layered into macOS user defaults
-under `com.openai.codex/requirements_toml_base64`. To uninstall:
+under `com.openai.codex/requirements_toml_base64`. By default it installs
+remote daemon mode against `http://127.0.0.1:9090`; override with
+`PERMIT0_URL=http://host:port` if your daemon runs elsewhere. To uninstall:
 
 ```bash
-defaults delete com.openai.codex requirements_toml_base64
+bash integrations/permit0-codex/examples/install-managed-prefs.sh --uninstall
 ```
 
 This is the path the live-demo launcher in `dev-test-rig/codex-demo`
@@ -114,8 +135,8 @@ enforcement boundary." permit0 inherits them.
 |---|---|---|
 | `Allow` / `Defer` | Zero stdout bytes | Tool runs |
 | `Deny` | `permissionDecision: "deny"` envelope with reason | Tool blocked, model sees the reason |
-| `HumanInTheLoop` (Medium/High tier) | `permissionDecision: "deny"` envelope with `" — requires human review"` marker appended to the reason | Tool blocked; the marker tells users this was a HITL action under Claude Code, not a hard Critical block |
-| Internal error in permit0 | `permissionDecision: "deny"` envelope with `"permit0 internal error: <msg>"` | Tool blocked (fail-closed) |
+| `HumanInTheLoop` (Medium/High tier) | `permissionDecision: "deny"` envelope with `" — requires human review"` marker appended to the reason | Tool blocked; the marker tells users this was a HITL action, not a hard Critical block |
+| Daemon unavailable / internal error | `permissionDecision: "deny"` envelope with the failure reason | Tool blocked (fail-closed) |
 
 Codex `PreToolUse` does **not** support `permissionDecision: "allow"` or
 `"ask"`; both are explicitly rejected. permit0 never emits either.