Document macOS desktop flow and split slow e2e loop

Author: GuthL

.github/pull_request_template.md

@@ -7,7 +7,8 @@
 - [ ] `cargo fmt --check`
 - [ ] `cargo clippy --all-targets --all-features -- -D warnings`
 - [ ] `cargo build --locked`
-- [ ] `cargo test --locked -- --test-threads=1`
+- [ ] `cargo test --locked`
+- [ ] `cargo test --locked --test e2e_cli -- --ignored --test-threads=1`
 - [ ] `cargo doc --no-deps`
 
 ## Docs

.github/workflows/ci.yml

@@ -66,13 +66,27 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - name: cargo test --locked -- --test-threads=1
-        run: cargo test --locked -- --test-threads=1
+      - name: cargo test --locked
+        run: cargo test --locked
+
+  slow-daemon-tests:
+    name: slow daemon tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest", "macos-latest"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: cargo test --locked --test e2e_cli -- --ignored --test-threads=1
+        run: cargo test --locked --test e2e_cli -- --ignored --test-threads=1
 
   publish-dry-run:
     name: publish dry-run
     runs-on: ubuntu-latest
-    needs: [fmt, clippy, build, test]
+    needs: [fmt, clippy, build, test, slow-daemon-tests]
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable

CONTRIBUTING.md

