AI Control Plane  //  Join us on Slack

agenthooks

Author coding-agent hooks once in Go; run them on Claude Code, Cursor, OpenAI Codex, Gemini CLI, OpenCode, and Kimi Code.

One clear interface, zero data-fidelity loss: the library owns the wire (JSON dialects, exit codes, stderr discipline, provider quirks), the consumer owns the logic. See DESIGN.md for the full design and the provider research behind it.

package main

import (
	"context"

	"github.com/speakeasy-api/agenthooks"
)

func main() {
	r := agenthooks.New(
		agenthooks.WithPolicy(agenthooks.Policy{
			Fail:        agenthooks.FailClosed,
			AskFallback: agenthooks.FallbackDeny,
		}),
	)

	r.OnToolPre(func(ctx context.Context, e *agenthooks.ToolPreEvent) (agenthooks.ToolPreDecision, error) {
		if e.Tool.Canonical == agenthooks.ToolShell {
			return agenthooks.AskUser("shell commands need confirmation"), nil
		}
		return agenthooks.NoDecision(), nil
	})

	// Fidelity escape hatch: every event, mapped or not, raw payload intact.
	r.OnAny(func(ctx context.Context, e *agenthooks.Event) error {
		agenthooks.Logger(ctx).Info("event", "provider", e.Provider, "native", e.NativeName)
		return nil
	})

	agenthooks.Main(r)
}

Packages

Installing hooks

m := install.Manifest{
	Command: []string{"/usr/local/bin/myhooks"},
	Hooks: []install.HookSpec{
		{Kind: agenthooks.KindToolPre, Blocking: true, Timeout: 30 * time.Second},
		{Kind: agenthooks.KindStop, Blocking: true},
	},
	Identity: install.Identity{Name: "myhooks", Version: "1.0.0"},
	Fail:     agenthooks.FailClosed,
}
err := install.Install(ctx, m, install.Target{
	Provider: agenthooks.ProviderClaudeCode,
	Scope:    install.ScopeProject,
	Dir:      repoRoot,
})

Generated configs bake in the argv contract (mybinary agenthooks run --provider=...), per-provider timeout units, async workarounds (sync Stop on Claude cowork, backgrounder wrapper on Codex), Cursor failClosed, and Codex trust-hash pre-seeding.

Semantics worth knowing

• NoDecision() != Allow(): an empty-opinion response defers to the provider's own permission flow; it never force-allows.
• Capability degradation is explicit: Policy.Unsupported chooses Degrade (nearest supported intent, logged) or Strict (handler error → Policy.Fail). Check e.Can(agenthooks.CapAsk) when you care.
• Event.Raw is the verbatim provider payload, always. Unknown fields decode into Extra on every native struct. Normalization is a projection.
• Provider gaps are backfilled best-effort: Kimi's and Cursor's print modes never fire their prompt-submitted hooks, so the runner synthesizes a reporting-only prompt.submitted before the next event that implies one — once per recovered prompt per session, so resumed headless turns (-p --resume) backfill again. Backfilled events carry Backfilled: true, a nil Raw (nothing is fabricated), no capabilities, and any returned decision is discarded — the prompt already reached the model. To gate on a recovered prompt, record what the PromptSubmitted handler saw and deny in the triggering event's handler: the backfill dispatches in the same process immediately before it. The prompt text is recovered best-effort — from Kimi's session store; on Cursor from the session transcript every hook payload names (covering stdin-piped prompts), falling back to the agent process's own argv. Disable with WithoutBackfill().
• MCP tool calls carry the target server's transport: MCPCall.URL/Command come from Cursor and Gemini MCP payloads and are otherwise resolved from the provider's own MCP config files (.mcp.json, ~/.claude.json, ~/.codex/config.toml, .cursor/mcp.json, .gemini/settings.json plus extension manifests, .kimi-code/mcp.json, ~/.kimi/mcp.json, opencode.json(c)). OpenCode's shim uses the running server's resolved inventory, including custom, inline, remote, and managed configuration. Codex replays launch -c overrides and profiles into a detached codex mcp list --json warm, keyed by the recovered launch context. On Claude Code, servers absent from config files (plugins, claude.ai connectors) are attributed via claude mcp list, started as a detached SessionStart warm in the launching process's project and configuration context. The first MCP hook waits for that same context's in-flight snapshot only when discovery has not finished. On Claude Code 2.1.214+, launch-only --mcp-config, --strict-mcp-config, --settings, --setting-sources, --plugin-dir, --bare, and --safe-mode semantics are recovered through CLAUDE_PID; older versions fall back to the ordinary on-disk context. Inventories are cached briefly by a secret-safe context digest under the user cache directory and replaced on refresh so removals propagate. Remote --plugin-url servers stay unattributed rather than being refetched with potentially different code during hook dispatch. Config-resolved transport is flagged FromConfig and is best-effort — ambiguous or unrecoverable matches stay empty. Disable with WithoutMCPResolution() (everything) or WithoutMCPListFallback() (provider CLI probes).
• The quirk registry (agenthooks.Quirks()) is the machine-readable list of provider glue this library hides, and doubles as the conformance-test plan.

Contributing

This repository is maintained by Speakeasy, but we welcome and encourage contributions from the community to help improve its capabilities and stability.

How to Contribute

1. Discussions: Have a feature request or want to discuss the roadmap? Use GitHub Discussions to share your ideas and engage with the community.

2. Issues: Found a bug or technical issue? Open a GitHub Issue to report it with details about the problem. Provider-behavior reports are especially valuable — the quirk registry only grows through observation.

3. Pull Requests: We welcome pull requests! If you'd like to contribute code:

   • Fork the repository
   • Create a new branch for your feature/fix
   • Submit a PR with a clear description of the changes and any related issues

4. Feedback: Share your experience using the library or suggest improvements.

All contributions, whether they're feature requests, bug reports, or code changes, help make this project better for everyone. Please ensure your contributions adhere to the existing code style and include appropriate tests where applicable.

License

Released under the MIT License.