Skills teach an agent how to integrate SourceryKit; nothing checks the agent actually did. An agent can skip wrapping a call, forget the structured output, or never verify — and the guardrail silently does nothing. We should ship hooks: deterministic checks that fire on coding-agent events (post-edit, pre-commit) and flag or block an integration that's missing its guardrails, while the code is being written.
Where skills are advisory, hooks are enforcement. Together they cover both halves: teach the right way, then catch when it wasn't followed.
What to ship
Checks that fire during development and fail loudly when the integration is incomplete — for example:
- an outbound HTTP call inside an agent tool that isn't wrapped in
async_intercept_context
- an agent whose output type isn't
SourceryKitAgentResponse (or a subclass), so claimed_values will always be empty
- a tool hitting a URL never registered via
insert_trusted_endpoint
- a terminal path that returns a result without ever calling
evaluate_handoff
The goal is to turn "the guardrail quietly did nothing" into an error the agent sees and fixes on the spot.
Why
- The whole value of SourceryKit is catching hallucinations. A silently-skipped integration is worse than none — it looks protected and isn't.
- Catching it at author time (not runtime, in prod) is cheap and immediate.
- Complements the skills work: skills reduce mistakes, hooks catch the ones that slip through.
Notes / out of scope
- Hooks are per-tool (Claude Code
settings.json, Codex, Gemini each differ) — no shared format like SKILL.md, so expect per-ecosystem adapters. Scope which tools to support during the work.
- The exact check implementation (static analysis vs runtime assertions) — decided by whoever picks this up.
Skills teach an agent how to integrate SourceryKit; nothing checks the agent actually did. An agent can skip wrapping a call, forget the structured output, or never verify — and the guardrail silently does nothing. We should ship hooks: deterministic checks that fire on coding-agent events (post-edit, pre-commit) and flag or block an integration that's missing its guardrails, while the code is being written.
Where skills are advisory, hooks are enforcement. Together they cover both halves: teach the right way, then catch when it wasn't followed.
What to ship
Checks that fire during development and fail loudly when the integration is incomplete — for example:
async_intercept_contextSourceryKitAgentResponse(or a subclass), soclaimed_valueswill always be emptyinsert_trusted_endpointevaluate_handoffThe goal is to turn "the guardrail quietly did nothing" into an error the agent sees and fixes on the spot.
Why
Notes / out of scope
settings.json, Codex, Gemini each differ) — no shared format likeSKILL.md, so expect per-ecosystem adapters. Scope which tools to support during the work.