docs(codex): default to daemon-backed enforcement

Author: Su Fu

README.md

@@ -7,7 +7,7 @@
 <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"></a>
 <img alt="Rust 1.85+" src="https://img.shields.io/badge/rust-1.85%2B-orange">
 
-> Permit0 integrates with **Claude Code** and **OpenClaw** — more integrations to come. The pilot `email` taxonomy is ready, with Outlook and Gmail packs. [Open an issue to request the next taxonomy domain or tool pack →](https://github.com/permit0-ai/permit0/issues/new?template=new-pack.md) and ⭐ star the project.
+> Permit0 integrates with **Claude Code**, **Codex**, and **OpenClaw**. The pilot `email` taxonomy is ready, with Outlook and Gmail packs. [Open an issue to request the next taxonomy domain or tool pack →](https://github.com/permit0-ai/permit0/issues/new?template=new-pack.md) and ⭐ star the project.
 
 ---
 
@@ -23,9 +23,9 @@ The vocabulary is published. The first pack is shipped. The rest is the work.
 
 ---
 
-## Try it — Claude Code + Outlook/Gmail in 5 minutes
+## Try it — Claude Code or Codex + Outlook/Gmail in 5 minutes
 
-> **On OpenClaw?** Skip to [`integrations/permit0-openclaw/`](integrations/permit0-openclaw/) — wrap a skill with `permit0Skill(...)` and gate every dispatch through the same daemon. The rest of this section is the Claude Code path.
+> **On OpenClaw?** Skip to [`integrations/permit0-openclaw/`](integrations/permit0-openclaw/) — wrap a skill with `permit0Skill(...)` and gate every dispatch through the same daemon.
 
 ```bash
 # 1. Build
@@ -74,6 +74,22 @@ Restart Claude Code. Ask it: *"list recent emails and archive any newsletters,"*
 
 Shadow mode (`permit0 hook --shadow`) logs decisions without blocking, if you want to observe before enforcing.
 
+For Codex, use the daemon-backed managed-preferences installer:
+
+```bash
+PERMIT0_URL=http://127.0.0.1:9090 bash integrations/permit0-codex/examples/install-managed-prefs.sh
+```
+
+Then add the MCP server to your Codex config:
+
+```toml
+[mcp_servers.permit0-gmail]
+command = "/abs/path/to/permit0-gmail-mcp"
+```
+
+See [`integrations/permit0-codex/`](integrations/permit0-codex/) for the
+full Codex setup, including unattended install and cleanup.
+
 ---
 
 ## What makes it different
@@ -99,7 +115,7 @@ The taxonomy is the canonical, append-only vocabulary for *what agents do* — `
 
 22 domains, 159 verbs are defined today in [`crates/permit0-types/src/taxonomy.rs`](crates/permit0-types/src/taxonomy.rs) and documented at [`docs/taxonomy.md`](docs/taxonomy.md). The engine fails closed on any tool call that doesn't normalize to a covered action — unknown actions queue for human approval, they don't auto-run.
 
-**Today (v0.1):** engine, signed audit, admin UI, CLI, one reference pack (`email`, 16 verbs for Gmail + Outlook), two integrations (Claude Code, OpenClaw).
+**Today (v0.1):** engine, signed audit, admin UI, CLI, one reference pack (`email`, 16 verbs for Gmail + Outlook), three integrations (Claude Code, Codex, OpenClaw).
 
 **Roadmap:** packs for Slack, Notion, Linear, Stripe, Postgres, Bash, GitHub; framework adapters for LangChain, CrewAI, AutoGen, OpenAI Agents; pre-built CLI binaries.
 
@@ -158,7 +174,7 @@ This preserves the determinism guarantee. The LLM is allowed to be fallible in o
 
 **5. Can I run it fully offline / air-gapped?** Yes. Default install uses SQLite and in-memory storage, no external dependencies. The LLM reviewer is optional — disable it in regulated environments where every medium-risk decision must go to a human.
 
-**6. Why is only the email pack shipped?** Phase 1 focus: prove the engine end-to-end on one domain that everyone has (their inbox), with two channels (Outlook + Gmail), through a real agent host (Claude Code). The taxonomy is the moat; the packs are linear work the community can parallelize. Yours next.
+**6. Why is only the email pack shipped?** Phase 1 focus: prove the engine end-to-end on one domain that everyone has (their inbox), with two channels (Outlook + Gmail), through real agent hosts (Claude Code, Codex, and OpenClaw). The taxonomy is the moat; the packs are linear work the community can parallelize. Yours next.
 
 ---
 

clients/gmail-mcp/README.md

@@ -1,21 +1,28 @@
 # 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 and Claude Code, permit0 enforcement happens at the host
+`PreToolUse` hook layer: the host 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
 
+```text
+Agent host ──PreToolUse hook──▶ permit0 hook --client <host> --remote :9090
+   │                                  │
+   │                                  └─▶ permit0 daemon/dashboard
+   │                                        (allow/deny/human)
+   │
+   └─MCP/stdio, only if allowed──────▶ permit0-gmail-mcp
+                                          └─▶ Gmail API
 ```
-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)
-```
+
+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
 
@@ -72,28 +79,76 @@ 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 or Claude Code
+
+Both Codex and Claude Code enforce Gmail tools through a host-level
+`PreToolUse` hook. The MCP server config only exposes the tools; the hook
+is what calls permit0 before Gmail runs.
+
+#### 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
+
+Start the same daemon:
+
+```bash
+cd /path/to/permit0
+cargo run -p permit0-cli -- serve --ui --port 9090
+```
+
+Add the permit0 hook to Claude Code, for example in
+`~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{ "hooks": [{
+      "type": "command",
+      "command": "/absolute/path/to/permit0/target/release/permit0 hook --remote http://127.0.0.1:9090 --unknown defer"
+    }]}]
+  }
+}
+```
 
-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.
+Restart Claude Code. The same `gmail_*` tools appear, and the hook gates
+each call 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 +157,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 +179,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
 
@@ -61,43 +66,77 @@ 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 Codex or Claude Code
+
+Both Codex and Claude Code enforce Outlook tools through a host-level
+`PreToolUse` hook. The MCP server config only exposes the tools; the hook
+is what calls permit0 before Microsoft Graph runs.
+
+#### Codex
+
+Install the daemon-backed Codex hook:
+
+```bash
+PERMIT0_URL=http://127.0.0.1:9090 bash integrations/permit0-codex/examples/install-managed-prefs.sh
+```
+
+For Codex, add the Outlook MCP server to your Codex config:
+
+```toml
+[mcp_servers.permit0-outlook]
+command = "/absolute/path/to/permit0-outlook-mcp"
+```
+
+#### Claude Code
+
+Add the permit0 hook to Claude Code, for example in
+`~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{ "hooks": [{
+      "type": "command",
+      "command": "/absolute/path/to/permit0/target/release/permit0 hook --remote http://127.0.0.1:9090 --unknown defer"
+    }]}]
+  }
+}
+```
 
-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 +146,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"}