From 38b3a00f110ae8ab1d3e305e017704521c05e61d Mon Sep 17 00:00:00 2001 From: knhn1004 <49494541+knhn1004@users.noreply.github.com> Date: Wed, 6 May 2026 14:08:19 -0700 Subject: [PATCH] Reconcile public status docs --- CONTRIBUTING.md | 6 ++++++ README.md | 9 +++++---- docs/guide/getting-started.md | 4 ++-- docs/index.md | 4 ++-- docs/reference/api.md | 6 +++++- docs/reference/detection.md | 2 +- docs/reference/hooks.md | 13 ++++++++++--- 7 files changed, 31 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a17b4d0..3b88525 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,12 @@ You'll need: 3. `bun test`, `cargo test`, and `go test -race` must pass before review. 4. Open a PR with a clear summary. CI runs `ci.yml` on each push. +For changes that ship or unship a public surface, update the status contract in the same PR: + +- `README.md` "What ships today" +- `docs/status.md` +- Any affected guide/reference page under `docs/guide/` or `docs/reference/` + ## Reporting issues - **Bugs / feature requests:** open a GitHub issue at . diff --git a/README.md b/README.md index a2563f3..cddb689 100644 --- a/README.md +++ b/README.md @@ -69,14 +69,15 @@ For agents that need to **author** new rules from natural-language intent, see [ | Surface | Status | |---|---| | `agentlock detect` | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | -| `agentlock install` (Claude Code, Codex CLI, Cursor) | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | +| `agentlock install` (Claude Code, Codex CLI, Cursor, Gemini CLI) | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | | `agentlock install --tier {unattested,software,totp}` | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | -| `agentlock install` (OpenCode, Cline, Gemini CLI, Continue, VS Code Copilot) | ![not yet](https://img.shields.io/badge/-not%20yet-f59e0b?style=flat-square) | +| `agentlock install` (OpenCode, Cline, Continue, VS Code Copilot) | ![not yet](https://img.shields.io/badge/-not%20yet-f59e0b?style=flat-square) | | Five baseline gates in monitor mode | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | | Tamper-evident Merkle ledger | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | | Local web dashboard | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | | Software + TOTP signers (with `signer enroll` + session mint) | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | -| OS keychain signer, hardware-key (YubiKey PIV / FIDO2) | ![not yet](https://img.shields.io/badge/-not%20yet-f59e0b?style=flat-square) | +| OS keychain signer (macOS) | ![shipped](https://img.shields.io/badge/-shipped-16a34a?style=flat-square) | +| Hardware-key signer (YubiKey PIV / FIDO2) | ![not yet](https://img.shields.io/badge/-not%20yet-f59e0b?style=flat-square) | | OIDC SSO + RBAC + LDAP | ![not yet](https://img.shields.io/badge/-not%20yet-f59e0b?style=flat-square) | | Signed PDF audit report | ![not yet](https://img.shields.io/badge/-not%20yet-f59e0b?style=flat-square) | @@ -87,7 +88,7 @@ The complete shipped/not-yet matrix lives at Claude Code · Codex CLI · Cursor"] + H["Agent harness
Claude Code · Codex CLI · Cursor · Gemini CLI"] CLI["agentlock CLI
owns long-lived signing key"] end subgraph docker["Docker (127.0.0.1)"] diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 03f1dde..1c582c0 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -70,7 +70,7 @@ agentlock --help agentlock detect ``` -This prints a table of every agent harness it found on your machine. Today, end-to-end hooks are wired for **Claude Code**, **Codex CLI**, and **Cursor**; other harnesses are detected but the installer flags them as not yet implemented. See [Status](../status.md). +This prints a table of every agent harness it found on your machine. Today, end-to-end hooks are wired for **Claude Code**, **Codex CLI**, **Cursor**, and **Gemini CLI**; other harnesses are detected but the installer flags them as not yet implemented. See [Status](../status.md). Then pick a signer tier and run `install`. Two recommended paths: @@ -124,4 +124,4 @@ Open the dashboard at to watch live activity. Out of the box, the control plane runs in **monitor mode**: every tool call is logged but nothing is blocked. Use the dashboard to review activity, then flip rules to enforce when you're confident. See [Policies and the five gates](policies.md). -OS-keychain and hardware-key (YubiKey) signers are stronger than TOTP and are on the roadmap; today TOTP is the strongest signer that ships. See [Signers](signers.md). +For stronger local signing, macOS can use the shipped OS-keychain signer. Hardware-key signers (YubiKey PIV / FIDO2), Linux Secret Service, and Windows DPAPI remain roadmap. See [Signers](signers.md). diff --git a/docs/index.md b/docs/index.md index 21f92a5..3d25338 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,7 @@ hide: ![OpenAgentLock](assets/banner.svg){ .oal-banner .no-zoom }

