Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

Tamper-evident tracing for AI agents: every tool call is recorded as an Ed25519-signed, hash-chained event by a signer
the agent can't control, checkpointed to witnesses, gated by a policy engine, and exported as offline-verifiable `.tkb`
bundles. Today's code (1.5) has two generations: the v1 laptop path (tracekitd, the
bundles. Today's code (1.6) has two generations: the v1 laptop path (tracekitd, the
JSONL ledger, Claude Code / Codex / Cursor / Gemini / OpenCode / Kilo Code / goose / Qwen Code / Factory Droid / Antigravity / Crush / Devin / Cline / gptme / OpenHands / Copilot CLI / CodeBuddy Code / jcode / Kiro CLI hooks) and the v2 signer service for server-hosted agents (evidence
format v2 at 1.4, signer-side policy, detection and containment, custody through the executor and MCP gateway, egress
observation), with Python and TypeScript SDKs and framework integrations. [HIGH CONFIDENCE — read
Expand All @@ -32,6 +32,8 @@ observation), with Python and TypeScript SDKs and framework integrations. [HIGH
| `tracekit/gateway.py`, `tracekit/executor.py`, `tracekit/mcp_gateway.py`, `tracekit/a2a_gateway.py`, `tracekit/egress.py` | LLM gateway, T2 tool executor, MCP gateway, A2A gateway (experimental), egress observer | [HIGH CONFIDENCE] |
| `tracekit/graph.py` | `tracekit graph`: a graded graph of what agents did across verified bundles (experimental) | [HIGH CONFIDENCE] |
| `tracekit/report.py` | `tracekit report`: a window of a signer's store on one page, built on the viewer's reader, check and review (experimental) | [HIGH CONFIDENCE] |
| `tracekit/tips.py` | `tracekit tips` and the viewer's TIPS page (`/api/tips`): the cost tips from signed records and Claude Code's transcripts, the LESSONS part, and a person's lesson actions (`approve`, `retire`, `restore`, `add`) and `--for-agent` (experimental) | [HIGH CONFIDENCE] |
| `tracekit/lessons.py` | Lessons (experimental, docs/viewer.md#lessons): the lookup, fix and told detectors over verified runs (taint from signed provenance, the never-evasion gate), the lessons folder in the dev data dir (auto-memory notes, MEMORY.md, git as history), the block the Claude Code hook gives (BM25 within 8,000 bytes) and each lesson's effect | [HIGH CONFIDENCE] |
| `tracekit/why/` | `tracekit why`: causal investigation and replay | [HIGH CONFIDENCE] |
| `tracekit/pcm/` | PCM 0.1, proof-carrying messages (experimental): `__init__.py` (message, schema and grant checks, replay, `verify`), `claims.py` (claim evidence), `cli.py` (`tracekit pcm verify`, `tracekit pcm demo`), `tools.json` (the frozen tool placement table, part of the protocol); its signer RPCs (`pcm_*`, contract version 20) are in `tracekit/signer/` | [HIGH CONFIDENCE] |
| `tracekit/grants.py` | Intent grants (experimental, docs/intent-grants.md): the `payment.send` intent, amounts, the payment reader and the caveat and limit checks the signer (`grant_*` RPCs, contract version 22; releases in `_decide`), the CLI (`tracekit grant`, `approvals approve --grant`) and the verifier (`intent grants`) share; a grant is a PCM grant as it is | [HIGH CONFIDENCE] |
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

<a href="https://github.com/Cygnux-Labs/Tracekit"><img src="https://raw.githubusercontent.com/Cygnux-Labs/Tracekit/main/docs/readme/banner.png" alt="Tracekit: the tamper-evident flight recorder for AI agents" width="840"></a>

# The tamper-evident flight recorder for AI agents
# Proof of what your AI agents actually did

**Tracekit checks each tool call your agent makes before it runs, and risky calls wait for a person to approve them.
Every action is signed into a tamper-evident log, so you can put agents on real systems and prove what they did:
your customers and auditors can verify the record themselves, offline.**
Every action is signed into a tamper-evident log by a process the agent can't touch, so you can put agents on real
systems and show what they did: your customers and auditors can verify the record themselves, offline.**

<a href="https://pypi.org/project/tracekit-ai/"><img src="https://img.shields.io/pypi/v/tracekit-ai?style=flat-square&color=F3B23B&labelColor=1C1A1C" alt="PyPI"></a>
<a href="#add-it-to-your-agent"><img src="https://img.shields.io/badge/works_with-42_agents_%26_frameworks-F3B23B?style=flat-square&labelColor=1C1A1C" alt="Works with 42 agents and frameworks"></a>
Expand Down
40 changes: 39 additions & 1 deletion docs/coding-agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -589,7 +589,9 @@ transcript's start: the hook notes how far the transcript was written while that

At each prompt (`UserPromptSubmit`; Cursor's `beforeSubmitPrompt`, Gemini CLI's `BeforeAgent`) the hook also records
what the person typed (`input.observed`, trusted, source `<agent>:UserPromptSubmit`: `claude-code`, `codex`, `cursor`,
`gemini-cli`, `qwen-code`, `droid`, `devin`, `openhands` or `codebuddy-code`; its text in the content vault). Text the harness added to the prompt is recorded apart, as untrusted
`gemini-cli`, `qwen-code`, `droid`, `devin`, `openhands` or `codebuddy-code`; its text in the content vault; a Claude
Code prompt its payload says a program sent through Claude Code's SDK, `source` `sdk`, is
`claude-code:sdk:UserPromptSubmit`). Text the harness added to the prompt is recorded apart, as untrusted
input under its own source, so a value in it keeps its provenance: in Claude Code a paste block, a skill's body, a
message from another session, agent, teammate, plugin, observer or channel, a task or system notification, a scheduled
task, uploads and command output (`claude-code:paste`, `claude-code:task-notification`, ...); in Gemini CLI its referenced files block
Expand Down Expand Up @@ -628,6 +630,42 @@ takes (32: an agent can add its own), a further one is refused, the hook says so
run waits for your approval from then on. A scope ("only change src/pager.py") is never held: `tracekit analyze --v2`
checks it after the run (TK-X204).

### Lessons at the first prompt

Claude Code only (experimental). At a session's first prompt, the hook gives the session the lessons you approved for
its project in `tracekit tips` ([Lessons](viewer.md#lessons)): what the signed records showed its agents kept relearning
there, and what you typed as a standing instruction. They go in as Claude Code's `additionalContext`, one block:

```text
Lessons from this project's signed runs, approved by the person (Tracekit). Each applies when what you are doing matches it.

## When `python3` fails: no module named `pytest` (fix-3f2a91c0.md)
When running python3 here
`python3` fails here: no module named `pytest`. With `.venv/bin/python` in its place it worked.
```

All of them whole while they fit 8,000 bytes (Claude Code caps a hook's text at 10,000 characters); past that, the
ones that share words with the prompt (BM25 over each lesson's name, description and text) whole, best first, then
one line each for the rest, within 200 lines and 25 KB, and a last line naming `tracekit tips --for-agent --query
WORDS`, which any agent may run mid-task. Later prompts get nothing; after a compaction or a resume (`SessionStart`
`compact` or `resume`) the block is given again, newest first. The hook reads the lessons folder and asks the
signer about each lesson's record (below), so it adds milliseconds.

Before it gives the block, the hook records what it gives: a signed `input.observed`, trusted, source
`tracekit:lessons`, whose kept value is `{"commit", "whole", "lines", "left_out", "sha256"}`: the lesson folder's git
commit, the ids of the lessons given whole or as lines and of those left out, and the block's sha256, never a lesson's
text. A lesson's values never enter the run's provenance index that way, and the folder's git history and the hash
prove the text. That record is what "given to N sessions" and each lesson's effect count. `TRACEKIT_LESSONS=0` in
the agent's environment turns it off. Only lessons whose note names the signed record of your answer
([Lessons](viewer.md#lessons)) are given: the hook reads each named record back from the signer (`content_get`, one
signed `content.accessed` record per run of answers) and gives a lesson only when its record holds your approve,
restore or add of that id and that text (the signer keeps a run of answers alone past its 7 days, so old lessons are
checked the same way). A note written by hand, naming no
record or one the signer doesn't hold as that answer, is never given, and with `TRACEKIT_DEV_CONTENT=0` none is. Any error
(the folder unreadable, a link inside it, the signer unreachable for the record) gives nothing and never blocks the
prompt. Subagents and other harnesses get no block; they can run
`tracekit tips --for-agent`.

### Hooks name their event

`tracekit init` writes each hook command with the event it's configured for as its last argument (the Claude Code
Expand Down
6 changes: 3 additions & 3 deletions docs/evaluation.md
Original file line number Diff line number Diff line change
Expand Up @@ -583,9 +583,9 @@ profiles: `TK-A039` holds `psql … -c "BEGIN; DROP TABLE staging_import; ROLLBA

| Latency (µs) | p50 | p99 | max | p99_ref |
|---|---|---|---|---|
| default, RE2 / regex | 136 / 148 | 355 / 411 | 889 / 1393 | 6.22 / 7.35 |
| strict, RE2 / regex | 136 / 149 | 330 / 398 | 694 / 1325 | 5.84 / 7.16 |
| dev, RE2 / regex | 140 / 155 | 370 / 435 | 885 / 1409 | 6.49 / 7.93 |
| default, RE2 / regex | 133 / 147 | 349 / 410 | 844 / 1328 | 6.27 / 7.35 |
| strict, RE2 / regex | 133 / 147 | 324 / 395 | 675 / 1304 | 5.92 / 7.11 |
| dev, RE2 / regex | 138 / 154 | 363 / 428 | 865 / 1441 | 6.44 / 7.58 |

Measured on macOS arm64, Python 3.11. Gates, recorded in the results file, guard against regressions from the
recorded run: per profile, held-out recall doesn't drop below its (56.4% default, 63.3% strict) and no benign set's
Expand Down
Loading
Loading