@@ -37,17 +37,27 @@ For the codebase module map, see [AGENTS.md](AGENTS.md) or [CLAUDE.md](CLAUDE.md
 
 ## Local Validation
 
-Run these before you open a pull request:
+### Routine local iteration
+
+Use this as the default local loop:
 
 ```bash
 cargo fmt --check
 cargo clippy --all-targets --all-features -- -D warnings
 cargo build --locked
-cargo test --locked -- --test-threads=1
+cargo test --locked
 cargo doc --no-deps
 ```
 
-The test suite includes cases that temporarily override `HOME`, so the documented full-suite command runs the tests serially to avoid cross-test environment races.
+### Full verification before a pull request
+
+Run the slow daemon/proxy tier explicitly before you open a pull request:
+
+```bash
+cargo test --locked --test e2e_cli -- --ignored --test-threads=1
+```
+
+The default `cargo test --locked` path skips the slow daemon/proxy lifecycle e2e scenarios so day-to-day iteration stays tighter. CI still runs that ignored tier explicitly.
 
 If you are changing release packaging, also run:
 

README.md

@@ -72,6 +72,7 @@ KeyClaw ships first-class wrappers for Claude Code and Codex. In generic proxy m
 |------|------|-------|
 | Claude Code | `keyclaw claude ...` wrapper or `source ~/.keyclaw/env.sh` | First-class CLI path |
 | Codex | `keyclaw codex ...` wrapper or `source ~/.keyclaw/env.sh` | First-class CLI path |
+| macOS desktop apps | System proxy + trusted KeyClaw CA | Finder-launched apps do not inherit shell proxy env by default; see [docs/macos-gui-apps.md](docs/macos-gui-apps.md) |
 | ChatGPT / OpenAI web traffic | Local proxy + trusted CA | In scope at the host layer for `chatgpt.com` / `chat.openai.com` when traffic truly traverses the proxy |
 | Direct API clients | `HTTP_PROXY` / `HTTPS_PROXY` + KeyClaw CA | Default hosts include OpenAI, Anthropic, Google, Together, Groq, Mistral, Cohere, and DeepSeek |
 
@@ -160,6 +161,8 @@ For tools outside the built-in `claude` / `codex` wrappers:
 3. Route the client through `http://127.0.0.1:8877`, either via shell env vars or app/OS proxy settings.
 4. Verify with `keyclaw doctor` and a real request that traffic is actually being intercepted.
 
+GUI desktop apps launched outside your shell do not necessarily inherit `source ~/.keyclaw/env.sh`. On macOS, the reliable path for `Claude.app`, `Codex.app`, `ChatGPT.app`, and similar desktop apps is to trust `~/.keyclaw/ca.crt` in the login keychain and use the macOS system proxy instead of assuming shell env injection will reach them. See [docs/macos-gui-apps.md](docs/macos-gui-apps.md) for the current supported flow and rollback steps.
+
 Built-in generic-proxy hosts are:
 
 - `api.openai.com`, `chat.openai.com`, `chatgpt.com`
@@ -229,6 +232,20 @@ If you want the proxy attached to the current terminal instead, use `keyclaw pro
 
 > **Tip:** Add `[ -f ~/.keyclaw/env.sh ] && source ~/.keyclaw/env.sh` to your `~/.bashrc` or `~/.zshrc` to auto-route through KeyClaw in new shells while the proxy is already running. The detached proxy does not auto-start after reboot unless you enable `keyclaw proxy autostart enable`, so after a reboot you may need to start it again.
 
+### macOS desktop apps
+
+The CLI wrappers (`keyclaw claude ...`, `keyclaw codex ...`) are the preferred path on macOS because they inject proxy settings and CA trust into the child process directly.
+
+Finder-launched apps are different: they are started by macOS, not by your shell, so they usually bypass `~/.keyclaw/env.sh` unless you configure the OS proxy itself. The current supported desktop-app flow is:
+
+1. `keyclaw init`
+2. start a healthy proxy and confirm `keyclaw proxy status`
+3. trust `~/.keyclaw/ca.crt` in the macOS login keychain for SSL
+4. enable the macOS HTTP and HTTPS system proxy on the active network service
+5. fully quit and relaunch the desktop app
+
+If the system proxy is enabled while no healthy KeyClaw listener is actually serving the advertised address, desktop apps and browsers can fail with proxy-connection errors. Use [docs/macos-gui-apps.md](docs/macos-gui-apps.md) for the exact commands, verification steps, and rollback path.
+
 ## How It Works
 
 ### Before: a real-looking request with a leaked AWS key

docs/README.md

@@ -6,6 +6,7 @@ KeyClaw's README is optimized for first contact. This directory holds the deeper
 
 - [Architecture overview](architecture.md): request/response flow, major modules, and runtime trust boundaries
 - [Configuration reference](configuration.md): config file sections, environment variables, allowlists, audit log behavior, and daemon restart semantics
+- [macOS desktop-app guide](macos-gui-apps.md): system-proxy and CA-trust setup for Finder-launched apps such as Claude.app, Codex.app, and ChatGPT.app
 - [Supported secret patterns](secret-patterns.md): what the bundled rules catch, how entropy detection fits in, and how to add or override rules
 - [Threat model](threat-model.md): what KeyClaw protects against, what it does not, and how to deploy it safely
 

docs/configuration.md

@@ -67,6 +67,18 @@ include = ["*my-custom-api.com*"]
 rule_ids = ["generic-api-key"]
 patterns = ["^sk-test-"]
 secret_sha256 = ["0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"]
+
+[[hooks]]
+event = "secret_detected"
+rule_ids = ["generic-api-key"]
+action = "exec"
+command = "notify-slack --channel security"
+
+[[hooks]]
+event = "request_redacted"
+rule_ids = ["*"]
+action = "log"
+path = "~/.keyclaw/hooks.log"
 ```
 
 Supported top-level sections today:
@@ -79,6 +91,7 @@ Supported top-level sections today:
 - `audit`
 - `hosts`
 - `allowlist`
+- `hooks`
 
 ## Environment Variables
 
@@ -129,13 +142,26 @@ By default, KeyClaw writes one JSON line per redacted secret to `~/.keyclaw/audi
 - Set `KEYCLAW_AUDIT_LOG=/path/to/file` or `[audit] path = "/path/to/file"` to relocate it.
 - Rotation is the operator's job; KeyClaw appends and does not rotate automatically.
 
+## Hooks
+
+Hooks let you trigger local actions from request-side rewrite events without exposing the raw secret value.
+
+- `event = "secret_detected"` fires when KeyClaw finds a secret during request rewriting
+- `event = "request_redacted"` fires after the request has been rewritten, just before forwarding upstream
+- `action = "exec"` runs a local command with sanitized metadata in env vars and a JSON payload on `stdin`
+- `action = "log"` appends a JSON line to the configured file
+- `action = "block"` rejects matching `secret_detected` requests with `hook_blocked`
+
+Hook payloads include only `event`, `rule_id`, `placeholder`, and `request_host`. Raw secrets are not passed to hook commands or hook log files.
+
 ## Daemon Restart Rules
 
 If you run KeyClaw as a detached daemon with `keyclaw proxy`, daemon-side settings are read when that process starts. After changing `~/.keyclaw/config.toml` or variables such as `KEYCLAW_PROXY_ADDR`, `KEYCLAW_LOG_LEVEL`, `KEYCLAW_GITLEAKS_CONFIG`, `KEYCLAW_NOTICE_MODE`, or `KEYCLAW_REQUIRE_MITM_EFFECTIVE`, restart the proxy so the running daemon picks them up.
 
 ## Notes
 
 - Repeated `--include` flags are available on `keyclaw proxy`, `keyclaw proxy start`, `keyclaw mitm`, `keyclaw codex`, and `keyclaw claude`. They are merged into the effective interception list for that process and accept `*` / `?` glob patterns.
+- GUI desktop apps launched by the OS usually do not inherit the shell proxy environment from `~/.keyclaw/env.sh`; on macOS, use the system proxy path documented in [macOS desktop-app guide](macos-gui-apps.md).
 - KeyClaw does not use or require `KEYCLAW_GITLEAKS_BIN`.
 - By default, KeyClaw creates a machine-local `vault.key` next to the vault instead of relying on a built-in shared passphrase.
 - `KEYCLAW_UNSAFE_LOG=true` is strictly for debugging and may expose raw secret material in logs.

docs/macos-gui-apps.md

@@ -0,0 +1,113 @@
+# macOS Desktop-App Guide
+
+KeyClaw's CLI wrappers are the preferred macOS path because they inject proxy settings and CA trust into the child process directly.
+
+Finder-launched apps are different. `Claude.app`, `Codex.app`, `ChatGPT.app`, and similar GUI clients are launched by macOS, not by your shell, so they do not reliably inherit the proxy environment you get from `source ~/.keyclaw/env.sh`.
+
+The current supported path for macOS desktop apps is:
+
+1. initialize KeyClaw normally
+2. trust `~/.keyclaw/ca.crt` in the login keychain for SSL
+3. run a healthy KeyClaw proxy
+4. enable the macOS HTTP and HTTPS system proxy on the active network service
+5. fully relaunch the desktop app
+
+## Prerequisites
+
+Run the normal first-run setup first:
+
+```bash
+keyclaw init
+keyclaw proxy
+keyclaw proxy status
+```
+
+If `keyclaw proxy status` is not healthy, do not enable the macOS system proxy yet. A system proxy that points at a dead KeyClaw listener can break browser and desktop-app connectivity.
+
+## Trust The KeyClaw CA
+
+Trust `~/.keyclaw/ca.crt` in the login keychain for SSL:
+
+```bash
+security add-trusted-cert -r trustRoot -p ssl -k ~/Library/Keychains/login.keychain-db ~/.keyclaw/ca.crt
+killall trustd || true
+```
+
+Verify it:
+
+```bash
+security verify-cert -c ~/.keyclaw/ca.crt -k ~/Library/Keychains/login.keychain-db -p ssl
+```
+
+Use the user login keychain path above. The desktop-app trace showed that an incorrect trust-domain shape can still leave Electron/Chromium apps rejecting the KeyClaw CA with certificate-authority errors.
+
+## Enable The System Proxy
+
+Find the active network service if needed:
+
+```bash
+route get default
+networksetup -listnetworkserviceorder
+```
+
+Then enable the proxy on that service. Example for `Wi-Fi`:
+
+```bash
+networksetup -setwebproxy "Wi-Fi" 127.0.0.1 8877 off
+networksetup -setsecurewebproxy "Wi-Fi" 127.0.0.1 8877 off
+networksetup -setwebproxystate "Wi-Fi" on
+networksetup -setsecurewebproxystate "Wi-Fi" on
+networksetup -setproxybypassdomains "Wi-Fi" localhost 127.0.0.1 "*.local" "169.254/16"
+```
+
+Check the live state:
+
+```bash
+networksetup -getwebproxy "Wi-Fi"
+networksetup -getsecurewebproxy "Wi-Fi"
+scutil --proxy
+```
+
+You want both HTTP and HTTPS proxies enabled and pointing at `127.0.0.1:8877`.
+
+## Relaunch And Verify
+
+Fully quit and relaunch the desktop app after changing the proxy:
+
+```bash
+osascript -e 'tell application "Claude" to quit' || true
+open -a Claude
+```
+
+Use the same pattern for `Codex` or `ChatGPT`.
+
+Useful verification checks:
+
+```bash
+keyclaw proxy status
+lsof -nP -iTCP:8877
+tail -n 50 ~/.keyclaw/audit.log
+```
+
+Healthy signs:
+
+- the app or its network helper has a live `127.0.0.1:* -> 127.0.0.1:8877` connection
+- `keyclaw proxy status` reports the proxy as healthy
+- audit-log entries or runtime logs show real provider hosts instead of only `stdin` or localhost test traffic
+
+## Roll Back
+
+To stop forcing macOS desktop traffic through KeyClaw:
+
+```bash
+networksetup -setwebproxystate "Wi-Fi" off
+networksetup -setsecurewebproxystate "Wi-Fi" off
+```
+
+Then relaunch the desktop app again.
+
+## Notes
+
+- The CLI wrappers remain the simpler and higher-confidence path when they are available.
+- Desktop-app support depends on both correct CA trust and a healthy system-proxy listener.
+- If traffic still \"feels low,\" inspect `keyclaw proxy stats`, `~/.keyclaw/audit.log`, and runtime logs before assuming detection is broken.

tests/docs_placeholder_contract.rs

@@ -201,6 +201,37 @@ fn readme_project_structure_shows_split_proxy_and_launcher_modules() {
     }
 }
 
+#[test]
+fn docs_cover_hooks_and_macos_desktop_app_flow() {
+    let readme = std::fs::read_to_string("README.md").expect("read README.md");
+    let docs_readme = std::fs::read_to_string("docs/README.md").expect("read docs/README.md");
+    let config =
+        std::fs::read_to_string("docs/configuration.md").expect("read docs/configuration.md");
+    let macos =
+        std::fs::read_to_string("docs/macos-gui-apps.md").expect("read docs/macos-gui-apps.md");
+
+    assert!(
+        readme.contains("macOS desktop apps")
+            && readme.contains("Finder-launched apps")
+            && readme.contains("docs/macos-gui-apps.md"),
+        "README.md should explain the supported macOS desktop-app path: {readme}"
+    );
+    assert!(
+        docs_readme.contains("[macOS desktop-app guide](macos-gui-apps.md)"),
+        "docs/README.md should link the macOS desktop-app guide: {docs_readme}"
+    );
+    assert!(
+        config.contains("[[hooks]]") && config.contains("- `hooks`"),
+        "docs/configuration.md should document hooks as a top-level config section: {config}"
+    );
+    assert!(
+        macos.contains("security add-trusted-cert")
+            && macos.contains("networksetup -setsecurewebproxystate")
+            && macos.contains("Roll Back"),
+        "docs/macos-gui-apps.md should document CA trust, system proxy setup, and rollback: {macos}"
+    );
+}
+
 #[test]
 fn proxy_docs_prefer_sourcing_env_script_and_describe_reboot_behavior() {
     let agents = std::fs::read_to_string("AGENTS.md").expect("read AGENTS.md");

tests/e2e_cli/process_lifecycle.rs

@@ -11,6 +11,7 @@ use crate::support::{can_bind, free_addr, install_fake_tool, prepend_path, wait_
 
 #[cfg(unix)]
 #[test]
+#[ignore = "slow daemon/proxy e2e"]
 fn mitm_releases_proxy_port_immediately_on_sigint() {
     let addr = free_addr();
     let socket_addr: SocketAddr = addr.parse().expect("parse socket addr");
@@ -67,6 +68,7 @@ fn mitm_releases_proxy_port_immediately_on_sigint() {
 
 #[cfg(unix)]
 #[test]
+#[ignore = "slow daemon/proxy e2e"]
 fn mitm_returns_control_to_interactive_shell_after_child_exit() {
     let bin = assert_cmd::cargo::cargo_bin!("keyclaw");
     let temp = tempfile::tempdir().expect("tempdir");

tests/e2e_cli/proxy.rs

@@ -35,6 +35,7 @@ fn proxy_fails_fast_on_broken_generated_ca_pair() {
 
 #[cfg(unix)]
 #[test]
+#[ignore = "slow daemon/proxy e2e"]
 fn proxy_detaches_by_default_and_prints_stop_instructions() {
     struct ProxyGuard(Vec<i32>);
 
@@ -108,6 +109,7 @@ fn proxy_detaches_by_default_and_prints_stop_instructions() {
 
 #[cfg(unix)]
 #[test]
+#[ignore = "slow daemon/proxy e2e"]
 fn proxy_relaunch_on_same_addr_replaces_existing_daemon() {
     fn process_alive(pid: i32) -> bool {
         unsafe { libc::kill(pid, 0) == 0 }
@@ -208,6 +210,7 @@ fn proxy_relaunch_on_same_addr_replaces_existing_daemon() {
 
 #[cfg(unix)]
 #[test]
+#[ignore = "slow daemon/proxy e2e"]
 fn proxy_relaunch_on_different_addr_keeps_existing_daemon() {
     fn process_alive(pid: i32) -> bool {
         unsafe { libc::kill(pid, 0) == 0 }
@@ -326,6 +329,7 @@ fn proxy_relaunch_on_different_addr_keeps_existing_daemon() {
 }
 
 #[test]
+#[ignore = "slow daemon/proxy e2e"]
 fn proxy_detached_fails_fast_when_configured_port_is_busy() {
     let temp = tempfile::tempdir().expect("tempdir");
     let addr = free_addr();