-Detect local agent harnesses, gate risky tool calls with a deterministic YAML policy, and anchor every decision in a tamper-evident Merkle ledger. Install once and keep working in **Claude Code, Codex CLI, and Cursor** as normal — your workflow does not change. +Detect local agent harnesses, gate risky tool calls with a deterministic YAML policy, and anchor every decision in a tamper-evident Merkle ledger. Install once and keep working in **Claude Code, Codex CLI, Cursor, and Gemini CLI** as normal — your workflow does not change.

[Get started](guide/getting-started.md){ .oal-cta .primary } @@ -36,7 +36,7 @@ Eight harness detectors registered: Claude Code, Codex CLI, Cursor, OpenCode, Cl #### Install plan / apply `agentlock install` -Interactive multi-select. Posts to `/v1/install/plan`, renders the diff, applies on confirm. Real install paths live for **Claude Code** (HTTP hooks) and **Codex CLI** (TOML hooks). +Interactive multi-select. Posts to `/v1/install/plan`, renders the diff, applies on confirm. Real install paths live for **Claude Code**, **Codex CLI**, **Cursor**, and **Gemini CLI**.
diff --git a/docs/reference/api.md b/docs/reference/api.md index d1f3eb4..f6b34da 100644 --- a/docs/reference/api.md +++ b/docs/reference/api.md @@ -27,7 +27,7 @@ Returns the list of currently active gates with their per-gate status (matched c Synchronous verdict for a single tool call. Request body: - `session_id` — required, string. From `POST /v1/sessions/create`. -- `source` — required, string. Harness id (`claude-code`, `codex`, `cursor`, `mcp-proxy`). +- `source` — required, string. Harness id (`claude-code`, `codex`, `cursor`, `gemini`, `mcp-proxy`, or another detected source). - `tool` — required, string. The tool name being checked (`Bash`, `Read`, `Write`, `mcp____`). - `input` — required, object. The tool's input shape (e.g. `{ "command": "rm -rf foo" }` for Bash). - `cwd` — optional, string. Working directory if relevant to the rule. @@ -79,6 +79,10 @@ The first time a new MCP server fingerprint is seen, it's queued for pinning. Ac `POST /v1/hooks/codex/` +`POST /v1/hooks/cursor/` + +`POST /v1/hooks/gemini/` + `POST /v1/hooks//` (other harnesses; not yet implemented in the installer) The hook event names mirror the harness's own naming. See [Hooks](hooks.md). diff --git a/docs/reference/detection.md b/docs/reference/detection.md index c9c2ac5..bfc1a2b 100644 --- a/docs/reference/detection.md +++ b/docs/reference/detection.md @@ -27,7 +27,7 @@ The result is a small struct with `name`, `present`, `surfaces`, `configPaths`, ## Wiring vs detection -A harness being **detected** is independent of whether the installer will **wire it up**. Today, `agentlock install` wires Claude Code, Codex CLI, and Cursor. The other detectors land in the picker but the installer flags them as not yet implemented and skips writing hook entries. +A harness being **detected** is independent of whether the installer will **wire it up**. Today, `agentlock install` wires Claude Code, Codex CLI, Cursor, and Gemini CLI. The other detectors land in the picker but the installer flags them as not yet implemented and skips writing hook entries. ## Adding a new harness detector diff --git a/docs/reference/hooks.md b/docs/reference/hooks.md index 7787fce..01ed41a 100644 --- a/docs/reference/hooks.md +++ b/docs/reference/hooks.md @@ -32,8 +32,9 @@ When the daemon is unreachable, the shim never writes user-visible text into std - **Claude Code — live `statusLine`** (best UX). The installer writes a `statusLine` entry in `~/.claude/settings.json` pointing at a tiny health-check script at `/bin/agentlock-status`. Claude Code re-runs that script on every UI render and shows the result as a persistent element under the chat: `OpenAgentLock ✓` when the daemon is up, `OpenAgentLock ⚠ daemon offline` when it's not. The output is pure UI — never seen by the model. - **Codex CLI — silent fail-open**. Codex has no `statusLine` analog and hides hook stderr on exit-0 (it only surfaces hook output as a red `(failed)` banner when the hook exits non-zero, which is the wrong channel for a status nudge). There is no in-Codex UI surface available for an indicator that won't either look like an error or pollute the model's input. The shim stays silent on every event when the daemon is unreachable. - **Cursor — silent fail-open**. Cursor's hook spec has no UI surface that's outside the model's input stream and no statusLine equivalent. On daemon failures the shim emits a plain `{"permission":"allow"}` envelope and stays silent. A live indicator for Cursor would need a real Cursor extension; tracked separately. +- **Gemini CLI — silent fail-open**. Gemini hooks have no status-line equivalent. On daemon failures the shim stays silent and lets the tool call continue. -All three harnesses share the wrapper-stability fix: the hook command Claude Code / Codex / Cursor spawn points at `/bin/agentlock` (e.g. `~/Library/Application Support/OpenAgentLock/bin/agentlock` on macOS), written by `agentlock install`. The path lives in our state dir, not in the package manager's `node_modules` tree, so package upgrades don't strand the wired path. The same applies to `agentlock-status`. Both paths are shell-quoted in the wired command string so spaces (`Application Support`) survive `/bin/sh -c` parsing. +All four harnesses share the wrapper-stability fix: the hook command that Claude Code / Codex / Cursor / Gemini spawn points at `/bin/agentlock` (e.g. `~/Library/Application Support/OpenAgentLock/bin/agentlock` on macOS), written by `agentlock install`. The path lives in our state dir, not in the package manager's `node_modules` tree, so package upgrades don't strand the wired path. The same applies to `agentlock-status`. Both paths are shell-quoted in the wired command string so spaces (`Application Support`) survive `/bin/sh -c` parsing. ## Codex CLI @@ -59,9 +60,15 @@ Cursor (≥1.7) uses **command hooks** in `~/.cursor/hooks.json`. The installer Daemon-down behavior is documented in the **Daemon-down UX** section above — Cursor gets silent fail-open on transport errors. We never set `agent_message` on those, since that field lands in the model's input stream and would register as a prompt-injection attempt. +## Gemini CLI + +Gemini CLI uses command hooks in `~/.gemini/settings.json`. The installer wires the `agentlock hook gemini ` shim for the same lifecycle shape as the Gemini settings file exposes, including pre-tool and post-tool events. The shim emits Gemini's permission-decision response shape on stdout. + +Daemon-down behavior is documented in the **Daemon-down UX** section above — Gemini gets silent fail-open on transport errors. + ## Other harnesses -OpenCode, Cline, Gemini CLI, Continue.dev all expose a hook surface but **the installer does not yet write to them**. The detectors find the harness, the picker shows it, and the install plan flags it as not yet implemented. Wiring is a follow-up tracked in the public roadmap. +OpenCode, Cline, and Continue.dev expose a hook surface but **the installer does not yet write to them**. The detectors find the harness, the picker shows it, and the install plan flags it as not yet implemented. Wiring is a follow-up tracked in the public roadmap. VS Code Copilot has no general-purpose pre-tool hook surface; we cannot harden it from outside. @@ -84,4 +91,4 @@ Ledger leaves use the same shape plus `verdict`, `reason`, `policy_rule_id`, and ## Nudges in deny replies -When a matched rule carries a `nudge:` hint (see [Policies → Nudges](../guide/policies.md#nudges)) and the final verdict is `deny`, every harness shim — Claude Code, Codex, Cursor — appends the hint to the deny reason it forwards to the model. The format is the literal string `"\n\n→ Suggested: "` — arrow `→`, capital `S`, colon-space — and is intentionally stable so external tools can grep for `→ Suggested: ` to spot the hint. Allow, monitor-suppressed, and non-matching paths drop the field; the reason flows through unchanged. +When a matched rule carries a `nudge:` hint (see [Policies → Nudges](../guide/policies.md#nudges)) and the final verdict is `deny`, every harness shim — Claude Code, Codex, Cursor, Gemini — appends the hint to the deny reason it forwards to the model. The format is the literal string `"\n\n→ Suggested: "` — arrow `→`, capital `S`, colon-space — and is intentionally stable so external tools can grep for `→ Suggested: ` to spot the hint. Allow, monitor-suppressed, and non-matching paths drop the field; the reason flows through unchanged.