Phase 3: LLM-host hook integration (Claude Code, Codex/ChatGPT, etc.)

[hanwencheng]

Goal

Let AgentKeys participate in the LLM host's lifecycle via the host's native hook system — without modifying the host. Targets the Phase 3 / M3 multi-runtime story (Hermes, OpenClaw, Doubao, Claude Code, Codex/ChatGPT all invoke the same AgentKeys MCP tools under their own runtime control).

This is the complement to the MCP tools we shipped in Phase 1 (memory.get, permission.check, audit.append, …). Tools are LLM-invoked on demand; hooks are runtime-invoked at lifecycle events. Both directions matter:

Direction	Trigger	AgentKeys role
Host → AgentKeys (most useful)	Host's lifecycle hook fires (pre-tool, post-tool, stop, session-end)	AgentKeys tool gets called as the hook body
AgentKeys → Host (later)	permission.check denies, cap.revoke fires	Hook fires in the host to update its UI / refuse the user / clear context

Why this matters

Today the LLM has to decide to call our tools. That works for memory queries but is wrong for guardrails — the LLM shouldn't be free to skip a permission.check before a payment, and shouldn't be free to skip audit.append after sensitive tool use. Hooks move those guarantees out of LLM discretion and into the runtime.

Concrete patterns this unlocks:

1. Pre-payment gate. Claude Code PreToolUse hook for any tool whose name matches *pay*|*order*|*purchase* → call agentkeys.permission.check → block the tool call if verdict=deny. The LLM physically cannot bypass.
2. Auto-audit. PostToolUse hook → agentkeys.audit.append with the tool name, params hash, and result. Every tool use lands in the off-chain audit feed without LLM cooperation.
3. Session summary. Stop hook → agentkeys.memory.put(namespace=profile, content=…) to roll up what the user agreed to / learned / changed during the session.
4. Cross-runtime parity. Same hook contract exposed for Codex/ChatGPT, Cursor, future agents. The runtime's lifecycle vocabulary differs, but the AgentKeys tool surface is the same.

Phase 3 scope (proposed)

• Reference hook configs for Claude Code + Codex/ChatGPT. Ship as starter snippets in docs/wiki/ showing PreToolUse / PostToolUse / Stop wired to AgentKeys MCP tools. Operator copies into their ~/.claude/settings.json (Claude Code) or equivalent.
• agentkeys hook check CLI helper — wraps the host's hook stdin/stdout JSON convention. Operator just writes command: 'agentkeys hook check --scope payment.spend' in their settings; we handle the JSON parsing + MCP call + return the right block/allow shape.
• Cap-mint pre-warming for hook latency — hooks add p99 latency on every tool call; pre-mint a short-TTL cap on session start so the per-call check is sub-50ms.
• One e2e demo per runtime — Claude Code, Codex/ChatGPT, xiaozhi (already partially covered by Phase 1) all running the same three-act storyboard via hooks instead of LLM-invoked tools. Demonstrates 'pick your runtime, AgentKeys behavior is identical.'
• Reverse direction stub — define the JSON shape the host hook fires when our server initiates a denial / revocation. Implementation deferred to M4.

Out of scope (defer to M4)

• Full delegation-chain hooks (parent-agent → child-agent lifecycle binding)
• Real-time UI push when a hook denies (parent app notification)
• Cross-host hook portability spec (a vendor-neutral hook standard)

References

• Claude Code hooks docs: claude --help → settings → hooks (PreToolUse, PostToolUse, Stop, etc.)
• Codex hook system: equivalent lifecycle events
• docs/spec/plans/milestones-roadmap.md §M3 — multi-runtime parity is the umbrella goal
• AgentKeys MCP tools shipped in Phase 1 (Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107) — the surface the hooks call

[vgudur-dev]

The hook architecture here is exactly right — moving permission.check and audit.append out of LLM discretion and into the runtime is the key insight. This maps cleanly to OWASP Agentic Security Initiative classifications:

