Grilling: how are custom per-harness capture hooks authored and registered?

[antejavor]

Part of #259

Question

agent-context-graph already frames itself as "Connect any agent runtime to any context-graph component" via a Runtime Adapter Protocol (Runtime Adapter -> Event Protocol -> Graph Connector(s)), with adapters today for Claude Code, Codex, and the OpenAI SDK. The driving user's longer-term goal is to "support most harnesses via different hook mechanisms." Is the gap (a) more built-in adapters context-graph should ship itself, or (b) a documented, stable extension API so third parties can write their own adapter for their own harness without forking context-graph? Audit what's actually missing today (may need a /research pass first) before grilling the design. Resolve with the driving user via /grilling + /domain-modeling.

[antejavor]

Resolution

Resolved by first auditing the actual code (no assumptions), then a single design question with the driving user:

Already exists, verified: RuntimeAdapter (agent_context_graph/protocols.py) is a genuine, public ABC, exported from the top-level package, with a documented pattern in README.md:379-402 ("Adding a New Runtime Adapter"). A third party can already pip install agent-context-graph, subclass it, emit the shared Event types, and plug into AgentLink for in-process/SDK-style runtimes — no fork required.

The real gap: nothing is documented for command-hook runtimes (Claude Code/Codex-style: harness invokes an external command with a JSON payload on stdin) — despite two real implementations already existing to copy from (adapters/claude_code.py, adapters/codex.py, including the build_hooks_config-style hook-config-generator pattern). A third party targeting a new command-hook harness has real prior art but no guide pointing at it.

Separately, bootstrap/doctor/setup <runtime> are hardcoded to a closed --runtime enum, with no plugin-registration mechanism (e.g. Python entry_points) for a third-party package to register a new runtime name.

Decision: document the command-hook adapter pattern now (extract what claude_code.py/codex.py already do into a second README section, mirroring the existing SDK-style one) — cheap, and directly closes the gap that actually blocks a third party today (discoverability). The CLI plugin-discovery mechanism is explicitly deferred — real, separable future work, not resolved here. Spun out as its own ticket: #268.

[antejavor]

Correction: the CLI plugin-discovery mechanism referenced above as deferred future work is tracked at #269, not #268 (#268 is the separate documentation task also spun out from this ticket).