acdp-agent-hooks
Hooks for agent frameworks that sign every tool result and every final output,
publish each one to an ACDP
registry, and link them together with derived_from. Each publish returns an
acdp:// link, and OpenTelemetry spans get the spec's acdp.* attributes.
- Claude Agent SDK:
PostToolUse,PostToolUseFailureandStophooks, appended to whatever hooks you already have (seam'sSeamHooks, for example). - OpenAI Agents SDK: a
RunHooks(on_tool_end,on_agent_end) plus a composer, so it runs alongside your own hooks. - OpenTelemetry: optional. Only the names in the spec's
registries/otel-attributes.mdare emitted.
pip install "acdp-agent-hooks[claude]" # or [openai]; add ,otel for spans
Python 3.10+. Depends on the acdp SDK (≥ 0.17.3)
for canonicalisation and signing, and on httpx for transport.
Configuration: two lines
ACDP_REGISTRY_URL=https://registry.agentcontextdistributionprotocol.io
ACDP_PRODUCER_KEY=ed25519:<base64url seed>
acdp-hooks keygen prints a fresh ACDP_PRODUCER_KEY line. The key decides
the producer DID:
ACDP_PRODUCER_KEY |
Producer |
|---|---|
ed25519:<seed> |
did:key, derived from the key. Nothing to host; verifiers check it offline. A new key is a new identity. |
ed25519:<seed>;did=did:web:agents.example.com:my-agent#key-1 |
did:web. Publish the key in that DID document (acdp-hooks keygen --did-web <key-id> prints the public key). Use it for a long-lived identity that can rotate keys. |
<seed> is the 32-byte Ed25519 seed as base64url or 64 hex characters. It is
the private key. Keep it in your secret store.
Keyless signing (RFC-ACDP-0021) is still a draft, so it is not supported yet.
In code, HooksConfig(registry_url, producer_key) does the same job, and
HooksConfig.from_env() reads the two variables. The other settings have
defaults: fail_policy (open), visibility (public), timeout_s (10)
and retries (2).
Claude Agent SDK
from claude_agent_sdk import ClaudeAgentOptions, query
from acdp_hooks import AcdpPublisher
from acdp_hooks.claude_agent import AcdpClaudeHooks
provenance = AcdpClaudeHooks(AcdpPublisher.from_env())
options = ClaudeAgentOptions(hooks=provenance.attach()) # or provenance.attach(existing_hooks)
async for message in query(prompt="...", options=options):
...
ledger = provenance.ledger(session_id)
ledger.tool_links # one Link per tool result
ledger.output_link # the final output's Link
- Tool results (
PostToolUse, andPostToolUseFailurewithis_error: true). One body per call. Itsctx_idgoes back to the model asadditionalContext(ACDP provenance for this Read result: acdp://…). Turn that off withinject_link=False. - Final output (
Stop). One body overlast_assistant_message. To publishResultMessage.resultyourself, useawait provenance.publish_final_output(result, session_id), and passpublish_output_on_stop=Falseso the output isn't published twice. attach(existing)returns a new hooks map:existingwith this package's matchers appended to each event's list. It never removes, replaces or reorders a matcher, and it does not mutateexisting.install(options)does the same in place on aClaudeAgentOptions.merge_hooks(a, b, …)concatenates any number of maps.- Each matcher's timeout (
hook_timeout_s) is set longer than one publish including all its retries. That way the fail policy settles a slow registry, not the SDK's hook timeout. - Every hook body is sentineled. A malformed hook input or an unexpected error is handled by the fail policy and never raised into the SDK.
With seam's SeamHooks
seam's SeamHooks (package seam-claude-agent, from seam-adapters) gates
tool calls with PreToolUse and audits them with
PostToolUse/PostToolUseFailure. The two packages coexist on the same
events:
from seam_claude_agent import SeamHooks
from acdp_hooks.claude_agent import AcdpClaudeHooks
seam = SeamHooks(gate)
provenance = AcdpClaudeHooks(AcdpPublisher.from_env())
options = ClaudeAgentOptions(hooks=provenance.attach(seam.matchers()))
- Order. Seam's matchers come first in each list and ACDP's are appended after them. Neither hook reads the other's output.
- Seam decides, ACDP records.
PreToolUsebelongs to seam alone. A call seam denies never runs, so it gets noPostToolUseand no ACDP body. A call seam transforms is recorded with thetool_inputthe SDK reports toPostToolUse. - Both audit, independently. Seam's
ToolUseAuditand the ACDP ledger both see the sametool_response. Seam's post hooks return{}. Under fail-open, ACDP's return onlyadditionalContext, so nothing collides. - Fail-closed. If you set ACDP to fail-closed, a failed publish replaces
the tool output that reaches the model (
updatedToolOutput/updatedMCPToolOutput). Seam's audit row still records the real result, because the tool did run. - Timeouts are per matcher. Seam derives its timeout from its gate deadline; ACDP derives its own from the publish deadline. Neither one stretches the other.
can_use_tool. ACDP never sets it, so seam's escalation adjudicator keeps working as before.
OpenAI Agents SDK
from agents import Runner
from acdp_hooks import AcdpPublisher
from acdp_hooks.openai_agents import AcdpRunHooks, compose_run_hooks
publisher = AcdpPublisher.from_env() # reuse across runs
provenance = AcdpRunHooks(publisher) # one per run
result = await Runner.run(agent, prompt, hooks=compose_run_hooks(my_hooks, provenance))
provenance.ledger.output_link # the final output's acdp:// link
on_tool_endpublishes one body per local tool call. For function tools the arguments come fromToolContext.tool_arguments, andon_tool_startsuppliesstarted_at.on_agent_endpublishes the final output, with the agent'snameincluded.Runner.runaccepts a singlehooksobject, socompose_run_hooks(a, b, …)forwards everyRunHookscallback to each member in order.- The SDK gives a hook no way to change a tool result, so fail-closed raises
PublishErrorout of the hook. The SDK wraps it inUserErrorand the run stops before the model sees the result.
What gets published
Bodies never contain the result. Each one is a record of salted hashes,
following the model of RFC-ACDP-0019 §4.3: H(salt ‖ JCS(value)), with a fresh
32-byte salt for every body.
| Tool result | Final output | |
|---|---|---|
type |
agent_hooks:tool-result |
agent_hooks:agent-output |
title |
Tool result: <tool> |
Agent output[: <agent>] |
metadata.record_version |
acdp-agent-hooks-tool-result/1 |
acdp-agent-hooks-output/1 |
metadata |
framework, tool, arguments_hash, result_hash, is_error, salted, embedded, started_at?, completed_at |
framework, agent?, output_hash, salted, embedded, completed_at |
tags |
["acdp-agent-hooks"] |
same |
The Link returned for each body (ctx_id, lineage_id, version,
content_hash, registry, producer, type, derived_from, salt) is the
only place the salt exists. Holding the result plus the link lets you prove the
binding: fetch the body, verify it, then recompute the hash with
acdp_hooks.salted_hash(salt, result). Without the salt, the public body
reveals nothing about the content. Treat the salt as carefully as the result.
It is not in repr(link) and never goes into a span.
These types are custom (<namespace>:<type>), not the RFC-ACDP-0019
acdp:mcp-tool-result. That record describes an MCP proxy's view of an MCP
server (serverInfo, transport, endpoint hash), and an in-process hook can't
see any of it, especially for built-in tools.
derived_from
Every body links to the ctx_ids the run consumed:
- Declared inputs:
ledger.consume(ctx_id, verified=…), for example a context your app placed in the prompt. - Cited in a tool's arguments: picked up by the RFC-ACDP-0019 §4.4 walk (JCS order, whole-string matches only).
- Seen in a tool's result: any
acdp://id embedded in what a tool returned. It counts as an input to everything the run does afterwards, not to that tool's own body. - The run's own tool results: the final-output body also derives from every tool-result body published during the run.
The list keeps first occurrences in that order and is capped at 1000, the RFC-ACDP-0002 maximum.
Visibility
The default is public. With salted hashes, a public body shows only that
the producer called a named tool at a given time; it never shows what went in
or came out. If even that is sensitive, set visibility="private". In that
case only callers the registry authorises can resolve the link.
RFC-ACDP-0019 §8.3 reasons the same way. The configured value is used as is; a
rejected publish is never retried with a wider visibility.
Publish failure policy
The default is fail-open. A hook that can't publish lets the agent carry
on, and the failure is recorded in three places: ledger.failures, the
acdp.publish.error span attribute and a WARNING on the acdp_hooks logger.
Provenance is an observer of the agent and shouldn't take production agents
down when a registry is unreachable. RFC-ACDP-0019 §7 uses the same default.
Set fail_policy="closed" when nothing should leave the run without
provenance:
| Fail-open (default) | Fail-closed | |
|---|---|---|
| Claude, tool result | result passes through unchanged | result replaced by a "withheld" message (updatedToolOutput / updatedMCPToolOutput, decision: block) |
Claude, Stop |
nothing changes | continue_: false with a stopReason |
Claude, publish_final_output |
returns None |
raises PublishError |
| OpenAI, any hook | the run continues | raises PublishError, which stops the run |
A publish counts as failed when the registry returns an error, when the body
can't be built (for example, metadata over 64 KB), or when retries run out:
retries extra attempts with exponential backoff, each with a timeout_s
limit. Retries resend the same bytes under
Idempotency-Key: acdp-hooks-<content hash>, so a retry never publishes twice.
PublishError.code holds the registry's RFC-ACDP-0007 error code, or
transport when no ACDP error was returned.
OpenTelemetry
Install the otel extra (opentelemetry-api) and configure a tracer provider
as usual. Without the extra, every OTel call is a no-op.
acdp.publishspan. Each publish opens a child span under the active span. It getsacdp.ctx_id,acdp.lineage_id,acdp.version,acdp.content_hash,acdp.producer,acdp.registry,acdp.typeandacdp.derived_from; on failure it getsacdp.publish.errorinstead of the identifiers. Giving each body its own span keeps several tool results under one agent span from overwriting each other'sacdp.ctx_id.- The active span (the work that used the inputs) gets
acdp.input.ctx_ids. When you reported verification throughconsume(..., verified=…), it also getsacdp.input.verified, which istrueonly if every input was reported verified. acdp_hooks.annotate_chain_verdict(verdict)copies an RFC-ACDP-0017 chain verdict'schain.latest,chain.as_ofandverdict_digestonto the active span (acdp.input.chain_verdict*,acdp.input.verdict_digest).
Values are copied from the wire without changes. A name outside the registry raises an error instead of being emitted. Body content, arguments, results and salts never go into an attribute. CI checks the name list against the pinned spec checkout.
Development
uv venv && uv pip install -e ".[claude,openai,otel,dev]"
ruff format --check . && ruff check . && mypy
coverage run -m pytest && coverage report # unit tests, coverage-gated
# integration: a local acdp-registry-rs (docker) …
docker compose -f tests/integration/compose.yml up -d --wait
ACDP_IT_REGISTRY=http://localhost:8443 pytest -m integration
# … or production (publishes public bodies under a throwaway did:key)
ACDP_IT_REGISTRY=https://registry.agentcontextdistributionprotocol.io pytest -m integration
CI follows the ACDP Delivery Standard:
format, lint, mypy --strict, a coverage gate, a no-extras install, a build
with twine check, and the integration suite against a local registry
container. main is protected by acdp-ci/scripts/standardize.sh.
Releasing
Bump version in pyproject.toml and __version__ in
src/acdp_hooks/__init__.py, update CHANGELOG.md, merge, then push a
v<version> tag. release.yml builds the package, attests provenance and
publishes to PyPI through Trusted Publishing, so no token is stored. The
PyPI trusted publisher names this repo, release.yml and the pypi
environment.
TypeScript packages will follow.
License
Apache-2.0
Metadata
Release files for acdp-agent-hooks 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| acdp_agent_hooks-0.1.0.tar.gz | 34.4 kB | With provenance | Details for acdp_agent_hooks-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| acdp_agent_hooks-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for acdp_agent_hooks-0.1.0-py3-none-any.whl |
Total release size: 62.2 kB
Release files / acdp_agent_hooks-0.1.0.tar.gz
| Download URL | acdp_agent_hooks-0.1.0.tar.gz |
|---|---|
| Size | 34.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e8f49bd6c2221cc6cb0bf2e74e1fac64ab33c2b6db39c77b34d93384933ac0d
|
|
BLAKE2b-256 checksum How to use checksums |
69a4a114536844b6797b95a7bb4ca6dd183d3a44bfbe6814cb4a82c2f55fe26f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / acdp_agent_hooks-0.1.0-py3-none-any.whl
| Download URL | acdp_agent_hooks-0.1.0-py3-none-any.whl |
|---|---|
| Size | 27.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
70c75b0dc0bb5db4c7b11efa5cf6a033ddd48148ce4d5e97d17736d4f465ad90
|
|
BLAKE2b-256 checksum How to use checksums |
99852c9a517f469e4c0cc7245f513ae29204cdc66e62e4dc1d0e673e4ea3fe25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for acdp-agent-hooks 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for acdp_agent_hooks-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.