AgentKeys hook pattern	OWASP ASI threat it mitigates
PreToolUse → permission.check (payment gate)	ASI-05 Excessive Agency — LLM cannot bypass capability boundary
PostToolUse → audit.append	ASI-06 Memory/Context Poisoning — tamper-evident audit trail
Stop → memory.put (session summary)	ASI-06 — provenance-tagged memory write
Cross-runtime parity	ASI-03 Indirect Prompt Injection — consistent enforcement regardless of host

One gap worth noting: the hook body itself is an injection surface

The agentkeys hook check CLI helper reads the tool call params from the host's stdin JSON. If those params contain injected content (e.g., a tool argument crafted to override the permission verdict), the hook body needs to scan them before passing to permission.check:

// agentkeys hook check — PreToolUse handler
import { scanContextInput, ThreatLevel } from 'agent-memory-guard';

async function preToolUseHook(hookInput: ClaudeHookInput): Promise<HookOutput> {
  // Scan tool params for injection before permission check
  const paramStr = JSON.stringify(hookInput.tool_input);
  const scan = await scanContextInput(paramStr, { source: 'tool_params' });
  
  if (scan.threatLevel >= ThreatLevel.HIGH) {
    return {
      decision: 'block',
      reason: `Injection detected in tool params: ${scan.indicators.join(', ')}`,
    };
  }
  
  // Proceed with AgentKeys permission check
  return agentKeys.permission.check({ scope: hookInput.tool_name });
}

This two-layer pattern (AMG scan → AgentKeys permission check) ensures that even a compromised tool argument cannot override the permission verdict through semantic manipulation.

The agentkeys hook check --scope payment.spend CLI helper is a great UX choice — operators shouldn't need to understand the JSON protocol. Worth adding a --scan-params flag that enables the AMG layer for high-sensitivity scopes.

References

• OWASP Agent Memory Guard (AMG): https://github.com/OWASP/www-project-agent-memory-guard
• AgentThreatBench (merged into UK AISI inspect_evals): https://ukgovernmentbeis.github.io/inspect_evals/evals/safeguards/agent_threat_bench/

[hanwencheng]

Architecture sketch — lifted from rohitg00/agentmemory

agentmemory ships hook integration across 8+ LLM hosts (Claude Code, Claude Desktop, Cursor, Codex, OpenCode, Cline, Roo, Gemini CLI, …) with one consistent surface. Worth copying the pattern wholesale, not reinventing.

How they make hooks portable

Layer	Their choice	Why it works
Distribution	Single npm package @agentmemory/agentmemory + thin shim @agentmemory/mcp	Operators get hooks + MCP + CLI from one npm i -g
State	Persistent local server on :3111; both hooks + MCP proxy to it	One source of truth — no "MCP saw X, hook saw Y, they disagree"
Hook scripts	Shell scripts in plugin/<host>/hooks/<event>.sh, POST observation JSON to localhost:3111/agentmemory/observe	Host-agnostic event capture; only the wiring file changes per host
Hook registration	Plugin marketplace per host: /plugin marketplace add rohitg00/agentmemory (Claude Code), codex plugin marketplace add … (Codex). Falls back to agentmemory connect <host> --with-hooks which merges paths into ~/.claude/settings.json	Plugin install handles version upgrades automatically; manual wiring uses absolute paths so per-host config files stay synced
Hooks covered (Claude Code)	12 — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, SubagentStart, SubagentStop, Stop, SessionEnd, Notification, TaskCompleted	Full lifecycle coverage; ours only needs the ones with security/audit implications
Hooks covered (Codex)	6 — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop	Codex's lifecycle vocabulary is smaller
Cross-runtime parity	A single `plugin/` dir per host (plugin/claude-code/, plugin/codex/, plugin/opencode/), each bundles hook scripts + that host's MCP config snippet	The MCP tool surface stays identical; only the trigger contract differs per host

Mapped to AgentKeys

