@shidesheng0218/agentguard 0.8.1 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 # 🛡️ agent-guard (formerly kimi-guard)
 
-**A runtime behavior guard for coding agents — [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) and [Claude Code](https://code.claude.com) — stop runaway agent loops before they burn your quota.**
+**A runtime behavior guard for coding agents — [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code), [Claude Code](https://code.claude.com) and [Codex CLI](https://github.com/openai/codex) — stop runaway agent loops before they burn your quota.**
 
 `npm i -g @shidesheng0218/agentguard && agentguard install` → done. (Existing users: your installed `kimi-guard` keeps working — its `kguard` bin and hook entries stay live.)
 
@@ -10,13 +10,13 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/shidesheng0218/kimi-guard/ci.yml?style=flat-square&label=CI)](/.github/workflows/ci.yml)
 
-<img src="https://raw.githubusercontent.com/shidesheng0218/kimi-guard/main/assets/banner.svg" alt="kimi-guard banner" width="100%"/>
+<img src="https://raw.githubusercontent.com/shidesheng0218/kimi-guard/main/assets/banner.svg?v=0.8.1" alt="agent-guard banner" width="100%"/>
 
 **[English](README.md) · [中文文档](docs/README.zh-CN.md)**
 
 <div align="center">
 
-![kimi-guard demo](https://raw.githubusercontent.com/shidesheng0218/kimi-guard/main/assets/demo.gif?v=0.6.1)
+![agent-guard demo](https://raw.githubusercontent.com/shidesheng0218/kimi-guard/main/assets/demo.gif?v=0.8.1)
 
 *Real terminal session: install → verify → a supervised run where the circuit breaker catches a looping tool call → live status & budget panels. Recorded with [vhs](https://github.com/charmbracelet/vhs) from actual commands ([demo.tape](assets/demo.tape)).*
 
@@ -34,19 +34,19 @@ Kimi Code CLI is a great open-source coding agent, but its subagent system has k
 - All subagents share **one API key**, so a burst of parallel dispatches exhausts TPM/RPM and everything hangs.
 - A mid-batch quota error leaves **half-written workspaces** that poison the whole run.
 
-kimi-guard is a local, zero-daemon guard that sits on the CLI's official [hooks system](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/hooks.html) and enforces hard caps — no source forking, no proxy, no account access.
+agent-guard is a local, zero-daemon guard that sits on the CLI's official [hooks system](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/hooks.html) and enforces hard caps — no source forking, no proxy, no account access.
 
 Since v0.8 the same engine also guards **Claude Code** via its [hooks system](https://code.claude.com/docs/en/hooks) (`agentguard install` auto-detects installed harnesses). Wire-mode supervision (`agentguard run`), mid-turn steering and official-API quota metering remain Kimi-exclusive; loop/churn/explore detection, quota gates, the completion gate, kill switch and checkpoints work on both.
 
 ## Features
 
-kimi-guard is not a preset pack — it is a **runtime behavior analysis and enforcement engine**. Every tool call flows through a normalization layer, a set of pure analyzers, and a policy engine that maps findings to actions (observe / warn / block / full stop).
+agent-guard is not a preset pack — it is a **runtime behavior analysis and enforcement engine**. Every tool call flows through a normalization layer, a set of pure analyzers, and a policy engine that maps findings to actions (observe / warn / block / full stop).
 
 | Guard | Signal it detects | Action |
 |---|---|---|
 | 🔁 **Repetition** | same `(tool, args)` signature re-run N times (whitespace-tolerant fingerprinting) | block |
 | 🔄 **Cycle detection** | oscillating loops: `A→B→A→B…` up to period-3, regardless of tool | block |
-| 📉 **No-information-gain** | different arguments, byte-identical output — the model is spinning without new data (the real root cause of upstream [#2142](https://github.com/MoonshotAI/kimi-cli/issues/2142) Case B) | warn → block |
+| 📉 **No-information-gain** | different arguments, byte-identical output — the model is spinning without new data (the real root cause of upstream [#2142](https://github.com/MoonshotAI/kimi-cli/issues/2142) Case B). Fuzzy variant catches near-identical outputs (trigram similarity) | warn → block |
 | ✏️ **Edit churn** | the same file edited over and over without converging ("thrashing") | warn → block |
 | 🐢 **No-progress stretch** | long run of tool calls with no successful edit landing — motion without progress | warn → block |
 | 🔭 **Exploration drift** | long streak of read/search calls with no action in between — exploring without implementing | warn → block |
@@ -62,7 +62,7 @@ kimi-guard is not a preset pack — it is a **runtime behavior analysis and enfo
 
 Warn-level findings are injected into the model's context (official hooks stdout mechanism) so the agent can correct itself *before* a block becomes necessary. Blocks feed a structured reason back to the model (official exit-code-2 mechanism).
 
-Everything is **fail-open**: if kimi-guard itself errors, the agent keeps working. It is a safety net, not a single point of failure.
+Everything is **fail-open**: if agent-guard itself errors, the agent keeps working. It is a safety net, not a single point of failure.
 
 ## Install
 
@@ -86,13 +86,14 @@ Claude Code users can also install via the plugin channel (this repo is a self-h
 
 ### Harness support
 
-| Capability | Kimi Code CLI | Claude Code |
-|---|---|---|
-| Loop / churn / explore detection, kill switch | ✅ hooks | ✅ hooks |
-| Quota gates | ✅ event-based + official-API precise (`[budget] precise`) | ✅ event-based estimates |
-| Completion gate (claim vs evidence) | ✅ | ✅ |
-| Checkpoints / resume, feedback loop, reports | ✅ | ✅ |
-| `agentguard run` Wire supervision, mid-turn steer | ✅ | — (hooks only) |
+| Capability | Kimi Code CLI | Claude Code | Codex CLI |
+|---|---|---|---|
+| Loop / churn / explore detection, kill switch | ✅ hooks | ✅ hooks | ✅ hooks (shell + `apply_patch`; hosted tools like WebSearch are not observable) |
+| Quota gates | ✅ event-based + official-API precise (`[budget] precise`) | ✅ event-based estimates | ✅ event-based estimates |
+| Completion gate (claim vs evidence) | ✅ | ✅ | ✅ |
+| Checkpoints / resume, feedback loop, reports | ✅ | ✅ | ✅ |
+| `agentguard run` supervised headless runs | ✅ Wire protocol | ✅ stream-json supervision | — |
+| Mid-turn steer, exact per-step token metering | ✅ | — | — |
 
 <details>
 <summary>What <code>agentguard install</code> writes</summary>
@@ -161,17 +162,20 @@ kguard config init|show|get <key> # manage ~/.kimi-guard/config.toml
 kguard hook <event>     # (used by the CLI, reads JSON from stdin)
 ```
 
-### `kguard run` — supervised headless runs
+### `agentguard run` — supervised headless runs
 
 This is the tool for CI, cron jobs and unattended agents — the exact scenario where a
 repeating tool call burns the full timeout (upstream issue #2142 was a headless run).
 
 ```sh
-kguard run "refactor the auth module and make tests pass" \
+agentguard run "refactor the auth module and make tests pass" \
   --max-steps 100 --max-minutes 20 --auto-resume 1 --json
+
+# Claude Code headless supervision (stream-json driver):
+agentguard run "migrate the test suite to vitest" --harness claude --max-steps 50
 ```
 
-What the supervisor does in-process (no shell hooks, no exit codes):
+What the supervisor does (Kimi, Wire protocol — in-process, no exit codes):
 
 - subscribes to `PreToolUse` over the Wire protocol and returns `allow/block` decisions — the same analyzers, zero-latency
 - **steers** the agent mid-turn (`steer`) when a warn-level pattern appears, before a hard block is needed
@@ -180,9 +184,15 @@ What the supervisor does in-process (no shell hooks, no exit codes):
 - enforces hard caps: `--max-steps` (cancel via official `cancel` method), `--max-minutes`
 - **kill switch**: after N blocks it cancels the turn and checkpoints
 - approval policy: default rejects with feedback (headless-safe), `--yolo` approves
-- writes a run report (`report.json`) + raw wire log (`wire.jsonl`) under `~/.kimi-guard/runs/`
+- writes a run report (`report.json`) + raw wire log (`wire.jsonl`) under `~/.agent-guard/runs/`
 - exit code 0 on clean finish, 2 on any intervention-triggered end — CI-friendly
 
+The Claude driver (`--harness claude`) spawns `claude -p --output-format stream-json` and supervises the
+event stream: same analyzers and state db (shared with the installed hooks, which do the actual blocking),
+hard caps via `--max-turns` + wall clock, kill switch (SIGINT → SIGKILL), verify rounds and auto-resume
+via `--resume`, exact token metering from `result.usage`. Mid-turn steer is not available (the stream is
+read-only) — blocks still reach the model through the installed hooks in real time.
+
 ## Configuration
 
 `~/.kimi-guard/config.toml` (see `kguard config init`; full annotated template included):
@@ -263,7 +273,7 @@ flowchart LR
     subgraph KIMI["Kimi Code CLI"]
         A["tool call"] -->|"hook event / Wire msg"| B
     end
-    subgraph GUARD["kimi-guard"]
+    subgraph GUARD["agent-guard"]
         B["Normalization layer<br/>schema-variant tolerant<br/>+ output hashing"] --> C["Analyzers (pure functions)<br/>repeat · cycle · no-gain · churn<br/>no-progress · near-repeat · explore"]
         M["Budget engine<br/>5h/weekly windows<br/>burn-rate projection"] --> C
         C --> D["Policy engine<br/>findings → action<br/>+ kill switch"]
@@ -279,7 +289,7 @@ The completion gate adds a claim-vs-evidence loop on top:
 ```mermaid
 sequenceDiagram
     participant A as Agent
-    participant G as kimi-guard
+    participant G as agent-guard
     participant DB as local evidence (state.db)
     A->>A: runs tools (Shell, edits...)
     A->>G: turn ends, claims "all tests pass"
@@ -328,17 +338,17 @@ Kimi Code CLI ──hook event──▶ kguard hook <event> (JSON on stdin)
 
 ## Ecosystem fit
 
-The agent-runtime tooling space is crowded, and pretending every tool competes with every other one helps nobody. kimi-guard occupies one specific layer — here is the honest map:
+The agent-runtime tooling space is crowded, and pretending every tool competes with every other one helps nobody. agent-guard occupies one specific layer — here is the honest map:
 
 ```
 ┌────────────────────────────────────────────────────────────────┐
-│  your agent (Kimi Code CLI)                                    │
+│  your agent (Kimi Code CLI · Claude Code)                      │
 │                                                                │
 │  built-in loop_control      step/attempt caps + compaction     │
 │  ├─ mechanical counter — stops the loop, explains nothing       │
 │                                                                │
 │  ┌──────────────────────────────────────────────────────────┐  │
-│  │  kimi-guard (this project) — the enforcement layer       │  │
+│  │  agent-guard (this project) — the enforcement layer      │  │
 │  │  semantic loop detection · quota gates · steering ·      │  │
 │  │  checkpoints · goal anchoring — the agent cannot bypass  │  │
 │  └──────────────────────────────────────────────────────────┘  │
@@ -350,7 +360,7 @@ The agent-runtime tooling space is crowded, and pretending every tool competes w
 │  kimi-boost                  security preset installer         │
 │  ├─ dangerous-command guards, branch protection, skills       │
 │  ├─ WHAT the agent may do (security) — different axis from    │
-│  │  kimi-guard's HOW it behaves (runtime loops/budget)        │
+│  │  agent-guard's HOW it behaves (runtime loops/budget)       │
 │                                                                │
 │  cli-agent-runner            lifecycle supervisor              │
 │  ├─ 7×24 restart loops, log-level anomaly detection           │
@@ -363,24 +373,24 @@ The agent-runtime tooling space is crowded, and pretending every tool competes w
 
 **Three lines of positioning:**
 
-1. **Monitors are plentiful, voluntary orchestrators exist — but a non-bypassable enforcement layer, kimi-guard is the first in the Kimi ecosystem.** (ccusage-family tools are read-only; kimi-session-orchestrator relies on the agent choosing to call it; kimi-guard intercepts.)
+1. **Monitors are plentiful, voluntary orchestrators exist — but a non-bypassable enforcement layer, agent-guard is the first in the Kimi ecosystem.** (ccusage-family tools are read-only; kimi-session-orchestrator relies on the agent choosing to call it; agent-guard intercepts.)
 2. **Mid-turn steering is an intervention outside the hook-lifecycle boundary — no verified analog does it: external supervisors (e.g. [loop-eng/loopguard](https://github.com/loop-eng/loopguard)) can only SIGSTOP-pause the process and post a desktop notification; in-process detector libraries ([LoopBuster](https://github.com/liuchunwei732-cmyk/loopbuster)) need the host app to honor them; security-hook suites (cc-safety-net) act pre-execution only. We do it natively over the official Wire protocol.**
 3. **The budget model understands Kimi's subscription semantics: 5h/weekly request windows, reserved headroom, burn-rate projection — USD-billing competitors don't reconcile against plan-based users.**
 
 **What we deliberately do NOT do** (so you know where to look):
 
 - Security scanning / destructive-command guards → use **kimi-boost** presets (different axis: authorization vs behavior). `kguard doctor` detects whether a security layer is present and points you there if not.
-- Completion verification exists in kimi-guard as a **deterministic claim-vs-evidence gate** (no LLM in the loop), with an *opt-in* single-vote LLM veto for false positives (`VETO: yes|no` protocol, per-session budget cap, fail-closed on any error). For richer semantic verification (refute-by-default judges, LLM grading), see kimi-session-orchestrator's `grade_step` or the refute-by-default pattern in multi-runtime governance suites.
-- Multi-runtime portability (Claude Code / Codex / Gemini) → by design, our leverage is Kimi's Wire protocol. The analyzer core (`src/analysis.ts`) is pure functions and reusable if you want to build adapters
+- Completion verification exists in agent-guard as a **deterministic claim-vs-evidence gate** (no LLM in the loop), with an *opt-in* single-vote LLM veto for false positives (`VETO: yes|no` protocol, per-session budget cap, fail-closed on any error). For richer semantic verification (refute-by-default judges, LLM grading), see kimi-session-orchestrator's `grade_step` or the refute-by-default pattern in multi-runtime governance suites.
+- Multi-runtime portability: ✅ shipped for Claude Code (v0.8) and Codex CLI (v0.9) — see the harness matrix. Next adapters (Gemini etc.) reuse the pure-function analyzer core ([PORTING.md](docs/PORTING.md))
 - Daemon-style process supervision (SIGSTOP/SIGCONT, systemd) → **cli-agent-runner** owns that layer; ours is semantic in-harness intervention
 
-Related Kimi-ecosystem projects worth knowing: [kimi-session-orchestrator](https://github.com/FirenzeClaw/kimi-session-orchestrator) (multi-session orchestration), [oh-my-kimi](https://github.com/xz1220/oh-my-kimi) (skill/hook presets), [cli-agent-runner](https://github.com/wan9yu/cli-agent-runner) (lifecycle supervision with a kimi preset), [kimi-code-usage](https://github.com/Golden0Voyager/kimi-code-usage) (read-only usage reporting). kimi-guard and [kimi-boost](https://github.com/shidesheng0218/kimi-boost) come from the same author and are designed as a pair: boost covers the authorization axis, guard the behavior axis.
+Related Kimi-ecosystem projects worth knowing: [kimi-session-orchestrator](https://github.com/FirenzeClaw/kimi-session-orchestrator) (multi-session orchestration), [oh-my-kimi](https://github.com/xz1220/oh-my-kimi) (skill/hook presets), [cli-agent-runner](https://github.com/wan9yu/cli-agent-runner) (lifecycle supervision with a kimi preset), [kimi-code-usage](https://github.com/Golden0Voyager/kimi-code-usage) (read-only usage reporting). agent-guard and [kimi-boost](https://github.com/shidesheng0218/kimi-boost) come from the same author and are designed as a pair: boost covers the authorization axis, guard the behavior axis.
 
 ### The cross-ecosystem landscape (verified 2026-09)
 
 The behavioral-enforcement niche is not just empty in the Kimi ecosystem — a survey of the wider coding-agent tooling space found no shipped equivalent:
 
-| Tool | Mechanism | What it can/cannot do vs kimi-guard |
+| Tool | Mechanism | What it can/cannot do vs agent-guard |
 |---|---|---|
 | [cc-safety-net](https://github.com/kenryu42/cc-safety-net) (1.5k★, 13 CLIs incl. Kimi Code) | pre-execution hooks | Blocks dangerous commands/secret access — the authorization axis. No loop detection, no quotas, no steering. Proves multi-runtime hooks appetite. |
 | [ccusage](https://github.com/ccusage/ccusage) (18k★) | log analytics | Read-only cost/token reports over 18 agent CLIs. Never blocks. The usage-data layer is commoditized; enforcement is the open layer. |
@@ -390,7 +400,7 @@ The behavioral-enforcement niche is not just empty in the Kimi ecosystem — a s
 | [ralph](https://github.com/frankbria/ralph-claude-code) (9.6k★) | shell wrapper loop | Exit gates and rate limits at iteration boundaries only — works around runaway agents by restarting, doesn't govern them. |
 | NeMo Guardrails / Guardrails AI / Langfuse / LangSmith / Helicone | content rails / SDK / proxy / SaaS | Structurally cannot intercept a local CLI's tool calls: proxies see only model HTTP traffic, content validators see text, observability is after-the-fact. |
 
-**The takeaway:** monitors are commoditized, security hooks are crowded, orchestration is well-served — behavioral, semantic, mid-run enforcement of a local coding CLI is the layer nobody ships. kimi-guard's moat is the combination, not any single feature: hook/Wire access point × semantic detectors × subscription-aware budgeting. The main strategic risk is single-runtime binding; the analyzer core is pure functions ([PORTING.md](docs/PORTING.md)) precisely so adapters can widen it.
+**The takeaway:** monitors are commoditized, security hooks are crowded, orchestration is well-served — behavioral, semantic, mid-run enforcement of a local coding CLI is the layer nobody else ships. agent-guard's moat is the combination, not any single feature: hook/Wire access point × semantic detectors × subscription-aware budgeting — now running on two harnesses (Kimi Code + Claude Code), with the pure-function analyzer core ([PORTING.md](docs/PORTING.md)) ready for more.
 
 ## Compatibility