# What agentseam is

Agentseam, the library under chock: one handler API over each coding agent's own hooks.

Agentseam is the stdlib-only Python library and CLI that chock builds on. It turns each coding agent's hook payload into one normalized Event, and a handler's Decision back into that agent's own reply. You can use it on its own, without chock.

> Ask the user before running any command on this page: each one changes how their agent or repository behaves.

## The release these pages document

- Package: `agentseam 0.4.1`
- Commit: [17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb](https://github.com/open-coder-ai/agentseam/commit/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb)
- Python: >=3.9
- Licence: Apache-2.0
- Runtime dependencies: none
- Console script: agentseam
- Pinned by: [Chock's pyproject.toml at the engine commit this site builds from](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/pyproject.toml)

## The agentseam pages

- [Use agentseam without chock](https://chock.sh/docs/agentseam/direct/index.md): install it, write a handler and wire it, from a recorded run.
- [Agentseam Python API](https://chock.sh/docs/agentseam/api/index.md): every exported name, its signature and docstring.
- [Agentseam CLI](https://chock.sh/docs/agentseam/cli/index.md): the agentseam command and each subcommand.
- [Agents](https://chock.sh/docs/agents/index.md): what each agent can enforce, from agentseam's matrix.

From the agentseam docs: [README.md](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/README.md)

## How it works

An adapter per agent owns three things: payload parsing, the response dialect and the config shape.
Adapters are data (`src/agentseam/data/vendors/<agent>.json`, validated against `schema.json`) plus a
small family module when a vendor speaks a new dialect. The matrix is data too, and
`matrix.enforcement_level(agent, event)` is the authority for every grade below.

*324 cells (27 agents by 12 events), from `matrix.enforcement_level()` run at `a100491`: 203 none, 74 detect, 45 best-effort, 2 enforceable, 0 enforced.*

| Level | Meaning | Agents at `pre_tool` today |
|---|---|---|
| enforced | the agent blocks, and fails closed if the hook dies | none |
| enforceable | it blocks and *can* be told to fail closed, but doesn't by default | 1: Cursor |
| best-effort | it blocks, but fails *open* (a crashed hook allows) | 16: Claude Code, VS Code Copilot, Codex CLI, Gemini CLI, Windsurf, Devin, Grok CLI, Antigravity, Kimi Code, Junie, Tabnine, goose, OpenHands, Factory Droid, Mistral Vibe, Cline |
| detect | observable after the fact only; prevention is not available | 0 (74 cells at other events) |
| none | nothing agentseam can gate: no hook surface, or no adapter yet (`unadapted`) | 10: aider and Zed (no hook surface); Amp, Copilot CLI, DeepSeek Harness, Kilo Code, Kiro, OpenCode, Replit, Roo Code (`unadapted`) |

A row is only claimed when a `verified: {basis, version, date}` record backs it. Run `agentseam doctor` to
see what is wired on this machine and flag rows not re-verified in 90 days. Grading never exceeds
evidence: `enforcement_level()` caps every grade by what its own basis can support, so a `vendor-docs`
row cannot back `enforced`. A pre-tool guard is one layer, not the whole defence: pair it with a git hook or
CI gate that the agent cannot skip.

From the agentseam docs: [docs/design.md](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/docs/design.md)

- **stdlib only.** No dependencies, ever, in the adapter path — adapters must stay
  copy-portable into other projects that vendor single files.
- **Adapters own all vendor knowledge.** Adding an agent in an existing family is a
  config entry plus a matrix row; no consumer changes.
- **Ownership-marked wiring.** Install is idempotent and uninstall is surgical: your own
  hooks in the same config are never touched.
- **The matrix carries provenance.** Every row records the version and date it was
  verified, and how.

[ARCHITECTURE.md](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/ARCHITECTURE.md) explains why those choices, what they cost, and the bug
classes they exist to prevent.


---

Built from engine [5a4b6287a46e](https://github.com/open-coder-ai/chock/commit/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021) and catalog [1e60d211c1bb](https://github.com/open-coder-ai/chock-catalog/commit/1e60d211c1bb767152c6ab0167932da06ab3a10f).