This issue's existing scope translates well, with a few revisions from what agentmemory already proved out:

Phase 3 deliverable	Revised approach using agentmemory's pattern
Reference hook configs in docs/wiki/	Keep, but generate them from a single plugin/ directory shipped in this repo. One plugin/claude-code/hooks/*.sh + plugin/codex/hooks/*.sh etc., compiled to wiki snippets at build time.
agentkeys hook check CLI helper	Keep — this is the equivalent of agentmemory's /agentmemory/observe HTTP endpoint. Implementation choice: stdio JSON-RPC subcommand on the existing agentkeys-mcp-server binary (no separate daemon needed), since hooks fire rarely enough that spawn-per-call latency is fine in M3. M4 can promote to a persistent daemon if we measure p99 latency pain.
Cap-mint pre-warming	Keep, but only worth doing if we go daemon route. With per-call spawn, pre-warming has nowhere to cache to. Re-evaluate after measuring.
One e2e demo per runtime	Keep — Claude Code, Codex, xiaozhi run the same three-act storyboard. Add a CI matrix that runs each runtime's hook scripts headlessly against the local binary.
Reverse direction stub	Keep deferral to M4. agentmemory doesn't do this either yet.

New deliverable: distribution mechanism

agentmemory's killer move is one-command install. We have two viable paths for a Rust binary (see #107 PR thread):

• A. GitHub Release binary + install.sh — curl -fsSL https://github.com/litentry/agentKeys/releases/latest/download/install.sh | sh drops agentkeys-mcp-server at ~/.local/bin/. Then agentkeys connect claude-code --with-hooks (a new subcommand) wires hooks + MCP into the right config files. Matches agentmemory's agentmemory connect <host> UX exactly. Worth the CI investment because this is what operators actually do.
• B. cargo install --git … — works today, requires Rust toolchain on operator's machine. Fine for internal/dev audience; weak for "any user". Should still be CI-tested as a publish-path smoke.

Recommend A as the primary distribution, B kept as a fallback.

File layout proposal

crates/agentkeys-mcp-server/
└── src/                          # existing — MCP tools
└── src/hooks/                    # NEW — hook event handlers, called from CLI
    ├── pre_tool_use.rs           # implements permission.check gate
    ├── post_tool_use.rs          # implements audit.append fire-and-forget
    └── session_summary.rs        # implements memory.put on Stop

plugin/                           # NEW — host-specific wiring (shipped in releases)
├── claude-code/
│   ├── hooks/
│   │   ├── pre-tool-use.sh       # one-liner: exec agentkeys-mcp-server hook pre-tool-use
│   │   ├── post-tool-use.sh
│   │   └── stop.sh
│   └── plugin.json               # plugin manifest for /plugin install
├── codex/
│   ├── hooks/*.sh
│   └── plugin.toml               # codex plugin manifest
└── README.md                     # which host gets which subset

scripts/
└── install-mcp-server.sh         # NEW — operator-facing one-liner

Minimal acceptance for Phase 3

• agentkeys-mcp-server hook pre-tool-use reads the host's JSON envelope on stdin, calls permission.check internally, returns the right {decision: allow|block, reason: …} shape Claude Code expects.
• plugin/claude-code/hooks/*.sh are one-liners that exec the above subcommand.
• agentkeys connect claude-code --with-hooks merges hook commands + MCP config into ~/.claude/settings.json with absolute paths, idempotent on re-run.
• One e2e test in CI: spin up agentkeys-mcp-server with MCP_BACKEND=in-memory, run Claude Code with a fake tool call matching *payment*, verify the PreToolUse hook fires permission.check and blocks above the daily cap.
• Same e2e for Codex via its own hook config.
• One-liner install: curl …/install.sh | sh && agentkeys connect claude-code works on a fresh ubuntu container.

— learned from the deploy thread on #107; lifted from rohitg00/agentmemory which has 950+ tests + 8-host parity already shipped.