Agentseam

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.

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`

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

`Decision`

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

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`

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

`handle`

handle(raw, handler, agent=None)

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

Source: src/agentseam/dispatch.py#L166

`degrade`

degrade(decision, event, agent=None)

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

Source: src/agentseam/dispatch.py#L116

Matrix

`agents`

agents()

No docstring.

Source: src/agentseam/matrix.py#L111

`adapted_agents`

adapted_agents()

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

Source: src/agentseam/matrix.py#L115

`capability`

capability(agent, event)

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

Source: src/agentseam/matrix.py#L56

`can_block`

can_block(agent, event)

No docstring.

Source: src/agentseam/matrix.py#L64

`can_rewrite`

can_rewrite(agent, event)

No docstring.

Source: src/agentseam/matrix.py#L68

`can_transform`

can_transform(agent, event)

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

Source: src/agentseam/matrix.py#L72

`enforcement_level`

enforcement_level(agent, event)

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

Source: 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

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 and catalog 1e60d211c1bb.