transient-trace 0.1.0a5

Python SDK for transient trace ATP reference implementation

transient-trace

Governance SDK for AI agents. Intercepts, evaluates, and audits every action an agent takes, with policy enforcement, tamper-evident receipts, and a self-learning rule engine.

Part of Transient, the trust infrastructure for autonomous agents.

Install

pipx install transient-trace

pipx installs into an isolated environment and puts the transient-trace binary on PATH permanently. If you don't have pipx: brew install pipx && pipx ensurepath.

pip install will fail on modern macOS and Linux due to PEP 668 system package protection. Use pipx.

Upgrade

pipx upgrade transient-trace

Quickstart

The fastest path to governed agents is the wrap command. It installs a persistent shell shim so every invocation of the binary goes through governance automatically, no prefix required.

# Wrap Claude Code and add shims to your shell RC file
transient-trace wrap install claude --auto-rc

# Restart your shell (or source the RC file)
source ~/.zshrc

That's it. Every claude invocation is now governed with a full receipt trail.

# Check governance is active
transient-trace wrap status

# View recent receipts
transient-trace receipts list --since 30m

# Summary with deny rate
transient-trace receipts summary --since 1h

---

Enforce a policy

By default, transient-trace runs in audit mode — records everything, blocks nothing. To enforce a policy, switch to strict mode:

cat > my-policy.json << 'EOF'
{
  "version": 1,
  "defaultAction": "deny",
  "rules": [
    { "id": "allow-git",       "action": "allow", "actionClasses": ["read", "write_low"] },
    { "id": "allow-anthropic", "action": "allow", "actionClasses": ["network"],
      "hosts": ["api.anthropic.com"] }
  ]
}
EOF

transient-trace run --mode strict --policy "$(cat my-policy.json)" claude -p "..."

Or set strict mode as the permanent default:

transient-trace config set mode strict

---

How transient-trace intercepts agent actions

transient-trace uses three complementary interception layers:

1. PATH shims — thin bash scripts for git, curl, and other monitored binaries are prepended to PATH. Shell-resolved calls are caught here.

2. Popen hook — sitecustomize.py is injected via PYTHONPATH into every Python subprocess. It monkey-patches subprocess.Popen to catch calls that use absolute binary paths, bypassing PATH. This is why transient-trace works inside Claude Code without any changes to Claude Code itself.

3. Inherited environment — both mechanisms are inherited by child processes, giving coverage across nested agents and subprocesses.

---

Python SDK

For direct integration into Python agents:

from transient_trace import Client

policy = {
    "version": 1,
    "defaultAction": "allow",
    "rules": [{"id": "allow-all", "action": "allow"}]
}

client = Client({"agentId": "my-agent", "policy": policy})

result = client.executeActionWithReceipt(
    lambda: {"ok": True},
    {"target": "resource-1", "action_class": "write_low"}
)

print(result["receipt"]["receipt_id"])       # TR-...
print(result["receipt"]["signature"]["alg"]) # Ed25519
print(result["decision"]["outcome"])         # allow

If policy returns deny, raises RuntimeError: Denied: <reason_code>.

Further reading

• Transient — full product docs, Recall, Intelligence, receipt bus
• ATP 1.0 — the open protocol specification underlying every receipt

Key differences from the TypeScript SDK

• Synchronous API — no await, no asyncio
• Config is a dict — Client({"agentId": "..."}), not keyword args
• Default policy is deny-all — pass a policy or set ATP_POLICY_PATH

---

Interoperability with TypeScript SDK

Receipt signatures are cross-verifiable — a receipt signed by the Python SDK can be verified by the TypeScript SDK and vice versa.

• Canonicalization: RFC 8785 JCS (both SDKs, action receipts)
• Signing: Ed25519 via PyNaCl (Python) / @noble/curves (TypeScript)