# Agentseam Python API

Every name agentseam exports, with its signature and docstring, read from the pinned release.

The site generates this page at build time from the installed agentseam: each name in \`agentseam.__all__\`, its signature from \`inspect.signature\`, and the first paragraph of its own docstring.

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

## How we build this reference

The page lists names as `agentseam` exports them. A summary is the first paragraph of the object's own docstring at the pinned commit. If an object has no docstring, its summary reads "No docstring." Source links go to the line that defines the object.

## Contract: Event and Decision

### `Event`

```python
Event(agent, event, *, tool=None, command=None, path=None, content=None, output=None, prompt=None, session_id=None, tool_use_id=None, cwd=None, raw=None)
```

One agent lifecycle event, normalized.

Source: [src/agentseam/contract.py#L39](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/contract.py#L39)

### `Decision`

```python
Decision(outcome, reason=None, updated_input=None, evidence=None, context=None)
```

What a handler wants to happen. Adapters translate this to vendor dialect.

Source: [src/agentseam/contract.py#L110](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/contract.py#L110)

| Member | Kind | Signature | Summary |
| --- | --- | --- | --- |
| `allow` | classmethod | `(reason=None, evidence=None, context=None)` | No docstring. |
| `deny` | classmethod | `(reason, evidence=None, context=None)` | No docstring. |
| `escalate` | classmethod | `(reason, evidence=None, context=None)` | Defer the action to the host's own approval path (ACS `escalate`). |
| `ask` | classmethod | `(reason, evidence=None, context=None)` | Deprecated alias of escalate() -- kept so existing callers keep constructing. |
| `transform` | classmethod | `(updated_input, reason=None, evidence=None, context=None)` | Replace the tool input wholesale (ACS `transform`, at whole-value granularity). |
| `rewrite` | classmethod | `(updated_input, reason=None, evidence=None, context=None)` | Deprecated alias of transform() -- kept so existing callers keep constructing. |
| `warn` | classmethod | `(reason=None, evidence=None, context=None)` | Permit the action with no change, recording a warning (ACS `warn`). |
| `vouch` | classmethod | `(reason=None, evidence=None, context=None)` | No docstring. |

## Dispatch

### `run`

```python
run(handler, agent=None, stdin=None, stdout=None, *, exit=True)
```

Read one payload from stdin, dispatch, emit the vendor response, exit.

Source: [src/agentseam/dispatch.py#L218](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/dispatch.py#L218)

### `handle`

```python
handle(raw, handler, agent=None)
```

Pure core: raw payload + handler -> (stdout_text, exit_code, event, decision).

Source: [src/agentseam/dispatch.py#L166](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/dispatch.py#L166)

### `degrade`

```python
degrade(decision, event, agent=None)
```

Reduce a decision to what the agent can actually honor, honestly.

Source: [src/agentseam/dispatch.py#L116](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/dispatch.py#L116)

## Matrix

### `agents`

```python
agents()
```

No docstring.

Source: [src/agentseam/matrix.py#L111](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/matrix.py#L111)

### `adapted_agents`

```python
adapted_agents()
```

Agents agentseam can actually hook. Everything else is instruction-files only.

Source: [src/agentseam/matrix.py#L115](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/matrix.py#L115)

### `capability`

```python
capability(agent, event)
```

What `agent` can do at `event`. Unknown agent/event -> no capability.

Source: [src/agentseam/matrix.py#L56](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/matrix.py#L56)

### `can_block`

```python
can_block(agent, event)
```

No docstring.

Source: [src/agentseam/matrix.py#L64](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/matrix.py#L64)

### `can_rewrite`

```python
can_rewrite(agent, event)
```

No docstring.

Source: [src/agentseam/matrix.py#L68](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/matrix.py#L68)

### `can_transform`

```python
can_transform(agent, event)
```

ACS-named alias of can_rewrite() -- same capability, same value.

Source: [src/agentseam/matrix.py#L72](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/matrix.py#L72)

### `enforcement_level`

```python
enforcement_level(agent, event)
```

The honest word for what a consumer may claim at this surface.

Source: [src/agentseam/matrix.py#L77](https://github.com/open-coder-ai/agentseam/blob/17dd700eb0b1f8af9c6bfd42bd9438fd5e4445cb/src/agentseam/matrix.py#L77)

| Name | Value |
| --- | --- |
| `MATRIX` | A dict with 27 entries |

The matrix as data. The site renders it on the Agents pages. [Agents](https://chock.sh/docs/agents/index.md)

## Events

| Name | Value |
| --- | --- |
| `EVENTS` | `('session_start', 'session_end', 'prompt_submit', 'pre_tool', 'post_tool', 'tool_failure', 'pre_compact', 'stop', 'subagent_start', 'subagent_stop', 'instructions_loaded', 'file_changed')` |
| `SESSION_START` | `'session_start'` |
| `SESSION_END` | `'session_end'` |
| `PROMPT_SUBMIT` | `'prompt_submit'` |
| `PRE_TOOL` | `'pre_tool'` |
| `POST_TOOL` | `'post_tool'` |
| `TOOL_FAILURE` | `'tool_failure'` |
| `PRE_COMPACT` | `'pre_compact'` |
| `STOP` | `'stop'` |
| `SUBAGENT_START` | `'subagent_start'` |
| `SUBAGENT_STOP` | `'subagent_stop'` |
| `INSTRUCTIONS_LOADED` | `'instructions_loaded'` |
| `FILE_CHANGED` | `'file_changed'` |
| `UNKNOWN` | `'unknown'` |

## Outcomes

| Name | Value |
| --- | --- |
| `ALLOW` | `'allow'` |
| `DENY` | `'deny'` |
| `ESCALATE` | `'escalate'` |
| `TRANSFORM` | `'transform'` |
| `WARN` | `'warn'` |
| `VOUCH` | `'vouch'` |
| `ASK` | `'escalate'` |
| `REWRITE` | `'transform'` |

## Submodules

### `adapters`

Per-agent adapters: parse a vendor payload -> Event; speak a Decision in vendor dialect.

Module `agentseam.adapters`. Its public names, from `__all__` where the module sets one, otherwise the functions and classes it defines:

| Member | Kind | Signature | Summary |
| --- | --- | --- | --- |
| `get` | function | `(agent)` | No docstring. |
| `claimants` | function | `(raw)` | Every adapter that claims `raw`, in name order. |
| `detect` | function | `(raw)` | Best-effort agent identification from a raw payload: the one claimant, else None. |
| `readers` | function | `(raw)` | Whose reading of `raw`'s event counts when `detect()` declines: the claimants; else, when the payload names its event, every adapter that maps names -- one that infers the event from shape alone has no say over a payload it did not claim; else nobody, and the event is unknown. |
| `shell_tools` | function | `(agent)` | Tool names a shell command arrives under, or () where none is established. |

### `bundler`

Hooks, rendered standalone: bundler assembles the engine + one vendor entry into one file.

Module `agentseam.bundler`. Its public names, from `__all__` where the module sets one, otherwise the functions and classes it defines:

| Member | Kind | Signature | Summary |
| --- | --- | --- | --- |
| `SUPPORTED_AGENTS` | tuple | `('antigravity', 'claude_code', 'cline', 'codex_cli', 'cursor', 'devin', 'factory_droid', 'gemini_cli', 'goose', 'grok', 'junie', 'kimi_code', 'mistral_vibe', 'openhands', 'tabnine', 'vscode_copilot', 'windsurf')` |  |
| `bundle` | function | `(agent)` | Render `agent`'s dispatch runtime as one self-contained, stdlib-only Python file. |
| `bundle_entry` | function | `(cfg)` | Render one vendor config entry as a self-contained, stdlib-only hook file. |

### `instructions`

Primitive 2: instruction files -- where each agent reads its standing instructions.

Module `agentseam.instructions`. Its public names, from `__all__` where the module sets one, otherwise the functions and classes it defines:

| Member | Kind | Signature | Summary |
| --- | --- | --- | --- |
| `agents` | function | `()` | No docstring. |
| `paths` | function | `(agent)` | Files `agent` reads, most-preferred first. Unknown agent -> []. |
| `reads_shared` | function | `(agent)` | No docstring. |
| `discover` | function | `(repo_root='.')` | Which instruction files actually exist here, per agent. |
| `plan` | function | `(targets=None, repo_root='.')` | Decide the smallest set of writes that reaches every requested agent. |
| `render` | function | `(existing, text, agent=None)` | Return `existing` with our managed block inserted or replaced. |
| `write` | function | `(text, targets=None, repo_root='.', *, dry_run=False)` | Write `text` as a managed block into the fewest files that reach `targets`. |
| `remove` | function | `(targets=None, repo_root='.')` | Strip our managed block from each file, leaving everything else intact. |

### `packaging`

Primitive 3: packaging -- describe a bundle once, lay it out for every agent that has one.

Module `agentseam.packaging`. Its public names, from `__all__` where the module sets one, otherwise the functions and classes it defines:

| Member | Kind | Signature | Summary |
| --- | --- | --- | --- |
| `COMMAND` | str | `'command'` |  |
| `EXECUTABLE` | str | `'executable'` |  |
| `HOOKS` | str | `'hooks'` |  |
| `MCP` | str | `'mcp'` |  |
| `PARTS` | tuple | `('skill', 'subagent', 'command', 'hooks', 'mcp', 'executable')` |  |
| `SHARED_SKILL_DIR` | str | `'.agents/skills'` |  |
| `SKILL` | str | `'skill'` |  |
| `SUBAGENT` | str | `'subagent'` |  |
| `UNRECORDED` | dict | `A dict with 20 entries` |  |
| `Bundle` | class | `(name, version='0.1.0', description=None, parts=())` | A named, versioned set of parts. |
| `Part` | class | `(kind, name, body, description=None, *, executable=False)` | One piece of a bundle: a kind, a name, and its body text. |
| `Plan` | class | `(agent, root, files, unrepresentable=(), executables=frozenset())` | The files to write, relative to the bundle root, plus what did not fit. |
| `Unrepresentable` | class | `(part, reason)` | A part this agent's format has nowhere to put, and why. |
| `agents` | function | `()` | Agents with a recorded packaging format. |
| `also_reads` | function | `(agent, part=None)` | Folders `agent` reads that belong to another agent's layout. |
| `executable_ref` | function | `(agent, path)` | The string a HOOKS command should use to reach a rendered EXECUTABLE at `path`. |
| `layout` | function | `(agent)` | The recorded format for `agent`, or None. |
| `plan` | function | `(agent, bundle)` | Lay `bundle` out for `agent`, reporting every part the format cannot hold. |
| `plugin_root` | function | `(agent)` | The token a hook command should use to reach its own plugin directory. |
| `same_path_for` | function | `(part, targets=None)` | Agents among `targets` whose path template for `part` is identical, grouped by template. |
| `supports` | function | `(agent, part)` | The path template for `part`, or None where the agent has no equivalent. |

### `permissions`

Primitive 4: config and permissions -- one policy, spelled in each agent's own dialect.

Module `agentseam.permissions`. Its public names, from `__all__` where the module sets one, otherwise the functions and classes it defines:

| Member | Kind | Signature | Summary |
| --- | --- | --- | --- |
| `UNRECORDED` | dict | `A dict with 23 entries` |  |
| `ContentRule` | class | `(kind, pattern, message=None)` | A deny on CONTENT matching a regex -- what bytes a file or a piece of text contain, |
| `Plan` | class | `(agent, fragment, path, fmt, unrepresentable=())` | What `plan()` produced: a native fragment, plus what did not survive. |
| `Rule` | class | `(action, capability, specifier=None)` | One policy statement: do `action` to `capability`, optionally narrowed by `specifier`. |
| `Unrepresentable` | class | `(rule, reason)` | A rule this agent's config has no faithful way to state, and the reason. |
| `agents` | function | `()` | Agents with a recorded permission model. |
| `capability` | function | `(agent)` | The full recorded model for `agent`, or None. |
| `config_files` | function | `(agent)` | Config files for `agent`, highest precedence first. Unknown agent -> []. |
| `deny_is_authoritative` | function | `(agent)` | Can a deny be overridden by an allow? True/False, or None where unestablished. |
| `discover` | function | `(repo_root='.')` | Which permission config files actually exist here, per agent. |
| `expresses` | function | `(agent, action)` | The config key implementing `action` for `agent`, or None if it cannot say it. |
| `plan` | function | `(agent, rules)` | Render `rules` into `agent`'s native config, reporting whatever could not be rendered. |

## Version

| Name | Value |
| --- | --- |
| `__version__` | `'0.4.1'` |


---

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).