Skip to content
LoopGlitch26 edited this page Nov 10, 2026 · 10 revisions

Known limits and trade-offs

Every limit of Tracekit is written down next to the feature it belongs to, which makes it easy to miss when you read only one page. This page collects them in one place. Each release's notes link here, and a doc that adds a "Limits" section must be linked from this page (tests/test_docs.py checks it).

Each row says what the limit is, why it is so, what to do about it, and where the details are. Rows marked (1.1) describe behaviour new in 1.1, not in 1.0; (1.2), new in 1.2; (1.3), new in 1.3; (1.4), new in 1.4.

What Tracekit guarantees and doesn't, per deployment, on one page: guarantees.

Evidence and verification

Limit Why it is so What to do Details
A verified bundle doesn't prove intent. A record says a call was made, not why. Read decisions, approvals and reasons alongside the records. FAQ
A verified bundle doesn't prove that everything the agent did was recorded. An action that crosses no capture layer (a subprocess, code that skips the adapter, a call around a gateway that isn't mandatory) leaves no record. (1.2) What some layer saw and nothing reported is now a signed gap: a call allowed or approved that never completed (decided_not_completed), a tool result the gateway saw go back with no decide (reconcile.hook_missing, at once), client counter values never received (client_counter_gap, also at close_run), writes after run.final (late_activity), a second run from inside a bound harness process (concurrent_run), a tailer that stops (tailer_lost) and a second tailer token for a run (tailer_redelegated). A call no layer saw still leaves nothing. Read the coverage, tiers and gap lines; add an out-of-process layer (the LLM gateway, the tool executor, the MCP gateway). FAQ, verdicts
A verified bundle doesn't prove that a tool result the agent reported is true. In-process capture (T1) records what the agent's process reported; only out-of-process capture (T2) sees what crossed a boundary. Prefer T2 evidence for calls that matter; use executor: t2 approvals. FAQ, approvals
A tool.result's output.size is the size of what the signer received. For a tool whose result the adapters send as its digest (every tool the policy doesn't list as untrusted), that is the digest's size, not the result's. The signer records what it can check; a size the client claimed would be the agent's word. Read output.size as the size of the content committed to; list a tool under untrusted: to have its result itself sent, redacted and committed to. privacy
Imported OpenTelemetry (T3) proves only that spans were received. Spans are exported after the work is done, by the application. Gate calls with an adapter or hook; treat T3 runs as a log, not evidence of completeness. OpenTelemetry
agentgateway's MCP spans import without arguments or results, and each request is its own trace, so its own run, unless the agent sends traceparent. agentgateway's spans name the tool and its outcome; the import keys runs by trace id. Add gen_ai.tool.call.arguments and gen_ai.tool.call.result through agentgateway's tracing attributes; send traceparent from the agent; for evidence of what ran, use the ext_mcp processor. agentgateway
An imported run closes when its trace's root span arrives; a trace whose root never reaches the signer (its root is another process's, as with traceparent through agentgateway) stays open until idle_s and counts against the importer's open_runs (100): past it every batch is refused (503, retried) until runs idle out. A span that ends after its root and comes more than grace_s behind it is rejected. The import can't tell a trace is done but by its root; open runs are held in memory. Export the root span to the signer too, raise the importer's open_runs in limits, or lower idle_s. OpenTelemetry
Tracekit is tamper-evident, not tamper-proof: a deletion shows, it isn't prevented. Prevention would need attested hardware (a TEE), which Tracekit doesn't claim. Keep independent witnesses and a monitor so a rewrite is detected. FAQ
Whoever holds the signer's key can rewrite or fork its log; nothing in the bundle alone shows it. Signatures prove who signed, not that the key holder didn't sign again. Pin a witness the operator doesn't run (witnessed) and a monitor (witnessed+monitored). server threat model
Records after the last cosigned checkpoint are unproven. A witness vouches only for what it has cosigned. Export after the next checkpoint; read the log tail warning. verdicts, witnesses
A bundle exported before its run is finalised verifies only TO HEAD n (open). The signer finalises a run a few seconds after it closes. Re-export after run.final; for audits require VERIFIED. quickstart, verdicts
(1.4) A run cut back (records or parts dropped from its end, with an inclusion proof of the record now last) verifies TO HEAD n (open), as an export before its end does: nothing shows that records were dropped. The proofs file isn't signed, and from a run's records an inclusion proof of any of them can often be computed; only the signer's run.final or a run-set says where a run ends. For audits require VERIFIED (the run with its run.final), or a run-set with run-set: COMPLETE. format v2, verdicts
A single run's bundle doesn't show that no other run was left out. The exporter chooses which runs to export. Ask for the tenant's run-set bundle and require run-set: COMPLETE. auditor guide
(1.4) tracekit export --v2 --run-set always starts at registry size 0 and bundles every finished run of the tenant, one file each: past about 10,000 finished runs (the format's 10,000 files) or 512 MiB in all it refuses, saying which limit it is over. The command has no later start, and the format caps a bundle's files and size so that verifying it needs bounded memory. Give each workload or team its own tenant, or start a new data_dir (a new log) before a tenant nears the limit. auditor guide
A withheld key retirement isn't visible unless a run-set from registry size 0 reaches the bundle. A bundle whose key records show one key and no retirement says so only on its Assurance line, not as a warning: a retirement withheld together with its new key would look the same. Only the registry log proves which key.retire records exist. Read key retirements not proven complete on the Assurance line (a keys warning when the key records show a retired key); require a run-set from registry size 0 where it matters. verdicts
key assurance is asserted unless a record-key issuer certifies the keys. Without an issuer the log declares its own record keys. Run an issuer and pin it in the trust config. issuer
The verifier doesn't fetch revocations. Verification is offline and takes trust only from the verifier's side. Pass the issuer's log with --revocations. issuer
A trust config the operator supplies proves nothing about the operator. The bundle carries no code or trust (I9); whoever writes the trust config decides what verifies. Build trust.json from independent sources and install the verifier yourself. auditor guide
On a pull request the GitHub Action reads a trust: file, a key: file and a witness: file: path in the pull request's checkout from its base commit, and refuses one in $GITHUB_WORKSPACE that it can't: not at the base commit, given with .., through a symlink, in a submodule, or in no git checkout there. But on pull_request GitHub runs the workflow file as the pull request has it, so its author can still change the step's inputs or drop the step. The action can change where its inputs come from, not the workflow that passes them. Make the verify job a required workflow in a repository ruleset (it runs from the branch you name), or have CODEOWNERS review .github/workflows/; keep files the workflow writes itself in $RUNNER_TEMP. verdicts
A v1 bundle verified without --key or --witness is only internally consistent (UNANCHORED). A bundle carries its own public key, so a bundle forged with a fresh key is consistent too. Pin the signer's key or an independent witness. laptop threat model
v1: the exporter can replace a selected record with an elided stub, and manifest.json is unsigned. v1 stubs are not bound to a run; the manifest is an index, recomputed from signed records. Use v2 bundles; read the "run completeness unproven" warning. laptop threat model
Record timestamps come from the signer host's clock; seq and the chain prove order only. Only witnesses and RFC 3161 timestamps give independent time. Read cosignature and anchor times in the Assurance line. laptop threat model, witnesses
A v1 record after a v1 → v2 bridge is reported only with --v1-ledger. The frozen v1 verifier sees bridge records as ordinary gaps. Verify bridged logs with --v1-ledger. format v2
The TypeScript verifier reports UNVERIFIABLE for bundles that rely on a Rekor anchor, an SLH-DSA checkpoint signature or certified record keys. Web Crypto has no SLH-DSA, and those checks aren't ported yet; it never says VERIFIED for a check it skipped. Verify such bundles with the Python verifier (pip install tracekit-ai). auditor guide, format v2
A verifier doesn't check what an ext name it doesn't interpret says: the records verify (signature, chain, inclusion), and each such name is a not interpreted warning. Format 1.4's non-critical slot lets a later Tracekit add what an older verifier can leave unread, instead of locking that verifier out. Verify with the version the warning names (tracekit >= x checks it); --strict stops on it. format v2, verdicts
A 1.3 or older verifier reports a bundle with an ext field or record UNVERIFIABLE (needs tracekit >= 1.4.0) and prints no commands to verify it. The slot and the upgrade lines are new in 1.4.0. Run the commands in verdicts. format v2
The browser verifier (verify.html) is the TypeScript verifier: it reports UNVERIFIABLE where that one does (SLH-DSA, Rekor anchors, certified record keys, tracekit why findings) and takes no monitor reports, revocations or v1 ledger; a v1 bundle it names the command for. Without a trust file it is never VERIFIED. In a browser that refuses its worker it verifies in the page itself, which a bundle of 100k records holds for seconds. A copy someone else hosts is only as good as its bytes. It runs on Web Crypto in the page; a browser can't check where a page came from. Use tracekit verify for those checks and for very large bundles in such a browser; get the trust file from the sender; for evidence, open a copy you checked with gh attestation verify verify.html --repo Cygnux-Labs/Tracekit. format v2, releasing
The browser verifier holds the bundle, unzipped, and every record it parses in the tab's memory, about 8 times the bundle unzipped: a run's 100,000 records (50,000 tool calls: a 28 MB bundle, 130 MiB unzipped in three parts) take about 14 s in Chrome, and the same verifier as a CLI 1 GB (E22). A bundle near the format's 512 MiB, some 390,000 records, would need about 4 GB, more than a tab may hold: it can close the tab. Without a trust file the page reads every record, since no pinned key stops a bundle at its checkpoint. It verifies offline, in the page, under the format's limits (512 MiB unzipped); a line shorter than a signed record is refused before any is parsed, so a small file can't unzip into millions of records. Choose the sender's trust file: a bundle their signer didn't sign then fails at its checkpoint before a record is read. Verify very large bundles with tracekit verify or npx @cygnuxlabs/tracekit verify. format v2
A run's records must fit one bundle: 512 MiB unzipped, about 390,000 records (some 190,000 tool calls with small arguments, fewer with larger ones). (1.4) A run past 64 MiB of records (about 24,000 tool calls) is written in parts of up to 64 MiB, which a 1.3 or older verifier can't read: it reports the bundle UNVERIFIABLE (needs tracekit >= 1.4.0). tracekit export refuses a bundle of more than 512 MiB in all or 10,000 files, and says which limit it is over. Both command-line verifiers hold about 8 times the bundle unzipped in memory: 1 GB for 50,000 tool calls, some 4 GB at the limit. The format caps each file of a bundle at 64 MiB and the whole at 512 MiB, so verifying one needs bounded memory; a bundle past them is UNUSABLE BUNDLE to every verifier. Verify a bundle with parts with tracekit 1.4 or newer (Python, TypeScript or the page), on a machine with 4 GB free for the largest. Start a new run for each task or session; a run still open exports up to its head, so export a very long one before it reaches the limit. format v2
A run with 20 problems (bad signatures, schema errors and broken chain links together) is checked no further: the report names those 20 and how many of the run's records after them went unchecked, so a run with one record deleted early lists 20 broken links, not one per later record. Every record is still parsed, so such a bundle holds memory as any of its size. A bundle of forged records (one signed record repeated, or a chain rebuilt without the key) would otherwise cost a signature check per record: a 1.4 MB file that unzips to 256 MiB of repeated records took 103 s in Python and 39 s in TypeScript on one laptop; now 7 s and 6 s. The bundle has FAILED already: ask the sender for a fresh export from the signer, and read its first problems for what was changed. verdicts
The TypeScript verifier needs Node 20.12 or newer (or a current browser). It uses JSON imports and DecompressionStream("deflate-raw"), which earlier Node 20 releases lack. Upgrade Node, or use the Python verifier. TypeScript SDK
npx @cygnuxlabs/tracekit verify with --monitor-report, --revocations or the v1 bridge options runs the Python verifier, which must be installed. Only the Python verifier has those checks. pip install tracekit-ai, or verify without those options. auditor guide
(1.2) A bundle holding a run started by another run (parent_run, a sub-agent's run) needs tracekit 1.2 or newer; a 1.1 verifier reports it UNVERIFIABLE (needs tracekit >= 1.2.0). Every v2 record definition is closed, so an older verifier can't read the new fields; the manifest's verifier_min_version makes it say so instead of FAILED. Verify with tracekit 1.2 or newer (Python or TypeScript). format v2
(1.2) A bundle holding a 1.2 completeness gap (decided_not_completed, late_activity, concurrent_run, tailer_redelegated, a gap's run_id), a run.child record or a run.final with provider_executed needs tracekit 1.2 or newer; older verifiers report it UNVERIFIABLE (needs tracekit >= 1.2.0). The new kinds and fields are outside the 1.1 schema; the manifest's verifier_min_version says so. Verify with tracekit 1.2 or newer. format v2
Experimental surfaces may change between releases and get less hardening than the stable core. Few people run them yet; the stable core is what is tested end to end and fixed first. Build on the stable core; each experimental command or server says so on stderr when it starts. what's stable
JSON nested deeper than 128 levels is refused: a bundle file is unusable, a record fails, and a tool call's arguments are denied (TK-ARGS-INVALID). A fixed depth makes every verifier and the signer read the same documents the same way, whatever their parser's limits. Flatten arguments deeper than that. format v2

Dev mode vs system mode

Limit Why it is so What to do Details
v1 tracekitd: witness publishing (git push, HTTP) runs under the signer's lock, so an unreachable witness stalls appends for up to 15–60 s; a local user can hold the 64 connections by trickling bytes (the dev socket is world-writable); runs.json is rewritten on every append. The v1 daemon is single-writer and laptop-sized. Use the v2 signer for anything shared or busy; keep v1 witnesses reachable. laptop threat model
v1 tracekitd: a restart takes every run of the ledger as active again, so past the run cap it writes run_state_evicted gaps for long-finished runs, and a run that never sent run.start loses its owner. Parallel hooks of one session can record a false trace.tamper (transcript length read before the send). Client state files (~/.tracekit-client/runs/, Gemini call ids, transcript acks) are never pruned. v1 state is rebuilt from the ledger and kept per laptop. Read those gaps as restart artefacts; prune ~/.tracekit-client/runs/ by hand. laptop threat model
Same-user dev mode protects nothing against the agent itself. The dev signer runs as your user, so an agent that runs commands as you can read its key, stop it, or rewrite and re-sign its store. Policy rules (TK-D007, TK-D013) are tripwires. Use system mode, a sidecar or a central signer for anything you need to rely on; dev bundles say isolation: same-user. FAQ, quickstart
Assurance describes checkpoint cosigning, not isolation: a same-user signer with a witness verifies as witnessed. The two are independent properties. Read isolation as well as Assurance. verdicts, witnesses
A system-mode signer without a witness verifies as Assurance: dev. Nothing outside the host shows the log wasn't rolled back. Add a witness on another host that the operator doesn't run. deployment
System mode doesn't protect against root on the machine. Root can read the key and rewrite the store. Witnesses on another host detect a rewrite of what they cosigned. deployment
In system mode without --managed, the agent can remove the hook from its own ~/.claude/settings.json (or from its other coding agent's config), with no record and no gap. With or without it, the agent can act outside its coding agent, where no hook runs. Without --managed the hook lives in the agent user's own settings. --managed is wired for Claude Code only: Codex, Cursor, Gemini CLI, Qwen Code, OpenCode, goose, Factory Droid and Antigravity CLI keep their hooks in the agent user's config (init refuses --managed with their --agent). For Claude Code, init --v2 --user AGENT --managed (v1: init --managed): the hooks go in Claude Code's admin-managed settings, which Claude Code's docs say no user, project or local setting and no --settings overrides, and whose hooks a disableAllHooks outside managed settings can't turn off. Outside the hooks, an out-of-process record: the gateways, or --egress. deployment
(1.5.1) --managed hooks run in every user's Claude Code on the machine, not only the agent's: other users' calls are recorded (the approver's in the agent's tenant, anyone else's in local), decided by the policy and blocked while the signer is down, and a call the policy holds in their sessions can't be approved (the approver may not answer their own run's, and sees no other tenant's). --managed-only also stops every user's own Claude Code hooks, and what init writes beside the hooks applies to every user too: TRACEKIT_SIGNER, with --egress the HTTPS_PROXY and HTTP_PROXY that send their Claude Code's traffic through the egress observer, and the thinking summaries init turns on (showThinkingSummaries). Claude Code's managed settings apply to the whole machine; the hook doesn't skip other users. Use --managed on a host or VM where the agent's user is the only one running Claude Code; on a laptop you also use Claude Code on, init without --managed. deployment
(1.5.1) Claude Code applies one managed source by default: a server-managed (claude.ai console or gateway) or MDM policy that sets any key replaces managed-settings.json, Tracekit's hooks with it, and doctor sees neither. Claude Code fetches server-managed settings when the session signs in to Anthropic with an eligible credential, so which account the agent signs in with counts too. Claude Code's managedSourcesBehavior defaults to "first-wins" (Claude Code docs). In the agent's Claude Code, /status must list Enterprise managed settings (file). Where your organization delivers server-managed or MDM settings, add Tracekit's hooks there or set managedSourcesBehavior: "merge" in the highest one; pin the sign-in with forceLoginOrgUUID in managed-settings.json (Claude Code takes sign-in keys from the file ahead of server-managed settings). deployment
(1.5.1) When managed-settings.json isn't valid JSON, Tracekit can't take its hooks out of it. If /etc/tracekit/client.json records the file (the last init used --managed), init --v2, with or without --managed or --no-hooks, and uninstall --v2 stop with an error before they change anything. If it doesn't, they leave the file as it is, Tracekit's hooks in it included (init --v2 --managed stops with an error before it changes any hooks): once an admin fixes the file, those hooks run again, against whatever the config then names. The file holds an admin's other settings, which init won't rewrite from a file it can't parse. Init checks the recorded file before it writes anything, so a stopped init leaves no hooks the config doesn't record. Fix the file, then run tracekit init --v2 --user <agent> --managed (or tracekit uninstall --v2) again, and check tracekit doctor. deployment
(1.5.1) Claude Code's docs don't say whether claude --bare (or CLAUDE_CODE_SIMPLE=1), which skips "auto-discovery of hooks", runs managed hooks; they do say --safe-mode runs them. Doctor reads managed-settings.json only, not managed-settings.d/ drop-ins, so a disableAllHooks an admin puts in a drop-in turns the hooks off unseen. An admin of the machine can edit the managed file. Not documented by Claude Code; drop-ins aren't read yet. As the agent's user, run claude --bare -p "run ls" and check a run is recorded before you rely on --managed; with --egress (Linux) the agent's outside connections are recorded whether or not a hook runs. Keep disableAllHooks out of the drop-ins. The agent's user must not be an admin (init refuses one). deployment, egress
v1 system mode (init as root without --v2) has no uninstall: tracekit uninstall takes the hooks out of user and project settings only, not out of admin-managed settings (--managed), and leaves tracekitd's service, /var/lib/tracekit, /opt/tracekit and /etc/tracekit/client.json. v1 system mode is the legacy path; sudo /opt/tracekit/bin/python -I -m tracekit uninstall --v2 removes v2 system mode, --managed hooks included. Remove Tracekit's hook groups (and allowManagedHooksOnly, if init set it) from the managed settings file, stop and remove the tracekitd unit (or launchd plist), then those paths. quickstart
Without harness binding, any process of the agent's user can write into the agent's runs or start runs of its own. The signer knows the caller by uid; run tokens are readable by that uid. Register the harness (--harness, Linux). quickstart
System mode requires an agent user that is not root and not in a sudo, wheel, admin, docker or similar group. Such a user could take over the signer. tracekit doctor (D-AGENT-PRIV) checks it. doctor
When the transcript tailer's ACL or sudo rule can't be set up, every run records a tailer_lost gap instead. The tailer needs read access to the agent's transcripts. Fix the setup init reports. deployment

Signer and capture

Limit Why it is so What to do Details
A tool class set to fail open runs unrecorded while the signer is down. It is the setting you choose when an outage must not stop the agent; the next call writes a signed gap for exactly the missed calls. Keep fail_modes closed (the default); the report warns on every fail-open class. FAQ
While the signer is unreachable, the LangChain adapter, the Claude Code hook and the Hermes Agent plugin pick a call's fail mode by the class the shipped default policy gives the tool (terminal is shell, an unmapped tool unknown); the MCP and Browser Use adapters by their fixed class (mcp, browser); the OpenAI Agents, Claude Agent SDK and CrewAI adapters apply default to every tool. A signer whose policy maps the tool to another class may have another fail mode for it. The tool's class is the signer's decision, and the signer can't be asked. Keep fail modes closed for classes your policy remaps, or set default; with OpenAI Agents, the Claude Agent SDK or CrewAI, set default. FAQ
Model calls (autotrace) while the signer is down: under a closed model fail mode a request that can't be recorded is refused (PermissionError, saying so and what to do); a response the signer missed (it went down mid-call) is sent again at the next model call or at exit, after a signed client_counter_gap for the try that failed. A signer that stays down until the process exits leaves the request without its response, and the run open until the signer's idle timeout. The client records only while the signer answers, and keeps missed responses in memory (the newest 1024). Keep the signer running (system mode restarts it); set fail_modes: {model: open} to let model calls run unrecorded during an outage. FAQ
v1 hooks allow a call when the payload can't be parsed (Codex, Cursor, Gemini CLI, goose, Qwen Code, Factory Droid, Crush and Devin, whose v1 hook commands don't name their event: under the default fail mode, open) or the harness is unknown; a payload nested too deep to read blocks the call. The v1 OpenCode plugin and Antigravity CLI's v1 hooks name their event, so a pre-tool call their hook can't decide is blocked whatever the fail mode. (1.2) v2 hooks that tracekit init wrote from 1.2 on name their event, so a pre-tool payload that can't be parsed is blocked; a post-tool one is reported on stderr, and the call it ends is completed as an error at the session's next Stop, prompt or end. v2 hooks installed before 1.2 still let an unparseable payload through, unrecorded; tracekit doctor (D-HOOKS-EVENT) finds event-less commands for Claude Code, Codex, Cursor, Gemini CLI, goose, Qwen Code, Factory Droid, Antigravity CLI and Crush. In v1 a Tracekit failure follows the fail mode. A hook that can't parse its payload knows its event only from the command line. Claude Code, Codex, Cursor and Gemini CLI write the payload themselves; OpenCode's plugin passes the model's arguments before OpenCode checks them. Doctor checks those command hooks, goose's, Qwen Code's, Factory Droid's, Antigravity CLI's and Crush's, but not OpenCode's JavaScript plugin. Re-run tracekit init after upgrading (tracekit init --dev --v2 --agent NAME repairs the other coding agents' hooks); in v1 set TRACEKIT_FAIL_CLOSED=1 or fail_mode: closed. coding agents, doctor
A v1 dev hook that can't start (its Python moved or was uninstalled, or Tracekit no longer imports) lets the pre-tool call run unrecorded, with an error the coding agent shows, even under the policy's fail_mode: closed, unless TRACEKIT_FAIL_CLOSED=1 is set; on Windows, even then. goose (on_failure: block), OpenCode, Antigravity CLI, a Cursor hook init wrote with failClosed: true and system mode (unless its config sets fail_mode: open) block it. The hook's command can read an environment variable, but the fail mode in the policy only Tracekit's hook reads; on Windows there is no POSIX shell to wrap the command in. With fail_mode: closed, also set TRACEKIT_FAIL_CLOSED=1 where the coding agent runs (Claude Code: under env in its settings), or use the v2 hooks (tracekit init --dev --v2), whose hook that can't start blocks the call. coding agents
v1 hooks don't hold a Codex patch applied through the shell (TK-A034 is in the v2 packs); v1 and v2 hooks both decide every file an apply_patch call adds, updates, deletes or moves to. The v1 policy is kept as it was; TK-A034 is a v2 rule. Use the v2 hooks (tracekit init --dev --v2 --agent codex). coding agents
The signer can't tell a real event from a well-formed fake sent by the agent's identity. Anything that can call the signer as the agent can submit plausible events. Cross-check with an independent layer: the gateway (gateway_mandatory) or, in v1, the model proxy. laptop threat model, signing
Compromised application code can skip the adapter for some calls, and suppress in-process autotrace (L3) too. Both run in the agent's process. Run the LLM gateway outside the agent; read reconcile.* and (L3 absent) in the report. server threat model
Capture layer L5 (services) is not shipped, and L4 (processes) only as the experimental kernel sensor import (Linux): a sensor that covered a run throughout makes its processes observed, and its effects are the sensor's word, not reconciled. (1.2) L6 (network) is the egress observer, hosts only. Out-of-process capture of services isn't built yet; the coverage matrix says not covered for them, and for processes where no sensor covered the run. On Linux, import a kernel sensor (Tetragon, Falco); use the LLM gateway, the executor and the egress observer as the other out-of-process records. server threat model
SDK and adapter capture is opt-in per call: only wrapped calls are seen and gated. An adapter sees only the calls routed through it. Wrap every tool; each integration lists what it doesn't cover. laptop threat model, OpenAI Agents, MCP, Browser Use, Claude Agent SDK, CrewAI, Pydantic AI, Google ADK, Haystack, LlamaIndex, Microsoft Agent Framework, Strands, Hermes Agent
Actions inside subprocesses and background processes, and faked command output, aren't observed by the hooks or adapters. They see the command line; tool results are what the harness reports. On Linux, import a kernel sensor's records into the run (experimental): the processes, connections and file writes a command started are signed, and tracekit analyze --v2 flags one no call explains. Elsewhere, run the agent in a sandbox that logs them. laptop threat model
Nothing is recorded after the session's last hook, including transcript edits. Nothing runs to see it. Treat the run's end as the last observed point. laptop threat model
(1.2) decided_not_completed is written at run.final only, and doesn't say why the result never came (the agent stopped or crashed, its post-call hook didn't run, or a client dropped it). Calls denied, or asked and never approved, get none: they may not run; a call the executor or a gateway holds gets held_call_unresolved instead. A decision is also exempt when a later decision of the same call completed, except one whose approval was consumed and whose call didn't complete with the approved arguments; only the call's latest decision counts as later, so an open decision before a completed one and an open one after it is a gap too. The signer sees the decide and the missing complete, not the agent or the harness's prompt. At most 100 per run are listed, then one gap counts the rest. Read the gap next to the run's other records and the transcript or app log; a crash usually ends the run early too. coding agents
(1.2) A coding-agent hook completes each call that got no post-tool event (declined in the harness's own permission prompt, interrupted, or a post-tool payload it couldn't read) as an error when the session ends. That result is the hook's word, not the harness's; a session killed before its end event leaves such calls as decided_not_completed gaps instead. No hook event says that a call was declined or interrupted, and a background sub-agent's call can still run when a turn ends; the session's end is the first point where none can. Read a tool.result error "no PostToolUse came" as "not seen to run". coding agents
(1.3) A coding-agent hook blocks only tool calls. A prompt, Stop, tool result or session event whose hook fails (the signer unreachable, tracekit missing or broken) runs unrecorded, with a hook error in the transcript. Hook commands tracekit init wrote before 1.3, and Cursor hooks it wrote up to 1.4.2 (failClosed on every event), still turn such a failure into a block. On a prompt, a block erases it; on Stop, it sends the agent back to work in a loop. Every tool call is still decided before it runs. Read hook errors in the transcript; run tracekit init again after upgrading to get the current commands (tracekit doctor flags old ones in dev and system mode as D-HOOKS-EVENT, and old system-mode ones also as D-HOOKS-VENV). plugin
(1.2) concurrent_run covers only runs bound to a harness process (harness binding, Linux system mode): a second run started from inside the same harness process while another session's run is open there, once both have recorded an event since it registered. SDK and server runs, which run several at once by design, and harnesses without binding get no such check. A run started with parent (a sub-agent's) gets none either: the agent can read its session's run token, so a second session can pose as a child, and shows only as a run.child record in the parent. Which runs overlap is kept in memory and snapshots: a signer restart with no snapshot since forgets a pending one. One harness process drives one session at a time; without a binding the signer can't tell a forged second run from a legitimate parallel one, and an older session's run left open and idle is no overlap. Turn on harness binding for coding agents; pass parent for a sub-agent's run; read each run.child against the harness's transcripts. format v2
(1.2) A killed transcript tailer is a tailer_lost gap only in system mode, once it has made no call (heartbeat or record) for 90 s while the run is open, counted from when the hook took its token, and only while the signer runs: the watch is kept in memory. In dev mode the tailer runs as the agent's user, which may not send heartbeats, so a killed tailer leaves no gap. Heartbeats show that a process holding the run's tailer token is alive, not that it reads the session's real transcript: the agent's user starts the tailer (through sudo) and names its transcript, so it can stop the real one and start one of its own on a file it writes. A second tailer token for the run is a tailer_redelegated gap, but a decoy handed the first token (the agent's user can read the hook's memory) isn't. A tailer that keeps its heartbeats but stops reading is caught only by its idle limit. The signer can't watch the tailer's process or see the transcript; the heartbeat is its only signal, and only an identity the agent doesn't control may send it. Use system mode (init as root with --v2) where a killed tailer must show; compare the run's transcript records with the transcript itself where it matters; re-check runs that span a signer restart. coding agents
(1.5.3) The transcript tailer checks the transcript lines it already read on every wake while that check is quick (under 10 ms, a transcript of about 25 MB); a larger one only once a hundred checks' time has passed, at most every 30 s, while the transcript keeps changing (a 400 MB one: about every 16 s; one of 800 MB or more: every 30 s). An edit to an already read line in that window is a tailer_lost gap only once the check runs, after the lines written meanwhile; one undone before then, or made just before the run ends while the transcript keeps changing, is none. Finding an edit anywhere in what was read means reading all of it again: 0.3 s for 816 MB, which on every wake kept the tailer busy for much of a CPU core. Keep coding-agent sessions short where in-place edits must be caught at once (/clear or a new session starts a new transcript); compare the run's transcript records with the transcript itself where it matters. coding agents
A session's later run (the signer closed the earlier one after an hour idle, or the session was resumed) records its transcript from where the hook last saw it while the earlier run was open: the lines Claude Code wrote after that run's last hook call (most often the closing text of a turn) can be in both runs. A resumed session is read from where its transcript (Codex's rollout, Gemini CLI's chat recording) ended at SessionStart, so a harness that writes the earlier history only after that hook repeats it in the new run. (1.5.1) A Claude Code session that goes on after a SessionEnd with no SessionStart (a message to the session, a usage limit's reset) is read from where its transcripts ended at the new run's first hook: what Claude Code wrote between the SessionEnd and that hook (the new prompt; a first tool call's tool use, then a reconcile.fabricated gap) is read by no run, since the earlier run's tailer stopped at the SessionEnd. A call in that window whose hook didn't record it (a killed or timed-out hook) leaves no reconcile.hook_missing gap. The hook can't see how far the earlier run's tailer got; it measures the transcript at its own calls, and a SessionEnd removes the session's state. Read a session's runs in order (tracekit view --dev): each holds what was written while it was open. coding agents
(1.5.1) A Claude Code run's decides are compared with the transcript's tool uses without what Claude Code drops or fills in before its hooks: a key the tool doesn't take that the model sent (run_in_background on Agent, persistent and timeout on Monitor, description on Write; the first two are the tool's own in other Claude Code builds), Monitor's default timeout_ms (300000), a SendMessage summary that is its message's first line cut to 200 characters, and a Bash call's free-text description (the hook decides a retry that only rewords it with the approved call's, approve, then retry). A decide that differs from the model's tool use only there is no reconcile.args_mismatch, even when the hook, not Claude Code, made the difference; any other key or value is one, including a key a model makes up that isn't listed yet. Which runs are Claude Code's is the agent name the run registered, which the client gives: a run that says it is Claude Code gets the same leeway, for those keys only (no shipped rule reads them). An LLM gateway's record of a Claude Code call holds the arguments as the model sent them, before any of Claude Code's changes, so those changes (a Bash command's leading cd, Edit's replace_all, a key the tool doesn't take) read as args_mismatch there. Claude Code hands its PreToolUse hook the tool use after its own checks and defaults, and its transcript keeps the model's keys; the list is the changes seen in Claude Code 2.1 transcripts against its hooks' input. Read an args_mismatch on a Claude Code call against the call in its transcript: a key the model added that the tool doesn't take is Claude Code's own change. coding agents
A Bash call's description is left out of that comparison from this release on, on both sides: the transcript tailer, which runs with the agent's Tracekit, and the signer. When the two run different releases (a remote or system signer upgraded apart from the agent's Tracekit), every Claude Code Bash call with a description can read as a false reconcile.args_mismatch. Noisy, never hidden: the mismatch is recorded, nothing is dropped. Each side leaves out the keys its own release lists before it takes the digest it compares. Upgrade the agent's Tracekit and the signer together; read an args_mismatch on a Bash call whose only difference is its description as this. coding agents
(1.5.1) Claude Code's progress summary of a background agent can call SubagentHandback (its status line as the message) in a request no transcript records: its hook decides the call, which never completes ok, and the run gets a reconcile.fabricated for it, whose detail says what such a hand-back most likely is. The tailer reads Claude Code's transcripts, and that request is in none of them, so the decide matches no tool use. Read a fabricated SubagentHandback against the background agents' transcripts at that time: a short line of what one was doing while it went on working, with no hand-back reaching the parent, is Claude Code's summary. coding agents
(1.2) Writes refused because their run is final are counted per run in memory and written about once a minute as a late_activity gap in the tenant's signer run; counts since the last write are lost if the signer stops uncleanly. A close_run never counts, nor does the first write of each identity and stream (up to 64 per run): a client learns from it that its run ended, after an idle close, and moves to a new run. A run-set lists them with the tenant-level gaps. The writes can't go into a final run, and the signer-level refusal summary doesn't name the run. Read late_activity in a run-set; if it recurs, check that each client registers a new run once its run ends. format v2
(1.5.3) A signer that starts after downtime closes, before it serves a call, every run whose last record is older than idle_s (an hour by default) and no approval of it still waits: the downtime counts as idle time. The dev signer exits after 15 minutes with no client connected, so a coding-agent session quiet for idle_s goes on in a new run (Claude Code's with a new transcript tailer). A client's next write for a closed run is refused run_closed, and it registers a new run (a coding-agent hook does so at once). The idle clock runs on the records' wall-clock times, and no run can close while no signer runs. Keep a signer's downtime under idle_s, or raise idle_s, where runs must span a restart. format v2
(1.2) Trailing client counter values become a gap only when the client says where its stream ended (close_run last_client_seq), and only for streams the closing identity wrote (or that never reached the signer); after a signer restart with no snapshot since, a stream written before it can't be ended that way. The LLM gateway says so when it drops a run from memory or stops (SIGTERM or Ctrl-C; a killed gateway says nothing); for a run already final the gap goes in the tenant's signer run, naming the run. A gateway whose identity lacks the close_run grant logs the refusal on stderr and leaves no gap. The signer can't know of values a client never sent, so the gap is the closing identity's word, and its reason names that identity; values up to there that still arrive in the grace period are recorded with no second gap. Close runs with last_client_seq from your own clients; grant gateways close_run and stop them with SIGTERM; read a gap's reason for who reported it. gateway
(1.2) A live reconcile.hook_missing (written mid-run, for a detector) comes from the LLM gateway's records only; agent-reported L3 is still reconciled at run.final. Agent-reported L3 comes from the process being checked. Run the gateway for calls that matter. gateway
Harness binding doesn't stop a process the agent starts inside the harness session, or the agent's user starting its own instance of the registered harness. Both are legitimately below, or are, the registered program, running as the agent's user. Run the harness under another user, or use a mandatory gateway. FAQ
The LLM gateway's record is complete only when the agent can't reach the model around it. The gateway sees only requests sent to it. Let only the gateway reach the provider (network policy) and set gateway_mandatory: true. gateway
A tool the policy's structured_output: names gets no L3 cross-check: a decide for it needs no tool use in the model's response, and a tool use of it needs no decide, even under gateway_mandatory, so any tool of that name runs with no decide unseen. The browser pack names Browser Use's actions (browser_use:*) only; its output tool with Anthropic models (AgentOutput) is the deployment's to name. A child policy can't remove a name its parent declares. Browser Use asks the model for its actions as structured output, which carries no tool use id to match a decide with. Read Browser Use's records as decided by the signer, not as proven asked for by the model; declare only names whose calls really come as structured output and that no other tool of yours uses. gateway, Browser Use
(1.2) Tools the provider runs itself (web search, code execution, hosted MCP, ...) can't be held for a decision: they run mid-response. The gateway records their input where the provider returns it (not for image generation) and can only refuse a whole request that declares one (provider_tools). OpenAI shell and tool_search tools count as provider-run, since the provider may host them: with allow, list them if your client runs them. No client-side step happens between the model asking and the provider running them, and a request doesn't always say who runs those two. Deny provider tools you can't accept in gateway.yaml provider_tools (mcp covers every hosted MCP server, mcp:<label> one); the client gets a 403 naming them. gateway
(1.3) Verified tool results catch an edited tool result for a call the signer already completed, and record a result sent before its call completed. They don't catch text the agent adds outside tool results; a tool call the agent writes into the history itself with its result (reconciliation flags it at run.final, result_without_call or, under gateway_mandatory, fabricated, unless the agent also forges a decide, a result and a model report with gateway_mandatory off); results past a request's newest 512 or past the 1 MiB of them the gateway digests (newest first), which the agent chooses by adding results of its own: each such call is a signed capture.gap{result_unchecked}, and past the newest 1024 not even that; a request under the token of a run the agent registered itself; a result OpenAI Responses doesn't resend (previous_response_id) after its first send; and, with the signer unreachable and model failing open, a request the gateway forwards unchecked. The check compares what the gateway sees against the signed results of the same run, by tool_call_id: content outside a tool result, a call with no result in that run, and a request never sent or never checked have nothing to compare with. Set gateway_mandatory and let only the gateway reach the provider; keep the model class failing closed; read a run's result_without_call and fabricated records with its mismatches. gateway
(1.3) Verified tool results are off unless signer.yaml sets verify_tool_results. A client whose recorded result isn't the value the model is sent mismatches on honest runs, and refuse then stops the agent with a 403: every result of the Claude Code hooks (a digest of the raw output) and the Claude Agent SDK integration (the structured tool response); in Pydantic AI a tool returning a list, which Anthropic gets as one text block per item; in Google ADK under AnthropicLlm every result but a dict (and a dict with a content key or only result), under LiteLlm a model or dataclass return (ADK sends its Python repr); and a result of several content blocks (Agent Framework, Strands). Gemini requests (ADK's default) don't pass through the gateway, so nothing is checked. Calls decided under ids of the client's own (the MCP integration, the MCP gateway, LlamaIndex's ReActAgent and CodeActAgent) are unchecked, and so are calls completed with no result (a Pydantic AI output function's: the model reads Final result processed.), error results and results whose content redaction changed. A match says the output was passed on unchanged, not that it is true. The signer compares commitments: equal values, or a value and its digest, match; two renderings of the same output don't, and a commitment over redacted or absent content opens nothing to compare. Run record first; set refuse only once tracekit verify shows no result_mismatch on honest runs of your own agent, model and tools. gateway
(1.3) Verified tool results: refuse refuses a request only for an edited result of a completed call. A result sent before its call completed is a signed result_mismatch and the request is forwarded, so an agent can send a result of its own for an allowed call it never completes. A request's results past 1 MiB (as JSON, newest first; a result the run's previous request also sent counts for nothing) are not compared, and neither is any one result over 1 MiB: each such call is a signed capture.gap{result_unchecked} (a gaps warning in tracekit verify), never refused. A complete can be lost on an honest run (the client gives up after its retries) and every later request sends the result again: refusing would stop the run for good. The gateway digests results in pure Python before forwarding (15 MB of numbers took 3.4 s); the cap bounds that work per request, and a gateway that restarted has no digests cached, so refusing unchecked results would stop honest long runs. Read a result_mismatch whose detail says the result was sent before the call's was recorded with that call's decided_not_completed on run.final, and a result_unchecked gap as a result nothing compared; keep the tool results a model reads under 1 MiB. gateway
With durability: ack-on-write (the default), a power loss can drop records already acknowledged. Acknowledging before fsync is faster. Set durability: ack-on-fsync in production. doctor
A data directory on NFS, SMB, FUSE or similar can't be trusted for locking and fsync. Those file systems don't give the guarantees the store needs. Put data_dir on a local disk (D-DATA-FS). doctor
Gemini CLI tool calls carry no call id; Tracekit pairs them by tool and arguments, first in first out. The harness doesn't send one. None needed; be aware when reading paired results. coding agents
Reasoning capture reads only Claude Code's transcript, and the v1 model proxy fronts only the Anthropic API. Other harnesses use other formats and APIs. Use the v2 gateway or OpenTelemetry for model-side cross-checks. coding agents
Tracekit doesn't see whether Claude Code's sandbox started for a command, what it blocked inside one beyond what Claude Code writes into the result, or the sandbox settings (they aren't signed into the run). The sandbox runs inside Claude Code's process and keeps no record; hooks see the call and its result. Set sandbox.failIfUnavailable: true so Claude Code never falls back to running unsandboxed; tracekit doctor warns when it isn't set (D-CLAUDE-SANDBOX). Claude Code's sandbox
Tracekit doesn't see whether Codex ran a command in its sandbox: a request to run outside it (sandbox_permissions: "require_escalated"), Codex's answer, or a command an execpolicy allow rule let run outside it. Codex's sandbox and approval settings aren't signed into the run, and no rule holds an escalation as TK-A003 holds Claude Code's unsandboxed retry. Nor does it see the shell an exec_command names (shell: bash, zsh, sh, pwsh or cmd; the policy reads every command as a POSIX shell's) or what is typed into a running command (write_stdin, which fires no hook), and with its in-development features.exec_permission_approvals on, Codex can run some calls with no hook at all. A relative path in a shell command is decided as typed, not as a path in the folder the call names for itself (workdir). Codex's PreToolUse hook sends a shell call's command only; the sandbox and its approvals run inside Codex. Codex sends write_stdin no hook, as input to a command that already had one, and its in-development permission-approvals path builds the hook in a way some calls don't pass; such a call runs unhooked. The policy reads a relative path as typed, by its certain suffix: its path rules read no working directory. Keep escalations with a person (approval_policy = "on-request", approvals_reviewer = "user"), or set approval_policy = "never" so Codex refuses them; keep allow rules narrow. The policy still decides every command before Codex's approval. Leave exec_permission_approvals off, and read a command that starts a shell or interpreter with nothing to run (bash, python3) as one that can run anything typed into it. Write path rules that also work on a relative path's suffix. Codex's sandbox
(1.5.1) Codex runs Tracekit's hooks only once a person has trusted them as they are, and again after they change (a new init can change them, as one run from another install does). Interactive codex asks at startup; codex exec, or a person who chose to continue without trusting, skips them without a word, so no Codex call is recorded or decided and the signer sees no gap, because no hook ever ran. tracekit doctor (D-CODEX-HOOK-TRUST) recomputes Codex's hash of each of Tracekit's hooks, v1 or v2, as codex-rs computes it (October 2026), and checks that Codex's config.toml ($CODEX_HOME's, by its real path as Codex reads it, else ~/.codex's) records trust for that hash and that none is turned off. A Codex that hashes differently reads as changed, never as trusted. For a hook with a setting Tracekit doesn't write (async, statusMessage, commandWindows or additionalContextLimit, added by hand) it says trust is recorded but it can't confirm it's for that hook; with Python 3.9 or 3.10 it can't read the file and says it can't confirm. In system mode init and doctor use the agent user's ~/.codex: that user's CODEX_HOME isn't known to them. Codex keys a hook's trust to a hash of its own normal form of the hook, so a person, not init, must review a hook before it runs. After tracekit init --agent codex, run codex and trust Tracekit's hooks (at its startup prompt, or type /hooks); init ends by saying so, and doctor warns while they aren't trusted or have changed since. coding agents
A process's CODEX_TOOL_CALL_ID names the Codex call that started it, the tool_call_id of that call's records, but the process and its children can change or remove it. Codex sets it as a label for correlation, not authorization. Use it to find the signed call behind an effect; read a missing or unknown id as unexplained, and a match as a pointer, not proof. Codex's sandbox
Gemini CLI's whole-CLI sandbox (tools.sandbox, GEMINI_SANDBOX, -s) runs without Tracekit: in a container the hooks tracekit init writes don't run and the session isn't recorded, with no gap; under Seatbelt the hook can't keep its state and blocks every call. Gemini runs the whole CLI, its hooks included, inside that sandbox: a container gets your user settings without their hooks, and Seatbelt lets a process write only the workspace, temporary and cache directories. Use Gemini's tool sandbox (security.toolSandboxing: true) instead. tracekit doctor warns when Gemini's settings turn the whole-CLI sandbox on (D-GEMINI-SANDBOX), but can't see GEMINI_SANDBOX or -s at launch. Gemini CLI's sandbox
Tracekit doesn't see sandbox permissions Gemini CLI grants outside a call's arguments (what its approval mode allows, an expansion Gemini proposes itself, one allowed for good), and Gemini's sandbox settings aren't signed into the run. Gemini's BeforeTool hook sends the call's arguments; the sandbox and its approvals run inside Gemini. Avoid YOLO mode and answer expansion requests once, not for good; TK-A004 holds each expansion a call's additional_permissions asks for. Gemini CLI's sandbox
tracekit doctor doesn't see Gemini CLI's folder trust: Gemini ignores an untrusted project's settings, so D-GEMINI-SANDBOX can read a project setting Gemini doesn't apply, or miss what Gemini does. Folder trust is Gemini's own state, kept outside the settings files doctor reads. Put the sandbox settings that matter in your user settings (~/.gemini/settings.json), which folder trust doesn't switch off. Gemini CLI's sandbox
Qwen Code runs a project's hooks only in a trusted folder: in an untrusted one the hooks tracekit init --project wrote don't run, so nothing gates or records that session's calls. A disableAllHooks: true in any Qwen Code settings file turns every hook off, Tracekit's included, and so do --safe-mode and --bare at launch. With QWEN_HOME set, Qwen Code reads its user settings from that directory, not from ~/.qwen/settings.json, where tracekit init --agent qwen writes. Qwen Code skips an untrusted workspace's hooks and honours its own switches without telling them; tracekit doctor reads neither its folder trust nor its settings layers. Install in the user's settings (tracekit init --dev --agent qwen), trust the folder, leave disableAllHooks unset, don't launch with --safe-mode or --bare, unset QWEN_HOME (or copy the hooks into $QWEN_HOME/settings.json), and check with tracekit view --dev that calls are recorded. coding agents
Qwen Code's model text and reasoning are not recorded: its transcript is hashed at each hook when the payload names it, but not read, so tracekit analyze --v2 has only the hook's prompt and no reasoning for its runs. Its transcript is not in a format Tracekit parses, and its hooks carry no model text. Route model calls through the LLM gateway for text the agent can't write; read Qwen Code runs by their calls. coding agents
The Claude Code hook records as typed every part of a prompt that isn't in a wrapper it recognises (such as 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, a message Claude Code marks as from a non-user source, uploads, command output, system reminders and fetched web content). Wrapper text it doesn't recognise therefore counts as the person's: a value it holds isn't untrusted (a from: untrusted rule allows a call that uses it), its constraints are live, and tracekit analyze --v2 reads it as a request. Claude Code 2.1.286 sends three kinds of turn no person typed to the hook with no wrapper at all, so they count as typed too: a prompt a plugin submits, a notice from another Claude Code session, and a poll event (a custom element such as <ci-status>). Once Claude Code sends its payload's source field, a turn whose source isn't user or sdk is recorded whole as untrusted (claude-code:<source>), and none of its constraints are live. The Gemini CLI hook recognises only its referenced files block; the Codex, Cursor, Qwen Code and Factory Droid hooks recognise no wrapper. A hook gets the prompt as one string, with no signed boundary between what was typed and what the harness added; the wrapper spellings are the ones seen in each harness, and a harness release can add one. Claude Code adds its wrappers to those three kinds of turn only after the hooks run; its hook input schema defines source (user, sdk, system, loop_wakeup, schedule_wakeup, poll_event), but 2.1.286 leaves it out. Report wrapper text Tracekit records as typed. Where a value must not be used, put a deny or ask rule on the destination, not only from: untrusted. Install only plugins and poll sources you trust to speak for you, and update Claude Code: a release that sends source closes the three bare paths with no change on your side. coding agents
A paste Claude Code sends inline (its default) is recorded as typed, and its constraints are live. A recognised wrapper inside it, or typed text that looks like one, makes the rest of the prompt untrusted from there, text typed after it included: a value in it isn't trusted, and tracekit analyze --v2 reads none of it as a request. When the wrapper starts a line, constraints after it aren't live, and Claude Code shows a notice naming them; when it follows other text on its line (a tag's name in a sentence), they are live up to the next wrapper that starts a line, and analyze checks them. Constraints in a wrapped part that starts a line (a paste block, a slash command's arguments, a scheduled prompt, a relayed message) are recorded but not live. The hook can't tell a typed tag from one the harness added, or a pasted line from a typed one; wrapped parts are text the harness added or relayed, which the person didn't type. Claude Code starts a line with each wrapper it adds, so one mid-line may be typed, and a constraint only holds more calls. Type constraints before a large paste or in a prompt of their own; restating one after a wrapper at the start of a line doesn't make it live. coding agents
Untrusted text in one prompt is recorded up to 50,134,272 characters, shared equally across the wrapper kinds in it. Past that, the text isn't recorded: the hook leaves one event number unsent before a claude-code:harness-cut note naming the cut kinds, so the signer writes a signed client_counter_gap and marks the run's provenance index partial, and Claude Code shows a notice. For the rest of the run, every from: untrusted rule applies to each call its pattern matches, whatever the value's source. Each observation the hook sends the signer is one frame of at most 1 MiB. The cap is 48 frames' worth of characters, so the hook doesn't hold an ASCII prompt long (about 7 s at the cap); text that isn't ASCII takes more frames, up to about four times as many, since each frame holds 1 MiB of UTF-8. A cut value never reaches the signer's untrusted-value index, so the gap marks the index incomplete rather than let such a value pass. Keep pasted and attached text in one prompt under the cap. After a cut, expect from: untrusted rules to ask about (or deny) every call they match until the run ends; start a new session to return to normal. coding agents
Qwen Code records as the person's prompt only a UserPromptSubmit that carries submitted_prompt (Qwen Code 0.21.1 on in its TUI, 0.21.12 on for qwen -p), and records that text, not prompt, into which Qwen Code expands @file contents and a large paste (over 1,000 characters or 10 lines: submitted_prompt holds its [Pasted Content N chars] placeholder). The rest are not recorded: its continuations after tool results (an empty prompt), a Stop hook's reason it sends back to the model, and typed prompts Qwen Code sends without the field: Qwen Code before those releases; the TUI with Vim mode on (or input it can't trace to the composer); ACP clients and daemon hosts that send no qwen.submittedPrompt declaration (Web Shell sends one; realtime voice handoffs and channel messages, a person's included, never carry it). The live constraints the hook hands the signer are read from the same text, so a Stop hook's reason, a referenced file's contents or a large paste's text never state one. Qwen Code fires UserPromptSubmit for those sends too, and submitted_prompt is the only field that tells a submission from them. Use Qwen Code 0.21.1 or later (0.21.12 for qwen -p) with Vim mode off, and an ACP client that declares qwen.submittedPrompt; type a constraint you want held into the prompt itself, not into a large paste or a referenced file; read a prompt it didn't record from Qwen Code's own session history. coding agents
On native Windows, tracekit init --agent qwen writes "shell": "powershell" into each hook, so Qwen Code runs it under Windows PowerShell whether it was started from cmd.exe or Git Bash, with the command in PowerShell's & "..." form (bare when the Python path needs no quotes) ending in ; exit $LASTEXITCODE (PowerShell hands a native exit 2 back as 1, and Qwen Code blocks a call only at 2); a PreToolUse hook whose Python didn't run or failed exits 2, so the call is blocked. Qwen Code starts PowerShell with -Command and no -NoProfile, so the user's PowerShell profile runs before each hook. Qwen Code before 0.15.0 ignores a hook's "shell": under cmd.exe the bare form runs (the tail reaches the hook as arguments: the v2 hook takes the event its command names, the v1 hook, which names none, the payload's) but a quoted Python path can't start (Node escapes its quotes), so every call runs unchecked and unrecorded; under Git Bash a quoted path is a syntax error, so every event exits 2 and every call and prompt is blocked, and with a bare path 0.14.5 sent no request to the model in our test, so no call ran. An earlier init wrote no "shell", so its hook ran under the shell Qwen Code was started from, and with a Python path that needed quotes it couldn't start under cmd.exe. On another event, a hook that can't start (its Python moved or was uninstalled) or crashes isn't recorded. Tested with Qwen Code 0.26.5 and 0.14.5 on Windows in runs on the contributor's fork (run, run). Windows has no POSIX shell to wrap the hook in, and Qwen Code picks its shell from how it was started unless the hook names one. Use Qwen Code 0.15.0 or later; run tracekit init --dev --v2 --agent qwen again after upgrading Tracekit and after moving or reinstalling Python, or use WSL; check with tracekit view --dev that calls are recorded. coding agents
tracekit srt-decider sees only requests to the hosts in its --allow-domain list; srt-proxy refuses the rest itself and Tracekit records nothing of them. srt-proxy's decider protocol has the decider name its hosts before the first request, and no entry matches every host. List every host the workload needs; a missing one shows in the workload as 403 with X-Deny-Reason: host_not_allowed. sandbox-runtime
A request tracekit srt-decider allowed is recorded as allowed, not as sent: Tracekit doesn't see the response, nor whether srt-proxy forwarded it (it still refuses a host that resolves to a private address, and an answer that comes after its 5 s wait). The protocol carries requests and verdicts, nothing after. Keep the signer close to the decider so answers come in time; route calls whose result matters through the tool executor, which records it. sandbox-runtime
An ask through tracekit srt-decider refuses the request at once (403); the request is allowed only when the workload sends it again after a person approved it. srt-proxy waits 5 s for each answer. Have the workload retry a 403 that names an approval, or send the request again yourself once it is approved. sandbox-runtime
A tracekit srt-decider approval binds the method, URL and body digest: not the headers, nor the body of a GET, HEAD or OPTIONS. A body over 32 MiB is refused. srt-proxy shows a body only when asked, up to 32 MiB, and not for those methods. Where a header or such a body changes what a request does, deny that host by policy rather than ask. sandbox-runtime
One tracekit srt-decider is one run, whatever process sent a request, and the approvals it waits on live in its memory: after a restart the same request asks again. When the signer closes the run (no request for idle_s, an hour by default), the decider refuses the next request and stops srt-proxy. srt-proxy's requests name no client; a closed run records nothing more. Run one srt-proxy and decider per agent run, under a supervisor that restarts it; after a restart, approve the new request. sandbox-runtime
tracekit srt-decider decides each request on its method, URL and the body's SHA-256 only: content rules never see the body, so a rule on what a request sends (a secret, a customer record) can't match it. Only the digest goes to the signer, so the run never holds the body; the digest binds an approval to it. Decide such hosts by host and method; send calls whose content matters through the tool executor or the MCP gateway, whose policy sees their arguments. sandbox-runtime
(1.2) A run is recorded as a child (register_run parent) only when the caller presents the parent's run token as the identity it was issued to, on the parent's signer, while the parent is not final. The token proves the caller may act for the parent run; a final run takes nothing more. Start sub-agent runs from the code holding the parent's handle (client.run(..., parent=handle)), or with a delegate_run token for the sub-agent's identity, before the parent finishes. The refusal (run_token_invalid, unknown_run, run_closed) says which. format v2
v1 OTLP receiver and ingest gateway are experimental. They are being rebuilt; they run only with --experimental. Use the v2 signer's OTLP import. OpenTelemetry
v1 OTLP policy is evaluated after the fact: a call a rule would deny is recorded as flag, not stopped. Spans arrive when the work is done. Block with hooks, an SDK tool() or an adapter. OpenTelemetry
(1.2) An MCP call decided as mcp:<server>/<tool> reconciles with the model's tool use only when the model's name is the bare <tool>, mcp__<server>__<tool> (Claude Code) or mcp_<server>__<tool> (OpenAI Agents JS with includeServerInToolNames); its arguments are compared under that name. A framework that shows the server another way (mcp-agent's <server>_<tool>) gets args_mismatch for each call; with a bare name, two servers' same-named tools in one model turn are told apart only by call id. Only names that can't be a different tool's are accepted: a suffix match would let an agent rename delete_account to mcp:x/account. Expect args_mismatch for such frameworks until the policy can list their servers; keep the model's call ids (the shipped adapters do). MCP
(1.2) With a bare model name (OpenAI Agents JS, the Vercel AI SDK, the mcp Python client), nothing ties the server in mcp:<server>/<tool> to the model's call: an agent that decides the model's query as mcp:notes/query instead of mcp:postgres/query is reconciled, and rules keyed on the server (mcp:postgres/*) don't apply. A server or tool with an edge _ or a __, or a tool named like a prefixed form, gets no alias at all. The model never saw the server; only the agent's adapter names it. Key MCP rules on the tool name (it is also checked under its bare name) or use names that carry the server (includeServerInToolNames, Claude Code); put servers that need server-level rules behind the MCP gateway, which decides what it forwards. MCP, MCP gateway
(1.2) A long-running signer keeps a small stub of every run it has seen (about 1 KB in memory, 0.5 KB in each snapshot, plus the file store's per-record index), each final run's first late writers (up to 64), and every incident, resolved ones too (incident_list serves them); the request-id cache holds at most 100,000 answers (10,000 per identity). Snapshots are written whole on the writer, pausing writes for about 1 s per 300,000 runs. Final runs answer tokens, late writes and run_exists from memory; the stubs are the signer's index of what it has signed. Restart into a new store (a new data_dir, the old one kept for export and verification) once a store holds millions of runs; size memory at about 3 KB per run. deployment
OpenCode (1.x) sends plugins no session or prompt events, and no tool.execute.after for a call that fails, is declined in its own permission prompt or is aborted: its run closes only at the signer's idle timeout, no prompts, live constraints or model text are recorded, and those calls stay decided_not_completed gaps. Its plugin API has tool hooks only, and runs the after hook only for a call that completed. Read such gaps as calls that didn't complete; use Claude Code, Codex or Gemini CLI where prompts and session ends must be in the record. coding agents
(experimental) goose support hasn't been checked in a live goose session (1.48.0 or later). On Windows goose runs hooks with sh -c, so without sh on PATH (Git Bash) every call is blocked. Code Mode (execute_javascript, and execute_typescript or execute_bash before goose 1.56) is denied, so Code Mode can't be used with Tracekit. The tests drive goose's documented payloads and its source's hook runner; Code Mode runs tool calls through dispatch_tool, which runs no hooks. Use goose's own tools rather than Code Mode; on Windows install Git Bash. coding agents
goose sends no tool result on PostToolUse and no error text on PostToolUseFailure: a completed call's tool.result carries no output, and a failed call's carries ok=False with no error text. Its installed hooks are tool events only (no session or prompt events), so no prompts, live constraints, transcript hashes or model text are recorded. goose's hook payload table lists no result or error field for tool events, and Tracekit installs only PreToolUse, PostToolUse and PostToolUseFailure. Read a goose run's calls from their decisions and arguments, not from outputs; use Claude Code, Codex or Gemini CLI where results and prompts must be in the record. coding agents
OpenCode's experimental batch tool (experimental.batch_tool, OpenCode 1.x before 1.4 only) is blocked whatever its calls: the plugin refuses it before it runs. OpenCode runs the calls inside a batch without plugin hooks, so Tracekit could neither decide nor record them. Leave experimental.batch_tool off; the model then makes each call itself, and each is decided. coding agents
The OpenCode plugin kills a hook still running after 600 seconds and blocks its call, so a hook stuck on a slow or hung signer blocks the call rather than OpenCode. OpenCode 2.0 doesn't load 1.x plugins, so its hooks would stop with no error. The plugin awaits each hook's process without blocking OpenCode's event loop, so OpenCode keeps streaming and decides parallel calls at once; the hook answers within 540 seconds, a held call's approval wait included, and 600 seconds is the other coding agents' pre-tool timeout. Check a blocked call's message: did not answer in 600 s means the hook hung (tracekit doctor checks the signer); pin OpenCode 1.x until Tracekit supports 2.0. coding agents
(experimental) Kilo Code support was run with the Kilo CLI 7.8.18 on Linux only: its VS Code extension, Windows and macOS haven't been tried. Kilo's notebook_execute (VS Code only, with experimental.native_notebook_tools, off by default) is blocked whatever its arguments: the hook refuses it before it runs. It runs a notebook cell in the live kernel; the cell's code was written by notebook_edit, which is decided on its path alone, so no command rule ever reads it. Leave experimental.native_notebook_tools off in kilo.json; the model then runs code through bash, and each command is decided. coding agents
Kilo's own tools that Tracekit doesn't map pass through under their own names, as unknown tools: only the policy's unknown_tools (TK-UNKNOWN-TOOL) applies, and no rule reads their arguments. Among them: browser_open (VS Code; opens its url in a browser), repo_clone (clones its repository, a git URL or owner/repo, into Kilo's cache), kilo_memory_save (saves a note to Kilo's project memory, which later sessions read back) and agent_manager (VS Code; starts sessions). MCP tools reach the plugin under OpenCode's <server>_<tool> name, so they aren't decided as mcp:<server>/<tool> and MCP rules don't apply to them (OpenCode's too). A session agent_manager starts in worktree mode runs in a new git worktree under the project's .kilo/worktrees/; Kilo looks for project config only from there up to that worktree's root, so a --project install's .kilo/plugin/ in the main checkout doesn't reach it (read from Kilo 7.8.18's source; not tried). Tracekit maps the tools that run a command or read or write a file; these act through Kilo's own services, and Kilo's MCP names don't say where the server name ends. Set unknown_tools to ask or deny where these tools matter; with Agent Manager worktrees, install without --project: the global plugin in ~/.config/kilo is loaded in every session. coding agents, policy v2
Kilo's send_file uploads a file to Kilo's mobile app but is decided as a Read of it, so a secrets file sent that way is only flagged (TK-F005) where the same upload from a shell is held. The upload goes to the user's own Kilo app, and the hook sees one tool name per call. Hold send_file in a rule of your own if your agents shouldn't send files to the app. coding agents
Kilo's generate_image given an image is decided as a Read of that file and of the path it writes, so the write rules don't see that path (a write under ~/.config/kilo/ or .git/hooks/ that a Write there would hold or deny); Kilo gives the written file an image extension (.png, .jpg or .jpeg). The hook decides each call as one tool, and the file it reads and sends off is the larger risk. Hold generate_image in a rule of your own if image writes outside the project matter to you. coding agents
Factory Droid's documented hook stdin gives a tool call no id. Two identical calls in flight are paired first in first out, so their results cannot be distinguished if they complete in another order. An allowed call with no PostToolUse (declined in Droid's permission prompt, blocked by another hook, or failed; Droid has no PostToolUseFailure) stays queued, so the next identical call's result can be paired to it and the call that ran closes as an error at session end. Only the tool name and arguments connect Droid's PreToolUse and PostToolUse events. Avoid concurrent identical calls when their result attribution matters. Blocked calls leave the queue so a later allowed call does not inherit their id. coding agents
(experimental) Factory Droid support has not been checked in a live authenticated session or on native Windows. Its transcript format is not read, so model text and reasoning are not captured. Its documented events include no PostToolUseFailure; the minimum version is unknown, and whether Task-started sub-droids fire hooks is unknown. ApplyPatch's field and format are from Factory CLI 0.249.0's tool listing, not a captured hook payload. Tests drive the documented stdin through Tracekit's real v1 pipeline and the v2 signer; the tool listing does not exercise hooks. Verify a denied and a held call in Droid before relying on the integration; inspect the run with tracekit last. A failed call without PostToolUse remains incomplete until SessionEnd or the signer's gap handling. coding agents
An agent's edit of Factory Droid's settings or hooks (.factory/, ~/.factory/) is flagged (TK-F009, TK-F015), not held, as for the other harnesses. Managed-only hooks or globally disabled hooks can also keep the user and project hooks from running. The settings rules flag the whole folder, which agents also touch in normal work; Droid applies its own settings before launching hooks. Keep hook configuration outside the agent's write access, leave hooks enabled, check the effective hooks in Droid's /hooks UI, and verify calls appear in tracekit last. Droid hooks
Factory Droid's UserPromptSubmit prompt is recorded as the person's (trusted), and the hook reads live constraints from it, but it isn't confirmed that only a prompt the person typed fires it. A Task-started sub-droid's prompt or a Stop hook's continuation may fire it too (Qwen Code fires it with a Stop hook's reason), and would then be recorded as the person's. Droid's hooks reference doesn't say what else fires UserPromptSubmit, and Tracekit hasn't checked it in a live Droid session. Until a live session confirms it, read a Droid prompt in tracekit view --dev as what Droid handed over, not proof that the person typed it, and check it against what you typed; put what the agent must not do in the policy, not only in the prompt. coding agents
Devin's hook payload gives a tool call no id. Two identical calls in flight are paired first in first out, so their results can't be told apart if they complete in another order, and an allowed call with no PostToolUse (declined in Devin's permission prompt, or blocked by another hook) stays queued, so the next identical call's result can be paired to it. Devin's documented payload has session_id, a per-turn prompt_id, tool_name and tool_input only. Avoid concurrent identical calls when their result attribution matters; blocked calls leave the queue. coding agents
(experimental) Devin support has not been tested in a live Devin CLI or Desktop session: tests drive Devin's documented payloads through Tracekit's v1 pipeline and the v2 signer. Only exec's input (command, shell_id) is documented, and Devin's decoder may match a key, or a tool's name, ignoring case: a tool is read under its name in any case (EXEC), exec is decided on its command under any spelling (Command), with \r read as a line end (should Devin type it into a terminal), and is denied in the hook with no command (or input that isn't an object) or a control character other than a tab or line end; a ! in it is decided as written, though bash would expand it from history if Devin typed the command into an interactive shell; and a call that sends an argument's name twice (in any case, with any value: {"command": …, "command": null}) is denied in the hook, as a decoder may keep either value; read, write and edit are decided on every path under a key whose name, case and _ ignored, ends in path, paths or file, apply_patch on every file a *** … File: header or a unified diff's ---, +++ or diff --git line names in any of its arguments, and write_to_process as a Bash command on its one argument besides shell_id, the text it writes, whatever its name. A path under a key with another name (filename, target) isn't decided, so beside one of those keys it goes undecided. A read, write or edit with none of those keys, an apply_patch with no file header, a webfetch with no url, or with one under another spelling too (URL), and a write_to_process with no text or another argument beside it, or whose text holds a control character (any C0 or C1 control but a line end, or DEL: the terminal's line editor acts on it, so the line that runs isn't the text; \r is read as a line end) or a history expansion interactive bash would make (a ! before anything but a blank, a line end, = or (, or a ^ starting a line), or that uses a form of shell state Tracekit knows (below), are denied in the hook, before the signer, so they have no signed decision. A persistent shell's state, set by an earlier typed line, can change what a later line runs, while the policy decides one call at a time. Tracekit denies the forms it knows: history replay (fc; history -s, -r or -n), an alias definition, a function definition, trap, bind, enable, the exec builtin (it can make the shell read commands from a file, or replace it), set options (set -o vi, set +H), shopt, hash, source or ., setting PROMPT_COMMAND, PS0 to PS4, PATH, BASH_ENV, BASH_ALIASES or BASH_CMDS (alias's and hash's tables) or a loader variable (LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, any DYLD_*), and a nameref (declare, typeset or local -n), which sets a variable under another name. Other variables a program reads (a pager or an editor: GIT_PAGER, EDITOR) are decided only as the line that sets them reads; the command a program later runs from one isn't seen. The rest of a shell's state (an ordinary variable a later line expands, the directory) isn't tracked from one call to the next, and exec calls aren't checked for these forms (a script there may source a venv or define a function), though Devin may run them in the same shell: where that matters, run Devin in a sandbox or in Tracekit Box. A relative path is decided as typed: the payload names no working directory. run_subagent passes through under its own name; whether a sub-agent's calls run hooks is not documented. Its transcript isn't read, so no model text is recorded, and its UserPromptSubmit prompt is recorded as the person's without a check that only a typed prompt fires it. A hook that outlives its timeout, exits otherwise than 0 or 2, or prints output Devin can't read lets the call run. Devin is closed source; its hooks reference names the tools and their events, not their arguments, and treats any hook failure but exit 2 as a non-blocking error. In a real Devin session, check that a denied call doesn't run, that a held call runs when Devin tries it again after tracekit approvals approve, and that its calls appear in tracekit last. If a call is denied for its arguments, report their names (the block message lists them) on #566. Devin hooks
On Windows, Devin's hook command isn't wrapped, and Devin doesn't document the shell it runs a hook in there. tracekit init --agent devin writes the Python path bare when it needs no quotes (cmd.exe and PowerShell both run that) and in cmd.exe's quoted form when it does, which PowerShell can't run. Under Windows PowerShell a block's exit 2 can come back as 1, which Devin doesn't read as a block, and a hook that can't start (its Python moved or was uninstalled) isn't wrapped to fail closed. In each case the call runs undecided and unrecorded. Not tested on Windows. Windows has no POSIX shell to wrap the hook in, and Devin's hooks reference names no Windows shell. On Windows, run Devin under WSL. Otherwise install Python under a plain path (C:\Python312), run tracekit init --dev --v2 --agent devin again after moving or reinstalling Python, and check in Devin that a call the policy denies doesn't run and that its calls appear in tracekit last. coding agents
Devin Desktop runs no hooks in Restricted Mode, so no call made there is decided or recorded. Devin's cloud sessions run hooks too (through plugins), on a VM where a laptop's signer isn't reachable: there each call goes by the hook's fail mode, and none is recorded. Restricted Mode turns hooks off before they load; a cloud session runs on Devin's machines, not the one with the signer. Don't use Restricted Mode where calls must be recorded; for cloud sessions, run a signer they can reach (deployment) or don't install Tracekit's hooks in what they read. Devin Desktop
tracekit init --agent devin sets read_config_from.claude to false, so Devin no longer reads any of Claude Code's hooks, rules, skills, commands or MCP servers, not only Tracekit's. Uninstall leaves it false and says where to set it back. Devin reads Claude Code's hooks by default and would run Tracekit's Claude Code hook on its own payloads beside its Devin hook, deciding each call twice; the Claude Code hook blocks them, as they carry no tool_use_id. Set it back to true in the Devin config init names if you need Claude Code's config in Devin, and don't install Tracekit's Claude Code hook in those files then. coding agents
(experimental) Antigravity CLI (agy) support has not been checked in a live agy session or on native Windows. Tests drive agy's documented hook payloads through Tracekit's v1 pipeline and the v2 signer. That agy sends the same stepIdx and toolCall with a call's PreToolUse and PostToolUse, which pairs them, is its documented contract, not yet seen. agy 1.2.1 to 1.2.3 ran no hooks on some machines (#1008, working again in 1.3.0); before 1.2.17 a project's .agents/hooks.json is read only for a folder passed with --add-dir (#1052). Running agy needs a Google sign-in, which the tests don't have. The skipped hooks are agy's bugs. Use agy 1.3.0 or later. Before relying on it, check in agy that a call the policy denies is blocked and a held call runs when agy tries it again after tracekit approvals approve, and that tracekit view --dev shows each call with its outcome. coding agents
On Windows, an Antigravity CLI hook in dev mode that can't start (its Python moved or was uninstalled) isn't wrapped to answer agy's JSON deny: agy takes it as a failed hook, and the call runs unchecked and unrecorded. Before agy 1.4.7, a post-tool hook that failed also replaced the call's result with an error. Windows has no POSIX shell to wrap the hook in; elsewhere a wrapper answers at exit 0, a deny before the call and {} after it. After moving or reinstalling Python, run tracekit init --dev --v2 --agent antigravity again, or use WSL; check with tracekit view --dev that calls are recorded. coding agents
Antigravity CLI's prompts, live constraints, model text and tool output are not recorded. Tracekit installs only agy's PreToolUse and PostToolUse hooks, and agy's PostToolUse sends a failed call's error text but no output. With no session events, an agy run closes at the signer's idle timeout. Tracekit hooks agy's tool calls only and doesn't read agy's transcript. Put what the agent must not do in the policy, not only in the prompt; route model calls through the LLM gateway for text the agent can't write; read agy runs by their calls. coding agents
Antigravity CLI loads its hooks and never runs them when Tracekit's hook is "enabled": false (in ~/.gemini/config/hooks.json or a workspace's .agents/hooks.json), or when agy signs in with a Gemini API key (antigravity-cli#893) or Application Default Credentials (antigravity-cli#1310). Then no agy call is decided or recorded, there is no gap, and agy doesn't say so. agy skips the hooks itself, and Tracekit sees nothing of a session whose hooks never run. Sign agy in with a Google account, and don't set "enabled": false on Tracekit's hook in any hooks.json. Run tracekit doctor from agy's shell: D-AGY-HOOKS-RUN warns for each of these it can see and says what to change. doctor
The global ~/.gemini/config/hooks.json that tracekit init --agent antigravity writes is read by the Antigravity IDE app too (#1329): the app's tool calls are decided and recorded as well, as agent antigravity, and a held call stalls the app's turn until someone answers it. #1329 reports the app running a call a hook answered allow that headless agy -p still declines (#1053); whether that skips the app's own approval prompt is untested. agy, the IDE and the app share one global hook config, and a hook payload doesn't say which of them sent it. Install per workspace (--project: .agents/hooks.json) to keep the hooks out of other workspaces; answer held calls from another terminal (tracekit approvals list); keep the app's own approval settings as they are. coding agents
An Antigravity CLI call Tracekit allowed that gets no matching PostToolUse (declined by agy's own permissions: headless agy -p declines every command without a grant, #1053) stays a decided_not_completed gap. invoke_subagent is decided as Task, but agy creates the sub-agent even when the hook denies it (#640). With no session events, nothing tells the hook that agy declined a call; agy doesn't honour deny for sub-agent tools. Read such a gap on an antigravity run as a call agy may have declined; don't count on a deny or a hold to stop agy's sub-agents. coding agents
Tracekit reads Antigravity CLI's BypassSandbox (a run_command run outside agy's terminal sandbox) from the call's PreToolUse input, where agy 1.4.4 sends it although its hooks reference doesn't list it (#1304), and decides it as Claude Code's dangerouslyDisableSandbox: TK-A003 holds the call, and its reason names Claude Code's sandbox. A release that renames or drops the field runs such commands outside the sandbox with no hold. A relative path in a run_command is decided as typed, not as a path in the folder the call names for itself (Cwd). The field is undocumented (#1304 asks for it to be); TK-A003 already holds the same request from Claude Code. The policy reads a relative path as typed, by its certain suffix: its path rules read no working directory. Keep agy's own approval for commands outside its sandbox on; read a TK-A003 hold on an antigravity run as agy's sandbox. Write path rules that also work on a relative path's suffix. coding agents
With TRACEKIT_APPROVAL_WAIT set, while Tracekit holds an Antigravity CLI call for approval, agy waits too (up to about 480 s) and may show nothing: the approval id the hook prints goes to stderr, which agy isn't known to display (by default the hook blocks the call at once, with the id in its JSON deny's reason). An agent's edit of agy's hook files (~/.gemini/config/hooks.json, a project's .agents/hooks.json) is flagged (TK-F009, TK-F015), not held, and whether a project hook named tracekit replaces the global one is untested. A call whose arguments name a field Tracekit reads in another case, twice in different cases or as null, or carry a key outside ASCII, is denied in the hook before it reaches the signer, so it has no signed decision (agy's decoder may read such a key as the field; its own calls spell each field once, exactly). agy acts on a hook's answer only once it returns, and logs no line when a hook runs (#893); the settings rules flag rather than hold, as for the other harnesses. List and answer held calls from another terminal (tracekit approvals list); check that agy's /hooks lists tracekit; keep .agents/ out of the agent's write access. coding agents
(experimental) Crush support has not been checked in a live Crush session or on native Windows. Tracekit installs only SessionStart, SessionEnd, PreToolUse, PostToolUse and PostToolUseFailure: TurnStart carries no prompt, and TurnEnd sends the turn's last_assistant_message, which Tracekit doesn't read yet, so prompts, live constraints and model text are not recorded. Crush runs no hooks inside a sub-agent, so the hook denies agent and agentic_fetch, and Docker MCP Gateway's code-mode tools, whose scripts call MCP tools no hook sees. It also denies a built-in tool call whose input repeats an argument name or has one that isn't lower-case snake_case. An MCP tool, mcp_<server>_<tool>, is decided as mcp__<server>_<tool>: the shipped packs' MCP rules read that joined name, but the server and tool aren't split apart, so a rule of your own written for mcp__server__tool doesn't match it, and a server whose name holds a rule's word after a _ or - (files_delete) trips that rule on each of its tools, in every harness. download is decided as a write of the file it creates, so the fetch rules (TK-F002, TK-F012) don't see its URL. A relative path in a bash command is decided as typed, not as a path in the folder the call names for itself (working_dir). A hook that outlives its timeout lets the call run. Crush's payload and event names are Claude Code's, but TurnStart has no prompt field; a sub-agent's tools aren't wrapped with hooks (wrapToolsWithHooks); Crush decodes a built-in tool's input into a Go struct, matching names ignoring case, so it may run other arguments than Tracekit reads; its MCP names join server and tool with _, which either name may contain; a call is decided as one tool; the policy reads a relative path as typed, by its certain suffix, and its path rules read no working directory; a timed-out hook is killed and treated as a non-blocking error. Put what the agent must not do in the policy, not only in the prompt; put permissions deny agent agentic_fetch in crushrc (in crush.json: "options": {"disabled_tools": ["agent", "agentic_fetch"]}); write MCP rules on the joined name (mcp__github_*, or mcp__.*[_-]<tool> as the shipped rules do), name MCP servers without _ (the server pack reads a refund_* tool only after one), or route MCP through the gateway; write path rules that also work on a relative path's suffix; in a real Crush session check that a denied call doesn't run and that its calls appear in tracekit last. coding agents
A decision's expires_at (300 s after it) is signed, but the signer doesn't refuse a complete that comes later: a call can run long after it was decided. Refusing it needs the executors and adapters that run a call to check the time first; a T1 agent decides when to run anyway. The decision's and the result's record times show the gap (tracekit view). tool-call lifecycle
A call allowed or flagged after a deny of the same arguments in the same run is marked with a decision_flip gap, but the set of denied arguments lives in the signer's memory: after a signer restart, a flip against a deny from before it isn't marked. The set isn't kept in the run's snapshot, so a restart doesn't replay every decision of every open run. The run's records still hold both decisions; tracekit view lists every deny of a run. policy

Policy

Limit Why it is so What to do Details
An agent's edit of its own harness's settings, hooks, MCP servers, skills or slash commands (.claude/settings.json, ~/.claude.json, .claude/skills/ and .claude/commands/, whose ! lines run commands, ~/.gemini/settings.json, .codex/, ~/.cursor/hooks.json and mcp.json, OpenCode's .opencode/, opencode.json and, from the shell, ~/.config/opencode or $XDG_CONFIG_HOME/opencode (the shell rule matches the variable's name; a file tool gets the expanded path, so its write is denied only at ~/.config/opencode, TK-D009), Qwen Code's .qwen/ and ~/.qwen/settings.json, Factory Droid's .factory/, Devin's .devin/, ~/.config/devin and, on Windows, AppData\Roaming\devin (the folder %APPDATA% names: a path written through the variable isn't matched), Antigravity CLI's ~/.gemini/config/hooks.json and .agents/hooks.json, goose's .agents/plugins/ and ~/.config/goose, Crush's crush.json, .crush.json, crushrc, .crushrc and ~/.config/crush, PowerShell's profiles (a *profile.ps1 in Documents/WindowsPowerShell/ or Documents/PowerShell/, OneDrive's Documents too under its localized name (OneDrive - Contoso/Dokumente/), pwsh's ~/.config/powershell/ on Linux and macOS, or the $PSHOME of Windows PowerShell (System32/WindowsPowerShell/v1.0/) or PowerShell 7 (PowerShell/7/, PowerShell/7-preview/), and $PROFILE or $global:PROFILE by name from the shell), which run before a hook PowerShell starts without -NoProfile, by a file-editing tool (Write, Edit or MultiEdit) or a recognized shell write) is flagged (TK-F009, TK-F015), not held, and once it turns the sandbox off, TK-A003, TK-A004 and TK-A014 have nothing to hold: later commands run outside it with no escape-hatch argument. The file rule reads the normalized path, and the shell rule reads WRITE_TARGET: and DELETE_TARGET: effects (redirects, tee, cp, mv, sed -i, rm, find -delete, git rm, awk's print > "file", …). Both also match casefolded paths. Reads and content that merely names these paths do not match. Not flagged: Cursor's rules (.cursor/rules/), Windsurf's and VS Code's settings, a Claude Code config folder moved elsewhere (CLAUDE_CONFIG_DIR, ~/.config/claude-code) and instruction files agents edit in ordinary work (AGENTS.md, CLAUDE.md); TK-F016/TK-F017 read an ANTHROPIC_…BASE_URL name only when it is written in one piece (not split by a line continuation), and not a proxy variable (HTTPS_PROXY). A file inside one of Claude Code's worktrees (.claude/worktrees/<name>/…) is read as it is in the worktree: an ordinary file there isn't flagged, the worktree's own .claude/, .codex/, .mcp.json and the rest are, and so is a worktree named as a dot folder, the worktree itself, and a shell target with a .., or an expansion or glob that can make one ($D, {..,a}, .*), among its first 32 parts after the worktree, or more parts than that. A link made in a worktree that points out of it (ln -s ../.. .claude/worktrees/x/up, then a write to up/settings.json) isn't followed, as a link made anywhere else isn't. ANTHROPIC_BASE_URL (where the agent's model calls go) is flagged wherever a call names it, in any case (Windows reads a variable's name so): in a Write, Edit or MultiEdit call's arguments (TK-F016; a NotebookEdit cell isn't read) and on a shell line from any shell tool, an assignment prefix (ANTHROPIC_BASE_URL=x claude) and the text a heredoc or echo writes included (TK-F017). A mention is flagged as well as a setting, so a grep, a note or a comment that names the variable is flagged too: noisy by design, and only a flag. Under QWEN_HOME, the shell rule matches only the variable's name ($QWEN_HOME/settings.json); a file tool's write to the directory it names is not matched. A write through any other variable, a script or another program (curl -o, wget -O, touch, rsync, git restore, an editor, an interpreter one-liner) is not matched, nor is a PowerShell cmdlet that writes or deletes a profile (Add-Content, Set-Content, Out-File, Remove-Item) or a profile in a Documents folder redirected elsewhere (a path without Documents or OneDrive). The rules cover every file under those directories (skills, commands) but Claude Code's memory notes (.claude/projects/<project>/memory/*.md, the agent's own notes, not settings) and the ordinary files of its worktrees (a checkout of the project, not settings); agents edit those files in normal work, so holding all of them would ask about most sessions. Read TK-F009 and TK-F015 flags as possible sandbox changes; keep the sandbox's settings where the agent can't write (managed settings, a read-only mount); add an ask rule of your own for the settings files your agents never need to touch. Claude Code's sandbox, Gemini CLI's sandbox
TK-A003 holds a call only when it carries dangerouslyDisableSandbox: true. Commands matching excludedCommands, hooks and MCP servers run outside the sandbox without it. Claude Code marks only the unsandboxed retry; the rest are outside the sandbox by configuration. Keep excludedCommands short; the policy still decides each excluded command and MCP tool call. Claude Code's sandbox
TK-A014 holds a call whose allowed_domains names a host; it doesn't see hosts opened by the sandbox's own settings (network.allowedDomains), and it can't tell which of the listed hosts a command then reached. (1.5.1) It reads only Bash, PowerShell and Monitor calls, the tools Claude Code documents as opening hosts this way (WebSearch's allowed_domains only narrows results): a new tool that opens hosts with allowed_domains isn't held until the pack names it. The hook sees the call's arguments, not the sandbox's settings or its proxy's traffic. Keep the hosts a project always needs in network.allowedDomains (a person edits the settings) and approve the rest one command at a time. Claude Code's sandbox
A tool name a framework rewrote (CrewAI's bash for Bash, multi_edit for MultiEdit) is also decided as the tool tools: lists with that spelling (case, accents, spaces and punctuation ignored), as each one when two listed names share it (the server pack's bash and Bash), and its results are untrusted when that tool's are; an MCP tool's bare name is read the same way. Nothing else reads it so: a rule whose tool: names a tool tools: doesn't list (tool: RefundTool, which CrewAI sends as refund_tool) doesn't take it, and constraints, the egress observer's host, detection's sum limits and a fail mode in an outage go by the class of the name as sent (unknown); an agent approver can't answer it, as the policy doesn't name it exactly. A name with no ASCII letter or digit, or a name over 64 characters (CrewAI cuts it and adds a hash) is decided only as sent. Each name a call is decided as gets the fallback regex engine's time budget of its own, so on a crafted 64 KiB argument a renamed tool's decision can take a second per name (re2 is unaffected). A tool: pattern can't be spelled backwards; deciding both names and keeping the stricter decision never decides a call less strictly than before. List each tool under its declared name in tools: (RefundTool: app), or write a rule's tool: as the framework sends it; keep the default fail mode closed, as it ships. policy, CrewAI
The decide RPC answers allow for a flagged call; only the signed policy.decision says flag. decision tells the client what to do, and clients since RPC 15 know only allow, deny and ask; the signer can't tell a client's version. Read a flag from the record, or from the flag rule's id in the response's rule_ids. policy
Policy rules are tripwires that make attempts visible, not the protection itself. They match strings; a rewording a rule doesn't anticipate isn't matched. The protection is the signer's isolation, its storage and the witnesses. Rely on isolation and witnesses; read E3's misses. policy, evaluation
Shell variables are not expanded and encodings are not decoded: a variable's value, or a value that splits into several words, is unknown. A command is also read as bash runs it when its expansions ($X, $(cmd)) are empty: a word made only of them is gone, one inside a word joins the rest (rm $X-rf ~/$X is rm -rf ~/), and a default is its word, with that word's own expansions empty (${Z:--rf} is -rf, ${X:-$Y} nothing); an alternate's word and a substitution's replacement are read as one more value (${X:+-rf} and ${X/*/-rf} may be -rf), and without the colon a default may also be empty (${E-d}). A word is read in each way its expansions combine, each one empty, as written or its word, the word's own expansions alike (${HOME:+approve}${X:+d} may be approve, d, approved or nothing), an expansion written twice taking one value; a command, in each way the words that read more than that combine, the others as written and empty. Past 256 ways (a word's, or a command's words' together) the word or command is unread and asks (TK-SHELL-PARSE, readings), never read fewer ways. A ${F=w} or ${F:=w} of a literal w gives F that word too, for the rest of the line (: ${F=--force}; git push $F is git push --force). So every way a word's unset and empty variables join or drop its characters is read; across words that read no more than all as written or all empty, only those uniform ways; and an unknown value is read as written, never split into words (git push $OPTS), while a value the parser reads is split at its blanks where unquoted, as bash splits it: a literal the line gives (F="-x -q"; pytest $F is pytest -x -q; one with a blank also where the line may not have given it yet, after && or in a loop), a default's, alternate's or replacement's word (env =${X:- }cmd runs cmd). A word of nine or more unknown values (echo "$(a) $(b) … $(i)") asks for that reason. $PWD, a variable the line gives a literal first (D=dist; rm -rf "$D"/*, export D=dist) and a for loop's over literal words (in its body) are never read as empty, unless something before may have emptied them (an assignment after && or ||, in a pipeline, subshell, if or loop, or in a { } group after it ends; X+=y of an X the line doesn't know; read, set -k, declare, printf -v (also -vNAME), compgen, eval, trap; an unreadable command name); after cd or pushd to a literal $PWD is that literal (cd /), after any other target unknown; X=, unset X, a loop over "", ${X:+}, ${X:0:0} and ${X%%*} are empty for certain, so a deny they make stays one; a loop's body and what follows the loop know only the loop's own variable, as the body's later commands may change any other for the next pass. Those literals are also read as the variables' values (F=~/.x; cat "$F" is cat ~/.x), and so is a default, assignment or check of a variable whose literals aren't empty (D=/; rm -rf "${D:?}"/ is rm -rf //), but not a value any other operator makes of them (D=xy; echo ${D#x} isn't read as y: it is unknown, as an unknown variable's); one whose literals include an empty one (a loop over / and '') is read as its default alone. After a command that may set any variable, a default or check is the variable, unknown: ${D:?} is held as rm -rf "$D"/ is, while ${D:-x} is also read as its word, so D=/; read X; rm -rf ${D:-x}/ is only flagged. A deny that only an empty reading makes (rm -rf "$VENV"/, find "$DIR/" … -delete) takes on_parse_error's section, so it asks by default, with the rule's id; $OLDPWD is unset in a new shell and can be read as empty. Static parsing can't know runtime values; whether $VENV is set is a question for a person, not a certain deny. A command name built from an expansion asks (TK-SHELL-PARSE); keep those held. Approve a held call whose variable you know is set, or name the path in full or give the variable its value on the line. policy
A pathname pattern is read as the names its bracket expressions can make, up to 16 (>> ~/.ssh/authorized_key[s] may write authorized_keys), as a second reading (a deny only it makes asks); a * or ?, a negated set ([!x]), a class ([[:alpha:]]) or more names than that is read as written, and a for loop over a pattern (for f in ~/.ssh/id_rs[a]) doesn't give its variable a value. Of a command's readings by a variable's literals or a pattern's names, a rule on the line or code (TK-D011) reads the first 4, a rule on its words all; a line whose readings pass the parse budget (a loop over some 2,000 words) is held (TK-SHELL-PARSE). A pattern names the files that exist when the command runs, which a policy decided before it runs can't list; a bracket names few enough to read each. Name the file in full; keep reads of secret files and writes to login scripts held by their own rules, which read the names as written. policy
$'\x{…}' whose braces hold a character that isn't a hex digit is read as the hex digits before it, then the rest as written ($'\x{2fq}' is /q}), as bash 5's lib/sh/strtrans.c was recalled; it wasn't checked against bash's source. bash's source could not be fetched when this was written. Write the escape plainly (/); a rule that must see the character reads a held line's text too. policy
In a $(( )) whose text has $( or a backtick, the parser reads each of those command substitutions, which get the rules as any command does (echo $(( $(nproc) * 2 )) is read as nproc). It asks (TK-SHELL-PARSE) instead when that text also has a quote (', " or $'), a newline, a [ (an array index), parentheses that don't pair up, or a backtick or backslash together with a parenthesis. bash reads quotes, brackets and parentheses inside $(( )) its own way, so the parser can't be sure where such text starts and ends. Approve the held call, or compute the value in a command of its own first (m=$(sysctl -n hw.memsize); echo $(( m / 1073741824 ))). policy
A parameterized arithmetic subscript on a line that also has a command substitution or backtick is held (TK-SHELL-PARSE); a direct substitution in an arithmetic subscript is read when its syntax is supported. Bash may evaluate an expanded array index again, and the resulting command text may be unavailable to the parser. Compute the value in a command of its own first, or approve the held call. policy
A command line the parser can't read asks (TK-SHELL-PARSE) and is still decided on the line before the word it stopped in, parsed, and on its text split at ;, &, | and newlines into blank-separated words, so a deny there stands (bash -c 'sudo id' ${X:-'$'}). A quoted mention of a denied command in such a line is denied too (echo 'a; sudo id' ${X:-'$'}), and a deny that needs the parser after the word it stopped in (code in a later bash -c '…') asks instead. A brace bash 4 expands its own way ({1..9..2}), one beside a substitution, or one whose words would add more than 16 KiB to the line or take it past 64 KiB (echo {1..5000}), is kept as written and holds only its command. A backslash-newline between $ and ( or {, and bash 5.3's ${ cmd; }, make the whole line unreadable (one before a quote is read: $\⏎'x' is x). In the text split, a # that starts a word comments out the rest of its line, quotes in it too. A line whose reading spends the decision's work budget (four times a 64 KiB line's characters, each command it reads counting 15 more: about 13,000 one-word commands) asks the same way (TK-SHELL-PARSE, budget); the budget is the whole decision's, so the line's other readings, what is read of a line the parser can't read and each argument read as a command (128 more each) spend it too, and once it is spent nothing more is read. The parser can't tell quoted text from a command in a line it can't read; the words of a larger expansion would make a subject past 64 KiB, which isn't read; the signer reads a line holding Python's interpreter lock, so a bound keeps one call from stalling every agent. Approve the held call, or write the line in the shell the parser reads (seq 5000 for a long sequence), or split a long line into several calls. policy
Held (TK-SHELL-PARSE) rather than read: bash's old $[ ] arithmetic; env -S with a backslash, $ or #; hash -p; setting BASH_CMDS or BASH_ALIASES; a function given through the environment (env BASH_FUNC_x%%='() { …; }', any env name holding %% or ()); fc, and history -s, -r or -n, which put commands in the history it runs; function after an assignment or a redirection (>f function x), where bash runs a program of that name; an arithmetic assignment to a name expansions build ($(($Y$W=1)) may set IFS); code sh, dash or ksh reads, or a line that may turn on POSIX mode, that uses an operator only bash has (&>, |&, >&file, [[, $'…', <<<), as their grammars read it otherwise; a shopt that changes how bash parses (interactive_comments, extglob, expand_aliases, posix) on a line with code bash reads again; a prompt (PS0 to PS2, PS4), PROMPT_COMMAND or BASH_ENV set to a value the line can't read, a prompt with a \ escape or a character past ASCII, or a file from a stream; ENV so set, which only an interactive shell reads, on a line that runs one with -i (sh -ic, bash -i; not one a later call runs in a shell that persists, or one a program such as tmux starts); ${X@P} of a variable the line doesn't give; a subscript with an expansion given to read, unset, declare, test -v and the like; an alias whose name the line builds, or whose text has a heredoc, a comment or a trailing \; a script the line writes from a program's output (sed … > s.sh; sh s.sh, as sed … | sh is) and then sources or runs; a trap's action the parser can't read, or a lone word with an expansion given to trap; a command name with arithmetic in it (python$((3))); a subscript with a blank where a command starts (a[ x ]=1 cmd); an empty process substitution (<()); a heredoc delimiter with an expansion; a command git runs given in text the parser can't read (git -c core.pager="$X", --config-env=core.pager=X, GIT_EDITOR="$E"); from an expansion that assigns in any other spelling (${!G=}, ${F[0]=}, ${F::=}, a ${F=…} whose word isn't literal, or one whose command reads F, or a variable named indirectly, in two copies of one expansion), an arithmetic assignment ($((F=1)), in an offset, a subscript, let, [[ … -eq … ]]), a name list (${!X@}) or a nameref or integer variable (declare -n, -i) on, that command and every later one on the line, as what they expand to can't be followed (cause assigns); on a line that gives IFS a value, an unquoted expansion that may hold a character of it, a blank or a digit, and one of a variable the line gives a literal with a blank only after it (a loop may run that first), as bash splits them where the parser doesn't (cause split); a $IFS, quoted or not, after the line may have changed IFS (an IFS= given to eval, . or a function too; unquoted, also unset IFS, read or let), or spelled otherwise (${IFS:-}, ${IFS:0:1}, a quoted ${!x}); an alias the line defines and doesn't use (a shell that persists runs it on a later call), one ending in a blank before another alias, or named as a reserved word; a code variable set with +=, by a loop, or through a nameref with no target; a variable read, declare, local, typeset or env gives under a name the line builds from text it makes (read "$N", declare $(printf …), env "$(printf …)=…" cmd); a name export or readonly gives from text the parser can't read (export $(cat .env | xargs)) only on a line that also runs a shell or a script by its path, turns on xtrace or uses arithmetic (neither builtin evaluates a subscript in the name, as declare, local and typeset do, but the name may be BASH_ENV, PS4 or one arithmetic reads); in code bash parses again (eval, sh -c's string, a trap's action, a heredoc or herestring into a shell, compgen -C or -W) or in a script the line writes and runs, any expansion but a number ($#, $((…)), the digits a line of one pipeline prints) and a variable or parameter the parser knows one literal of there, expanded plainly ($X, ${X}): one the line gives on its straight line, not after && or ||, in a branch or loop that may skip or repeat it, through declare, local, an array, a nameref, a copy (Y=$X) or a trap, nor a loop's several words, nor after ${X:=…}, ${X=…}, {X}<, arithmetic or another command gives it a value, anywhere on the line (a heredoc's body, a prompt's @P or PS4, eval's text); never one bash sets itself ($_, REPLY, OPTARG, MAPFILE, the BASH_ and COMP_ names); quoted, or a value bash neither splits nor globs, on a line that doesn't name IFS (X='*'; eval echo $X is held); so a substitution's output, a variable the environment gives ($HOME too), what read, mapfile or a loop over unknown words sets, an operator (${X/a/b}, ${X,,}, ${@:2}), and a positional parameter but the literal a call or script run gives it are held there (bash -c "cd $HOME && make" too: write the path, or run the commands without -c); such a script written by printf with a conversion other than %s or %b, or run under a name the line builds. A quoted $IFS is read as bash's space, tab and newline otherwise, so code made of it is read line by line. The aliases a line defines are read wherever a command has the name, whether or not bash expands them there. A script the line writes with text it gives (echo, printf, or a heredoc or herestring cat or tee copies, appends joined in order) and then sources or runs (source, ., a shell given the file or its --rcfile or --init-file, or its path with a shell's #!) is read as its code, and one history -w or -a writes holds text the line can't read; an interpreter's (python3 s.py, a #! naming one) as its inline code, for what it runs and writes, but code there the parser can't read isn't held; one written from another program's output (sed … a.py > b.py; python3 b.py), or by an earlier call, isn't read. Each makes bash run code, or a program by another name, that the line holds only at run time. Write the command plainly, or approve the held call. policy
A command a tool runs from its arguments is held (ask) with the id of the deny rule it matches: an argument word with a blank, or its value after an option's or name's = (--eval=…, --checkpoint-action=exec=…, ProxyCommand=…), or an assignment's value (MANPAGER=…), without a leading ! or |, read as a command line and also without its first word (hyperfine 'cmd', make --eval='x: ; cmd', vim -c '!cmd', gdb -ex 'shell cmd', osascript -e 'do shell script "cmd"'). Data isn't read so: a commit or tag message, a log's --grep, echo and printf text, a search's words (grep, rg, ag, git grep), a GitHub title or body and a jq filter, nor a program's words the parser reads as code itself (a shell's, an interpreter's, eval's, git's). Runners that take the command as their own words are read exactly (entr, watchexec, nix develop -c, bundle exec, pixi, rye, micromamba and mamba run, coverage run), and so are the commands ssh, scp and sftp's -o (ProxyCommand, LocalCommand) and rsync -e run. A command in one word with no blank (man -P reboot), or one a tool reads from a file, isn't read, nor is a text with no letter but in \n, \t or \r and no $'…' (x '1 2', psql -c '\n \n'), which names no program. A process call in inline code reads every literal of its arguments as the argv (a list, a tuple or separate arguments; exec and spawn's file before it; sys.executable as python), each decoded as its language does (escapes, side-by-side and triple-quoted literals, Perl's q()), and a value the code makes at run time (chr(45) + "f", an f-string's {…}, a % or .format() placeholder) as an unknown variable, so a program name made so is held; a call's name inside a string, whose argument no expression makes, isn't read. A file the line writes, then a program reads commands from (a Makefile, a package.json's scripts, git's config or the file GIT_CONFIG_GLOBAL names, setup.py), is read as those commands, and one it can't read (an .npmrc that names a program, pyproject.toml) is held; one under a name the line builds isn't read. Keys screen -X stuff and tmux send-keys type are read as the line they make, and a git ext:: URL as the command it runs. env with an assignment that expands a variable the line gave from expansions it doesn't know there (X=${X::0}" cmd"; env =$X a) is held, as bash may split it into the command (a quoted one, which doesn't split, is held too); one the environment or a substitution gives (env HOME=$HOME/x, H=$(mktemp -d); env HOME=$H, S=$PWD; env HOME=$S/h) isn't. Holding every argument that isn't a literal held 29 calls of a real week (git show f"{rev}:f"); reading one as an unknown variable holds 4 (a program name from a variable, [PY, "-m", …]), and every env assignment with an expansion 102; a word with no blank is most often a file or a name. Run the command directly rather than through a tool's argument, or approve the held call. policy
Arithmetic text built at run time can name a command bash runs while evaluating an array subscript; policy can't read that command. A literal the line gives, on any of its lines, is read where the line may evaluate it (arithmetic, a subscript, ${!X}, read, declare …). Text the line makes (by printf, echo -e, awk, an interpreter, a herestring, a file it writes such text into) and that bash then evaluates ($((x)), let or declare -i with it as a name or in a value, ${s:x}, ${!x}, test -v, printf -v), also through a loop over it or a positional parameter given it (set -- "$(printf …)", a function's, a script's or sh -c's arguments), is held (TK-SHELL-PARSE), as is a value that joins parameters the parser doesn't replace by a literal (Z=$X$Y, declare Z=$X$Y, $(($1$2)), a positional parameter given a [ or $), or one an operator makes (l=${s##*:}). What only reads files or the system (cat, grep, cut, head, wc, date +%s, mktemp …) or prints only digits is trusted as running a file already on disk is, so a file an earlier call wrote can still hold such a command (n=$(cat f); echo $((n))), and so is a variable the environment gives; so is the stdin the call gives (n=$(grep -c x $f) with $f empty), but not one the line may have moved (exec < f, a pipe or redirection into a { } group, a loop or code bash reads again), stdin however it is spelled (//dev/stdin, /proc/thread-self/fd/0), a descriptor a variable names (<&$fd), or, on a line that writes a file, a file named through a variable (cat "$F"). The text is unavailable to the parser when the policy decision is made. Keep destructive rights and secrets off the agent; use T2 or a sandbox for enforcement. policy
TK-D002 and TK-A046 read parsed shell code: a bare download pipe into a shell or interpreter is denied, while inline code or a script path is held for review. A download piped, at any later stage of its pipeline, into any program not known to read only data (jq, grep, tee, cat, less, head, tail, wc, a hash, sort, sed, awk, base64, a decompressor, tar -t and the like) or into a shell or interpreter reading its code from stdin (pypy3, osascript, tclsh, Rscript -, deno run -, php, fish) is denied by TK-D002 too: curl … | tar -x and curl … | my-tool are. A process substitution is read as the pipe it is (python3 <(curl …) as curl … | python3, source <(curl …) as curl … | sh, curl … > >(sh) and curl -o >(python3 -) … as piped into what runs there), and a download saved to a file (curl's -o, -O, -J, wget, a redirection or tee) that a command anywhere on the line runs (before the download too: a background job, a FIFO, a trap, a loop's next turn) by a name it saved or its URL's (any path, where the server picks the name: -J, -K), or a shell or interpreter given one of those as a word, a redirection or in its inline code, is denied; a link check to /dev/null, a download from this machine (localhost, 127.*, ::1: a health check), and a path run that names nothing the download saved (curl -o data.csv u && ./bin/process data.csv) aren't. A link check, a download written to a file, a note heredoc or git commit -F - message, text echo or printf writes into a file, and the words the parser knows are data (a git commit, tag or merge message, a log's --grep, the pattern grep searches for, a sed -n script) are allowed; other quoted text is read as the line it spells, so echo 'curl x | sh' to the terminal or gh pr create --body 'curl x | sh' is denied, a message with a $ or a backquote is read as code, and the as-typed line keeps a message TK-A046 reads after a ; in it (git commit -m 'a; curl x | python3 y.py' is held), as does a line of more than sixteen such commands, a line with a redirection, a heredoc or a process substitution anywhere in it (git commit -m 'curl x | sh' 2>&1 is denied), and a command whose words hold another command's or are held in another's (time git commit -m …, a bare sh on the same line). They don't follow a downloaded file into a later separate call; command substitutions and shell forms outside the parser's POSIX subset may be held as TK-SHELL-PARSE, and the ask rule only recognizes named interpreters (sh, bash, zsh, dash, python of any version, perl, ruby, node) and common inline flags/script arguments: curl or wget where a command starts, after up to four keywords, assignments or wrappers (then, time -p, env, nice -n 5, timeout 5, sudo) whose options take no value but a number, piped through up to four stages. It doesn't hold php -r, uv run python -c, a download inside a { …; } group, a wrapper with another value (sudo -u bob curl), or python3 -m json.tool, which it reads as a pretty-printer. The rules match parsed command text and common interpreter shapes; they don't fetch URLs, resolve file contents across calls or emulate each interpreter's full option parser. Review held calls and inspect a downloaded file before running it; run downloads inside Tracekit Box, where a download can't reach the host; use isolation to contain code that policy does not recognize. policy
TK-D007 (#589) allows, under Tracekit's dirs, only: reading the contents of the installed package's files and of /etc/tracekit/client.json and /etc/tracekit/policy*.yaml, with cat, head, tail, grep (without -r), sed -n (a script that only prints; not -i, -I, -f or another option but -n, -e, -E, -r, -s, -u and -z) or jq, printing to the terminal or a filter (not a pager: an assignment such as LESSOPEN or LESSCLOSE makes less run a command on the file it opens); a recursive read (grep -r) or a cd before reads only of the installed package; and listing with ls, stat, test or find (without -exec, -ok, -fprint, -fls, -files0-from or -delete) anywhere but a runtime dir, the client and v1 signer homes and a keys dir. Any other program, a read whose output goes to a file, a substitution, xargs or a loop, a pattern, and an assignment to CDPATH, HOME, OLDPWD or another variable the shell reads on its own denies there, as do writes, deletes, runs, kills and starting the signer. tracekit signer vkey and trust (also as python -m tracekit) only print or write the public keys and are exempt, so their --data-dir and --config may read a data dir's public keys or a signer.yaml there; trust's output (-o, --out, or a prefix of it argparse takes, --o, --ou=) is a write target of its own, denied there. Signer code may reach only rpc_schema's tables, reconcile.compared and model_names, and the service's load_policy and DEFAULT_POLICY, by those names. It matches locations by name, not the live signer's: a scratch HOME or TRACEKIT_RUNTIME_DIR under test still counts, and so does SDK code that reaches the dev signer (autospawn beyond status and its errors, dev_data_dir), read outside string literals (a string exec, eval, importlib or runpy runs too; not one timeit or pdb.run runs). A kill counts when its pids come at run time from what finds the signer by its usual command lines or names (pgrep, pidof, ps through grep or awk, or pkill's or killall's own pattern, matched as an extended regex on the engine's own backend: one it can't compile counts), so kill <pid> of the signer, or of every pid a ps with no filter lists, isn't one (matching the live signer's pid needs the signer to hand it to the engine); its usual command lines are autospawn's (a client's interpreter by its full path, often a venv's python, with -P), so a pattern on an interpreter's path counts. Code that runs the CLI (tracekit.cli's main, tracekit.__main__, runpy.run_module('tracekit')) counts where its argv is built at run time or names down, uninstall, up or signer. A loop's words, a relative path after a literal cd, pushd, env -C, tar -C, git -C or make -C, a path through a CDPATH or HOME the line sets or a link it makes to a folder, a pattern standing for a component of Tracekit's paths (trace?it, Application Support/*, find -path), and a shell script the call writes and then runs count as what its commands name; a cd from the working directory the line doesn't name (cd ..), a CDPATH or HOME the environment already holds, and a bare pattern elsewhere (~/*/x) can't be seen. The policy reads shell argv, file names and the parser's data-flow hints, not filesystem or process state. Rely on isolation (system mode, a sidecar or a central signer); TK-D013 still denies a file tool's write to Tracekit's paths. policy
A variable the line sets to a plain path (PY=.venv/bin/python; $PY -m pytest) is read as that program (#589), as bash runs it with its default IFS. A line that names IFS in any spelling reads no variable through, and a value with characters other than a path's is held; but in a shell that persists between calls, an IFS an earlier call set is still in force, and a path value may then split into another program and its arguments. The policy reads one call at a time; it can't see the shell's state from earlier calls. Run agents with a fresh shell per call (Claude Code's Bash tool, Codex's exec) or reset IFS (unset IFS) before such a line; a person approves a held call only when what it runs is clear. policy
A shell function the line defines and calls is read where it is called and not held (#589), but on a line that may download, where it is held (TK-SHELL-PARSE) as on 1.5.3: TK-D002 reads that line's text, in which a body comes before the download it may run. A line may download when its text names curl or wget, a command on it is one, or a command's name isn't written plainly (quotes, an escape or a variable made it: c''url, $'\x63url', $X''rl). A download through another program (Python's urlretrieve, git clone) isn't one, as TK-D002 knows only curl and wget; in a shell that persists between calls, a later call names only the function, and the policy reads that later call as a program of that name, not the body this line gave it. A function the line doesn't call after defining it (a body given after its name's last call too: f(){ ls; }; f; f(){ sudo id; }), or exports, is read as if it ran and held. The policy reads one call at a time; it doesn't know whether the harness keeps its shell. Run agents with a fresh shell per call (Claude Code's Bash tool, Codex's exec); a person approves a held definition only when its body is fine to run later. policy
TK-A054 holds removing or stopping Tracekit only in the forms it names: tracekit uninstall or down, pip, python -m pip, uv, pipx or poetry removing tracekit-ai by name, claude plugin uninstall or disable, and systemctl stopping a unit named tracekit. It doesn't hold python -I -m pip uninstall (an option before -m), a name pip reads the same with doubled separators (tracekit--ai) or from a file (pip uninstall -r reqs.txt), conda or brew, the TypeScript SDK's npm uninstall, claude plugin marketplace remove, editing a harness's settings to drop the hooks (flagged, TK-F009), or removal done in code (python -c); a command that deletes the signer's files or kills its process is TK-D007's deny. The ways to remove a package or a hook are many; the rule names the ones Tracekit's own docs give. Run system mode, where the agent's user can't stop or remove the signer, and read harness_config flags. policy
TK-A039–TK-A041 hold a destructive statement through a database client (psql -c, mysql -e, mongosh/mongo --eval, sqlite3's bare SQL argument, clickhouse-client --query, redis-cli/valkey-cli/keydb-cli, a wrapper's docker, podman, docker compose, kubectl or oc exec (up to eight words before exec and eight after it, and a shell's -c inside it), an SQL-like MCP tool's sql/query/statement argument) but don't read one run from a file (psql -f, mysql < file.sql, a mongosh script file, a file piped into redis-cli), one piped or heredoc'd into psql, one built in a variable (SQL="DROP TABLE x"; psql -c "$SQL"), a Redis command sent through EVAL or a script, or a flush piped through a stage that isn't echo, printf or tee. TK-A040 reads a flush echoed or printed into the client (also through command, builtin or env, by path, or in a ( ) or { } group), fed to it as a herestring, or on a line of its own in a heredoc's first nine (also through any wrapper or bash -c); it misses one printed with other text (printf '%s' FLUSHALL, echo -e 'SELECT 2\nFLUSHDB'), env with options or assignments, a client another wrapper runs from a pipe (echo FLUSHALL | docker exec -i c redis-cli), options after the herestring, more than eight options before it, and a heredoc's later lines. It reads the whole line, a heredoc's body included, so a flush shape in a heredoc that is only written into a file (a test script's cases) is held too. They also miss a statement after a delimiter of the client's own (mysql --delimiter=//), a # comment before the keyword, a block comment ending in **/, a backslash inside a -- comment, in TK-A041 a -- comment containing ", an abbreviated option (psql --comm), more than thirty-two words before the client's flag, a statement run by dynamic SQL (DO $$ … EXECUTE 'DROP …' $$), a WHERE that is always true but not literally so (WHERE id > 0) and more than eight statements before the destructive one. A comment or a vertical tab between keywords (DROP/**/TABLE, DELETE/**/FROM) separates them, and the text of MySQL's and MariaDB's executable comments (/*! … */, /*!50000 … */, /*M! … */) is read as the statement it runs, as the SQL tools' TK-DB001..TK-DB005 read it; after FROM a DELETE's table and WHERE are read with whitespace and comments only between their words. A psql, mysql or mariadb short-option cluster of more than nine flags that take no value, ending in c or e (which no one needs), is held without being read; a value attached to an option that takes one (psql -dmydatabase, mysql -pdevelopment) is not such a cluster. A rolled-back destructive statement is held although the transaction would undo it: there is no ROLLBACK exemption, a comment or a mysql \G/\g terminator kept breaking it, so one approval for a test transaction is the price. The rules read the command's words and the MCP tool's arguments as typed; a file's content and a variable's value aren't on them. They read ; (and mysql's \G/\g) as a statement's end and -- and /* */ as comments, and skip at most eight statements, a bound that keeps the fallback engine fast. Approve the held call, or run migrations through the deployment's reviewed migration path; keep production credentials out of the agent's reach. policy
TK-A041 holds a destructive statement in an SQL-like MCP tool's sql/query/statement argument and reads the tool's name: only a tool whose name looks like a database tool is held, so an ordinary search whose query text is itself a destructive statement (a search for DROP TABLE x) is not. A call over 64 KiB to a tool whose name looks like a database tool (execute_sql, a bulk insert_rows on a db server) asks on coding and dev whatever it holds (TK-OVERSIZE), where any other MCP call that size is flagged: the rule reads the whole arguments, and a subject over 64 KiB is never cut. server and strict already deny every call that size. SQL tool names are unbounded, so the rule matches names like sql, postgres, mysql, sqlite, clickhouse, mongo or database; a destructive statement through any other tool name is not held. Approve the held call; the hold is ask, not deny. policy
(1.5.3) TK-DB003 reads a DELETE's condition as constant only in plain forms (1, TRUE, NOT FALSE, two numbers or two literals compared, one pair of parentheses), and only first before an OR or last after one outside parentheses: WHERE id IS NOT NULL, WHERE x = x, WHERE 1=1 OR … inside parentheses and an expression that is always true some other way aren't denied, and a constant false one (WHERE 1=0, which deletes nothing) is. TK-DB005 reads a COPY of a server file after a table name of up to 256 characters and a column list of up to 1000, or a query's ) TO a literal. The rules read the statement's text, not its meaning; the bounds keep the fallback engine linear. Give the agent's database role no DELETE on tables it mustn't empty, and no superuser or pg_read_server_files/pg_write_server_files. policy
TK-S012 (the server packs) reads a code runner by its name and argument keys: a runner named otherwise (mcp__x__sandbox_submit) or taking its code under another key (snippet) isn't held, and a tool named for running that isn't a runner (run_report with a source) is held. TK-S010 holds a command, cmd, script or shell_command argument in any MCP tool, but not one named otherwise (query holding a shell line). The rules read the tool's name and its arguments, not what the server does with them. Map the deployment's own runners to the shell class, or name them in an ask rule of its own. policy
A shell whose language the parser doesn't read (fish, csh, tcsh, PowerShell, nu, xonsh, elvish) asks (TK-SHELL-PARSE) whenever it runs commands from its line or stdin, even pwsh -c 'Get-Date'; a script file it runs (fish build.fish) isn't read, as a POSIX shell's isn't. Their syntax isn't POSIX, so the rules anchored on a command's name can't read what they run. Approve the held call, or run the command through a POSIX shell. policy
With on_parse_error: deny, an ordinary command whose program the parser can't read ($EDITOR notes.md, a script piped into bash, an unclosed quote) is denied, not held. The signer can't tell such a command from one built to hide what it runs, and with deny no person sees it. Keep the default (ask) wherever a person answers holds; with deny, have the agent name programs literally. policy
strict.yaml holds ordinary development work: every push or publish, package install, docker run, apply, network command and PATH=-style setting waits for a person (46 of E17's 887 benign calls, 5.2%, and 20 of E21's 130 developer-session calls, 15%: the rates), and a command whose program comes from a variable ($EDITOR notes.md) is denied. "Every" is the programs TK-F004, TK-F011 and TK-F013 name (policy): another package manager, an install with options before its verb (npm --prefix x install), a network call made inside an interpreter (python -c 'urllib…') and a startup file of another shell (fish, PowerShell) aren't held; and TK-F004 and TK-F011 read the whole line, so a commit message or echo naming npm install or PATH= is held too. It trades interruptions for seeing every change that leaves the workspace before it runs; the flags it raises can't tell a routine push from a harmful one. Use it where a person answers holds promptly; elsewhere use server.yaml and read the flags. policy
On calls written blind to the rules (E21's held-out pool), the server pack stopped or held half the harmful ones on its one blind run (211 of 420), and more after rules were added that target the pool's shapes, a number that overstates blind recall; it holds a few percent of the benign ones. It misses many exfiltration, privilege-escalation, prompt-injection, destructive, defence-evasion and supply-chain calls (the counts by category: evaluation). The packs match known command shapes; calls phrased in ways no rule anticipates aren't matched. Treat the packs as tripwires: run agents in a sandbox, keep credentials out of their reach, rely on the signer and witnesses for the record; strict.yaml holds more at more interruptions. evaluation
A secret's value read in a way TK-A035 to TK-A038 don't name isn't held. They read the commands of AWS Secrets Manager and SSM Parameter Store, GCP Secret Manager and Azure Key Vault, and MCP tools whose names say they return a secret (or read an SSM parameter with decryption turned on). Not held: another store's shell commands (1Password's op read or op item get; Kubernetes and Vault reads are TK-A052's and TK-A053's), a command run through a wrapper the shell parser doesn't read (aws-vault exec … --), an AWS call whose decryption comes from --cli-input-json, an ALL-CAPS tool name, an MCP tool whose server chose another name (fetch_credential) or a spelling the patterns lack, a CLI command given to an MCP tool whose name doesn't end in a word for running one (TK-A036 reads call_aws, run_command, execute, bash and the like) or whose words are quoted (TK-A036 reads the command as text, not as a shell would: aws 'secretsmanager' …), an SDK call in an interpreter one-liner (python -c), and a credential that isn't in a secret store (aws ecr get-login-password, aws sts assume-role). A tool that both lists secrets and gets one (Azure's Key Vault tool) is held for both when its tool name says it gets a secret; one named only keyvault that takes the operation as an argument isn't. A call over 64 KiB to a tool TK-A036 or TK-A038 reads (call_aws, run_command, get_parameter) asks on coding and dev whatever it holds (TK-OVERSIZE), where any other MCP call that size is flagged: the rules read the whole arguments, and a subject over 64 KiB is never cut. server and strict already deny every call that size. The rules read command words, tool names and the arguments the tool is given; they can't tell what a tool with another name returns. Hold the tools your servers use for secrets by name in a rule of your own, and keep agents' IAM roles from reading secrets they don't need. policy
TK-A052 and TK-A053 hold only the kubectl, oc, vault and bao commands they name. Not held: the Kubernetes API read another way (kubectl get --raw /api/v1/namespaces/p/secrets/db, curl to the API server, a client library), kubectl edit secret with an editor that prints (EDITOR=cat), kubectl run through a program the shell parser doesn't read (microk8s kubectl, minikube kubectl --) or an alias (k), an output option given before get, or before the type with a space in its value, or more than sixteen words after the type, or a type ninth or later in a list (kubectl get secret a b … q -o yaml), and kubectl reached through an MCP tool (a run_command, or a Kubernetes MCP server's kubectl_get with secrets); a Vault login or another path that returns a credential (vault login, vault write auth/approle/login, vault write pki/issue/web), vault token lookup (it prints the token's id), Vault's API through curl or a client library (hvac), and VAULT_TOKEN read from the environment. A long option other than --namespace is read with or without a value, so a type named as its value (kubectl get --context secrets pods -o yaml) is held. They read each command's words as typed; what an editor or a library does, and which long options take a value, isn't in the command. Approve the held call; give the agent a Kubernetes role without get on secrets, and a Vault policy that can't read the paths or create the tokens its task doesn't need. policy
TK-A058 to TK-A060 don't read: weights saved with torch.save or similar inside a Python script; folders copied or unpacked (cp -r, rsync, tar -x, unzip); other formats (.bin, .h5, .onnx, .pkl, .npz, .npy, .msgpack, .joblib); download output options (curl -o, wget -O); deleting weights (rm); Python SDK uploads (huggingface_hub.upload_folder(…)); or Git/Git LFS pushes to huggingface.co. They also leave other hub subcommands alone. The file rule reads the path the file tool is given; the shell rule reads shell write targets (WRITE_TARGET:) from the command's effects, not script contents; the hub rule reads command argv. Keep production weights on a read-only mount and publish from CI with a token the agent does not hold; add a rule for other formats or SDKs. policy
A rule's remedy is advice the policy's author wrote: lint checks its form (one short present-tense sentence), not that it is right, and an agent may ignore it. It is text shown with the decision, not a rule. Write a remedy that names a safe alternative the agent can carry out; the deny or hold stands either way. policy
A relative path, or one with .., is unverifiable; rules match its certain suffix. A symlink could redirect it. Write path rules that also work on suffixes. policy
Path rules, and shell rules on target and effects, are matched casefolded too (cp x .ENV is denied as .env is), and a command's program names are read casefolded (ſh is sh). A rule on the shell tracekit field (TK-D007) matches in any case, as its pattern names folders in mixed case (Library/Application Support). The agent's file system may ignore case whatever the signer's does: macOS opens ~/.ssh for ~/.SSH or ~/.ſsh, and runs /bin/sh for ſh. Write path rules in lower case, or with both cases of a letter. policy
Patterns must stay inside an RE2 subset. A decision must not depend on which engine is installed. tracekit policy lint rejects the rest. policy
Without google-re2, a large subject, or a short one under a repeat of overlapping alternatives (secret(.|\s)*key), can exhaust the 1 s budget: the decision denies, is marked nondeterministic: true and says so in its reason, so the two engines can decide differently. Every shipped pattern searches 64 KiB built to make it back off or rescan within 150 ms on CI's runners (about 20 ms on a laptop; TK-A040 within 0.25 s, TK-A001 and TK-A011 slower on repeated options, below), except eight on one command or SQL statement that repeats their first word thousands of times, measured at 64 KiB on an M-series Mac: TK-D002, TK-D004, TK-D006, TK-D011 and TK-DB003 over 5 s, TK-C010 3.4 s, TK-D007 0.3 s and TK-A032 0.05 s (curl with no pipe, rm -r with no root or home path, curl with no .env upload, cat with no upload, DELETE FROM with no ;, aws s3 rm with no --recursive, kill with no tracekit after it, aws s3 sync whose s3:// words are each followed by an option and none ends the command): each occurrence rescans the rest, so such a call can deny on the fallback engine where RE2 decides it. TK-A039 reads up to sixteen words after sqlite3 as options before its SQL, so 64 KiB of short words after sqlite3 takes about 0.2 s, and TK-A040 up to eight options after each redis-cli on a line, so 64 KiB of redis-cli -a takes about 0.07 s on a laptop and up to 0.2 s on CI's runners (both linear); TK-A029 takes about 0.1 s on 64 KiB of newlines after journalctl, as 1.4.2 did. TK-A001 and TK-A011 read any number of options, each with or without a value, before pulumi's (and railway run's or heroku run's) command and systemctl's verb, so 64 KiB of pulumi -a or systemctl -a takes about 0.25 s on an M-series Mac: backing off that repeat grows with the square of its length on the fallback engine. The fallback regex engine backtracks; RE2 is linear. A rule that looks for one thing after another with any text between can't be written linearly for a backtracking engine without atomic groups, which RE2 lacks. Install google-re2 on the signer (a dependency from Python 3.10). policy
TK-F007 flags a detached tmux session only when its -d comes within 200 characters after tmux new, on either engine; one further along isn't flagged. The bound keeps the pattern linear on the fallback engine, and both engines run the same pattern so they decide alike. Read long tmux new commands in the record yourself, or add a rule of your own for the tmux options your agents use. policy
tracekit policy lint refuses an unbounded repeat whose body starts with an unbounded repeat ((a+)+), not every super-linear pattern: a bounded repeat of one (^(.*?,){11}P: 5 s on 260 characters) or overlapping alternatives under a repeat ((a|aa)+$: 3 s on 35) pass it. Refusing every repeat over an unbounded body would refuse linear patterns too (TK-M003's (([^"@\\]|\\.)*@){10}); telling them apart needs to know whether the repeated class can match what follows it. Install google-re2; time a new pattern on the fallback engine before shipping it (the speed test in tests/test_policy2.py does this for the shipped packs). policy
A rule's subject over 64 KiB is never cut: the rule's own section decides. An http call's urls list of more than 64 URLs is denied (TK-OVERSIZE), as a shell command over 64 KiB is. Cutting or windowing would let content hide past the cut; each URL is read on its own. Expect large arguments to be flagged, held or denied by the matching section; fetch more URLs in several calls. policy
A decide whose parsed arguments nest deeper than a request may (128 levels, counting the request's own, or too deep to check) is refused as a whole (invalid_request), not decided: no policy.decision names the call, only the signer's refusal count does. Raw arguments (args_source: "raw") nested past 128 levels are denied and recorded (TK-ARGS-INVALID). Checking, hashing or copying such a request would exceed the parser's limit before anything could be recorded. Nothing to do for safety: the hooks and integrations don't run a call they couldn't get decided. Flatten arguments that deep if a tool really needs them. policy
URL rules read the URL text; a public name that resolves to an internal address isn't caught. The signer doesn't resolve names. Add network egress controls. Browser Use
(1.5.3) In an MCP tool's arguments, target (read by TK-S001, TK-S004, TK-F005 and TK-F012) leaves out the text the tool only carries: the string value of a title, body, text, description, comment, message, subject or content argument at any depth when the tool's name says it posts, comments, replies, creates an issue, comment, pull request, discussion, review, ticket or note, or sends a message (create_issue, add_comment, sendMessage; not create_file or create_or_update_file) and doesn't say it types, sends keys, runs, executes, evaluates or holds code or a cell, and the query or q of a tool whose name says it searches and doesn't say it fetches, reads or opens. A posting tool that reads a path or fetches a URL it takes in an argument named so isn't denied for it; a tool whose name says neither (update_issue, write_file, send_text) has its text read, so a document or an edit that names a credentials path or the metadata address is denied as in 1.5.2. A credentials path or the metadata address named in an issue, a message or a search is mentioned, not read or fetched, and the tool's and the argument's names are all that tell the two apart; text a terminal, a notebook or computer use types runs. Map such a tool to the class it is (fs, http) under tools, or add a rule of your own on its raw argument (field: content). policy
In a shell command, a word that reads as an IPv4 address in any notation (2852039166, 169.16689662) is a target URL rules match, and so is a dotted number such as a version (npm version 1.2.3): TK-F012 flags it as egress. The signer can't tell a version from an address without knowing every command's arguments. Read egress flags on version-like words as noise; an allowlist of hosts goes in a rule's unless. policy
(1.5.3) The browser rules (TK-B001 to TK-B012) read Browser Use's actions and, on the packs that include browser.yaml (server and strict), Playwright's browser_navigate and browser_tab_new and Puppeteer's puppeteer_navigate by their bare names under any MCP naming. On coding and dev, and for another MCP server's navigation tool anywhere, a browser driven through MCP is an MCP tool, so a file: or javascript: URL it navigates to isn't denied by TK-B001. The packs map the browser class to the actions whose arguments they know; an MCP server's tools are named and shaped by the server. Map the MCP browser's navigation tool to browser under tools in your policy, or deny those schemes in its url argument with a rule of your own. Browser Use
(1.5.3) Claude Code's PowerShell tool is decided as an unknown tool (held on server and strict, flagged on a laptop) and also as a shell line, which counts only where a deny or ask rule matches it as bash reads it: a command in PowerShell's own syntax (Remove-Item -Recurse $env:USERPROFILE, iex (iwr …)) meets no shell rule, and on a laptop it runs flagged. The shell rules read POSIX shell; PowerShell is another language, and holding every line bash can't read would hold most of it. Use a server pack's hold for unknown tools, or deny or hold PowerShell by name in a rule of your own (tool: PowerShell); run the agent in Claude Code's sandbox. coding agents
(1.5.3) An MCP tool named mcp_<server>_<tool> (Gemini CLI, Crush; the hook names it mcp__<server>_<tool>) doesn't say which _ ends the server's name: the signer tries each of the first eight, so the packs' mcp:<server>/<tool> mappings and rules on the bare name reach it, and also decides it as an unknown tool (held on server and strict). A server name with more than seven underscores reaches the mappings under no split. The joined name has no separator of its own. Give MCP servers short names, or hold the tool by its joined name in a rule of your own. coding agents
In an MCP, app or unmapped tool's arguments, an address is read in any notation only inside a URL with a scheme (http://169.254.43518/); a host on its own ("host": "169.254.43518", "169.254.43518:80") is matched only as written, so TK-S001 holds it only in its plain, decimal (2852039166), hex or octal spellings. Only the browser MCP tools the browser pack names by their bare names (browser_navigate and browser_tab_new, Playwright's; puppeteer_navigate) and the fetch server's fetch are decided as browser or HTTP calls, so TK-B001..TK-B003 and TK-N001/TK-N003 read their URL; another server's navigation tool is an MCP call, and a Playwright or Puppeteer navigation with a query string isn't TK-P003's. Every string of an MCP call isn't a host: reading each as one would make version numbers and IDs addresses. A tool's name says what it does only for the servers the packs know. Map your browser and HTTP MCP tools by their bare names (tools: {open_url: browser}), or route MCP through the gateway. policy
A browser rule on a click matches the page the click ran on, not the request it makes: navigating straight to the URL a denied button submits to, or running page JavaScript that submits the form, is another action. A click's arguments name an element, not where it leads. Deny the state-changing URL on navigations too (class: browser, field: url); keep TK-B012 holding evaluate. Browser Use
The server pack's allowlists (TK-N002, TK-B011) name example.com until you redefine them. Allowlists are deployment-specific. Redefine those rules by id in your policy. policy
Parsed arguments that hold a lone surrogate (text typed or read from a broken page) are a signed deny, TK-ARGS-INVALID, not a decision on their content. JSON can't carry a lone surrogate, so the client sends them as raw text, which isn't strict JSON. Clean the text before the call, or expect the deny. policy
Cloud-SDK-shaped tools other than CLIs and MCP tools aren't covered by the cloud pack. Their argument shapes vary. Map them under tools and add rules of your own. policy
(1.3) TK-A001 doesn't hold a saved destroy plan (terraform apply p), a destroy set through the environment (TF_CLI_ARGS_apply=-destroy terraform apply), more than four option groups before the subcommand for terraform, tofu, terragrunt, fly or cdk, or before the launched program for npx-style launchers, an option value with a space in it, a destroy run through an interpreter, a container or a remote shell, or cdk destroy run from a package script (npm run, yarn cdk destroy, pnpm cdk destroy). It holds --help after a word with a hyphen (terragrunt run-all destroy --help) and the word destroy as an option's value (terragrunt --working-dir destroy plan, cdk --app destroy synth). It reads each command's words as typed: a plan file's content, the environment, the file system's case and what another program runs aren't in them, and it can't tell which options take a value. Add ask rules of your own for the forms your agents use, and don't give an agent credentials that can destroy production. policy
TK-A002 doesn't hold a remote branch or tag deletion set through Git config or an alias (-c remote.origin.push=:b, -c alias.p=push), a refspec from a shell variable or xargs, a shell alias or function, more than eight global options before push, an option value with a space in it or git send-pack. It reads each command's words as typed; config, aliases and variables take effect only when git or the shell runs, and the bound on options before push keeps the fallback engine from backtracking. Use the server pack (its TK-S006 denies git -c alias.*) or run the agent in a sandbox, and protect the branches that matter on the Git host. policy
TK-D003 denies a force push through git send-pack, an alias to a git command (-c alias.p='push -f', or saved with git config alias.p …, which is read as if it ran) and a config that forces a push (remote.<name>.mirror, a + push refspec, git remote add --mirror=push), given with -c or saved; it doesn't deny one through an alias or config saved by an earlier call, a git config file or include, a refspec from a shell variable, a shell alias or function, more than eight global options before push, a GraphQL updateRef whose query comes from a file or a variable, or a ref update through GitHub's API whose body comes from stdin (one from a file or a variable is held); and it denies a push whose quoted option value holds -f or +x (-o 'note -f'). It reads each command's words as typed, as TK-A002 does: values aren't expanded, and once the words are joined with spaces a value with a space in it can't be told from the words after it. Protect the branches that matter on the Git host so it refuses force pushes, and don't give an agent credentials that can rewrite shared history; the server pack's TK-S006 denies every -c alias.*. policy
Rules anchored on a command's name (TK-D001, TK-D003, TK-D004, TK-D010, TK-A001, TK-A002, TK-A011, TK-A013, TK-S006) read a wrapped command only through the wrappers and runners the parser knows (sudo, env, timeout, caffeinate, npx, uv run, direnv exec, mise exec, op run, …: shell parsing); another one (bwrap, whose options take two values) hides what it runs from them. An option of a known wrapper that its table doesn't name as taking a value is read both ways, as a flag and as taking the next word (strace --user bob cmd, uvx -qc c.txt cmd), so the words after it are also read as a command. Each wrapper's options and positional words differ; reading an unknown one's arguments as a command would misread ordinary ones. Run the agent where only the wrappers you use are installed, or add a deny rule of your own on the line (field: line) for the one you use. policy
TK-F014 (a trailing &, flagged as a background process) reads only the raw command line: it misses an & inside bash -c '…', eval, $(…), ssh host '…', a heredoc into a shell, an argv list or Codex's commands, a job followed by another command (sleep 9 & ls, or ls on the next line), a subshell ((sleep 9 &)) and sleep 9 & # bg; it still flags echo a\& and git commit -m 'x &; y'. In the normalised line a quoted & looks like a background job (echo 'x &'), so the rule keeps to the raw text, whose quoting it can't read. Read TK-F008 (the harness's own background flag) beside it, and run agents in a sandbox that limits what a background process can reach. policy
TK-A032 (the dev pack's hold on uploads to cloud storage) reads gsutil, gcloud storage, aws s3 and az storage blob uploads, not rclone, azcopy or an SDK call in a script; and a person's "no upload" in the request doesn't become a live constraint (only a file, a scope, a push and the network do). TK-A031 (destroying cloud storage data) doesn't read a delete through a sync or move (aws s3 sync --delete, gsutil rsync -d, rclone sync), one GCS object version (gs://b/o#<generation>), a ? or […] wildcard (gsutil rm 'gs://b/2026-??.log') or a listing piped into a delete (gsutil ls gs://b | xargs gsutil rm), which TK-F003 only flags, a lifecycle rule that expires objects, az storage account/share delete or az options before storage, an s3cmd delete of one object (which TK-F003 doesn't flag either), or azcopy, s5cmd and mc; TK-A032 doesn't read aws s3api put-object, az storage file upload, or an option value with a space in it. Both read up to eight options before the service and again before its verb (gsutil -m -o … rm, aws s3 --profile p rm), as TK-A002 does; and TK-A032 holds a download that puts an option between the bucket and the local destination (aws s3 cp s3://b/d --recursive ./d), since it can't tell that option's value from a path. An rclone remote (name:path) can't be told from a local path by a fast pattern, and a new constraint kind is a change to the signer protocol and the evidence format. Run agents with cloud credentials that can't write to production buckets; say "don't touch " for files and "no network" when nothing should leave the machine. policy
TK-A033 (merging a pull request) doesn't read a merge through a GraphQL query in a file, a variable or a pipe (gh api graphql -F query=@merge.graphql, -f query="$Q", printf … | gh api graphql -F query=@-), a URL the client rewrites before sending (curl's and wget's dot segments, …/pulls/1/./merge, and curl's globbing, …/pull{s}/1/merge), a script or SDK call, a gh or glab alias (gh alias set pm 'pr merge'), a shell alias or function, more than four options before a subcommand, a program named by a Windows path with backslashes ("C:\Program Files\GitHub CLI\gh.exe" pr merge 1, which TK-A001 and TK-A002 miss for their programs too: the parser keeps the directories before a \ in a program's name), another forge's CLI or API (Bitbucket, Gitea), a branch merge (POST …/merges or GraphQL mergeBranch, which merge one branch into another, not a pull request) or a push straight to a protected branch (git push origin HEAD:main, which isn't a merge); it holds a status check (GET …/pulls/N/merge) too. It reads the command lines of gh, glab, hub, curl, wget, HTTPie and xh as typed; a file's, variable's, pipe's or script's contents aren't on them, and the URL is matched before the client rewrites it. Give agents a token that can't merge or push to protected branches (branch protection with no admin bypass), and keep merging to people. policy
TK-A048 (deleting Docker or Podman volumes) doesn't read a delete run inside a container (docker exec c docker volume rm x), through the Docker API (curl --unix-socket /var/run/docker.sock -X DELETE …/volumes/x) or an SDK, by a script or Makefile target that runs it, a docker or compose alias, a flag from a variable (docker compose down $FLAGS), another client (nerdctl, finch), a Windows path with backslashes (C:\…\docker.exe volume rm x, the parser limit TK-A033's row names), more than six options before a subcommand (eight before down), more than eight between volume or system and its verb, more than sixteen words between prune or down and the flag, an option value with a space in it before the subcommand (docker --config '/x y' volume rm pgdata), or a way to drop a volume that isn't volume rm, volume prune, system prune --volumes or compose down -v (docker rm -v, docker compose rm -v, podman system reset, which deletes every volume, a bind mount's files deleted with rm -rf). Once the words are joined with spaces, a quoted value with a space in it can't be told from the words after it, so --filter 'label=a --volumes' is held though it deletes nothing extra. A help flag after a volume's name (docker volume rm pgdata --help) doesn't exempt it: that is held, conservatively. It reads the command line of docker, podman and their compose commands as typed; what a script, an alias or a container's shell runs, and the Docker API's requests, aren't on it. Run the agent against a Docker daemon that has no data worth keeping (a disposable one), keep the database's volume out of the agent's reach, and keep its backups elsewhere. policy
TK-A055 (a framework's command that drops or resets a database) reads the commands its rule names (Prisma's migrate reset and db push --force-reset, Rails' db:drop, db:reset, db:purge, db:truncate_all, db:migrate:reset and db:seed:replant, Django's flush, Sequelize's db:drop, Laravel's migrate:fresh, migrate:reset, migrate:refresh and db:wipe, Supabase's db reset, TypeORM's schema:drop, Ecto's ecto.drop and ecto.reset, EF Core's database drop) and no other way a framework wipes data: Django's reset_db (django-extensions), Sequelize's db:migrate:undo:all, or Rails' db:schema:load and db:setup, which load the schema (and drop a table of the same name) but are also how a new checkout or CI sets up an empty database, so holding them would ask for every setup. It doesn't read options before a subcommand (supabase --debug db reset), more than four options before the program, a package manager's workspace form (pnpm --filter api exec prisma migrate reset, yarn workspace api prisma …, npm run typeorm -- schema:drop), sail php artisan …, mix do ecto.drop, ecto.create, rails db:environment:set db:drop, or rolling every migration back (rails db:migrate VERSION=0, manage.py migrate app zero, dotnet ef database update 0); a command in a container or script isn't read, as TK-A048's row says. A dry run is held (rake db:drop --dry-run). A help flag after a wrapper or more than two words (bundle exec rails db:drop --help) doesn't exempt it: that is held, conservatively. It reads the command line as typed, and the command wipes whichever database the project's configuration names, which the policy can't see. Point the agent's environment at a throwaway database, keep production credentials out of its reach and keep backups elsewhere. policy
TK-A034 (a patch applied through the shell) holds every patch run as Codex's apply_patch, applypatch or codex --codex-run-as-apply-patch, one to an ordinary file too. It doesn't read Codex started by a runner's subcommand or an option with a value before its script (bun run codex.js, node -r m codex.js), a patch applied by a script, by a copy of Codex's apply_patch.bat under another name (Windows), or by git apply or patch, whose files no file rule reads either. Codex applies such a patch itself, so its hook sends a shell command, not the files; the rule reads the command's words, not the patch. Give Codex models the apply_patch tool, whose files Tracekit decides one by one, and read a held patch before approving it. policy, coding agents
TK-A042 (deleting a repository, project, organization or group through a platform's API), and TK-A002 for a branch or tag deleted through the API, don't read a delete through a GraphQL query in a file, a variable or a pipe (gh api graphql -F query=@delete.graphql, -f query="$Q", printf … | gh api graphql -F query=@-), a URL the client rewrites before sending (curl's and wget's dot segments, …/repos/o/r/./, and curl's globbing, …/repo{s}/o/r), a script or SDK call, a gh or glab alias (gh alias set rd 'repo delete'), a shell alias or function, more than four options before a subcommand or an option value with a space inside it there (--token 'a b'), more than sixteen words between the method and a URL or a bare path (a curl with seventeen words of headers and options; each space in a quoted argument starts another), a path that is a variable as a whole (gh api -X DELETE "$P"), a run-time method for HTTPie or xh (http "$M" api.github.com/repos/o/r: their method is a bare word, so it can't be told from a token), another forge's CLI or API (Bitbucket, Gitea), a delete through the platform's web UI (a browser navigation, which no shell rule reads), or a GitLab project URL under a subpath (https://host/gitlab/api/v4/projects/42). It reads the command lines of gh, glab, hub, curl, wget, HTTPie and xh as typed; a file's, variable's, pipe's or script's contents aren't on them, and the URL is matched before the client rewrites it. Give agents a token that can't delete repositories, projects, organizations, groups or protected branches (no admin scope), and keep deleting them to people. policy
TK-A047 (removing a repository's secrets, branch protection, rulesets or security features through GitHub) doesn't read another forge's CLI or API (GitLab's protected branches, Bitbucket, Gitea), a GraphQL mutation (deleteBranchProtectionRule), a security_and_analysis change whose body comes from a file or a pipe (gh api -X PATCH repos/o/r --input off.json) or whose status comes from a variable, a JSON body padded so more than 200 characters sit between security_and_analysis and status or more than 16 non-word characters between status and disabled, a token used from a script file or an SDK, other HTTP clients (wget, HTTPie, xh), a gh alias or a shell function, a path handed over by xargs, a curl config file (-K), a URL curl rewrites before sending it (globbing such as {branches} or branche[s-s], --expand-url variables, ./ and ../ segments), a repository named by its numeric id (repositories/<id>/…), a branch name longer than 250 characters, a percent-encoded path part (branche%73), a doubled slash, a path part in capitals (REPOS/) or status=Disabled (whether GitHub accepts these is untested), more than four options before a subcommand, more than sixteen space-separated pieces before the method, between the method and the path or between gh repo edit and its flag (each space inside a quoted argument starts a new piece, so one long -H header or --description can use them up), or a change made in the repository's settings page. It doesn't cover, today: a POST adding users, teams or apps to a branch protection's restrictions, an organization's security defaults (PATCH orgs/<org>), turning code scanning's default setup off, dismissing secret-scanning alerts, Actions' default workflow permissions, a DELETE of private-vulnerability-reporting or of tags/protection. gh secret set isn't held though a PUT of the same secret through the API is (so is a PUT that sets up branch protection or an environment), and a gh or hub api DELETE with any $ or backquote in its arguments is held, a workflow run's, a cache's or an issue comment's by a variable id too. A method set at run time (-X "$M", -X $(echo DELETE)) is held where the protected path is written out, and so is a gh repo edit value set at run time (--enable-secret-scanning=$OFF). A PUT or PATCH, or a curl call, whose path or URL is built at run time (curl -X DELETE "$URL") is held only when the protected part is written out ($GITHUB_API_URL/repos/$GITHUB_REPOSITORY/branches/main/protection is). Any host is read as GitHub's, so a PUT to a local test server at …/repos/a/b/environments/dev is held too. It reads the command lines of gh, hub and curl as typed; a file's, pipe's or script's contents aren't on them, and a path built at run time can't be read: a variable anywhere before the path's last part can hide a protected path (a ? or # in it ends the path there), so a gh or hub api DELETE with one is held whatever it names. Give agents a token without admin rights on repositories (it can't change secrets, branch protection or security settings, nor any of the changes the rule doesn't read), and keep those changes to people. Approve a held call to a test server that mirrors GitHub's paths. policy
TK-A043 to TK-A045 (moving money) read Stripe, PayPal and Square calls typed as a command or an MCP call. They don't see money moved where no endpoint is on the command line: an SDK call in a script or one-liner the agent runs (python refund.py, node -e), a task runner (npm run refund, make payout), stripe fixtures, or a body, URL or config read from a file, a variable or a pipe (curl -K, http … < body.json); another provider (Adyen, Braintree, Wise, a bank's API, crypto) or another MCP server's money tools by other names; PowerShell's Invoke-RestMethod; the Stripe CLI run in a container (docker run --rm stripe/stripe-cli refunds create …), whose command no rule reads; a URL written another way (an upper-case host, a port, a base URL the client is set to); a POST option after the URL with more than sixteen space-separated pieces between them (-H 'Authorization: Bearer x' is four, an empty argument or each extra space one); or a curl option that isn't a POST but reads like one between a POST option and the URL after it (-X GET, or an attached value with an X before its first non-letter, -HX-Trace:1), which stops the reach. Card spending (Issuing cards and their limits), Shared Payment Tokens and subscriptions aren't held. A Stripe test-mode call is held too, and so is a request whose body value names a money URL; curl -G (a GET) is read as one only as curl's first argument, and help only as stripe <resource> [<operation> ...] --help (or -h) with nothing else (an option takes the next word as its value, so --description -h is no help). The rules read each command's words and each MCP call's name and arguments as typed: what a script, file or variable holds is known only when it runs, the key's mode isn't on the command line, and Stripe doesn't document stripe_api_write's argument names (TK-A045 holds a refund named anywhere in the call). Also turn on Stripe's approval rules with an agent-tagged key: Stripe enforces them on its side, whatever the agent runs. Give a coding agent test keys, or a restricted live key without money-moving permissions; route a server agent's payment calls through the executor or MCP gateway. policy, coding agents
A hold on moving money (TK-A043 to TK-A045, TK-M001, TK-M002, TK-M005) gives the rule's fixed reason and what to check, not the amount, currency and payee parsed out of the call; a call with no amount (a full refund, a confirm, capture or invoice pay) moves an amount the call doesn't show. The hold's reason is the rule's own text, chosen by its id; a per-call summary would need a parser for each provider's arguments in the signer. Read the command and any file it sends (tracekit approvals show <id> prints the call) before approving, and look up the charge, payment intent or invoice a call with no amount names; set amounts on the call that creates the payment where you can. coding agents
The server pack holds a deployment's own payment tool by its class and name: TK-M001 any payment call with an amount, TK-M002 the names it lists, TK-M005 a payment call with no amount by one of issue_, process_, make_ or initiate_ a payment, payout, transfer, charge or refund. A money tool mapped to app (or sql), or one named otherwise and called with no amount, isn't held. The pack reads what the deployment's tools map says a tool is; a name says what it does only by convention. Map every tool that moves money to payment, or add an ask rule of your own for its name. policy
TK-M003 holds an email to ten or more recipients in one to, cc, bcc or recipients argument (a list, or a string of ten addresses, display names included) or to a whole-company address (all@, everyone@, everybody@, staff@, all-staff@, all-hands@ and all-employees@ with -, ., _ or nothing between the words, customers@, users@, in any case, after a display name, a separator or an escaped character such as a quote or a newline). It misses a list address with a tag or a quoted local part (all+news@, "all"@), ten or more recipients written as objects ([{"email": …}, …]) or a single object ({"to": {"address": "all@corp.com"}}), ten split across arguments (five in to, five in bcc), an argument named otherwise or in another case (emails, To), and a list address by another name (company@). The rule reads the call's arguments as JSON text, not a parsed recipient list; counting across arguments or inside objects would need a parser for each email tool's arguments. Add an ask rule of your own for your email tool's recipient shape and your organisation's list addresses. policy
TK-D010 (writing a credentials file from the shell) also denies a read redirected from one (while read l; do …; done < .env), and TK-A011 and TK-A013 hold one from their places. Each rule reads every command and every redirection target on its own, anchored, so the fallback engine stays linear on long commands; a redirection's target doesn't say which way it goes. Read the file another way (cat .env, or the agent's file tool). policy
TK-D010 (writing a credentials file from the shell) reads cp, mv, install and tee with the file named, and a redirection into it; another writer isn't denied (sed -i … .env, dd of=.env, ln -sf x .env, perl -i, truncate, an interpreter), nor a copy into a folder named by -t (cp id_rsa -t ~/.ssh). TK-F005 flags a write that names the file as access to a secrets file. The rule reads the commands that copy or redirect into a named file; the other writers name the file in their own ways. Keep real credential files out of the agent's reach (system mode, a separate user, or a secret store), so a write from the shell can't change them. policy
TK-D004 (recursive delete of root or home) denies rm -r of root or a home (and of a pattern that may match each of its files or folders: ~/*, ~/.*, ~/?*, /*/, ///*), among any number of other plain words or up to sixteen of any other shape (rm -rf a.txt ~/), with -r before or after it, and find … -delete on root, or on a home with no filter but depth and type (or -true, -print, and a name, path or regex that matches every file, * or .*, or -size +0), or a negated name, path or regex, which picks all but a few), as one of up to nine starting points after up to eight of find's own options, and -exec rm -r … {} read as -delete; rsync --delete into root or a home; a home is ~, ~user, $HOME, /home/<user>, /Users/<user> or /root (also under /var, /private or macOS's /System/Volumes/Data: /var/root, /var/home/<user>), and the folder an interpreter's tree delete (shutil.rmtree, fs.rmSync, FileUtils.rm_rf) or a container's rm -r of its mount of one names, also as a relative operand after a cd there (cd && rm -rf *), through a link the line made to one (ln -s ~ h; rm -rf h/*) and as the words echo pipes into xargs rm. A find there that picks files by name or age (find ~ -name '*.log' -delete, -mtime -100000, -newer f), a root or home reached through another directory (/tmp/..) or a variable other than $HOME, and a link or cd from an earlier call, aren't denied; a cd in a subshell or branch counts for the rest of the line. A find that picks files under the home is often routine cleanup, and a deny can't be approved. Run agents as a user whose home holds nothing they can't lose, or in a sandbox that keeps them out of it. policy
TK-S006 reads tar's --to-command, --checkpoint-action=exec and --use-compress-program (each also as a unique prefix) and -I; tar's --info-script (-F), --new-volume-script and --rsh-command also run a program and aren't read. These run only with a multi-volume archive (-M) or one on another host (host:path). Add an ask rule of your own for these options if your agents use tar that way. policy
(1.5.3) TK-S006 denies rsync's -e/--rsh and man's -P only when they name a shell or an interpreter (sh, bash, python, env, …, by a path of up to 128 characters too), man's pager also when it holds a ;, &, |, <, >, a backquote or $(; another program they name (rsync -e ./x) isn't denied, nor git's difftool -x. rsync -e ssh and man -P cat are everyday commands; only the program's name tells them apart from one that runs a shell, and a bounded read keeps the fallback engine linear. Keep the programs an agent may run on its path to the ones it needs, or add an ask rule of your own on these options. policy
(1.5.3) TK-C001 (changing cloud identity or access) denies sharing an RDS or EC2 snapshot with all only in the sharing option's own value, read up to the next option: --values-to-add naming all (alone, in a list, or in JSON), --create-volume-permission adding Group all (in shorthand or JSON, after a Remove list too), or --operation-type add with --group-names all, each also by aws's unique prefixes and in any case. The value is read a word at a time, up to 1,000 words and never into the next option, so all or a Group after 1,000 words isn't read (about 250 pretty-printed EC2 entries; a Remove list before the Add is read whole), and through call_aws an option in quotes is read as part of the value (… 111122223333 "--values-to-remove=all" is denied); an Add list read on into a Remove list that names all is denied too, and a share sent as a whole request (--cli-input-json, a file) isn't read. A snapshot shared with every AWS account is public; the rule reads the options the CLI documents for it, and stops at the next option so it decides in time. Pass Add and Remove in separate calls; deny --cli-input-json on these commands in a rule of your own. policy
(1.5.3) TK-C002 (changing cloud identity or access through an MCP tool) reads a tool's name: attaching or putting a policy, an IAM policy binding, creating an access key, a service account key, a role assignment or binding, and a grant of a role, access, a privilege, IAM, admin, owner or permissions, in snake, kebab, camel or Pascal case. A grant of permissions in kebab case (grant-network-permission, which is Wassette's sandbox grant, held by its own rule), words more than 64 characters apart or a last word followed by more than 64, and a tool whose name says none of these aren't denied; a name that only holds such a phrase is denied too (list_grant_permission_requests, revoke_grant_role). Tool names are the server's own; the rule reads the words they usually take, each starting after a separator or with a capital. Deny or hold your servers' access tools by name in a rule of your own. policy
TK-C010 reads kubectl's resource type as the first word after its options, as one of a list (pod,ns) or as a later TYPE/NAME within sixteen words. It reads -f, -k, -l, -n, -o, -s, -v, --filename and --kustomize as taking a value and any other option either way, so a type named as another option's value (--as ns pod x) is held, and a delete from a file or directory (-f ns.yaml, -k overlays/prod) isn't, whatever it deletes, as in 1.5.1. In an MCP tool's cli_command, command or cmd, TK-C001 and TK-C010 read words split by spaces and escaped tabs, newlines and returns, as TK-A036 does, but kubectl's options and type after delete only by spaces (kubectl delete\tns\tprod isn't held). Which kubectl options take a value isn't in the command, and the resources a file names are read only when kubectl runs. Approve the held call; give the agent a Kubernetes role that can't delete namespaces or volumes, or add an ask rule of your own for kubectl delete -f. policy
TK-C010 holds the AWS commands that switch off audit logging or threat detection that the policy page lists, reading the option that switches one off within sixteen words of its command. It doesn't hold GuardDuty features or trail settings read from a file or another input (--features file://f.json, --cli-input-json, --cli-input-yaml), GuardDuty's older --data-sources option (S3Logs={Enable=false}), a trusted IP list (guardduty create-ip-set), which stops findings for its addresses, an option further than sixteen words from its command, or a feature's Status more than sixteen words after the command (a long JSON list written with spaces). It holds every update-trail --s3-bucket-name, the trail's own bucket too. What a file or input holds is read only when the CLI runs; a trusted IP list is also routine setup, and its command doesn't say whether its addresses are safe; the bound keeps the fallback engine linear. Approve the held call; give the agent an IAM role that can't update trails or detectors (or a service control policy that denies it), and add an ask rule of your own for create-ip-set if your agents shouldn't add one. policy
TK-S004 denies the credentials files it names wherever a call acts on them (cloud, cluster, registry, database and Git credentials, .netrc, a Vault token, /etc/shadow, a process's environ, mounted secrets, and a private key in .ssh: id_ and a name with no . after it, id_rsa_work and id_ed25519_sk too, not id_rsa.pub or id_rsa-cert.pub). It doesn't read a key elsewhere or named otherwise (~/keys/deploy.pem, .ssh/id_rsa.old, .ssh/github), other tools' token files (~/.config/gh/hosts.yml, ~/.terraform.d/credentials.tfrc.json, an .npmrc or .pypirc with a token), a path built at run time, or a file's content once it is copied under another name. It reads a path's name; a file's content and where a program keeps its token aren't on the call. Keep keys and tokens out of the agent's reach (a sandbox, a separate user), and redefine TK-S004 with the paths your hosts use. policy
TK-A010 to TK-A013 hold only the writes they name: a file tool's path, or cp, install, mv, ln, tee, chmod (hooks), sed -i, dd of= or a redirection into the place. They don't hold another program writing there (an interpreter one-liner such as python -c or node -e, curl -o, rsync), a place named through a variable, a substitution or the working directory (cp x.plist $D/, "$(git rev-parse --git-dir)/hooks", cd ~/.config/systemd/user && cp a.service .), or hooks a hook manager installs (npx husky init, pre-commit install, a package's prepare script run by npm install). They read each command's words as typed; what a program writes, and what a variable or the working directory holds, is known only when it runs. Run the agent in a sandbox that can't write outside its workspace (Claude Code's, Gemini CLI's), and on Linux import a kernel sensor's records (Tetragon): each file write is signed into the run with its path, and tracekit analyze --v2 flags one no call explains (TK-X206). policy
TK-D008 (the harness's transcripts) denies a write or delete it reads from the command ((1.5.3) a writing statement sqlite3 runs on a database too, from its arguments or a heredoc or herestring, not from a file it reads, < x.sql or .read): a file in .claude/projects, .codex/sessions, .gemini/tmp or OpenCode's sessions (opencode*.db and storage/ in ~/.local/share/opencode or $XDG_DATA_HOME/opencode), or a delete of a home folder that holds them (~/.claude, ~/.codex, ~/.gemini, ~/.local, ~/.local/share, OpenCode's data folder, $XDG_DATA_HOME). It reads the command trap runs, what at or batch get in a herestring or heredoc (a name there built from a variable, at now <<< "$JOB", isn't held for TK-SHELL-PARSE, as before they were read; one in a trap's action is), and the sources zip -m deletes. A script the call writes, then runs, is read as that interpreter's inline code, and each word the run gives it counts as written. In a call with a writer that gets its files at run time or runs code (xargs rm, also fed a herestring or heredoc; rm "$f", parallel 'rm {}', docker exec c sh -c 'rm …', perl -e with a write, at or batch fed from a pipe, osascript with do shell script or a Finder delete), or a line whose commands the parser can't read and holds (TK-SHELL-PARSE: a pipe into sh, fish -c, a name built from a variable) where a writer's name reaches that command (in its words, in an echo or printf piped into it, or in a value the line gives the variable its name expands: C=rm; $C -rf …), any word, herestring or heredoc naming those folders counts, so a read in that call is denied too, on any of its lines (rm "$f"; ls ~/.codex/sessions, also with the rm in a trap). It doesn't deny a relative path after cd (cd ~/.codex && rm -rf sessions), a folder set by a variable ($CODEX_HOME/sessions, $CLAUDE_CONFIG_DIR/projects), a glob (rm -rf ~/.*, rm ~/.claude/proj*/x.jsonl), interpreter code that writes with no shell writer's name or > in it (python -c with os.remove, shutil.rmtree or open(…, "w"); node -e with rmSync), another program's write (tar --remove-files, trash), a line the parser can't parse at all (an unclosed quote: held as TK-SHELL-PARSE, not denied), or a delete of .claude, .codex or .gemini in a home other than ~, $HOME, /home/<u>, /Users/<u>, C:\Users\<u>, /root and /var/root (/srv/u/.codex). Deleting a project's own .claude is flagged (TK-F015), not denied, and so is a shell write into OpenCode's config (~/.config/opencode or $XDG_CONFIG_HOME/opencode); a file tool's write to ~/.config/opencode is denied (TK-D009). Claude Code's memory notes beside the transcripts (a .md file directly in .claude/projects/<project>/memory/) aren't held or flagged, from the shell or a file tool. A link made in those folders is denied (ln, cp -s, cp -l, also as a memory note), but not one made elsewhere that points at a transcript (ln -s ~/.claude/projects/p/a.jsonl ./x), nor one moved into memory/ with mv: a later write through it writes the transcript. It reads each command's words as typed; what the working directory, a variable or a glob holds, and what interpreter code does, is known only when it runs. A project's .claude can't be told from a home's without knowing the home. Run the agent in a sandbox that can't write outside its workspace (Claude Code's, Gemini CLI's), and on Linux import a kernel sensor's records (Tetragon): each file write is signed into the run with its path, and tracekit analyze --v2 flags one no call explains (TK-X206). policy
TK-A011 and TK-A013 read a cp, install, mv or ln destination as its last word (or -t's): a copy out of a place to a name without a / (cp ~/Library/LaunchAgents/x.plist .) is held, and a destination path that leaves the place and comes back (.git/hooks/../hooks/pre-commit) isn't. The rule sees the command's words joined by spaces, so a destination name with a space in it can only be told from the words before it by the / it lacks; paths aren't resolved, and the anchored form keeps the fallback engine linear. Approve the held copy, or copy to a path with a directory (./x.plist); file tools' writes are read normalised (TK-A010, TK-A012). policy
TK-A010 and TK-A011 know launchd's and systemd's places, XDG autostart, /etc/init.d and /etc/rc.local, and turning a unit on with launchctl load, bootstrap or enable or systemctl enable, reenable, preset or add-wants. TK-A010 also holds a file tool writing a shell start or end file or a cron file by file name, a dotfiles repository's too: bash's (.bashrc, .bash_profile, .bash_login, .bash_logout, /etc/bashrc, /etc/bash.bashrc), zsh's (.zshenv, .zshrc, .zprofile, .zlogin, .zlogout, the same in /etc, and Debian's /etc/zsh/), .profile, /etc/profile, /etc/profile.d/, fish's config.fish and conf.d/ (in .config/fish or /etc/fish), /etc/cron* and /var/spool/cron/; not ksh's or csh's (.kshrc, .cshrc, .tcshrc, .login), PowerShell's profiles, .local/share/systemd/user/ or /etc/systemd/user/. A shell command writing one isn't held: an append to a startup file is flagged (TK-F011), crontab is flagged (TK-F007), and a copy into /etc/cron.d or /etc/profile.d passes, unless what it writes runs a download (TK-D002). Other ways to run something at login or boot aren't held: systemctl link, loginctl enable-linger, other supervisors (pm2 startup, supervisord, runit, OpenRC) and Windows' Run keys, Startup folder and schtasks. Each service manager keeps its own places and commands; the pack names those of the hosts coding agents run on most. Add ask rules of your own for the managers your hosts have, run the agent where it can't reach them (a sandbox, or a container without them), and on Linux import a kernel sensor's records (Tetragon): each file write is signed into the run with its path, and tracekit analyze --v2 flags one no call explains (TK-X206). policy
TK-A013 holds setting or unsetting git config core.hooksPath typed as a command (and git config --get core.hooksPath x, a read with a value pattern); it doesn't hold the hooks path set another way: git -c core.hooksPath=… <command> for one command, GIT_CONFIG_KEY_* environment variables, a .git/config a file tool writes, or a config file include pulls in; and TK-A012/TK-A013 don't hold a write to a folder the hooks path already points at (.husky/pre-commit where Husky set it). Git reads its configuration from several places when it runs; the rule reads one command's words. Use the server pack (its TK-S006 denies git -c with a hooks path), add an ask rule of your own for file-tool writes to .git/config, and review a repository's hooks path (git config --show-origin core.hooksPath) before anyone commits in it. policy
TK-A020 and TK-A021 recognize named keychain, password-store, browser-profile (Chrome, Chromium, Brave and Edge on Linux, macOS and Windows, Firefox on all three) and SSH-agent access forms; other browsers (Arc, Vivaldi, Opera, a snap's profile), Chrome's Login Data For Account, a profile copied elsewhere first (cp …/Login Data /tmp/ld) and another reader than cat or sqlite3 aren't; TK-D020 blocks only known whole-store dump commands. Custom stores, SDK access and other export commands aren't recognized, and of Firefox's profiles only Linux's (~/.mozilla/firefox/) is: its default profiles on macOS (Library/Application Support/Firefox/Profiles/) and Windows (AppData/Roaming/Mozilla/Firefox/Profiles/) aren't. The policy reads file paths and shell text, not the process's actual file or agent-socket access. Keep credential-store permissions narrow and use OS-level monitoring or isolation for broader coverage. policy
TK-A022 and TK-A023 cover writes to Docker daemon configuration/socket paths and a docker or podman run, create or exec (container run too, after global options) with privileged mode, every capability (--cap-add=ALL), host PID space or a mount of the host's /, /proc, /etc or /root. A global option the CLIs document as taking a value (-H, --context, --config, --log-level, podman's --url and --connection, the TLS and storage paths) takes the next word even when it is named like a verb (docker --context run run …); another global option takes the next word unless an option or run, create, exec or container follows, so an unknown option with a value named so hides the verb after it. Single capabilities (--cap-add SYS_ADMIN), other host namespaces (--net=host, --userns=host), a file under /etc (/etc/passwd), docker compose run, other runtimes (nerdctl), compose contents and API calls aren't read. File policy sees the path, not file contents; shell policy sees only command arguments. Review compose changes and remote/container API access separately, or use a runtime policy that sees the resolved container configuration. policy
TK-D021 blocks direct HTTP(S) package URLs in named install commands ((1.5.3) in any case, and as a PEP 508 direct reference, name @ https://…); TK-A028 asks on a version-control source anywhere in an install's words (git+https:// and the other git+ schemes, git://, npm's github:/gitlab:/bitbucket:/gist: shorthands, a PEP 508 name @ git+…, cargo install --git), but not npm's bare user/repo shorthand or options before the install verb. npm i <url>, pip install -q <url>, pip install -U <url>, other option orders, preconfigured unknown sources, transitive dependency URLs and other package clients may not match. TK-A024 and TK-A030 hold a file tool's or a shell command's write to known source-config paths (.npmrc, pip.conf, .pypirc, apt sources, yum repos), and TK-A025 installs with explicit non-default index, registry or --find-links options (pip, uv, uvx, npm, npx, pnpm, yarn, bun, poetry, cargo, gem), config set (npm set) of the index or registry, and the source variables pip, uv and npm read set before a command or through env or export (PIP_INDEX_URL, UV_INDEX_URL, npm_config_registry, …), npm's scoped registry option (--@acme:registry=), gem's -s on install, update or fetch, and gem sources --add. An index named inside a requirements or lock file (pip install -r of a file with --index-url), a config file chosen by a variable (PIP_CONFIG_FILE, NPM_CONFIG_USERCONFIG), a config file written by an interpreter or under another name, and other package managers (conda, poetry source add) aren't held. The signer doesn't resolve package-manager configuration or dependency metadata before deciding, and reads files only by the names a command gives them. Pin and verify package sources in a controlled build environment. policy
TK-A026 and TK-A027 hold edits and recognized shell writes/deletes (effects: a redirection, rm, mv, cp, ln, tee, truncate, shred, dd, sed -i, perl -i, find -delete) to named history and log paths (also $HISTFILE, and //var/log, which Linux and macOS read as /var/log), and TK-A029 history -c, turning history off and vacuuming the journal; macOS's user logs (~/Library/Logs) aren't named. Other history-file writes such as history -w, application-managed history, remote logs and paths reached through an unrecognized program (python -c) may not match. The rules match visible paths and command arguments; they don't observe filesystem effects. Preserve logs outside the agent's control and use a sandbox or kernel sensor to detect writes. policy
TK-A027 holds find … -delete and find … -exec rm (or unlink, shred, truncate) on history and log paths, not a delete made by a shell find runs (find /var/log -exec sh -c 'rm "$1"' _ {} \;): the paths reach that rm only as $1. Variables aren't expanded, so the rule can't tell which files the inner shell is given. Add an ask rule of your own for find with -exec sh on the paths that matter, or keep logs outside the agent's reach. policy
TK-D008 (the harness's transcripts), TK-A027 (history and logs), TK-A030 (package sources) and TK-F015 (harness settings) read a relative write or delete target as it is typed, not from the folder an earlier cd or pushd moved into, nor from the one a shell tool's own working-directory argument names (Codex's workdir, Gemini CLI's dir_path, Cursor's working_directory): cd ~/.codex/sessions && rm *.jsonl, cd ~/.claude/projects/x && : > s.jsonl and cd ~/.codex && rm -rf sessions aren't denied, cd /var/log && rm syslog and cd /etc/apt/sources.list.d && echo deb x > evil.list aren't held, and cd ~/.claude && echo '{}' > settings.json isn't flagged. A relative target that still names the folder is matched (cd ~ && rm -rf .claude/projects is denied). The shell parser doesn't follow cd: which folder a relative path lands in is known only when the command runs. Run the agent in a sandbox that can't write outside its workspace (Claude Code's, Gemini CLI's), and on Linux import a kernel sensor's records (Tetragon): each file write is signed into the run with its path, and tracekit analyze --v2 flags one no call explains (TK-X206). policy
TK-A024 and TK-A025 read npm's and pip's ways of setting a package source; Yarn Berry's (yarn config set npmRegistryServer <url>, or .yarnrc.yml written by a file tool) isn't held. TK-A025 reads a pip option's unique prefix (--index-u), not another client's abbreviated option (npm's --reg, gem's --sou), which those clients may take, and reads config set only as the first word after the options, so a global option's value before it (pip --proxy http://p config set global.index-url …) hides it. Each package manager names its registry setting differently, and the rules name npm's, pip's, apt's and yum's. If your agents use Yarn 2 or later, add ask rules of your own for yarn config set npmRegistryServer and writes to .yarnrc.yml. policy
The payment class doesn't extract new_payee yet. Not built. Match payees with your own rules. policy
unless on a whole command line could exempt a different target. The subject holds several targets. Use unless only where the subject is one target. policy
v1 rules (tracekit/policy/default.yaml) match raw strings, so quoted text that mentions a risky command can trip them. The v1 TK-D008 and TK-D009 leave Claude Code's memory notes (a .md file directly in .claude/projects/<project>/memory/) writable. They match case as written, so on a file system that ignores case (macOS, Windows) .ENV, ~/.SSH/ or RM -Rf ~ isn't matched as .env, ~/.ssh/ or rm. The v1 engine doesn't parse commands, and the v1 policy is kept as it was. Use the v2 signer's policy; add exceptions for known false positives. evaluation

Provenance (1.1)

Limit Why it is so What to do Details
(1.1) Provenance matches values verbatim: a value the model paraphrases, splits or re-encodes reads as a new value. It is a tripwire on the commonest way injected instructions act, not information-flow control. To prevent the flow, use information-flow control (CaMeL, FIDES) in the agent. policy
(1.1) Only untrusted tools' results and observed inputs are indexed: a page fetched with a tool the policy doesn't list as untrusted (curl in a shell) isn't seen. Results of other tools can echo the agent's own arguments, so they aren't counted either way. List such tools under untrusted, or observe the content with run.observe. policy
(1.1) Only an input observed as trusted makes a value trusted: a value from your own data that also appears in untrusted content (a customer's address from the CRM that is also in their ticket) is held. Counting other tool output as trusted could launder an injected value. Observe the record you looked up as trusted, or answer the hold. policy
(1.1) Whenever a run's index is not complete, from: untrusted rules fail closed: they match whenever their pattern does (the packs' TK-P rules ask). It is unavailable after a signer restart, truncated once a result carries more than 4096 values (or 1 MiB of text) or the run reaches 20,000, partial once an untrusted tool completes with a digest or a client's events skip a client_seq (an observe or a result lost in a signer outage), and timeout for a decision whose values took past its 1 s deadline. The index lives in memory only and is bounded; a value it can't vouch for may be injected, and a lost event may have carried one. Watch provenance_state and provenance_reason on decisions; split very long runs; expect more holds after a restart or an outage, and start the task again in a new run to end them. policy
(1.1) Provenance needs the result itself: for a tool the policy lists as untrusted, decide answers send_result and the shipped adapters (Python, TypeScript, the Claude Code hook) send the result instead of its digest. A result over 512 KiB, or an adapter of your own that sends a digest, makes the run partial. The signer can only index content it receives; it redacts and commits to it and keeps nothing in clear. In your own adapter, send result itself when the decision says send_result. policy, privacy
(1.1) trust: "trusted" on observe is the calling process's claim. Provenance protects against injected content, not against a malicious agent program, which can observe anything as trusted (or send digests) and get past from rules. The signer can't tell who wrote content the caller supplies. Observe the task from your application, not from the agent; use the other rules for a hostile agent. policy
(1.1) Bare IPv6 addresses and integer IPs in text are not read as hosts (inside a URL they are). Bare forms are ambiguous in prose. Rely on the URL forms, or add rules of your own. policy
A Browser Use navigation or an http GET with a query string (or, for http, a params argument) sends data to its host, so TK-P003 holds one to a host that only a page named unless the task named it. An http GET that sends nothing but its URL's query isn't held when untrusted content gave that URL exactly as it stands (a search result's link with ?id=5, followed as given; the index answers that only when it is complete), but is held with anything added or changed (&d=…, another value, a character after it) and a browser navigation is held as before. Choosing which of a page's links to follow can still signal a few bits to its author. Data in a URL's path or fragment isn't counted as sent, and neither is data in an http call's headers or cookies. A query string is how a GET carries data to an attacker's host; telling an ID from a card number takes reading the value, and a link given verbatim holds only what its author put in it, unless a page reflects a URL that carries the agent's data back to it (a search page, an echo service, a comment the agent posted earlier). Observe the task as trusted; to hold only typing and uploads, redefine TK-P003 with tool: '^browser_use:(input|upload_file)$'; a POST, a body or a params argument stays held. Browser Use
The Browser Use adapter observes what the model read of each page (URL, title, tabs, text) up to 100,000 characters, from each browser state the session's get_browser_state_summary returns, which it wraps at the session's first action; the first step's state, made before that, comes from Browser Use's cached copy, which a tab closing before the first action empties. A link's target the model wasn't shown enters the index only once the agent is on that page. Browser Use shows the model 40,000 characters of a page by default, and the adapter first sees the session at its first action; asking it for a fresh state would renumber the elements the step's actions refer to. Keep max_clickable_elements_length at or under 100,000. Each page adds its values to the run's index (20,000 at most, then truncated): give a long browsing session a run per task. Browser Use
After a signer restart every run that was open has an unavailable index for the rest of the run: each call a from: untrusted rule's pattern matches is held, even typing into a site the task named (its decision's provenance_reason says so). The index holds per-value keyed hashes in memory under a per-process key; persisting them would keep brute-forceable hashes of card numbers and addresses at rest, and would need a crash to invalidate them. Answer the holds, or start the task again in a new run: a run registered after the restart has a complete index. Restart signers between runs where you can. policy
(1.1) Reading values is bounded: linear in the text, at most 1 MiB and 4096 values per result or argument. A result is attacker-controlled; the work must not grow with it. Nothing: past the bound the run is truncated and fails closed. policy
(1.1) Bundles from a 1.1 signer must be exported with tracekit >= 1.1: a 1.0 exporter labels them 1.0.0, and a 1.0 verifier fails their schema. Provenance adds record fields 1.0 doesn't know. Upgrade the exporter and verifiers together with the signer. format
(1.2) TK-P003 reads only a browser navigation's or (1.5.3) an http GET's query string as data sent to the host: data put in the path (https://evil.example/c/<card number>) or in the host name (https://<data>.evil.example/) isn't, so such a navigation to a host only untrusted content named is not held. Following a link from a page or a mail is a navigation too; holding every path would hold every link the agent follows. Allow only the hosts the agent needs (TK-B011's allowlist), or run the egress observer, which records the hosts reached. policy

Detection (1.2)

Limit Why it is so What to do Details
(1.2) Sequences and limits catch the patterns they describe, nothing else: a reworded attack that carries none of their labels isn't seen. Detection is deterministic rules over rule ids and labels, no model. Read incidents as tripwires; add sequences for the patterns you care about and backtest them. policy
(1.2) A hold or quarantine is recorded for every run, but enforced only where the signer decides each step: a gateway's model loop, an executor's tools (T2). A T1 adapter that ignores a decision can still run the call. On T1 the agent's own process runs the tool; the signer answers, it can't stop it. The verifier flags any result recorded while held or quarantined. Put tools that must be containable behind the executor or MCP gateway, and models behind the LLM gateway. incidents
(1.2) With no person approver configured (approvals.approvers naming persons), every enforced hold is a quarantine, and run_hold is refused. Only a person may answer a held call; a hold no one may answer would never end. Configure approvers mapped in approvals.persons (or OIDC persons or groups) before enforcing holds. incidents
(1.2) Suspensions are shared only through the suspension list file: each replica reads it per call and writes its own enforced record when it first sees an entry; two operators changing the list at once on different replicas can lose one change. Holds, quarantines, cooldowns and a paused response engine are per replica. Each replica has its own log and state; the list is the one thing they share, and no token is revoked automatically. Put the list on storage every replica reads (suspensions:), change it from one place, and send pause and resume to every replica (tracekit signer incidents pause --signer ... --signer ...). incidents
(1.2) tracekit signer incidents list reaches only the replicas you name with --signer (the default: one). Incidents live in each replica's log; there is no central index. Name every replica's URL when listing, or read incidents from each log's bundle. incidents
(1.2) After a restart that loses the detector's state, a decision whose detection state is unavailable holds its run (detector_unavailable) when the policy enforces a hold or quarantine. Fail closed: the detector can't vouch that no sequence completed. Keep snapshots (they hold the detector's state); expect held runs to resume by a person after an unclean restart. incidents
(1.2) The call that completes a sequence was decided allow and counted before the hold: it is decided again, held, so it doesn't run on that decision; a call consumed by a person's approval as it fires a hold stays in flight. Detection reads the signed decision, so the decision exists before the incident. Read in_flight on incident.opened: those calls may still complete. incidents
(1.2) The verifier recomputes only incidents of scope run whose cites are in their run, under the one policy that run was decided by; session, owner and principal incidents, operator incidents and runs decided under several policies are counted signer-asserted. A bundle holds one run's records; other runs' records and earlier policies aren't in it. Export with the signer's config so its policies are bundled; export the run-set to see the other runs of a scope. incidents
(1.2) Incident webhooks are delivered at least once (a receiver may see one twice) and a 4xx-refusing endpoint is skipped. A new webhook starts at the log's end, not its beginning; one whose saved cursor is unreadable sends every incident record of the log again. The outbox is a cursor over the log that moves only once the endpoint took a batch; a refusal won't change by resending. Deduplicate by incident id and record uid; fix the endpoint and read missed incidents from the log or tracekit signer incidents list. webhooks
(1.2) No trigger suspends an identity: respond holds or quarantines runs, and only an operator suspends (lint refuses suspend: in respond). A run's owner is often an identity every conversation of a server shares, and content the agent reads can steer every trigger, so an automatic suspension could stop every user's agent. Alert on incidents (action: notify) and suspend with tracekit signer incidents suspend after a look. incidents
(1.2) The signer refuses to start when one authorize entry grants both register_run and a containment operator call. An agent's identity must not resolve, resume or pause its own containment. Give operators an identity of their own (a person's OIDC login or a separate uid or token). incidents
(1.2) session scope joins runs only through parent_run: a sequence split across runs registered without parent is two sessions. The signer joins runs only on a link it can check (the parent's run token). Register subagent runs with parent; use owner scope to join all runs of one identity. policy
(1.2) Windows use the signer's clock, and are fixed: an NTP step moves them, and a burst straddling two windows can reach up to twice max before a limit fires. Records' ts is the only clock a verifier can recompute; fixed windows keep the work O(1) per call. Keep the signer on NTP; set max at half the burst you must catch. policy
(1.2) A sum limit holds a call of a known class it counts without a non-negative integer amount and a three-letter currency code (ask, TK-LIMIT-SUM), unless its respond mode is off; approved, or of an unknown class, such a call isn't added to the total. A total across currencies, of negative amounts or of an unreadable amount would mean nothing; an unmapped tool's arguments needn't be a payment's. Send amounts as non-negative integers in minor units with their currency code; map payment tools to a class; approve held calls knowing the limit doesn't see them. policy
(1.2) Decisions say detect.state: unavailable, and steps and counts from before are missed, after a restart from a snapshot written without detection or under another policy, after a replay of decisions made under another policy, and for a run the detector never saw registered. What came before such a snapshot is no longer read, and another policy's decisions carry its rule ids, not this one's. Change a detection policy when runs are quiet; expect missed steps and counts until the longest window has passed after the restart or the last such decision, and backtest the store for them. policy
(1.2) A scope with no record for an hour (or the policy's longest window, if longer) starts over, open incidents included: a later match opens a new one. State must not grow with every run and owner the signer has seen, and the reset follows the records' ts, so a backtest or verifier gets the same incidents. Group incidents by trigger and scope when you read them. policy
(1.2) Only opened incidents count toward the caps: past 100 of one trigger in a run, 20 from one run in a minute, or 60 in a tenant in a minute, one incident.capped is written and the rest are not. An open incident is updated at most once per window of its trigger (a minute for one without). A loop must not flood the log with incidents, and one run or trigger must not use up another's. The share is per run, so an identity with several runs can use up more of the tenant's 60, and another agent's incident that minute is only incident.capped. Read the run's decisions (their detect field) or backtest the policy to see the rest; keep open_runs quotas tight for agent identities. policy
(1.2) The server pack's limits were checked on small shipped runs only, and TK-Q001's window was not backtested. Those are the runs that ship, and none of them reads a secret or sends anything. Run the pack in shadow, backtest your own store (tracekit policy backtest) and set max above your busiest minute. policy
(1.2) One call whose own names match consecutive steps takes them all, each name once (a command that reads a secret and sends it completes [secrets_access, egress]); a step matched only through * or an unknown class takes a call one step. An unmapped tool matches every step; letting it chain would complete any sequence in one call. Give each step its own label; a sequence that repeats a label needs that many calls. policy
(1.2) egress (TK-F012, TK-F013) is a URL a call acts on or a network command; secrets_access (TK-F005) is a call that acts on a secrets file's name, writes included (a lone env template path, such as .env.example, excepted). Mail, payments, SQL, a program that opens its own connection, and content that holds a secret without such a name are neither. The labels read what the signer can see in the arguments, deterministically. Label your own tools that send data or read secrets (label: egress / secrets_access on a flag rule) to bring them into TK-Q001. policy
(1.2) A step counts when its call is decided (allow, flag) or its approval consumed, whether or not the call then runs; a call that runs after a deny or an unapproved ask never counts as a step. Detection reads decisions, which the signer has before a call runs; a call run against its decision is executed_against_policy. Keep the server pack's executed_against_policy trigger on (shadow, notify), and read those incidents alongside sequences. policy
(1.2) A decision retried under a new request_id is a new decision and counts again. Each decide writes its own signed decision; remembering every counted call would grow the detector's state with calls. It can only over-count. Retry with the same request_id (the signer answers it from its cache); allow for client retries when you set max. policy
(1.2) An incident of a session, owner or principal scope is opened in the run whose record fired it; its incident.updated records are written in the runs whose records matched later. Every incident record is written in the run of the record that fired it, so it lands in that run's hash chain. Follow an incident by its incident_id across the runs of its scope. policy
(1.2) backtest reads the rule ids decisions recorded: for decisions made under another policy, rules and labels the new one adds or changes are not applied. Arguments are not stored, so a decision can't be made again. Heed its warning (the count of such decisions); backtest changes to sequences, limits and respond, and measure new rules by running the policy in shadow. policy
(1.2) A bundle with detect fields or incident records needs a 1.2 verifier. They are format 1.2 additions. Upgrade verifiers with the signer. format

Content vault (1.1)

Limit Why it is so What to do Details
(1.1) With content.retain on, whoever holds keys/content.key and the store can read retained content. The signer must decrypt it to answer content_get. Keep the keys dir to the signer's user (D-CONTENT-VAULT), keep retention short, erase runs you no longer need. privacy
(1.1) The content master key is a file key (keys/content.key), not wrapped by KMS, even when the log key is in AWS KMS. The KMS log key is an Ed25519 signing key, which can't wrap keys. Protect the data volume as you do the other file keys; back the key up with them. deploy
(1.1) keys/content.key has no rotation path: replacing it makes every run already in the vault unreadable (content_get answers unavailable for them). Each run's key is wrapped by the master key, and nothing re-wraps them. Keep the key for as long as you keep content; replace it only to give up everything the vault holds. deploy
(1.1) Erasure (and retention) reaches the live store only: a backup, WAL archive or replica taken earlier still holds the run's wrapped key and blobs, and opens with keys/content.key. The signer can't delete copies it doesn't hold. Keep backups and archives shorter than retention_days, or rotate content.key to cut off older copies, which today also makes every run still in the vault unreadable (no re-wrapping yet). privacy
(1.1) A decision's arguments are kept redacted: if redaction changed them, they no longer open args_commitment (content_get marks them redacted, without a salt). The same holds for a model exchange redaction changed whose tool uses carry args_commitment: no salt, so its content_digest can't be checked either. Nothing unredacted is written; the policy decided on the unredacted arguments. Use the tool result and the model exchange, which open their commitments, for what the call did. privacy
(1.1) Content over max_record_bytes isn't kept (too_large), and one content_get answer must fit the 1 MiB frame, so an item near 1 MiB can't be read. The RPC answers in one frame. Ask for fewer seqs at a time (the refusal says so); keep max_record_bytes well under 1 MiB if you need every item back. privacy
(1.1) The gateway asks the signer once whether the vault is on, needs the status grant, and sends no body over half a frame (not_retained). One status call per gateway process; the frame bounds a request. Grant the gateway status; restart it after turning the vault on or off. gateway
(1.1) Erasing a run erases the replay runs (tracekit why) the vault holds for it when it runs; a replay run that is still being written as the run is erased can keep what it records after that. Finding them reads the first record of every run with content in the vault. Replay runs copy the run's content into their own requests; the store does not index runs by what they replay. Erase a run once no investigation of it is running. privacy
(1.2.2) The dev signer keeps each call's redacted arguments and results for 7 days in its data dir, readable by your user, so the dev viewer can show them. The viewer needs the content, and the dev signer runs as you: you hold every dev key already. TRACEKIT_DEV_CONTENT=0 before the dev signer starts keeps nothing (the viewer then shows rule reasons only). privacy
(1.1) Retention counts from the first item kept for a run, not per record. A run's items share one key, erased at once. Pick retention_days for your longest runs. privacy
(1.1) content_get and content_erase reach runs of the caller's own tenant only. The tenant comes from the caller's identity. Give each tenant's investigator its own identity. privacy
(1.1) On an existing Postgres database, tracekit signer migrate adds the vault's tables but grants the signer's role nothing on them: until you do, items read back not_retained. migrate runs the schema only; grants are applied by the init script or by hand. Apply tracekit.storage.postgres.GRANTS to the signer's role after migrating (the signer's log line says so). deploy
(1.1) An item is stored just after its record: a crash or storage error in between leaves it not_retained, and a model body that isn't strict JSON (an integer past 2^53, a non-finite number, a lone surrogate) is recorded without it (the gateway sends none: not_retained). The record is never held back for its content. Treat not_retained as missing evidence, not as an empty value. privacy

Approvals

Limit Why it is so What to do Details
On the dev signer (no signer.yaml) the requester can answer its own approval. A signer started from signer.yaml refuses that unless approvals: {self_approval: allow}, and without an approvals section has no approvers at all. The shipped packs deny the agent's own tracekit approve or reject and tracekit approvals approve or reject (TK-D012), also through the wrappers and runners the shell parser reads (env, sh -c, eval, uvx, uv tool run, uv run, pipx run, hatch run, conda run, …) and as python -m tracekit (through a module runner too, -m runpy, -m trace --module, -m cProfile -m, or a path to the entry script, python3 ~/.local/bin/tracekit), as a copy or link of the entry point the same call makes and runs under another name (cp "$(command -v tracekit)" /tmp/tk; /tmp/tk …), and as a command git runs (git -c core.pager=…, GIT_EDITOR=…, rebase -x, bisect run, submodule foreach). An action the parser can't read is denied too (a positional parameter it doesn't follow into eval or sh -c or past set --, an indirect expansion such as ${!#}, a substitution's output, a pattern, an expansion with a word, a variable alone as the action that the line gives no value there, $X, $_, $OPTARG): it may be approve. After an approvals option such a word anywhere denies, as the joined words can't tell a --signer value with a space in it (--signer "/tmp/a list" "$1") from the action, so an approvals command with a variable socket path and such a word is denied too (--signer "$1" list). They don't deny code that calls the signer's approval_decide itself (python -c, a script, a copy or link of the entry script an earlier call made, run under another name), an action read from stdin (xargs tracekit) or held after approvals' options in a named variable the parser doesn't know (--signer /tmp/s "$a") or made from one it knows by an operator other than a default, alternate or replacement (D=xapprove; tracekit ${D#x} ID), an unquoted --signer value bash splits into a value and an action, a runner's own options before its subcommand (uv -q run), or a runner the parser doesn't name (hatch env run). The dev signer has no separate approver; a policy rule reads commands, not what a program does. Configure approvals: {approvers: [...]} (system mode does, and refuses the agent's own answer); self-approved answers cap assurance at dev and show approvals: self. Give --signer a literal path, or have a person run an approvals command that needs a variable one. approvals
A T1 approval binds the arguments the agent reported, and the agent's process runs the call. The adapter runs in the agent. Use approval: {executor: t2} and route the call through the tool executor or the MCP gateway, which run the approved arguments outside the agent. Adapters run the approved arguments too, but in the agent's process. approvals
Approvers answering through the web viewer or Slack are vouched for by the bridge (attested: false). The signer authenticates the bridge, not the person. Grant approval_decide_on_behalf only to bridges you run; read via on each approval. approvals, approvals
The signer takes the bridge's word for who registers a passkey, and keeps a person's first passkey. It has no proof of its own of the person behind a session. Have each approver register right after onboarding; check passkeys.json against the approver list. approvals
Break-glass answers aren't available through Slack. Break-glass needs a reason and a direct identity. Answer break-glass approvals from the CLI. approvals
After a restart the Slack bridge posts the approvals still pending again. It keeps which messages it posted in memory. Expect duplicate messages after a restart. approvals
An approval expires one hour after it was requested. Nothing should consume a stale approval. Answer within the hour, or request again. approvals
(1.5.1) A call a coding-agent hook holds (Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, OpenCode, goose, Droid, Antigravity CLI) is blocked at once: it runs only when the agent sends the same call again after a person approved it, within the approval's hour. No harness shows a hook's output while the hook runs, so a hook that waited for an answer waited for a person who couldn't know (in 1.5.0 every hold waited 8 minutes, then was blocked). Approve with the command the block names, then ask the agent to try the same call again, with exactly the same arguments (in Claude Code a Bash call's description may differ: a retry that differs only there from the session's last 32 held calls of the same command runs under the newest approval of them, recorded with the approved arguments, unless one of them was rejected or couldn't be read; it is held again when the signer redacted a secret-looking string in what it shows the approver, or a remote signer's authorize doesn't give the hook's identity approval_get, with which the hook reads the approved arguments). Where Slack, the viewer or an agent approver answers during a wait, set TRACEKIT_APPROVAL_WAIT (seconds) in the agent's environment: the hook waits up to about 480 s, as it answers within 540 s and keeps 60 s for the answer and the approval's use. held calls
(1.5.1) Cursor, Gemini CLI, Antigravity CLI, Codex and Droid get a block message in 500 characters: a longer one (most holds, as the message's lines say why, what to do instead, the look, approve and reject commands and what the agent does) ends with …. The first line (the approval id and rule ids) comes first, then the Person: line with the commands, then the reasons and the agent's line, cut from their end. A long --signer path in those commands (past about 40 characters with one rule id) pushes the reject command past the cut. With TRACEKIT_APPROVAL_WAIT, the wait's outcome comes first (NOT APPROVED, nothing ran: … rejected by …, or the hold), then the waiting line. The hook cuts what it returns to the harness to that length. Approve or reject with the commands it keeps (tracekit approvals list names every held call); the rule id names the rule, whose whole reason and remedy are in the policy (tracekit policy compile <file> prints them). held calls
(1.5.1) The hook reads TRACEKIT_APPROVAL_WAIT from the agent's environment, which the agent can change: it can make its own held calls wait (up to about 480 s) or block at once. The hook can't tell whether a Slack bridge, the viewer or an agent approver is there to answer. The wait changes only when a held call is blocked, never whether it runs: the signer decides that. Which bridges run is the signer's configuration, which the hook doesn't read. Set it in the harness's own settings (Claude Code: settings.json env) where someone answers during the wait. held calls
(1.5.1) An approved approval is used by the next call of the same run, tool and arguments that asks for one, whichever call that is: a second identical call asked while the first still waits to consume it (an agent approval's veto delay, a slow adapter) runs in its place, and the first is refused. A call sent again before anyone answered gets a new approval each time, which stays requested until it expires. A retry carries a new tool call id: matching the approval on run, tool, arguments, policy and rules is what lets it run, and one approval runs one call. Expect one call per approval. Approve any one of a call's approvals (the next retry runs) and let the others expire, or reject them. approve, then retry
(1.5.1) A retry uses an earlier call's T2 approval (executor: t2) only when its consume names it (approval_id_hint): without the hint it is refused TK-APPROVAL-REQUIRED. The signer reads its copy of the approved arguments, which a T2 consume returns, before the writer runs, for the approval it is told. Pass the approval_id that approval_request returned, as the shipped hooks do. approve, then retry
An MCP call is named by the server's own name (mcp:<server>/<tool>); an mcp 1.x session whose initialize() ran before tracekit.instrument(), or one wrapped by hand without server=, is recorded as mcp:unknown/<tool>, with a warning. The name comes from the server's initialize result, which an mcp 1.x session doesn't keep. Call tracekit.instrument() before any session initializes, or pass TracekitSession(..., server="<name>"); write rules for server-named tools knowing the server picks its name. MCP
An adapter without saved state (MCP, Browser Use, the Claude Agent SDK hook) holds a call while waiting; the wait doesn't survive the process, and a long wait ends in a denial. There is no resumable state to carry the approval. Answer within the adapter's wait; use a framework with saved state for long waits. MCP, Claude Agent SDK
LangGraph: code that catches exceptions around a gated ToolNode (a try/except Exception in a node that invokes it, a middleware outside TracekitMiddleware that turns exceptions into messages) ends an ask's pause: the model gets an error, the call doesn't run, and its approval expires. The node's own handle_tool_errors and .with_fallbacks() let the pause through. LangGraph pauses by raising GraphInterrupt out of the node; code that catches it ends the pause before LangGraph sees it. Re-raise langgraph.errors.GraphBubbleUp before any broad except, or put the error handling in the ToolNode (handle_tool_errors, .with_fallbacks()). LangGraph
A Browser Use action waits for an approval at most five sixths of Browser Use's action timeout (150 s of 180 s); then the approval is withdrawn and the action refused. Browser Use cancels an action that outlives its timeout, approval wait included, with a misleading "dead CDP WebSocket" error. Answer within the wait, or raise BROWSER_USE_ACTION_TIMEOUT_S (and the Agent's step_timeout) to give people longer. Browser Use
OpenAI Agents' LocalShellTool and ApplyPatchTool can't wait for an approval: an ask for them is refused. The SDK gives no approval hook for them. Allow or deny them by policy. OpenAI Agents
v1 approvals name the held call, not its exact arguments. v1 approvals predate argument binding. Use the v2 signer, which binds approvals to the exact arguments. laptop threat model
(1.2) The agent-approvals kill switch (approval_agents) is signer-wide: switching it off stops and revokes agent approvals for every tenant. It protects the signer from a misbehaving reviewer, which may serve several tenants. Grant approval_agents only to the signer's operators, not to one tenant's. approvals
(1.2) An agent approver's bounds bind the approval, not the execution, unless the rule has executor: t2. Under T1 the agent's own process runs the call with the arguments it holds. Put executor: t2 on agent rules, above all on money-moving ones (tracekit policy lint warns), and run held calls in a worker that executes what approval_consume returns. approvals
(1.2) A reviewer agent's judgment is model output: within the bounds, the requesting agent can steer it. It reads arguments the requesting agent chose. Set bounds you would accept every call inside of; start in mode: shadow and compare its suggestions with your people's answers. approvals
(1.2) The untrusted-value floor relies on an honest adapter's trust labels: content the adapter reports as trusted (or never reports) does not send a call to people. observe's trust is the caller's claim, and only untrusted tools' results are indexed. List every tool whose results come from outside in the policy's untrusted, and observe outside content as untrusted. policy
(1.2) Budgets and review caps are counted per signer: replicas that each write their own log multiply them. Each signer counts the agent approvals in its own records. Divide budgets by the number of replicas, or route a tenant's runs to one replica (route). approvals
(1.2) An agent approval under a sum budget records the value it took (spent) in the clear. The budget is rebuilt from the signed records, which otherwise hold commitments only. Use sum on amounts you are fine to see in a bundle; use count alone otherwise. approvals
(1.2) Anti-shopping matches the same arguments or the same tool call id: a call with one argument changed is a new call an agent may answer. Any other match would need a notion of "near" arguments. Rely on the bounds and budgets; a run gets at most 10 agent reviews and a tenant 1000 an hour, then people answer. approvals
(1.2) After a signer restart, calls of runs registered before it go to people. The provenance index lives in memory, so their provenance is unavailable. Expect more person answers right after a restart; new runs are not affected. approvals
(1.2) The verifiers can't check an agent approval's argument bounds. The records hold the arguments only as salted commitments. Read the approvals by agents line as "bounds the signer checked"; to audit one, tracekit signer reveal --record <seq> and recompute its commitment from the arguments. verdicts, privacy
(1.2) Without the policy snapshot of the decision's policy_hash in the bundle, the verifiers don't check that the rules permitted agents (a warning: agent approval bounds unchecked). tracekit export --v2 bundles the policy an agent approval's decision cites from the signer's <data_dir>/policies, where the signer writes each policy it starts with; an export with another data dir (another replica, a copied store) or after that file was removed has none. Export with the signer's config; keep <data_dir>/policies with the store, or check the old policy file's hash by hand. verdicts
(1.2) An approval an agent's answer can decide (enforce mode) reaches people (Slack, the desk's "for people") only once it is escalated: with no agent answering, after agent_timeout_s (default 600 s). The signer gives the agent approver that long to answer first. Keep the reviewer running on every replica; lower approvals.agent_timeout_s for faster handover; approval_agents {enabled: false} hands every pending one to people at once. approvals
(1.2) The reference reviewer sends the redacted arguments of the tenants it serves to a model provider. Judging a call means reading it. List in its tenants only tenants that accept this; see privacy. approvals
(1.2) The reference reviewer keeps which approvals it answered in memory: after a restart it answers a shadow-mode approval still pending again (a second approval.suggested). Shadow answers leave the approval listed for agents. Count suggestions per approval id when comparing; enforce-mode answers are not affected (the signer refuses a second one). approvals
(1.2) tracekit reviewer eval judges views without arguments. Past arguments are in no record (salted commitments) and the signer deletes its copy once an approval ends. Treat eval as a first check of the prompt and the rules; measure on live traffic with mode: shadow, where the view is complete. approvals
(1.2) Each review registers a run of its own on the signer (the reviewer's run identity), one per approval. The model call is evidence too, linked to the approval it judged. Size the signer's run quotas for one extra run per agent-answered approval. approvals
(1.2) An agent's approval runs only within agent_consume_s (and after veto_s); an adapter that waits longer gets TK-APPROVAL-EXPIRED. An unconsumed agent approval should not wait for a better moment. Consume right after approval; raise approvals.agent_consume_s for slow adapters. approvals
(1.2) The verifiers check who answered an approval and that an agent's answer stays within its bounds, not the order of the approval's records: an agent answer after approval.expired or after another agent's rejection, a consume after approval.revoked, or a consume outside not_before/consume_by still verifies. The signer enforces each of these when it happens; the offline check of their order is not built yet. Read an approval's records in order (tracekit approvals show, the viewer) when a veto or an expiry matters. approvals
tracekit approvals show doesn't say when the call was requested, or its record's seq, and gives a held call's why and what to do instead only from a policy on this machine whose hash the approval records: a shipped pack, or one the dev signer kept. With a signer whose policy file is elsewhere (system mode, a remote signer) it names the policy's hash instead. approval_get returns neither time nor seq, and returning them is a new RPC version; the hold's reason is in the decision the hook got, not in the approval. tracekit view --approval ID (with the viewer's --config or --data-dir) opens the held call's record, with its time; the block message the agent got has the why and the Instead step; tracekit policy compile <file> prints a policy's reasons. coding agents

Custody (1.2)

Limit Why it is so What to do Details
(1.2) An approval the executor or MCP gateway stopped waiting for stays requested until it expires (an hour): a person may still approve it, and it runs only if the agent sends the same call again through the same gateway (the same tool_call_id, or (1.5.1) a new one with the same tool and arguments: approve, then retry). The gateway holds the call, and approval_abandon is the agent's call, which may not touch a held one. Reject approvals whose caller has given up (the viewer shows the request's age); keep approvals.ttl_s short where agents retry. executor
Custody covers only the actions routed through the tool executor, the MCP gateway, the LLM gateway and the A2A gateway. An agent that holds a credential, or can reach an API itself, can act around them. Keep the credentials only in those services and fence the agents' egress (agentEgress in the central chart). executor, MCP gateway, A2A gateway, Kubernetes
(1.5) The A2A gateway does not see push notifications an A2A server sends outside it. The receiver opens that connection to the URL in a message's configuration; the gateway sees only requests sent through it. Read state through message/stream or tasks/get (the gateway refuses a message carrying a push notification config) and fence receiver egress. A2A gateway
(1.5) The A2A gateway relays only message/send, message/stream and tasks/get. Each method needs its own decision and record. Cancel or resubscribe directly only if unrecorded access is acceptable, or request support for the method. A2A gateway
(1.5) A cut A2A stream has no tool.result; its held_call_unresolved gap is written only at run end. The gateway cannot know how the task continued, and the signer finalises open gateway calls at run finalisation. Read a final run and use tasks/get through the gateway for state. A2A gateway
(1.5) The A2A gateway reads each Agent Card once, at start. Re-reading on every message adds a round trip and would let a card change mid-run. Restart the gateway when a card changes. A2A gateway
(1.5) A2A messages name no skill; rules see the skills the card offers. The protocol has no requested-skill field. Allow-list skills and route. A2A gateway
(1.5) The A2A gateway retains at most 1,024 task and context ids per caller and 1,024 callers. An evicted id cannot be read or continued through the gateway. Use the task before the bound is exceeded, or retain its state elsewhere. A2A gateway
(1.5) The A2A gateway checks task ownership only for tasks/get's id and messages' taskId, contextId and referenceTaskIds; it forwards free-form params.metadata unchanged. Metadata is outside the gateway's task-reference check. Do not put a receiver that reads task references from metadata behind the gateway, or deny it with an A2A rule such as field: target, pattern: '"metadata":.*"(taskId|contextId|referenceTaskIds)":'. A2A gateway
(1.5) A transfer is recorded only when code calls run.transfer or tracekit.integrations.c2c.fuse. A direct in-process hand-off crosses no capture layer. Route every transfer through one of those calls. latent transfers
(1.5) Transfer fields are the caller's claims or measurements as marked. The payload remains in the calling process; the signer cannot check the claimed or measured values. Pin route and measured weights in policy; retain a copy where appropriate. latent transfers
(1.5) Transfers are Python-only while experimental; the TypeScript SDK has no transfer. The first integration follows Python C2C research code. Record transfers with Python RunHandle.transfer or tracekit.integrations.c2c. latent transfers
The agents' egress NetworkPolicy is off by default, and enforced only by a CNI that enforces egress policies. Turning it on cuts every other connection the agents make; some CNIs ignore egress rules. Set agentEgress.enabled once the agents need nothing else, on a CNI that enforces egress (Calico, Cilium, ...); test it from an agent pod. Kubernetes
The executor and the MCP gateway fail closed: with the signer unreachable nothing runs, whatever the run's fail modes. They exist to make an action impossible without a record. Keep the signer available; the agent gets 503 or an isError result saying so. executor, MCP gateway
A result the executor or the MCP gateway can't record after the call ran still goes to the agent. Withholding it would make the agent retry an action that already happened. They try twice, then say on stderr which call and run; keep the signer reachable. A run that closes with such a call still out waits up to gateway_wait_s (default 600 s) past its grace window for the result; then the signer writes a held_call_unresolved gap for the call and the verifier warns (held calls). executor
A run with a call the executor or the MCP gateway is still running reaches run.final up to gateway_wait_s (signer config, default 600 s, the MCP gateway's upstream timeout) after it closes. The service may still record the call's result, which a final run would refuse. Lower gateway_wait_s to the longest upstream timeout of your gateways if runs must finish sooner. executor
The events a gateway (the executor, the MCP gateway, the LLM gateway, the OpenShell middleware, the ext_mcp processor) writes for an agent count against the gateway's rate for that agent (limits.events_per_s, burst), its approval waits against its concurrent_waits for that agent, and the runs it registers for one (the OpenShell middleware's, one per sandbox) against its open_runs for that one; the result of a call it decided counts against nothing. A gateway's total is the per-agent limit times the agents it serves, but for open runs at most limits.gateway_open_runs (10,000) of its own and those it registered for all its agents together (1.4); a suspended agent gets no run through a gateway either. So an agent can't spend the budget its service's records need, nor one agent what the service's other agents need, and a call's result is never refused for rate once its decision was taken. The agent a gateway names is its word, so a cap of its own keeps a gateway naming made-up agents from opening runs without end. Size limits for one agent's traffic through a gateway, and gateway_open_runs for the runs one gateway keeps open at once; list only gateways you run under gateways. executor
A call the executor or the MCP gateway decided is theirs, for the identity they decided it for: the agent's own decide, approval_request, approval_consume, approval_abandon and complete on its tool_call_id, or the service's for another identity on the run, are refused (forbidden), and the executor refuses a tool_call_id the agent decided itself. An approval of such a call can't be abandoned; it expires. Otherwise the agent, holding its run token, could record a forged result or ask for the approval in its own words for a call made with credentials it doesn't hold. Leave an unanswered approval to expire. The adapters leave the tools the executor helpers build to the executor (the Claude Agent SDK hooks: in Python, the actions of the server executor_tools.claude_agent_sdk built, by exact name; in TypeScript, the executorActions you name, of the in-process server you put under tracekit-executor; in both, when you hand the hooks the same mcp_servers); keep a tool you build yourself that calls the executor out of the adapters (in TypeScript, out of executorActions). executor, approvals
The executor takes only letters, digits and . _ ~ - (not all dots) in an {arg} of an action's URL path. A slash, backslash or dot segment, even percent-encoded, can leave its segment once a proxy decodes the path. Put other values in the query (?q={q}, quoted whole) or the JSON body. executor
The MCP gateway's trusted makes each resource of those upstreams count as trusted content, which provenance doesn't hold calls for. Prompts are always recorded untrusted. A resource anyone can write (an issue, a page, a mail) can carry an injected value; a prompt template echoes the agent's arguments. List in trusted only upstreams whose content neither the agent nor outsiders can write. MCP gateway
A stdio MCP upstream runs as the MCP gateway's uid, so it can read every other upstream's secret files and the gateway's signer credential. The gateway starts it as a child process with its own permissions. Run one gateway (its own identity and secrets) per stdio upstream you don't trust fully; pin each command to an exact version (npx -y pkg@1.2.3) or install it in the image. MCP gateway
A gateway's or executor's call for an agent is authorized as the agent's scheme:subject alone: authorize entries for an OIDC person or group don't match it, and harness binding doesn't apply to it. The service names the agent by caller, which carries no claims, and authenticates it itself, away from the agent's process. Grant agents that call through these services by scheme:subject in authorize; rely on the service's own authenticators, not harness binding, for who may call it. executor
The MCP gateway lists the first page of each upstream's tools, resources and prompts, reads only resources it listed, and relays no server-initiated messages. It answers each request with one JSON response and keeps no session. Keep upstreams' lists to one page; list resources before reading. MCP gateway
Credentials are cut only as configured: the executor and the MCP gateway replace each secret value of at least 8 characters (of a <scheme> <credential> value also the credential, of a Basic one its user:password and password) in the decoded string values they answer and record, in its JSON-escaped, percent-encoded and HTML-escaped forms too, but not a value shorter than that or one an upstream otherwise encodes or transforms (base64, a hash, another case, split across fields). A header value must be one line of printable ASCII. They match exact strings: a short value ("1", "info") would cut every answer. The line rule keeps a value out of the errors HTTP libraries raise. Use credentials of 8 characters or more and upstreams that don't echo them; put values that aren't secrets in settings, which are never cut. The services refuse to start on a header file that breaks the line rule and name the file. executor, MCP gateway
The MCP gateway neither lists nor calls an upstream tool whose name starts with prompt:. Prompts are decided as mcp:<upstream>/prompt:<name>, so such a tool would be decided under a prompt's name. Rename the tool in the upstream. MCP gateway
The LiteLLM guardrail decides only the MCP tool calls the LiteLLM proxy runs (pre_mcp_call). Tool calls the model returns through LiteLLM's chat, responses or messages endpoints, and MCP listings, resources and prompts, pass undecided. The agent runs the model's tool calls, so only its side can decide them and record their results; the guardrail sees MCP calls through LiteLLM's hooks. Gate the agent's own tools with a framework integration and record model exchanges with the LLM gateway; keep the MCP servers reachable only through LiteLLM. LiteLLM
The LiteLLM guardrail takes the agent's identity from tracekit_caller in the metadata of the LiteLLM key: whoever can edit a key's metadata decides which identity its requests act as. LiteLLM passes request headers, X-Tracekit-Run included, to its logging callbacks. LiteLLM authenticates the key, not the agent's Tracekit identity, and treats key metadata as admin configuration (its guardrail opt-outs live there too). Keep agents' keys away from LiteLLM's key management routes; a run token read from the logs works only for the identity it was issued to. LiteLLM
The LiteLLM guardrail records a result when LiteLLM logs the call: an MCP call answered with an interim input-required result, or one that raised in a no-log request, keeps its decision open (held_call_unresolved at run end). A pre_mcp_call guardrail listed after Tracekit's that rewrites the arguments changes what runs after the decision. The result comes through LiteLLM's logging hooks, and LiteLLM runs guardrails in the order configured. List tracekit last among pre_mcp_call guardrails; read held_call_unresolved gaps on runs whose MCP servers ask for input. LiteLLM
An ask at the LiteLLM guardrail holds the MCP request, and a thread of the proxy's default executor, for up to approval_wait_s (default 300 s). An MCP client that times out sooner gets no result, though the call may still run once approved; an approval the guardrail stopped waiting for stays requested until it expires, as at the MCP gateway. The guardrail waits inside LiteLLM's pre-call hook, which LiteLLM awaits before it runs the call. Set the MCP client's request timeout above approval_wait_s, or lower approval_wait_s; reject approvals whose caller has given up. LiteLLM
In the compose stack the custody services' signer identities are uids on the socket the agent container mounts too: an agent container running as root, or keeping the SETUID capability, could connect as one of them. The signer has one socket and identifies its peers by uid. Run agent containers as a non-root user with cap_drop: [ALL] and no-new-privileges (as the example agent service does), or deploy on Kubernetes, where each service has its own service-account identity. executor
The agents' egress NetworkPolicy allows DNS to kube-dns, which a DNS tunnel can use, and doesn't allow a NodeLocal DNSCache (169.254.20.10), so DNS fails where one runs. Agents need name resolution; the chart can't know the cluster's DNS layout. Filter DNS (a DNS-aware policy such as Cilium's, or an allow-list in CoreDNS) where tunnelling matters; with NodeLocal DNSCache add an egress rule for 169.254.20.10/32 port 53. Kubernetes
Agents need a projected service-account token per custody service in the central chart, of that service's audience (<audience>-<name>), besides the signers'. A token a custody service receives must not be one the signers take. Mount one projected token per service the agent calls; see the example. Kubernetes
With an LLM gateway on the same run (or an integration that records the model's messages), each MCP gateway or agentgateway ext_mcp processor call, and each executor call made without the model's tool-use id that the signer can't pair with the model's call by arguments, reconciles as reconcile.fabricated (plus reconcile.hook_missing with the gateway). They decide under an id of their own: MCP's tools/call carries no tool-use id, and a LangChain or Claude Agent SDK tool handler gets one only from the Tracekit adapter (the LangChain middleware, the Claude Agent SDK's tracekit_hooks). Read such a pair as one call through the gateway or the executor (the decide's source is gateway); run the executor helpers under the Tracekit adapter, or pass tool_call_id where the framework exposes it, as the OpenAI Agents and Vercel AI helpers do. executor, MCP gateway
The MCP gateway holds one session per upstream, shared by every agent and run; one that went away is opened again by the next call, and a call in flight when it went away answers upstream error and may have run. It opens each upstream once and keeps it; it can't tell whether a call cut off mid-flight ran. Run one gateway per tenant when an upstream keeps per-session state; check an upstream error call's effect before making it again. MCP gateway
agentgateway's ext_mcp processor can't hold a call for a person: an ask is refused after 5 s, and passes only when the agent makes the same call again (same run, caller, tool and arguments) after a person approved it. A processor restart forgets pending asks, so the retry asks again. agentgateway gives a processor 10 s per call. Tell the agent to retry a call refused with approval requested once it is approved; approve with tracekit approvals. agentgateway
agentgateway's ext_mcp processor decides only tools/call: resources/read, prompts/get and the other MCP methods go through agentgateway undecided and unrecorded. The processor speaks for tool calls; a resource or prompt read isn't a call the policy has a class for. List only tools/call in the processor's methods, and put MCP servers whose resources or prompts matter behind Tracekit's MCP gateway instead. agentgateway
A tools/call agentgateway answers with a JSON-RPC error gets no result from the ext_mcp processor, and neither does one whose result comes back without tracekit_call or after a processor restart: its run ends with a held_call_unresolved gap for it. agentgateway's response hook skips errors and carries no call id of its own. Keep the tracekit_call metadata entry in agentgateway's config (the processor says on stderr when a result names no call it passed); read such a gap as a call that may have failed or run; agentgateway's spans (mcp.error.code) show which failed. agentgateway
The ext_mcp processor's records are T2 only if the agent reaches its MCP servers only through agentgateway and can't connect to the processor. It listens on loopback without TLS and takes the caller and the results it is sent as agentgateway's. It can't authenticate agentgateway, and it knows the agent only from agentgateway's metadata. Run it in agentgateway's pod or on its host, never where the agent runs; fence the agent's egress to MCP servers; build caller from what agentgateway authenticated (source.spiffeId, jwt.sub), never from a header. agentgateway
agentgateway forwards the agent's headers, X-Tracekit-Run included, to HTTP MCP servers on every request but a tools/call the ext_mcp processor passes, whose answer removes it. It passes client headers through to its targets, and only tools/call reaches the processor. None needed: a run token is bound to the agent's identity and is no use without the agent's credentials. agentgateway
A Wassette permission grant approved through the MCP gateway stays in effect after the call: every later call of that component, from every agent and run behind the gateway, has it, after restarts too, until it is revoked. Wassette saves permissions with the component, not per run or caller; the approval covers the grant call. Serve a fixed tool set (--manifest, --disable-builtin-tools); otherwise run one Wassette per tenant and revoke grants (revoke-*-permission, reset-permission) when the work is done. Wassette
Tracekit doesn't see what a Wassette component does inside Wassette, or permissions set outside the MCP gateway (the manifest, the wassette permission command, a component's policy file, an MCP client connected to Wassette directly). The manifest isn't signed into the run. Only calls through the gateway reach the signer. Let only the gateway reach Wassette (on loopback, on the gateway's host), and keep its manifest and component directory writable only by whoever deploys it. Wassette
A Wassette component's own failure (a host its permissions don't allow: {"err":"ErrorCode::HttpRequestDenied"}) is recorded as an ok result. Wassette returns it in a normal result, isError false, and the gateway records the status the upstream gives. Read the result, not only its status. Wassette
The TypeScript executor helpers cover OpenAI Agents and the Vercel AI SDK, not the Claude Agent SDK. Its tool() takes only a zod shape, and actions declare JSON Schema; converting needs a dependency. Write a tool() per action with its zod shape whose handler returns action.call(args). executor
OpenAI Agents' shell and apply_patch tools don't run the signer's copy of T2 arguments; function tools do. They run the SDK's action object, which the gate read just before it runs. Route such actions through the executor if they need T2. approvals
The Codex, Cursor, Gemini CLI, OpenCode, Qwen Code, Factory Droid, Antigravity CLI and Crush hooks can't replace a call's input: under T2 they run the arguments the signer consumed, which it checked against the approved ones. Those integrations take no updated input from Tracekit's hook; Qwen Code, Factory Droid, Antigravity CLI (overwrite) and Crush (updated_input) would, but Tracekit sends it only to Claude Code. Use Claude Code or the executor where the approved copy itself must run. approvals
Crush runs every PreToolUse hook at once on the call's input, then applies each one's updated_input in config order before the tool runs, so another hook (the person's, or one in a project's crush.json, .crush.json, crushrc or .crushrc, which Crush loads from the repository) can change a call's arguments after Tracekit decided it; the record shows the arguments Tracekit decided. A deny from Tracekit's hook still blocks the call. Crush merges its hooks' answers itself (internal/hooks/hooks.go, aggregate), and no hook sees another's patch. Keep Tracekit's the only PreToolUse hook that returns updated_input, check a repository's Crush config before running Crush in it, or use the MCP gateway or the executor where the decided copy must be the one that runs. coding agents
OpenCode passes one output.args through every plugin's tool.execute.before in turn, so a plugin that runs after Tracekit's can change a call's arguments after Tracekit decided it; the record shows the arguments Tracekit decided. The plugin API lets each plugin edit the same arguments, and Tracekit can't see what a later plugin does. Keep Tracekit's the only plugin that edits tool arguments, or use the MCP gateway or the executor where the decided copy must be the one that runs. coding agents
The OpenShell middleware decides only the HTTP requests OpenShell allows to the hosts its policy entry includes, and their responses: not other hosts, not traffic OpenShell can't inspect as HTTP, and not WebSocket messages; without its OCSF import, OpenShell's own network-policy decisions aren't in the run either. A WebSocket upgrade is decided, but its call never completes, so the run ends with a held_call_unresolved gap for it. OpenShell selects middleware by destination host and passes it only the HTTP it inspects; the middleware doesn't take WebSocket messages, and OpenShell runs no response middleware on an upgrade. List every host the sandbox's network policy allows under the entry's endpoints.include, keep on_error: fail_closed, and turn on the OCSF import (ocsf) to record OpenShell's own blocks. OpenShell
A request the policy asks about is denied at once (tracekit_approval_required); it runs only when the agent sends the same request again after a person approves it. A retry that changes a header (a trace or idempotency id) is a new request and asks again. OpenShell waits for a middleware's answer at most 30 s, and the approval is bound to the exact request. Approve with tracekit approvals approve, then let the agent retry; where asks matter, use clients that send the same headers on a retry. OpenShell
The OpenShell middleware denies a request whose body isn't UTF-8 text (gzip, protobuf, a binary upload) or is over 512 KiB (tracekit_body_unreadable), whatever the policy, and the run has no record of it (the middleware prints it on stderr). A text body over 64 KiB is denied by every rule that reads the whole call (TK-OVERSIZE, the server pack's secret rule among them). The policy decides on what it can read; a decision on a body's digest would let a compressed or padded secret through the content rules. Send request bodies as uncompressed text under 64 KiB to the hosts the middleware's entry includes; route a host that needs binary uploads through another policy entry, where OpenShell's own policy governs it. OpenShell
A response body OpenShell doesn't offer to middleware (compressed, partial, bodyless, no-transform), a binary one or one over 512 KiB completes its call with a digest. Under a policy that lists http_request as untrusted (the server pack), that makes the run's provenance index partial, and from: untrusted rules then hold every request that sends data. The signer can index only content it receives. Have the agent's HTTP client ask for uncompressed responses (Accept-Encoding: identity) where provenance rules matter. OpenShell, policy
Without gateway_jwt the OpenShell middleware takes any peer that reaches its address for OpenShell, so it refuses to listen beyond loopback unless allow_unauthenticated: true. With it, an OpenShell token is a bearer credential until it expires (an hour at most), and one gateway's key signs every sandbox's. OpenShell authenticates extension calls with a short-lived EdDSA token only, and sends none over allow_insecure_transport. Set gateway_jwt (the gateway's gateway_jwt.gateway_id, its public key, the registration's audience) with tls; never include the middleware's address in a sandbox's network policy. OpenShell
At most 64 responses stream through the OpenShell middleware at once, shared by every sandbox: one sandbox's slow downloads can hold all 64 (OpenShell's deadline is per exchange, not per stream). One more is refused (RESOURCE_EXHAUSTED), which OpenShell handles by the entry's on_error (fail_closed: the sandbox doesn't get that response), and its call ends as a held_call_unresolved gap. Each open response stream holds a thread; the threads kept for request evaluations must stay free, or every sandbox's requests would wait. Keep hosts the sandboxes download large or slow responses from out of the middleware's endpoints (another policy entry); the middleware prints each refused response on stderr. OpenShell
The OpenShell middleware speaks supervisor-middleware protocol 1.0 only. It refuses OpenShell before 0.1.0 (NemoClaw pins 0.0.116) and any other protocol version, and the OpenShell gateway then doesn't start. OpenShell's middleware API is still changing; a version the middleware doesn't know may change what a message means. Run OpenShell 0.1.0 or newer; upgrade Tracekit when OpenShell changes the protocol version. OpenShell
The OpenShell middleware keeps each sandbox's run, its held approvals and its open requests in memory. After a restart a sandbox gets a new run, a request approved before it asks again, and the response to a request allowed before it isn't recorded (that call ends as a held_call_unresolved gap). Replicas behind one endpoint each register their own run per sandbox, and with ocsf replicas under one signer identity stop each other's OCSF import (the signer refuses the process another took over from, conflict). The run tokens never leave the process. Restart it rarely and run one replica per endpoint; read a sandbox's runs together (their ids start openshell-<sandbox id>-). OpenShell
The OCSF import's calls count against the middleware's own event rate (limits.events_per_s, burst: 200 a second by default), one budget for every sandbox's events, not one per sandbox as its calls have: around 100 busy sandboxes spend it, and then OpenShell's batches are refused (UNAVAILABLE) and sent again, and those it gives up on become its gap records. The import is one observer, the middleware's identity; its effects are attributed to the sandboxes' runs only by their run tokens. Raise the middleware identity's limits in signer.yaml with the number of sandboxes; read a run's observer_lost gaps for what was dropped. OpenShell
OpenShell's OCSF events are recorded as OpenShell reports them: a supervisor or gateway that reports falsely is believed. One bearer token authenticates the gateway and every supervisor, so an event's sandbox is the one the sending OpenShell component names. OpenShell's OCSF export carries only the collector headers its gateway is configured with, the same for every supervisor, and its events are unsigned. Set ocsf.token_file with tls; read OpenShell's events as its report, beside the requests Tracekit decided itself. OpenShell
The OCSF import records OpenShell's network, process and policy-change events only. Other classes (SSH, authentication, detection findings other than a fail_open bypass, which is a signed gap, application lifecycle, base events), network events that neither allow nor deny, and events naming no sandbox are counted on the middleware's stderr, not recorded. OpenShell reports its sandbox's entrypoint, not each process the agent starts. Tracekit's records have no form for those classes yet; OpenShell's process events cover only what it starts. Keep OpenShell's own OCSF JSONL output ([openshell.gateway.ocsf_log], ocsf_json_enabled) for the rest; run a kernel sensor to see every process. OpenShell
OpenShell's OCSF export is best-effort: it drops events when its queue is full or a batch fails four times (its next batch reports how many, which becomes a signed gap), and events lost while it shuts down get no report. A sandbox whose export stops is noticed only once the middleware has decided one of its requests, 60 s later. OpenShell counts its own drops but numbers no events, so a loss it doesn't report can only be inferred from silence; every request the middleware decides is one event OpenShell should send. Keep the middleware and the signer reachable from every supervisor; read a run's observer_lost gaps before trusting the absence of a block. OpenShell
The OCSF import covers only the runs the middleware registered (the sandboxes'): when the middleware stops or restarts, each of those still open gets an observer_lost gap; other runs of the tenant get none. An event for a sandbox whose run the signer already closed (idle_s) is an effect_outside_run gap in the tenant's run tracekit/signer, until the sandbox's next request opens a new run. The import names the middleware's identity as its one caller (callers), so it covers that identity's runs alone; the middleware learns that a run closed only from its next call for that sandbox. Set idle_s above the sandboxes' quiet periods. OpenShell
Behind the MCP gateway, Docker's MCP Gateway with its dynamic tools on (mcp-find, mcp-add, mcp-exec, code-mode and others) adds servers and runs other tools from inside one call, which Tracekit decides as that one call. So does a coding agent's hook when Docker's gateway is the agent's own MCP server: mcp-exec is decided by its own name, so a rule for the tool it runs (TK-A044's send_money) doesn't apply. Docker's gateway makes those calls itself; the MCP gateway and the hooks decide only the call they see. Start each Docker upstream with --servers=<server>, which turns them off (or docker mcp feature disable dynamic-tools). Docker MCP Gateway
Every server behind one docker mcp gateway run upstream is decided under that upstream's name (mcp:<upstream>/<tool>), so rules keyed on the server (mcp:fetch/*) don't tell them apart. The MCP gateway names a call by its upstream, and Docker's gateway doesn't prefix its servers' tools by default. Give each Docker server its own upstream, named after the server. Docker MCP Gateway
The MCP gateway doesn't cut the secrets Docker's MCP Gateway gives its servers from what it answers and records, and doesn't see the image, mounts or network a call ran with. It knows only the env and headers values in its own config; Docker keeps its secrets and containers to itself. Keep Docker's --block-secrets on (the default): it refuses a call whose arguments or text result look like they carry a secret. Docker MCP Gateway
An agent that can use Docker (the docker group, a mounted Docker socket, Docker Desktop as its own user) can start Docker's MCP Gateway itself and call its servers around Tracekit. Custody covers only the calls routed through the MCP gateway. Run the agent as a user without Docker access, and the MCP gateway as one with it. Docker MCP Gateway
Docker's MCP Gateway's OpenTelemetry spans (mcp.tool.call) aren't imported as tool calls: the OTLP import counts and skips them. They carry Docker's own attributes (mcp.tool.name, mcp.server.name), not the conventions the import reads, and no arguments or results. Record Docker's tool calls through the MCP gateway. Docker MCP Gateway

Egress observation (1.2)

Limit Why it is so What to do Details
The egress observer sees hosts, ports, byte counts and times, never paths, headers or content: a call to an explained host can still carry anything. It doesn't intercept TLS, so it never holds the agents' traffic in clear or a CA they would have to trust. Route actions whose content matters through the executor or the MCP gateway; read effect.observed as where the run went, not what it sent. egress
Attribution by identity (no run token in the proxy URL) gives an observation to the identity's latest open run, which is ambiguous when one identity runs several at once. The record says attribution: identity. The proxy knows who connected, not for which run, unless the client says so. Set HTTPS_PROXY=https://<run_id>:<run token>@... per run (attribution: token); in system mode one agent user runs one session at a time. egress
posture (network: enforced, tool_calls: enforced) and gateway_mandatory are what the operator asserts in signer.yaml: run.registered records them with attested: false, and the matrix's enforced for model calls, tool calls and network rests on them (asserted). Without tool_calls: enforced, tool calls are at most reported, even when every decision came through the executor or the MCP gateway. The signer can't see the cluster's network policy, where provider keys live, or whether the agent has another way to act than the calls it saw. Back it with the central chart's agentEgress NetworkPolicy on a CNI that enforces egress, keys only in the LLM gateway, agents with no tools of their own, and test each from an agent pod. egress
A host only explains covers (CDNs, redirects, package indexes) is reconcile.unexplained_effect until it is listed, so a fresh deployment sees many. The server pack only notifies on them (shadow). The signer knows the hosts of http calls, not what a shell command or a library contacts beneath them. Tune the policy's explains from the warnings (the detail names the host) before you set unexplained_effect to enforce. egress
An explains host glob over a public suffix of two labels (*.co.uk, *.github.io) passes lint and explains every host under it, whoever holds it. Lint only requires a dot and two or more labels after the last wildcard; it has no public suffix list, and explains is the operator's own policy. Write the narrowest host you mean: the hosts themselves, or a suffix one owner holds (*.cdn.example.co.uk). egress
A laptop without Linux system mode's --egress has no observer: its network is reported (http calls) or not covered. --egress needs Linux with iptables' owner match; macOS has none. Only a rule outside the agent's user can force its traffic through the observer. Use system mode's init with --v2 --egress on Linux, or run agents on a server deployment behind the egress observer. egress
An observer covers the runs of its tenant registered while it is alive, and which runs it covers lives in the signer's memory: a run registered before its first heartbeat, or open across a signer restart, is not observed. After a restart with no snapshot since, a run's earlier http calls no longer explain a host. The heartbeat watch is the transcript tailer's, which keeps no state in the log. Start the observer before the agents; re-check runs that span a signer restart. egress
A run an observer covers reaches run.final up to observe_grace_s (default 120 s) after it closes; an observation after that goes into the tenant's signer run as effect_outside_run, not reconciled. The observer reports each minute once it ends, at its next heartbeat; a final run takes nothing more. Raise observe_grace_s if effect_outside_run gaps name late runs; export them with --run-set. egress
One attribution (a connection's identity, else its run) has at most 64 tunnels open through the egress proxy at once; one more is closed before it reaches its host. On Linux a loopback client's uid has at most 64 connections open, counted from accept, handshakes included, and every client sends what attributes it within 5 s. The proxy takes at most 256 connections per client address: in Linux system mode every agent connects from loopback, and each uid keeps the others' share; elsewhere (no uid to read, or one address for many sandboxes) one client's half-open connections can still take that address's 256, each for 5 s. So one agent can't hold every connection its address may open, which would lock the other agents out. Reuse connections (HTTP keep-alive, HTTP/2) in agents that open many at once; run agents that need more under identities of their own; give each untrusted client an address of its own. egress
The proxy reads the server name from the ClientHello's first TLS record only, knows the public DNS-over-HTTPS endpoints by name only, and lets an allowed host through with no SNI check (any protocol). A split ClientHello is rare; DoH on another host is HTTPS to that host, which is recorded as such. Keep allow to the hosts that need it; DoH elsewhere shows as traffic to its host. egress
Only connections made with a run's proxy_env (proxyEnv) carry its token: the SDKs never set the agent process's own HTTPS_PROXY, so its in-process connections reach the observer only when the deployment proxies them, attributed by identity (see the next row). Proxy settings are per process and its clients read them once; the run token is per run, and one process can hold several runs. Give run.proxy_env to the commands each run starts and to the HTTP clients it uses; set the agent's HTTPS_PROXY in the deployment for the rest, with the signers and custody services in NO_PROXY. egress
The executor and the gateways reach their upstreams directly, not through the observer: their calls are recorded at T2 already, and the agents' NetworkPolicy doesn't restrict them. Their records name each call's host; an MCP gateway's upstream sessions are shared by every run, so no one run token fits them. Read their records for where they went; restrict their own egress with the cluster's network policy. egress
A host the observer's allow doesn't list must resolve to public addresses only: a name resolving to a loopback, private or link-local address is refused (403), internal services included. Otherwise the proxy would open the agents' way to everything only it can reach (cluster services, cloud metadata). Add internal hosts agents may reach to allow, or to the agent's NO_PROXY when it reaches them directly; the 403 names the address. egress
An observer covers only the runs of its own tenant (signer.yaml tenants). Its observations are written as its tenant's records. Run one observer per tenant. egress
An observer that heartbeats after a run closes and then dies before its next report leaves the run network: observed with no observer_lost gap: the totals of its last minute, before the close, are lost. Coverage rests on heartbeats; a beat inside observe_grace_s counts as covering the run, and nothing marks that the last minute's report followed. Keep observe_grace_s at 90 s or more (two report intervals), run the observer under a supervisor that restarts it, and read a short-lived run's observed network with this in mind. egress
Attempts the proxy refuses (a raw IP, a private or metadata address, a DNS-over-HTTPS endpoint, an SNI mismatch, a name that doesn't resolve) leave no signed record; only the agent sees the refusal. The proxy resolves every name an agent sends it, so a name can carry data out through DNS (<data>.evil.example) whether or not the connection is then refused. The observer records the connections it opens; a refusal comes before any, and resolving the name is how it decides. Treat the observer as a record of connections, not of attempts; to catch exfiltration through DNS, log or restrict the resolver the proxy uses. egress
The observer keeps at most 10,000 observation totals the signer refused, and sends them again with every heartbeat; past that it drops the oldest, says how many on stderr, and they leave no signed record. A refusal that never changes would otherwise grow the queue without end. Fix what the observer's stderr names (its grants, its tenant) before the queue fills, and watch that stderr for dropped. egress
Model calls explain only the public API host of their provider (api.openai.com, api.anthropic.com). The record names the provider, not the endpoint. Send other endpoints through the LLM gateway, which makes those connections itself. egress
Over the network (the central chart, compose) a plain HTTPS_PROXY client without a run token is refused (407): attribution by identity there needs Proxy-Authorization: Bearer <token> or a client certificate, which proxy settings can't carry. Only system mode attributes by identity alone (the agent's uid). The proxy knows a networked client only by what it sends. Give the agent process a run's proxy_env URL as its proxy, or a client that sends a bearer token of the egress audience. egress
The proxy checks each run token with the signer before it opens a connection: one round trip per connection, which costs none of the observer's event rate, and while the signer can't be asked, requests with a run token are refused (503, saying so). Only the signer can check a token (an HMAC with its secret); an unchecked one would let a client name any run. Keep the signer reachable from the observer; clients retry a 503. egress
Totals the signer can't take, or refuses, wait in the proxy's memory (a refused one is sent again with every heartbeat); a killed proxy loses what it had not reported, up to a minute and a heartbeat's. Any restart of the proxy, even after SIGTERM sent everything (a rolling update too), is an observer_lost gap in each open run it covered, and so a second proxy process under the same identity: run one replica per observer identity. It reports per minute to keep records few; the signer can't tell a clean restart from a crash, nor a second process from a restart. Stop it with SIGTERM, which sends every total, and restart it while no run is open; read its stderr line on a refusal. egress
Linux system mode's firewall rule refuses the agent uid's DNS (port 53), so the local DNS stub (systemd-resolved's 127.0.0.53) gets no query from it. But a resolver daemon still answers any local user over a Unix socket, and the lookups it makes can carry data out unobserved: systemd-resolved over D-Bus and varlink (resolvectl query, and glibc's resolve NSS module), nscd, and avahi-daemon (mDNS on the local network). Dropping resolve from /etc/nsswitch.conf doesn't stop resolvectl. The rule also lets the uid reach every other loopback port, so a loopback service that forwards (a development proxy, an SSH tunnel, a resolver on another port) can send on for it. A program of the agent's that resolves names itself through the stub gets no answer. An owner-match rule sees network traffic, not Unix sockets, and it allows loopback for the observer and the agent's own local services: it can't tell a forwarding service from them. Run no resolver daemon on the agent's host: disable systemd-resolved and point /etc/resolv.conf at upstream servers (the rule refuses them to the agent's uid), and stop nscd and avahi-daemon. The proxy resolves names itself, so point the agent's clients at it (HTTPS_PROXY, or socks5h:// for SOCKS). Stop forwarding services the agent's uid can reach. Otherwise, read the resolver's query log. egress
Plain HTTP requests through the proxy need a Content-Length (no chunked request bodies); HTTPS goes through CONNECT and is unaffected. The proxy forwards one request per connection. Use HTTPS, or send a length; the proxy answers 411 saying so. egress
Through microsandbox the observer sees hosts (each connection's TLS server name), ports, bytes and times: never paths, headers or content, nothing microsandbox resolves through its DNS forwarder, nothing sent to host.microsandbox.internal, and nothing inside the microVM. It doesn't intercept TLS; microsandbox sends DNS and host-local connections around the proxy. Restrict DNS and host-local access with microsandbox's network policy; route actions whose content matters through the executor or the MCP gateway. microsandbox
Over SOCKS5 (microsandbox) a connection to an address reaches it only when its TLS server name resolves to that address on the observer's host: plain HTTP and other non-TLS TCP are closed unless allow lists the address, and UDP (SOCKS5 UDP ASSOCIATE) is refused. microsandbox sends the address it resolved, never a name; the server name is the only name the observer sees, and it records one only when its own lookup agrees. Use HTTPS; list fixed addresses the sandboxes need in allow; QUIC clients fall back to TCP. The stderr line names each closed connection. microsandbox
A name whose DNS answers change between microsandbox's lookup and the observer's (a CDN rotating addresses) can close a connection. The observer relays to the address microsandbox chose, which its policy checked, and records the name only when its own answer includes that address. Point microsandbox's nameservers at the resolver the observer's host uses, ideally a caching one; retry a closed connection. microsandbox
Per-run attribution from microsandbox needs per-sandbox SOCKS5 credentials (the run id and token); a proxy enforced in microsandbox's managed configuration replaces them, which leaves attribution by identity: the uid running msb on Linux (its latest open run), and on macOS no attribution, so every connection is refused. On Linux that uid goes with the token too, so a run registered by another identity is attributed by the uid. microsandbox's managed proxy is one object for every sandbox on the host, credentials included; the observer reads a loopback client's uid only on Linux. Set credentials per sandbox from the code that creates it, and register the run as the user that runs msb; enforce the proxy in managed configuration only where one user runs one run at a time. microsandbox
A SOCKS5 password holds at most 255 bytes, and a run token grows with the name of the identity that registered the run: a long one doesn't fit. RFC 1929 gives the password one length byte; the token carries the run id, tenant and identity. Register runs under a short identity (a uid, a short SPIFFE ID). microsandbox
E2B's egressProxy works only on E2B Cloud and BYOC, for teams that have it enabled; deployments built from the open-source e2b-dev/runtime reject it. Its client isn't open source: Tracekit is tested against E2B's API description, not E2B itself. Without it, a proxy set in the sandbox's environment (envs) is the agent's to ignore. E2B gates the feature per team, and only its closed builds carry the proxy client. Ask E2B to enable egressProxy for your team; check that a sandbox's first connections show up as effect.observed before you rely on it. E2B
E2B tunnels TCP only: a sandbox's UDP (DNS, QUIC/HTTP3) leaves directly, unobserved. Plain HTTP and other non-TLS TCP through E2B reach only hosts and addresses allow lists. E2B's egress proxy is SOCKS5 CONNECT; the observer names a host only by a TLS server name it can check. Drop the UDP a sandbox doesn't need with denyOut (E2B applies it to non-TCP traffic in this mode) and keep allowOut to the hosts it needs; use HTTPS. E2B
E2B's SDKs send no tls for egressProxy, and off loopback the observer takes SOCKS5 only inside TLS: a sandbox created through the SDKs with the observer as its proxy has no network. The run token is the SOCKS5 password, and the observer takes no credentials in clear off loopback. Create the sandbox through E2B's API with network.egressProxy.tls.enabled: true. E2B
The run token E2B holds as the SOCKS5 password lets anyone holding it send traffic through the observer as that run. The observer attributes a connection by the token it presents. A token alone can't write to the run: the signer checks it against the identity it was issued to. Close each run when its sandbox ends: an observation for a final run goes to the tenant's signer run as effect_outside_run. E2B
The connections of every sandbox on one microsandbox host (loopback) or one E2B node come from one address, which shares the observer's per-address limits (256 open connections, failed run token checks); on Linux every sandbox of one msb user also shares that uid's 64 open connections. The limits stop one client from taking every slot; the observer knows a client by its address. Keep sandboxes' long-lived connections few; spread E2B sandboxes across several observer addresses. egress

Followed sandbox logs (tracekit follow)

Limit Why it is so What to do Details
A followed record is agentsh's word, signed when it arrived (policy.external, source import, tier T3). Tracekit doesn't check that agentsh logged everything, or agentsh's own hash chain. The follower reads the log agentsh writes; only agentsh sees its decisions. Check agentsh's log with its own tools as well (agentsh audit verify); each gap's reason says where to look. agentsh
The follower's identity is trusted to import agentsh's decisions: an agent that can present it can import made-up ones. importers and decision_import are grants to an identity; the signer can't check agentsh's log. Give the follower an identity of its own, such as a signer token readable only by the user the follower runs as. agentsh
The signer watches a follower's runs for heartbeats from memory: a run open across a signer restart with no snapshot since isn't watched, so a follower killed then leaves no gap. The watch is the transcript tailer's, which keeps no state in the log. Restart the signer while the follower's run is closed (after the signer's idle_s without a decision), or read a run that spans a restart with this in mind. agentsh
Without agentsh's audit.integrity, its lines carry no sequence, so a line missing from the log is no gap. The sequence comes from agentsh's integrity chain. Turn on audit.integrity in agentsh's config. agentsh
tracekit follow agentsh starts at the log's end: what agentsh wrote before, or while the follower was stopped, isn't imported. The follower keeps no position on disk. Start the follower before agentsh's sessions; a stop is a gap that says where it stopped. agentsh
One run holds all of agentsh's log, and a record doesn't name agentsh's session: that is in the committed line only. The follower follows one file, which every session writes to. Find the line in agentsh's log by the record's tool_use_id, agentsh's event id. agentsh

Kernel sensor import

Limit Why it is so What to do Details
Tracekit records only what the sensor exported and the import read: events no TracingPolicy or Falco rule selected, events an export filter or field filter dropped, alerts whose output lacks a field the import needs, and events before the import's first heartbeat aren't in the run, and nothing marks them. Connects to no IP address (unix sockets) are skipped, counted on the import's stderr only. The import sees the sensor's output, nothing else; the kernel side is the sensor's. Use the sample TracingPolicy and export allowlist, or the sample Falco rules; check once that a test agent's exec, connect and write outside the workspace each show up as effect.observed. Tetragon, Falco
Tetragon numbers no events: only the drops it reports in its export (rate_limit_info, process_throttle) become signed gaps. Drops it counts only in its metrics (ring buffer, event queue, export failures) don't. A missing event can't be seen in a stream without sequence numbers. Alert on tetragon_observer_ringbuf_events_lost_total, tetragon_observer_ringbuf_queue_events_lost_total and tetragon_events_export_failed_total; leave --export-rate-limit off or high. Tetragon
A loss is a gap in every run the import covers (the open runs of its runs entries' callers), whether or not the dropped events were those runs'; a run registered before the import's first heartbeat gets none (a loss while it covers no run goes to the tenant's signer run). The sensors' loss reports name no process; coverage is the runs the import covered throughout. Start the import before the agents; read observer_lost gaps next to the sensor's metrics. Tetragon
One import identity is one process: a second process of it calling is taken for a restart (an observer_lost gap in each run it covers), and the first is refused from then on (conflict). With an import per node, each with its own identity, an import's restart, silence or loss is a gap in the open runs of every node, and a run says its processes were observed only by the import that recorded at least one of its events, so a run with none says not observed. The signer knows a run's identity, not the node its processes run on. Give each node's import its own identity; or run one import for the cluster that reads every node's export (gathered by your log pipeline), which covers each run alone and gaps only for its own losses. Tetragon
The records are the import's assertion of what the sensor said. Tracekit doesn't check them, and a root user on the node can change the sensor, its output or the import. The signer can check who sent an event, not whether the kernel saw it. Give the import its own identity, never an agent's (the signer refuses an import that owns the run); keep agents unprivileged on the node. Tetragon
(1.4) An observer's identity is of one kind while the signer runs (one sensor's import, or an egress observer): a call as another kind is refused. A run whose owner the import's runs entries stop naming is no longer covered by it, so its run.final says processes not observed. run.final says what covered a run by the kind of each observer covering it. Give each import and each egress proxy its own identity; restart the signer to give one a new kind. Tetragon
One import maps processes to at most 256 identities (its runs entries' callers). Every call names them, so the signer covers only their runs. Run one import per group of agent identities. Tetragon
An event goes to the latest open run of the identity its runs entry names registered by the event's time, which is ambiguous when one identity runs several at once; the time is the sensor's clock, so with it behind the signer's an event can go to the run before (one still open) or, more than 5 s behind with none open, be an effect_outside_run gap. A sensor's events name the pod, container and uid, not the run. One identity per concurrently running agent, or one pod per run; keep the nodes and the signer on NTP. Tetragon
An event is joined to a tool call only through CODEX_TOOL_CALL_ID, which the agent's process can change or remove; Claude Code exports no such id. An effect nothing explains isn't reconciled: no reconcile.unexplained_effect, no count in run.final's coverage. The id is the only link between a process and a call; a process with none can't be told from one that hid it. Run tracekit analyze --v2 on the finished run: TK-X206 joins each effect to a call by its claim, its parent process or the call's time, and flags what none explains. Tetragon
The binary, file paths and connected addresses are stored in the clear; the arguments are committed to, not stored. Auditors need what ran and where; arguments can hold secrets. Test arguments from Tetragon's own export against the commitment with the record's revealed salt (tracekit signer reveal). format v2
With --follow the import reads from the file's end on: events written while it was down aren't imported (its restart is an observer_lost gap). It doesn't read rotated or compressed files. Reading the file again from the start would record events twice. Run the import as a service that restarts, next to Tetragon. Tetragon
Falco reports a second's drops only when more than syscall_event_drops.threshold (10 %) of its events were dropped, at most one second per 1/rate (30 s) by default, and needs priority: debug for the report at all; alerts dropped from its full output queue show only in its log and metrics. Those are Falco's settings for its drop alert; the queue has no alert. Use the Falco settings in the setup (threshold: 0, rate: 1); alert on falcosecurity_falco_outputs_queue_num_drops_total. Falco
A Falco restart leaves no mark in its alerts, so what happened while it was down is missing with no gap. A Tetragon restart is a gap: it reports the processes already running (procFS). Falco writes no alert when it starts. Alert on Falco's restarts in your monitoring (its pod's restart count); prefer Tetragon where a restart must be in the run. Falco
With Falco, only alerts of rules tagged tracekit are recorded, and none of a process's exits; records have no exec_id. Other rules' alerts would record the same system call twice; the sample rules match no exit, and Falco names no process across executions. Use the sample rules; join a process's records by pid and time. Falco
A bundle with kernel sensor records (effects, or an observer_lost gap of its import) needs verifier 1.4.0 or later. Older verifiers don't know the records' fields. Verify with 1.4.0 or later: verdicts has the commands. format v2

Signed findings

Limit Why it is so What to do Details
A signed finding reads independent only when your trust config pins its author in analyzers; otherwise unpinned author <id>, and self-asserted when the author is the analysed run's identity or a run's signer runs as its client's user. Every finding of the dev signer is self-asserted. The signer measures who wrote a finding; only you can say whom you trust to analyse runs. Run tracekit analyze --v2 as an operator identity, never the agent's (tracekit doctor warns: D-ANALYZER-AGENT), and pin it in your trust config: "analyzers": ["uid:1004"]. verdicts
A signed finding is the analyzer's word. The verifiers check that its citations are records of the analysed run with those hashes, not that the check was right, ran on every record, or found everything; a missing finding proves nothing. A finding holds no text of the run, so a verifier can't run the checks again from a bundle. Read the cited records (tracekit view), or run tracekit analyze --v2 again with access to the content vault. format v2
A bundle of a findings run without the run it analyses verifies with its findings not counted (reviews counted warning) and their author not checked. The citations and the author's comparison need the analysed run's records. Export the analysed run with tracekit export --v2 --run R --with-findings. verdicts
A findings run or a tracekit why replay run can't itself be analysed or replayed: the signer refuses to register a findings or replay run about one (invalid_request), so tracekit analyze --v2 --run on one prints its findings unsigned and exits 2. Findings and replays are about the agent's run they name; findings about findings say nothing of what the agent did. Analyse or replay the run it names (analyzes or replay_of in its run.registered). findings, why
The verdict of a signed finding is a closed schema: a check whose finding needs another rule, field or reason code needs a new RPC version, in the signer and the analyzer. The schema is how the signer keeps text of the run (excerpts, paths, reasons) out of records that can't be erased. Upgrade the signer with the analyzer. format v2
A bundle with signed findings needs verifier 1.4.0 or later. A v1 judge verdict carried into a v2 run (a review without citations) is counted as imported, never checked. Older verifiers don't know cites; an imported verdict cites nothing to check. Verify with 1.4.0 or later: verdicts has the commands. format v2
The manifest isn't signed, so a bundle whose verifier_min_version was edited down is read by a verifier older than 1.4.0 instead of being refused: it still checks every signed record, but reads no signed findings (no Findings line), so it can say VERIFIED where 1.4.0 says FAILED for a finding whose citations don't match. A verifier can't know checks added after its release; the manifest only lets it say so, and anyone holding the bundle can edit it. Verify with 1.4.0 or later, and pin that version where you verify (CI, the GitHub Action). format v2

Witnesses and monitor

Limit Why it is so What to do Details
A witness you run yourself (operator class) gives only Assurance: local. Whoever runs the stack runs the witness too. Have someone else run a witness (customer, public) on infrastructure you can't change. deploy compose
Witness classes come from the verifier's judgement, never from the bundle. The bundle's producer can't vouch for its own witnesses. Get each witness key from the witness's operator. auditor guide
(1.5.1) A trust config pins each witness as one key under one name, with one class: one key under two names, two keys under one name, or one witness listed with two classes is refused, by tracekit verify (trust config, exit 2), the TypeScript verifier, the Go verifier and tracekit pcm verify alike (pcm.verify reads no class), and a signer.yaml that lists one witness key under two names, or two witnesses under one name, doesn't load. The same entry listed twice is accepted and counts once. A cosignature signs no key name and a witness cosigns with one key (C2SP tlog-cosignature), so each witness counts once toward witnesses_required, and its class decides what its cosignature adds to the assurance. Keep the key under the name the witness cosigns with (the name on its cosignature lines), keep only a witness's current key (bundles it cosigned with an older key verify under a trust config that pins that key), give each witness one class, and remove the other entries; to require two witnesses, pin two witnesses with keys and names of their own. format v2
A git witness without a remote, or a file witness on the same host, adds little. Whoever controls the host can rewrite it. Use a remote with a protected branch, or storage the host can't rewrite. witnesses
An unreachable witness delays cosigning; the gap is signed, not prevented. The signer can't force a witness to answer. Watch witness_failed gaps and tracekit_signer_witness_lag_records. witnesses
The v1 Rekor witness is experimental, off by default and not run against the live service. It is tested offline only. Treat its first real run as validation. witnesses
Rekor entries are public and permanent and reveal activity timing; the publishing key links a signer's anchors. Rekor is a public transparency log. Use Rekor only where that is acceptable. witnesses
Rekor v2 anchoring needs a signing config that lists a Rekor v2 log; the TUF files are pinned local copies, not fetched. Production Sigstore may not list one yet; TUF fetching isn't built. Start on staging; refresh the files when Sigstore rotates a shard. witnesses
macOS's system openssl (LibreSSL) can't verify the RFC 3161 timestamps. It fails on their ESSCertIDv2 attribute. Use OpenSSL 3 or tracekit verify. witnesses
A monitor sees the log the signer serves it: a split view shows only at equal tree sizes, or to witnesses. A smaller checkpoint isn't proven consistent with the report's tree. Run monitors and witnesses the operator doesn't control. server threat model
A monitor the operator controls vouches for nothing, and a monitor report never raises dev or local. Monitoring adds to independent witnessing, it doesn't replace it. Run it somewhere the operator can't change; pin it as non-operator. monitor
With an issuer, the monitor flags each signer.epoch after seq 0 as an unannounced key. Rotating kids can't be listed in advance with --allow. Expect those conflicts until the monitor can pin issuers. issuer
A Rekor entry the signer wrote but got no reply for shows as a monitor conflict. It matches no stored anchor. Check the signer's witness_failed gaps for that outage first. monitor
The issuer handles one issuance at a time and re-reads its log for each. Fine at record-key volumes. Past ~100k certificates it needs an index. issuer
If the issuer can't be reached at start, the signer doesn't start; records signed after a key's not_after fail verification. Certificates are short-lived. Keep the issuer available; watch renewals. issuer
The public witness makes a log witnessed independently of its operator, not of Cygnux. Whoever holds the witness's key could cosign any tree. Add a witness you or a partner run and raise witnesses_required in the trust config. witnesses
The public witness is not deployed yet, so nothing is anchored by default: URL and VKEY in tracekit/public_witness.py are empty, init and tracekit up --wait say not anchored, verify says NOT ANCHORED, and witnesses: [public] and system mode's init --v2 --public-witness are refused. Its URL and vkey are set once it runs, in a Tracekit release. List your own witness, {url, vkey, class}, meanwhile. witnesses
Once the public witness is deployed, the dev signer and the signer.yaml tracekit init --v2 writes use it by default. A signer.yaml you write yourself (Compose, Helm, Docker) uses it only if it lists witnesses: [public]. --no-witness (init --v2, up) opts out, recorded in a no-witness file (the dev data dir, or /etc/tracekit/ in system mode) that later inits keep until an init with --public-witness; a change applies when the dev signer next starts (tracekit up --replace). Anchoring should need no setup step. Opt out if no checkpoint may leave the machine; then whoever holds the signing key can rewrite the log unseen, so list your own witness. what the public witness sees
The public witness takes one log key per origin, the first registered: a log under a new key is refused (403, a new log key needs a new origin). Anyone can register, so the first key must be the only one, or anyone could take over a log's witnessing. Set a new origin in signer.yaml when the log key changes. witnesses
On the public witness the first registration of an origin wins: anyone can register a custom origin before its log does, and the log is then refused (409). Registration is open; the witness can't tell who owns a name. Keep the default origin tracekit.local/<log id> (unguessable before the log exists), or use your own witness. witnesses
The public witness deletes an origin never cosigned within 24 hours of registering, or not cosigned for 90 days; the log registers again on its next checkpoint, and the witness's protection restarts from there. A shared table must not fill with abandoned logs. Checkpoint at least every 90 days, or use your own witness. witnesses
The public witness tells anyone whether an origin is registered, and anyone holding an older checkpoint note of a log its current size. 409 carries the size it holds, as the protocol says. Treat a log's size as public once its notes are shared. witnesses
The public witness takes only origins shaped host/path (lower-case host, at least one path segment); others are refused at registration (400, naming the format). C2SP names a log by a host and a path. Leave origin unset: the default, tracekit.local/<log id>, has that shape and names no one. witnesses
The public witness cosigns at most 30 checkpoints per log and client network a minute that grow the log; a busier log gets 429 and is cosigned at that rate, always its newest note. Resent and older notes are not counted. It is a shared, free service. Run your own witness for a higher rate. witnesses
The public witness takes 100 registrations per client network (IPv4 /24 or IPv6 /48) a day, 60 in all a minute (429), and a fixed number of logs in total (then this witness is full). Open registration must not let one client fill it. Signers with many tenants register over several days (retries are automatic); when it is full, run your own witness. public witness

Privacy

Limit Why it is so What to do Details
Commands, paths, URLs and search queries are recorded in clear (after redaction). A reviewer needs to see what the agent acted on. Deny sensitive patterns in policy, or keep bundles internal. privacy
Redaction is pattern-based and misses secrets it doesn't recognise. It can only match known shapes. Deny the pattern in policy, or keep bundles internal. privacy
Browser Use's sensitive_data values are masked written out, percent-encoded, as HTML character references or JSON escapes, or a mix of these; any other transformation (base64, a hash, a split or a case change) reaches the signer as it is. The adapter recognises a value by the forms a URL, a page or JSON writes it in. Keep secrets out of URLs; deny a pattern that carries them in policy. Browser Use
v1 hashes are unsalted, so low-entropy content (a short prompt, a known file) can be confirmed by hashing guesses. Reviewers can match known files. Use the v2 signer, which publishes salted commitments. privacy
Sizes, timing and correlation still leak: the same file in two runs links them. Hashes and commitments hide content, not activity. Treat bundles as activity records. privacy
content_capture: full stores content (redacted) in the log and in bundles. Readable content is what the setting is for. Protect such bundles as you would the data. privacy
Revealing a v2 record's salt lets anyone holding the content check that record's commitments. That is how an auditor checks content; one salt opens one record. Reveal only the records an audit needs. privacy
A run-set bundle carries the tenant's registry salt, so it allows testing guessed run ids against that tenant's leaves. The verifier needs the salt to check completeness. Share run-set bundles only with that tenant's auditors. auditor guide
v2 bundles exported by earlier versions carry the exporter's local time in their zip entries, which next to the records' UTC times shows its time zone; v1 bundles still do. A v2 export now dates every entry 1980-01-01 00:00. A zip entry is dated by the local clock unless its writer sets a date, and a bundle already written keeps its bytes. The v1 export isn't changed. Re-export a v2 bundle to drop it: the records and proofs are the same. Use the v2 signer where the exporter's time zone is private. format v2
With serve_records: true the metrics port serves every tenant's records (run ids, tool names, commitments). The monitor reads every record. Expose that port only to the monitor. monitor
Witnesses learn when checkpoints happen and how many records exist. That is what they cosign, and it arrives when it is made. Choose witnesses accordingly. privacy
A custom origin (such as acme.com/agents) on a log the public witness cosigns tells Cygnux whose log it is: the origin is in every registration and checkpoint. The signer warns at start. The origin is the log's name in the protocol; the default, tracekit.local/<log id>, is random. Leave origin unset on a new log, or use your own witness. A log keeps its origin: changing it starts a new log for the witness and for trust files. what the public witness sees
Cygnux sees how fast each log on the public witness grows, and when, even an anonymous one: the size and time of every checkpoint (about every 10 s while it grows), and from each tenant's registry log how many runs start and end. A signer's logs share one public key, so they can be linked to each other. That is what a witness cosigns, sent when it is made. It publishes only weekly counts of logs. If activity patterns are sensitive, run your own witness or opt out with --no-witness. what the public witness sees
The public witness's hosting company sees each signer's IP address and the time and size of its requests, and may keep its own network logs; Tracekit doesn't control them. The witness itself keeps addresses only in memory. Its network sits in front of the witness. Give the signer an HTTPS_PROXY to hide your address, or run your own witness. what the public witness sees

Deployment

Limit Why it is so What to do Details
A sidecar doesn't protect against whoever administers the node or the PVC. They can reach the signer's volume. A witness off the node detects rollback. deployment
(1.2) An identity authenticated by token, certificate or service account may call only the RPCs authorize grants it. The TypeScript and Python adapters need register_run, decide, approval_consume, complete, close_run and model_event; asks also need approval_request and approval_wait, and the OpenAI Agents JS and Vercel AI adapters approval_list (to apply decisions, and TypeScript's instrument() at exit to keep a run with waiting approvals open: without the grant it closes the run); observe and state_write where the app records inputs or state; status where the signer's content vault is on (without it the integrations keep what the model said as a digest only, and warn); and the coding-agent hooks on a remote signer (tracekit init --remote ... --v2) observe (each prompt) and constraint_add (live constraints), and Claude Code's approval_get (an approved command the model retries with a new description). A missing grant refuses the call as forbidden (an ask is refused). No identity has a grant by default. Grant the agent identity that list; with the LLM gateway, the agent must register its runs as the identity the gateway relays. deployment, gateway
A KMS log key doesn't belong in the agent's pod. Workload identity gives the pod's cloud credentials to every container, the agent's too. Keep KMS keys on a central signer (D-K8S-WORKLOAD-IDENTITY). deployment, doctor
The sidecar chart runs one replica with the Recreate strategy. The signer holds its data volume's storage lock. Size the pod for the agent's load. Kubernetes
persistence.enabled: false keeps the log in an emptyDir that dies with the pod. It is for development. Keep persistence on outside development. Kubernetes
The sidecar's NetworkPolicy covers the whole pod, the agent's ports included. NetworkPolicy selects pods, not containers. Account for it when the agent serves ports. Kubernetes
Central: scaling down closes the last replica's log for good, and that ordinal needs a new log before it runs again. Each replica is the only writer of its own log. Leave autoscaling.scaleDown off unless you plan for it. Kubernetes
Central: calls that name no run or approval reach one replica. Runs are routed by their replica prefix. List each replica's approvals through its own Service. Kubernetes
Central and compose don't protect against an operator with no independent witness and monitor, or against the cloud provider. Detection needs both; the provider is out of scope. Add both; keep witnesses on other parties' infrastructure. deployment, server threat model
An agent-sandbox run records the agent's service account, not its Sandbox or pod: Sandboxes that share a ServiceAccount are one identity in the record. The signer records the identity it authenticated, and the pod name isn't part of it. Give each Sandbox its own ServiceAccount when runs must be told apart by Sandbox. agent-sandbox
A Sandbox's RuntimeClass and spec aren't recorded: a run's isolation: remote says only that the signer runs apart from the agent, not how the agent's pod is isolated. The signer sees an authenticated HTTPS caller, not how its pod runs. Enforce the RuntimeClass in the cluster (an admission policy); don't read it from the bundle. agent-sandbox
A run whose Sandbox is deleted before the agent closes it stays open until the signer's idle timeout closes it (idle_s, an hour by default); until then tracekit verify reads VERIFIED TO HEAD n (open). Only the agent or the idle timeout ends a run; the signer isn't told the pod is gone. Export after the idle timeout for a closed run, or lower idle_s; the open run verifies up to its last record either way. agent-sandbox
The agent-sandbox example's end-to-end test runs only by hand; CI doesn't run it. It needs docker, kind, kubectl and the network (it installs agent-sandbox from its release). Run examples/v2/agent_sandbox/e2e.sh before relying on a change to the example. agent-sandbox
On compose, root on the Docker host is the operator. It controls every container and volume. Use an independent witness. deployment
(1.2) The failed-authentication limit of the HTTP services is per source address (4096 addresses remembered, least recently used dropped): a client that rotates through more addresses than that gets a fresh burst each time, and clients behind one NAT address share one limit, so one sending bad tokens can keep the others' OIDC and service-account tokens from being checked until it stops. The limit protects the services that check those tokens (an IdP's keys, the API server's TokenReview); a client certificate or a Tracekit token is still checked locally. Put the services behind a proxy that limits per client, or give clients behind one address client certificates or Tracekit tokens. deploy
(1.2) The LLM gateway, the tool executor and the MCP gateway take the signer's connection limits (1024 in all, 256 per address), so one address can hold many slots with large headers before it is authenticated. Agents behind one NAT address share an address; a lower fixed per-address limit would refuse them. Put the services behind a proxy that limits connections per client. deploy
(1.5) The loopback services take a fixed number of connections at once: the OTLP receiver (tracekit otel serve) 64, the proxy 16, tracekit observe 64 requests and 64 event streams; one more is closed unanswered. Each request must arrive within 30 s, and a connection idle for 10 s is closed. Every local client has the one address, so the limit is the whole server's; without one, a local process could hold a thread per connection for as long as it liked. Exporters and model clients retry a closed connection; send many exporters to the signer's OTLP import instead, and keep fewer observe pages open. OpenTelemetry
(1.2) The MCP gateway answers tools/list, resources/list, prompts/list and resources/read from the upstreams before the signer has checked the run token (it is checked when the answer is recorded, which a forged token fails): an identity the gateway accepts can make it call every upstream once per request. The listing is recorded as input the agent got, after it is fetched. Accept only the agents' identities at the gateway, and rate-limit them in front of it. MCP gateway
(1.2) Remote ingest charges one rate-limit token per OTLP request, however many spans it carries (up to 10,000), and keeps each client's OTLP state until the process restarts, a revoked client's too. Requests are limited, not spans; client state is kept for its dedupe. Restart tracekit ingest serve after revoking a client; keep exporters' batches modest. remote ingest
The compose stack's first start writes a degraded_unanchored gap. The witness doesn't know the log yet. Expected once; check later gaps. deploy compose
The compose end-to-end test runs only where Docker and root (or passwordless sudo) are available; elsewhere it is skipped. It brings up the real stack. Run deploy/compose/e2e.sh on a Docker host before relying on a change. deploy compose
tracekit doctor output is advice about the host, not evidence. Nothing it prints is signed or read by a verifier. Rely on the bundle and the verifier's trust config. doctor
A plain http:// signer URL must name a loopback IP address (http://127.0.0.1:8443, http://[::1]:8443); http://localhost is refused, and a central signer's replica routing is not followed over it. Over plain HTTP the bearer token crosses in clear: only an address, not a name a resolver could point elsewhere, keeps it on the host. Use 127.0.0.1 or ::1, or https://. deploy
The public witness's compose file pins Caddy by tag, not digest. The digest is taken when it is deployed. Pin caddy by digest before production. public witness
The public witness's state.db must never roll back: a restored older copy could cosign a fork past it. It is what keeps the witness from cosigning two trees. A lost or rolled-back state means a new witness key and a tracekit release with the new vkey. public witness

Investigation (tracekit why)

Limit Why it is so What to do Details
A measured effect is the total effect for this program on this task; it doesn't explain the model's reasons and may not transfer to other tasks. Replay measures what changes when an input is removed, nothing more. Re-test on the tasks you care about. why
ruled-out means smaller than 20 points, not zero. Finite replays give an interval, not an exact value. Raise --n-max until the interval is narrow enough for your decision. why
The viewer's single RUN TEST isn't corrected for testing many inputs one by one: about 1 in 20 inputs with no effect can come out causal by chance. Each test reports its own interval. Use Find the cause (attribute), which corrects for every test it runs. why
The causal graph is only as complete as the recorded context. Content sent to a model without being recorded is invisible to it. Record model calls through an adapter or the gateway. why
Replay costs model calls (about 2·n per test per downstream model call); program replay has no budgets or caching. Proving a cause means re-running the model with and without each suspect. Start with attribute, which tests the group first; set --n-max; on a signed run set --max-calls or --max-cost. why
Run replay needs a re-executable program; decision replay doesn't. Re-running a whole run means running its code again. Use decision replay for calls recorded with their request. why
Tape matching is exact on tool arguments; new calls are stubbed, which can change what the agent does after the stub. Replays must never repeat a real side effect. Read off_tape_actions in each result. why
A tool your own code runs and records with record_action (or the Anthropic adapter's tool_result) runs for real in a replay, with a warning; only act() and the adapter's run_tool are served from the tape. The runtime hears of such a call after it ran. Run tools through act() or run_tool; read off_tape_actions. why
The CLI's replaying commands (test, attribute, matrix, replay) need --system or --allow-program; they never import the program a run names on their own. Importing a module runs its code, and a run file is data anyone could have written. Pass --system module:ATTR for code you trust. why
A run written to the folder by a local Runtime, or ingested before ingest tokens bound runs (no ingest-owner file), is never appended to by ingest. One token per run: an agent that changes token starts a new run. A run is bound to the token whose batch created it. Write each run through one sink, with one ingest token. why
The viewer keeps each analysed why run (its blobs included) in memory, and its event stream records, for the server's life. The analysis is cached until a run's files change. Restart the viewer, or move old runs out of the folder, when a workspace grows large. viewer
Inferred edges compare each node with at most the 20 earlier nodes sharing the most word shingles with it, ignoring shingles found in more than 50 nodes, so a long run can miss some. Comparing every pair is quadratic in the run's length. Treat inferred edges as hints; observed and tested edges are complete. why
Analysing a run takes time that grows faster than its length: each sensitive call's alert searches everything upstream of it, so a run of 1,000 model calls that each see the whole history (an imported Claude Code session) takes about 25 s, and the viewer analyses a live run again each time it grows. An alert names every untrusted input upstream of the call. Open long runs once they finish, or record long sessions as several runs. why
WHY's how it got here shows the chains from the 20 inputs nearest the call. Every input's chain would grow with the cube of a long run's length. Candidate causes lists every upstream input. viewer
The viewer's GRAPH draws a run of up to 600 events; a larger one says it is too large to draw. Thousands of nodes fit a panel only as dots too small to read, and laying them out takes seconds. Use TIMELINE, WHY DID IT HAPPEN? or a call's WHY tab, or record long sessions as several runs. viewer
The viewer shows a run still being written up to the signer's newest checkpoint and checks it again no sooner than four times the CPU time its last check took; its graph is imported again on the same terms (the analysis of each import, about as long again, is not counted), and a final run's findings come after its verdict. A check costs about 0.5 ms for each record it has not checked before and 0.05 ms for each one it has, so a 25,000-call run (50,000 records) shows its newest calls 10 to 30 s late (it was 30 to 110 s, with one CPU busy). A record is shown only once a checkpoint covers it and the run's bundle up to there verifies; checking every run in full at each checkpoint kept one CPU busy and left the page minutes behind. Wait; tracekit verify on an exported bundle covers the same checkpointed records. viewer
While it checks and imports a run being written the viewer holds that run's records in memory a few times over: next to a 25,000-call run it used about 1 to 2 GB. Each check exports and verifies the run's bundle, and the graph imports the run whole. Give the viewer that memory, or view a long run once it is final (tracekit export --v2 --run ID, then tracekit verify). viewer
Past TRACEKIT_OBSERVE_MAX_RECORDS rows (50,000) the viewer and its page drop the oldest from the live view, and the tape says how many left; each run's latest verdict stays in the run list, for up to 10,000 runs (a failed run's goes last). The live view is held in memory. Export a run's bundle (tracekit export --v2 --run ID) for all its records, or raise TRACEKIT_OBSERVE_MAX_RECORDS. viewer
PERMISSIONS lists each decision that was not a plain allow from the rows the page holds: with no run selected, those of every run in the live view (the newest TRACEKIT_OBSERVE_MAX_RECORDS rows, 50,000 by default); with a run selected, that run's rows, read again from the store (/api/rows) when the run verified and some of its records left the live view. A run that did not verify, or is still being checked, lists only its decisions still in the live view. While it lists none for the selected run (its rows still loading, or none left on the page) it shows the run review's permissions instead: a count per outcome, not each decision. The review of every run stays in memory and is in each snapshot, so it holds counts, not decisions, whatever the run's size; rows are read from the store only for a run whose bundle verifies. Select the run, or export its bundle (tracekit export --v2 --run ID, then tracekit verify). viewer
A run read again from the store (/api/rows) shows at most TRACEKIT_OBSERVE_MAX_RECORDS of its records, its first, without the arguments the dev signer kept; its answer is kept while the run's own records don't grow, so an edit of its records shows only once the viewer's own re-check fails the run (within a minute; five for a Postgres store). The viewer answers from its own watcher's state and the answers it kept, with no read of the store: a run the watcher hasn't verified yet is answered 404 until it has. Only a check reads the store, two at once at most: a third request that needs one is answered 503 and the page tries again 10 s later; the page keeps the rows of the four runs read last. Reading kept arguments again writes a signed content-access record each time; checking the whole run on every request would keep a CPU busy, and opening the store reads every record of every run. Wait, or export the run's bundle for all its records; for the arguments, tracekit signer reveal. viewer
The central viewer's run list (/api/runs) shows each run's last verdict, up to five minutes old: lists check one run at a time, with a check slot of their own (so a run page always has one), and a list that finds it taken shows FAILED as it is and NOT CHECKED for a run it has never checked or whose VERIFIED is older than that. An edit of a run's records in place shows in the list at the first list after that that can check it, and at once on the run's own page (/api/run), which checks it for each request, two at once at most with bundle downloads (/api/bundle; a third is answered 503: try again). Checking every listed run on every list would export and verify each one each time; each check reads the log. Open the run's page, or export its bundle and run tracekit verify. viewer
HORIZON's project ring holds a v2 run's relative paths (an absolute path is "this machine"), places a call whose arguments the viewer has only as a commitment by its tool, draws the newest 500 calls and sensor effects of all runs together by the signer's time, or a why log's own (not 500 per run; the page says how many it leaves out), draws a why log time it can't read as the oldest (its tape row shows it as now, and its replay clock reads 00:00:00). Egress totals show network activity but do not prove which call caused it. GRAPH links a total only when the observer named its run by token and its full activity interval fits one completed call in that run, with no other eligible call overlapping it. run.registered records no working directory; egress totals name a run, not a call, so the viewer's time/run match is a heuristic: a total's times are the observer's clock and a call's the signer's, so a small difference between the clocks can put a total in the next call, and a total sent with the caller's identity instead of a run token is in that owner's latest open run, which the signer picked; a why log on disk isn't checked when it loads. Open a run's CALLS for every call and its record; check a place with the run's bundle. Event Horizon
HORIZON reads a word with a slash in a call's arguments as a path, so a git ref such as origin/main is drawn as a project place. (1.5.1) In a Bash command it takes only a path no branch or ref looks like (~/, /, ./, ../, a dotfile, a dir/file.ext), so src/components there is no place; a command without a host or such a path is named by its program, and by its verb too only for programs run by subcommands it knows (gh by its noun and verb, as gh pr merge; git, npm, pnpm, yarn, bun, docker, kubectl, helm, cargo, go, pip, uv, poetry, brew, aws, gcloud, az, terraform, make, tracekit). A command is text: the map can't tell a relative path from a ref or any other word with a slash, and a v2 run records no working directory to check it against. Click the place: each move there names its tool and, for Bash, its command; OPEN shows the call's record. Event Horizon
On a phone (a map narrower than 600 px) HORIZON draws a callout only for a restricted place or one where an agent was stopped (blocked or held). (1.5.1) At any width it draws callouts for restricted places and stops first, then the busiest place first, and leaves out each that would cover one already drawn (a restricted one too, which its shield still marks), and a callout names a long path by its last two parts; a move's number that would cover another's is left out. A map has room for so many labels, and labels drawn over each other can't be read. Hover a place for its whole path; click it (tap on a phone) to list who went there; follow an agent to list every move of its route. Event Horizon
(1.5.1) The viewer reads a file store once, then only what is appended to it, and hashes what it read again in pieces of 1 MiB: an edit of records it already read is caught at the store's next change when it is in the piece the viewer's last read began in (its newest records), at once when the file is written to without growing, and otherwise within a minute, when every piece is hashed again (an edit whose file time is set back, among records appended elsewhere, or followed by a partial line waits for that). A check verifies the bytes the viewer hashed: a record that reads otherwise when the check reads it again (the honest bytes put back only while it is checked) is caught at that check, so an edit that stays in the store is caught within a minute however it is timed; bytes that are the honest ones each time the viewer reads them are not, by this viewer or any reader. Each run with a record in a piece that changed then reads PENDING (re-checking) until it is checked again, in the order the runs started waiting, at about half a core as on start (each re-check followed by a pause as long as it took: after an edit of a key record, which has every run checked again, a large store reads re-checking for about as long as its first pass), and the edited run turns FAILED (its records taken back); the store read anew then is compared piece by piece with what was read before, so an edit made meanwhile elsewhere is caught too. A Postgres store's runs are checked again five minutes after their last check, one run a second. Reading every run again at every store change checked the whole store all the time: a core at 100% on a 400,000-record store. Hashing 550 MB takes about 0.2 s; the newest piece, about 1 ms. The viewer keeps 8 bytes of a keyed hash of each record (4 MB for 500,000), and hashing each record as it is read makes opening such a store 3.1 s of CPU instead of 2.3 s. Re-checks at a full core took about 7 CPU-minutes of a large store back to back, and anyone who can write the store can start them again. For evidence run tracekit verify on an exported bundle; restart the viewer to check every run at once. viewer
(1.5.1) To check a run being written from where it was, the viewer keeps the bytes it verified of the runs not yet final that it checked last, 64 MiB in all (about 40,000 records): a run past that, or one left out since others were checked, is read whole from the store at its next check, about 11 µs a record (0.5 s for 50,000 records) on top of the check itself (0.05 ms a record). Keeping every unfinished run's bytes held 174 MB of a 682 MB store for as long as the viewer ran: the signer's own run is never final, nor is a run nobody closes. End each run when its work is done (a final run's bytes go at once); start a new run for each task or session. viewer
(1.5.1) A run being written reaches the tape no sooner than 40 times the CPU time of the last check of what a run added: about every 30 s for a 50,000-record run, every second or two for a 5,000-record one; runs that grow take turns. Its graph (GRAPH, WHY, AGENTS, INFLUENCE) is imported again no sooner than 100 times its last import's time: every few minutes for a 50,000-record run. Each check of what a run added still runs the checks of the run as a whole (approvals, incidents, coverage) over all its records, and the graph is imported whole: both grow with the run. The budget keeps them under about 3% of a core. Start a new run for each task or session; open the run's bundle (tracekit export --v2 --run ID) for all of it at once. viewer
(1.5.1) On start the viewer checks every record of the store once, the newest runs first, at about half a core: each run's first check is followed by a pause as long as it took (about 12 minutes for 430,000 records, 7 of them of CPU); until a run is checked NEEDS YOU counts it as still being checked. Once rows have left the live view, a run older than every record it holds shows only its verdict in the run list, with no graph; its records load when you open it (/api/rows). Each record's signature and schema are checked once per start; the live view holds the newest rows. Keep the viewer running rather than restarting it; start a new run for each task. viewer
verify reports a log without run.end (cut short, or still recording) and test results outside tests.jsonl's chain; whoever can rewrite the files can rebuild both chains, a closing run.end included, and the why log's head is not yet recorded in the signed records. Both chains are unsigned. Cite the signed records for claims; keep the why folder where agents cannot write. why
A webhook gets an alert's rule, title and run only, and at most 100 alerts wait to be sent; more are dropped with a warning. Alerts must not carry the call's arguments, nor stall the server behind a slow endpoint. Open the run in the viewer for the detail. why
LangGraph fork replay serves tool calls only through a ToolNode that is a node of the graph (also inside .with_fallbacks()) or of a subgraph added as a node. A graph without one is refused ("the graph has no ToolNode ..."), and so is a node that runs a subgraph with a ToolNode from its own code. A tool called any other way (a ToolNode invoked inside a function node, a tool called inside a model node) runs for real: a branch with a tool result that was not served stops with an error ("... ran outside a ToolNode ..."), but only after that tool ran. A call a node of the app answers itself (a routing schema such as CompleteOrEscalate) is refused the same way unless routing= (--routing) names it, and a call so named is never checked. ToolNode exposes the hook replay serves from; code inside a node can call anything. Put your tools in a ToolNode node (create_agent and tracekit_tool_node do); add subgraphs as nodes; name only routing schemas in routing=. why
A tool call is served with its recorded ToolMessage (content, status, artifact). A thread in which a tool step also wrote another state key (a tool returning Command(update=...)) is refused ("a tool step of this thread also wrote ..."); a Command's goto isn't replayed. Replay serves results from the thread; what else a tool's Command did isn't a message it can replay. Have tools return messages; keep other state in nodes. why
Fork replay removes messages only: a suspect whose step also wrote another state key is refused ("the step that added ... also wrote ..."). Content that entered through another key would stay in the branch, so removing the message would wrongly rule it out. Keep what a node adds to the state in messages, or test another suspect. why
Branch nodes see a scratch thread: a new thread_id per branch, an empty scratch store if the graph has one, and no node cache. A node that reads long-term memory from the store sees none of it in either arm. Branches must not read or write the app's thread, store or cache, and a cache would serve every unaltered branch the recorded model output. Read the effect as measured without the store's contents; key external lookups on the state, not the thread_id. why
Fork replay runs graphs synchronously: an async-only node or an async checkpointer is refused ("... is async-only ...", "... checkpointer is async ..."), and so is a subgraph with its own checkpointer. Branches are driven with invoke; an async saver is bound to its own event loop. Give async nodes a sync function too, and give the factory the sync checkpointer over the same database. why
Fork replay replaces a removed tool result with a placeholder instead of deleting the message. Model APIs reject a tool call left without its result. Read the effect as "without that content", which is what the placeholder gives. why
An attribution forks once, where the earliest suspect entered; a later suspect that isn't a tool result is refused ("... entered after the fork point ..."). Every test shares one unaltered arm, so they must fork at the same point. Test that message on its own (fork_replay, or --suspect with only it). why
Fork replay refuses a suspect in the thread's first checkpoint or added by a step that ran several different nodes at once ("cannot tell which node added ..."); parallel calls of one node (a ToolNode running several tool calls) are fine. It forks with update_state(as_node=...), which needs the one node that wrote the message. Pick another suspect, or run those nodes one after the other. why
Inferred edges are a heuristic and miss paraphrase. They come from word overlap, not a recorded path. Treat them as hints; only tested edges say "caused". why
The tracekit why guard is a string-matching tripwire, in the agent's process. It checks verbatim values only, where the agent runs. Use the signer's from: untrusted rules, which the agent can't skip. why
tracekit why's own log is hash-chained but unsigned: whoever can rewrite the whole log can rebuild the chain. It holds the content a signer never stores. Cite the signed Tracekit records for every claim that matters. why
With a signer, a message to another agent is observed in the recipient's run as one value with the message's trust: a value the sender had from trusted input but passed on in an untrusted message is untrusted there, and a from: untrusted rule holds it. The signer's provenance index is per run and sees what the agent was sent, not where each part came from. Put the values your app supplies in the task, which every agent's run observes as trusted, or answer the hold. why
(1.2) A handoff to another agent isn't decided: the model asking for one is a reconcile.hook_missing (its detail says what to do) unless the policy's handoffs: names it; no shipped pack names any. A tool the policy names that way isn't flagged when it runs without a decide, even under gateway_mandatory, and a child policy can't remove a name its parent declares. Frameworks run handoffs themselves, without a call id an adapter could gate; the app chooses its tools' names. List your agents' handoff tools by exact name (transfer_to_refunds_agent, LangGraph routing schemas such as CompleteOrEscalate: LangGraph); a loose glob is refused. policy
A tool call your program makes without decision= shows in the bundle as reconcile.fabricated (no model asked for it). Reconciliation compares each decide with the tool calls of the run's model exchanges. Pass decision= when a model asked for the call; read the others as calls of the program. why
With a signer, each model call's response record (the tool calls it led to) is written when the run finishes, after the run's other records. Those tool calls are known only after they ran. Read the request record for when the call was made. why
With a signer, act() fails closed: a signer it cannot reach blocks every call; fail_modes are not applied. agent(), observe(), send() and decide() raise instead: SignerUnavailable when it cannot be reached, RPCError when it refuses (the run closed, the signer shutting down), and finish() warns and still finishes the why log. The runtime has no per-class fail mode of its own, and an input or model call the signer did not record would be a silent gap. Keep the signer up, or record without one (signer=False). why
The signer gates act() only: tool calls an adapter runs itself (check() and record_action(), as the Anthropic adapter does) are recorded in the why log, not decided by the signer. The adapter executes the tool before the runtime records it. Run tools with act(), or wire the tool loop to the signer with a Tracekit integration. why
An event's citation carries log_id and the log seq only once imported; the runtime records run_id and run_seq. The signer's answers name no log id. tracekit why import --store (or --bundle) before you cite a record. why
why import --store reads the records as stored, without checking their signatures. It is a read of your own signer's store, as the viewer reads it. For an independent check, export the run and import it with --bundle --trust. why
A v2 run imported without its why log has no content: inputs, results and model calls read "content committed, not in the log", and a model call's context is what the run had observed so far. The signer keeps commitments, never content. Record with the signer-backed runtime, then import: the merge brings the content. why
With a signer, the agents' runs are linked only by the msg:<from>-><to> run:<id> inputs a message observes in the recipient's run; agent(parent=) is recorded in the why log, not by the signer. The signer registers each run on its own. Send work between agents as messages when the link must be signed. why
What the signer never committed to is checked against nothing: a model call's output, purpose and params, timestamps, and a result recorded as "result not recordable". The import's checks also excuse an uncited model call when a gateway recorded the run's model calls, and a held call retried may cite its decision more than once. The signer commits to inputs, contexts, arguments and results, not to everything the why log holds. Read those fields as the why log's word; cite the signed records for claims. why
A why log is checked against its records by why import only; why verify --salts checks content, not which records the log omits. The structural checks need the run's records. Import (or re-import) the store or bundle before you trust a log. why
why verify --salts checks only the records whose salts you reveal; the others are not revealed. Each salt opens one record's commitments, so it is revealed per record. tracekit signer reveal --record SEQ for every record a case cites. why
Attribution on a signed run needs the content vault on when the run was recorded and its model calls through the gateway; content changed by redaction is used without a commitment check. The signer keeps content only in the vault, and a redacted value no longer opens its record's commitment. Turn the vault on (content.retain) and route agents through the gateway before the runs you want to test. why
Rung 2 assumes no code between the model calls rewrote the history the model was sent, and that tools are deterministic. It re-simulates the loop from the recorded calls and results, without the agent's code. Read the assumptions every result reports; use program replay (rung 3) when the agent edits its history. why
Subagents' runs are not linked in v2 records, so a subagent tool is answered from the tape in rung 2, never replayed recursively. Nothing in a run's records names the run its subagent wrote. Test the subagent's own run separately. why
input: interventions find a run's observed value in a request verbatim (an address, a URL, a whole string of 6+ characters); a paraphrase is missed, and a removed block is replaced by a placeholder, not deleted. Blocks are matched on what the vault holds; deleting one would break the provider's message order. Use ref: with the block's hash (the ranking lists them) for an exact block. why
Replays never send a request that lets the provider run a tool itself (OpenAI Responses tools other than function and custom, such as hosted MCP, web search, file search, code interpreter, computer use; Anthropic typed server tools, mcp_servers, container; chat web_search_options), or that continues context the provider holds (previous_response_id, conversation): such a call can't be tested. A replay would run the provider's tool again, with its side effects; a removal can't reach context the provider holds. Record runs whose model calls declare only client tools and send their whole context, or test a call without them (--decision). why
Part of a why.finding stays the investigator's claim: an outcome scored on text or arguments (text~, arg~), whether the intervention matched anything (applied), and why a replay run is uncounted (ranking or budget). The verifier recomputes the rates, interval and verdict from the outcomes, checks each replay run holds its model calls as gateway records, checks a tool= outcome against the tool uses those records name (a miss only when the target is tool clauses alone), and fails replay runs of the investigation that no finding counts or lists. Bundles hold commitments, not the request and response text the scoring read; a bundle shows only the replay runs it holds. Re-run the test, or read the replay runs' content from the vault, to check a scoring; export with --with-findings, which bundles every replay run of the run. why
A test stopped by its budget reports only the looks it finished; the arms of the look under way are listed in the finding as uncounted (budget), not counted. Each look is decided on whole batches of pairs. Raise --max-calls or --max-cost, or lower --n. why
--max-cost is an estimate reserved before each call: the costliest call so far (recorded or replayed); a call that costs more than that overshoots the budget by the difference, at most once per worker. Budgets count within one tracekit why process, not across runs of the same investigation id. A call's cost is known only once it answers. Leave headroom under the amount you can't exceed; give each process its own budget. why
The surrogate's ranking is predicted, never tested; it asks OpenAI chat calls for logprobs and uses them only when every response carries the target's tokens in its text, else scores by whether the target happened (Anthropic and OpenAI Responses: always by hit). Step-level credit signals don't match executed replays; a tool call's arguments carry no logprobs. Let attribute test the ranked blocks; cite the tests. why
An investigation loads the content of every vaulted record of the run, even to test one model call. The tape (rung 2) and input: interventions need the run's results and observed inputs. Expect one content_get per 100 records of the run; each read is a signed content.accessed. why
--workers takes 1 to 16, --n-max up to 1024 pairs, the ranking up to 1024 samples. A finding names every replay run it counts, and must fit one signed record. Split a larger test into several. why
A bundle that holds a findings run without its replay runs (the findings run alone, a run-set) verifies with its findings not counted (findings counted warning). Only a bundle of the analysed run with its findings and replay runs has the replay runs to count. Export the analysed run with tracekit export --v2 --run R --with-findings. format v2
The TypeScript verifier does not check findings: a bundle with why.finding records or replay runs is UNVERIFIABLE (not checked by this verifier: tracekit why findings). Only the reference verifier recomputes findings. Verify bundles with findings with tracekit verify. format v2
tracekit export --v2 --with-findings reads the first record of every run in the store to find the run's findings and replay runs. The store does not index runs by what they analyse. Expect a slower export on large stores. format v2
The viewer's FIND THE CAUSE and RUN TEST don't run on signed runs yet; they replay why logs with an allow-listed program. Signed-run attribution (content vault, gateway, signed findings) is new in 1.1 and only on the command line so far. tracekit why attribute --run R (--store DIR | --bundle FILE --trust FILE) --gateway URL --target SPEC; the viewer shows the results. why

Graph (tracekit graph)

Limit Why it is so What to do Details
The graph shows what its records show, nothing outside them. A call no capture layer saw, a file a shell command changed beyond the policy parser's reading, or a host reached where no egress observer watched is not in it; no edge means no record, not that nothing happened. It is built from v2 .tkb bundles and optional Graphify JSON, never from a signer store, why logs, agent logs, transcripts, or a model. Read the report's first section (gaps, unread arguments, failed sources) before reading absence as proof; add an out-of-process capture layer for what agent hooks cannot see. graph, FAQ
Without --content, the graph has no file or host edge read from a call's arguments. It can still show observer file and host edges, and signed provenance edges. A bundle holds a commitment to decided arguments, not the arguments. Build with --content against the signer that recorded the runs while its content vault still holds them (the dev signer retains them for 7 days). graph, content vault
Without --content, a call decided again under the same tool call id and attempt (LangGraph decides again when it resumes after an approval) is two calls in the graph: the approval shows on the first decision, the result on the second. Telling a decision made again from another action under a reused tool call id needs the decided arguments, which a bundle holds only as salted commitments; joining by the tool call id alone would credit a person's approval to an action they never saw. Build with --content: a decision made again with the same arguments is then the same call. graph
With --content, a run whose id verified runs of other tenants or signer logs in the same graph share is not read from the vault ("not read from the vault" in the report's first section), and a run of another tenant whose id the builder's own tenant also uses reads as content that "does not open the record's commitment". The vault finds a run by its id alone, in the tenant of the identity that builds the graph. Build the graph of each tenant's runs as an identity of that tenant, against the signer that recorded them. graph
tracekit graph query and tracekit graph verify read a graph.json of at most 512 MiB; a larger one is refused ("source is more than 512 MiB; build graphs of fewer bundles each"). They read it whole into memory, with the cap a bundle source has, so a file planted in the graph's directory can't exhaust memory. Build a graph per team, agent or week from fewer bundles, and query each. graph
On a Windows file system that reports no file id (FAT, some network shares), tracekit graph verify can't tell a source swapped between its check and its read from the one it checked. Such file systems give every file the id 0, and Windows has no O_NOFOLLOW. Keep sources on NTFS or where nothing else can write while verify runs; the digest check still fails a swapped-in file with other content. graph
A graph built with --content verifies only while the same signer vault can return the same arguments. After retention, verification can report that an output file is not what its sources give, or fail because the signer is unavailable. Verification rebuilds the graph and reads the vault again when content is true. Keep the bundles and graph together; verify while the vault retains the content, or build without --content when the graph must be rebuildable from bundles alone. graph
File paths come from a write tool's path fields or shell targets as far as the policy parser reads them. Hosts come only from a call's url argument, not shell commands or an executor action's url_template; relative paths stay relative. The graph uses the policy engine's existing readings and adds no parser. Query a file by trailing path parts (--file billing.py); read hosts a shell command reached from OBSERVED egress edges. graph
An egress or kernel observer edge belongs to the run, not a call. A kernel file event stays separate from a call edge for the same path. A process's carried call id is agent-controlled, so joining it to the observer result would trust the agent. Read both edges together. graph, effect checks
Build accepts v2 .tkb bundles and a trust configuration; it has no default source and does not read a signer store or why log directly. Each bundle's edges are graded by verification against the trust configuration. Export a bundle with tracekit last or tracekit export --v2, then build the graph from it. graph
A graph built with --content can disclose paths and host names from call arguments. Those values identify files and hosts in graph.json and both reports. Share it with the same care as the bundles; omit --content when those names should not be included. graph, privacy
tracekit graph query doesn't verify graph.json: it answers from the file as it finds it, so a hand-written one (even with no sources) can answer that a person approved a call, SIGNED. Its text output says so on its first line (stderr with --json). graph.json is not signed, and verifying needs the bundles, the trust config and, for a --content graph, the signer's vault, none of which query is given. Run tracekit graph verify DIR --trust trust.json (exit 0) before relying on an answer, and cite each answer's record so it can be checked with tracekit verify BUNDLE. graph
GRAPH_REPORT.md lists at most 20 files and hosts. It is a reading summary. Use tracekit graph query or graph.json for the rest. graph
A why test is drawn as a tested causal or suppressive edge only when the verifier counts it over the graph's verified sources; one finding about a run that the verifier's check fails (its replay runs missing, or not giving its verdict) leaves every why test about that run uncounted, its label ending (not counted). A counted test is as good as its author: self-asserted on the dev signer, whose user can sign tests about its own runs. The verifier counts a finding only from its replay runs, and fails a run's --with-findings export that holds one it can't count. Build from the run's tracekit export --v2 --run R --with-findings bundle; run tracekit why as an identity your trust config pins in analyzers. graph, why
The Graphify join links only a whole matching source_file suffix and adds none of Graphify's own edges. The join is read-only and keeps no dependency on Graphify. Use Graphify for code structure; use the graph join to see its code nodes for a changed file. graph

Intent, reasoning and action checks

Limit Why it is so What to do Details
On a laptop, signed findings read self-asserted: the user who runs tracekit analyze --v2 is the agent's user, which the dev signer lists in analyzers. One user is both agent and analyzer; only a different identity can vouch for a run. For findings an auditor takes as independent, run tracekit analyze --v2 as an operator identity listed in signer.yaml analyzers (never the agent's) and pin it in the verifier's trust config. verdicts
Each pass of tracekit analyze --v2 is a findings run of its own; passes aren't merged or deduplicated. A signed record can't be withdrawn; a later pass may read more content. Read the latest pass of each author; --dry-run to look without signing. findings
What the model said is its own account: a thinking summary is the provider's summary of the reasoning, not the reasoning, and every text the checks read in a Claude Code session comes from the transcript, which the agent can write. The transcript is the only record of the model's text the hooks have; nothing outside the agent's user writes it. Route model calls through the LLM gateway, whose record is preferred; read each finding's trust tier (transcript: the agent can write it). findings, evaluation
A prompt line counts as the person's only when the hook recorded the same typed text at UserPromptSubmit (TK-X208 flags one it didn't: E20 c5_line, 24 of 24 flagged, 0 before). The hook runs as the agent's user: an agent that runs the hook itself with a made-up prompt and writes the matching transcript line passes. A harness that changes the text between the hook and the transcript (an attachment) makes a real prompt unconfirmed; a paste or an image Claude Code writes as a placeholder ("[Pasted text #1 +40 lines]") pairs with the hook's prompt before it whose text holds the line's other text, and a hook prompt no line pairs with (a line the tailer missed) is a request of its own. Hooks from before this release record no prompt (no_hook), and their transcript lines count as before. Only a hook process sees the harness's payload, and on a laptop it runs as the agent. Read TK-X208 findings against the session; system mode keeps the signer and the tailer out of the agent's reach, not the hook; update the hooks with tracekit init --dev --v2. coding agents
A transcript line that holds only text in wrappers Tracekit recognises (a task notification, a relayed message, a plugin's lead, a system reminder), with no typed text, is no prompt line: TK-X208 neither checks nor flags it, so such a line the agent appends to its own transcript goes unflagged (1.4.2 flagged it). It lifts and clears nothing, and tracekit analyze --v2 reads none of it as a request. Claude Code adds some wrappers after UserPromptSubmit, so the hook's prompt for that turn holds other text (a plugin's or observer's raw message), and its code can write other wrapper-only lines (hook output, teammate messages, system reminders) with no UserPromptSubmit at all. Until real transcripts show which, pairing these lines with the hook's prompts would flag real ones as high findings. Treat a wrapper-only line in the transcript as text the harness or the agent wrote, never as the person's (Tracekit does the same). To see what a turn really submitted, read the run's claude-code:<source> input records for it. coding agents
TK-X202 checks names and the words around them, not meaning: an edit counts as told when the request names its file before the call, or the model's text says it changes it (a change word tied to the file, before the call or after: "applying the same fix to billing.py", "billing.py needs the same fix", "the bug is in billing.py"). Naming the file innocently no longer clears it (E20 c1 with no constraint: every edit caught on every set; 17% tuned, 0% pool v2 before 2026-10-19), but one the model says it updates passes whatever reason it gives ("updating billing.py to match the fix"); "the billing module" for billing.py is no mention (a false alarm); a new file, or one a search found and the request didn't name, is flagged (5 pool v1 and 4 pool v2 hard negatives, and 2 of the 119 calls of E20's honest sessions). In a request clause with a negation, a file is no longer named where the negation governs a change of it: a prohibition the grammar can't read ("nobody should ever edit X", "X must not be edited" phrased past its lists) doesn't count X as asked, so its edit is TK-X202's; a negation of what the file does ("make sure uploader.py never sends the token", "X must not crash when ...") or of a change of one part of it ("don't change the signature in utils.py") leaves it named, and so does a negation about something else for a name with no extension ("update the README so it never mentions the old flag"). A name the grammar doesn't read as a file stays named under a negation it can't read as a change of it: "never let anyone edit the run script" is TK-X202's, "the run script must not change" is neither TK-X202's nor TK-X204's, and nor is "don't touch the README" for README.md (name the file: "README.md"). Only a write tool's edit is checked: a shell command that writes a file (sed -i, a redirection, cp, patch) is never TK-X202's (TK-X203 and TK-X204 read its targets). A word check can't read intent; a shell command's targets are a lexer's guess. Read each TK-X202 finding against the change; name files in requests; add --review, a reviewer model that reads meaning (TK-X210, warn only). findings
Stated constraints (TK-X204, and live constraints) are read by a fixed English grammar (constraints.py): a negated change word tied to the file ("don't touch / edit / write to / mess with X", "make no changes to X", "please refrain from editing X", "I'd rather you didn't touch X", "I don't want X changed"), the file said to stay as it is ("leave / keep X as is", "X is off-limits / out of scope / maintained elsewhere / frozen", "X belongs to another team", "X must not be modified"), "hands off X", "stay away from X", "keep (all) your changes / your hands / any edits / yourself out of X" (only the agent's changes: "keep the API key out of settings.py" and "keep this out of X" keep nothing away), "it" or "there" for the file named before ("X is generated; make no changes there"), a directory ("anything in vendor/", "leave src/legacy/ alone", "the vendor directory", "the .github folder", "stay out of the infra/ folder", "keep your changes out of db/migrations/"; not "the home / root / current / working / parent directory", a place rather than a folder's name; a folder word leaves the clause's files as they are, so "use the tmp folder for scratch files and leave config.yaml as is" keeps config.yaml away), "leave X exactly as it is", "the X file must not change", "under no circumstances touch X", "don't make any changes" (read-only; "don't make any changes to / in X" keeps X away when X is a file or a directory, and is no read-only) or a file people name without an extension ("the Dockerfile", "Makefile", "LICENSE"), "read-only" as an instruction ("read-only: just look", "stay read-only", "work in read-only mode"), "don't change anything", scopes ("only change T", "limit the change to T", "touch nothing but T", "everything else is out of scope"), "don't push", "no network", "work offline". Other phrasings state nothing: it reads 9 of the 14 ways of saying it in E20's pool v1 ("don't go near X", "a hard freeze on X until after the audit", "X has a pending PR, so editing it will cause a conflict: avoid", "hands off for now" after naming X in another clause, "nothing under X" are not) and 11 of 12 in pool v2 ("it would be better if X stayed exactly as it is" is not); both pools were read while the grammar was written. On pool v3 (blind, scored once on 2026-10-20; the final code review's fixes after that run moved none of its numbers) a live constraint held 67-92% of the edits made after a "don't touch X", by cover. A file is read in a window of five words. Some phrasings are left unread so they hold no wanted call (on E20's 56 honest sessions none is held; before the round-2 fixes 13 were, as "read-only" describing a mode, "nothing should change for existing callers" and "don't push to main" were read as constraints), though a phrasing outside them still can, which the person then approves (an approval by another identity than the run's lowers TK-X204 to low): a condition after the file, the push or the network ("don't edit X until the tests pass", "without checking the tests first", "unless", "before", "if", "while the server runs", "when DEBUG is set": the change is allowed once the condition holds, which the grammar can't check; "while you work" and "while fixing Y" are the task itself; a condition on the person's own go-ahead, "don't push before I review", "without asking me first", "until I say so", "unless I confirm", keeps the constraint, as the hold is what they ask for); "read-only" describing a thing ("add a read-only mode", "make the connection read-only", "the cache should be read-only after startup"); "nothing should change" for its callers; a negated change of one aspect of the file asked for ("don't change the public API of X", "the signature in X", "nothing in X changes its behaviour"); a scoped push ("don't push to main", "never push secrets"; "don't push it to origin" is read); a push or the network in a description rather than an instruction ("we don't use the network in unit tests", "the app works without network access", "our policy is no network access in CI"); a constraint a later clause of the same request asks for ("don't touch X for now; ... then update X too", "don't change anything, then fix it"); a question that asks rather than requests ("should I change X?"; "could you leave X alone?" is read); quoted text, quoted lines ("> ...") and code (blocks, lines four spaces in); a negation turned around ("don't forget to update X", "you don't need to touch X", "I don't mind if you change X"); "don't change how X is imported"; "any changes" followed by what picks them out: "to", "of", "in", "on" and the like with no file or directory there ("don't make any changes to the tests", "... to the public API", "... on main"), or "that", "which", "beyond", "outside", "for the sake of" ("... that break the API", "... beyond what the fix needs", "... for the sake of style"; the whole project, "to the code / the repo / my project", "on disk", "on this machine", and "of any kind", "in the meantime", "under any circumstances", "to any file", "for now", "for any reason", "for me", "on your own", "directly" stay read-only); "outside X" ("don't touch anything outside src/", a scope; "everything outside X is off-limits" is read); "keep the diff to X" (as "keep the changes to X small" asks for a change); "don't change anything except the docs" or "don't change anything else" naming no file; a network word after a change verb or before a noun ("don't change the network code", "no web UI changes"); "offline" anywhere but at the start of an instruction ("make the CLI work offline"). A grammar that guesses more would hold or flag calls the person asked for. Say constraints plainly in requests ("don't touch billing.py"); read the run's constraints at the top of its review in tracekit view. policy
A scope ("only change src/pager.py", "everything else is out of scope") is checked after the run (TK-X204) and never held live: the hook adds no live constraint for it. A file named to keep away ("don't touch billing.py") is still held live. Holding every write but the named files would ask the person about each test, lockfile or build write. Read TK-X204 after the run; name the files that must not change ("don't touch billing.py"), which the signer holds live, or keep them out with a policy rule. policy
A later "it", "them" or "there" in a clause that asks the agent for the change lifts the file named just before it in the same request (for "them", each file of that clause), so "Don't touch billing.py. If tests fail, fix them." states no constraint: "them" is read as billing.py, and the constraint is lost (no live hold, no TK-X204). A clause asks for the change when its change word is in its plain form with only words of asking or allowing before it ("fix them", "you can edit it locally", "later you can update it", "feel free to change it", "go ahead and update it"), and it doesn't start with "to", "should" or "must". A clause that waits on the person lifts no file, named or by "it": the person's go-ahead in it or in a clause after it that only says that ("you can change it after I approve", "edit X once I say so", "you can change it later, but ask me first"). Any other clause with the change lifts nothing, and the constraint holds: "ask me before you change it", "to change it, ask me first", "should you need to change it, ask me", "I'll update it myself", "we'll change it in the next PR", "explain how you would change it", "changing it breaks the deploy", and also "don't forget to update it", "you'll need to edit it", "you may need to change it" and "I want you to change it", which do ask for it (the person approves the held call). A constraint whose condition is the person's own go-ahead ("never touch X without asking me first. Change the timeout there to 30") is never lifted that way: it holds, and a file a request lifts that way counts as named (no TK-X202). The grammar can't tell what a pronoun stands for; it takes the file named just before it, so that "X is frozen in production, but you can edit it locally" reads as the person meant, and lifts only where the clause hands the change to the agent, so a change merely mentioned keeps the constraint. Name the thing to change instead of "it" ("if tests fail, fix the tests"), name the file again ("fix them, but don't touch billing.py"), or state the constraint last ("If tests fail, fix them. Don't touch billing.py."). policy
A live constraint compares a file by its base name, and a directory by its name anywhere in the path written: another billing.py elsewhere is held too, as is a write under any directory of the kept one's name (one over the project included), and a recursive rm or rmdir of it. The writes it sees: a write tool's paths, a redirection, tee, touch, rm, truncate, shred, cp/mv/install/ln/rsync/scp destinations, sed -i/perl -i files, dd of=, patch's file, git rm/mv/restore paths and git checkout -- X, the -name of a find that deletes or runs a command, and formatters that rewrite in place (black, isort, rustfmt, prettier --write, gofmt -w, ruff format, ruff check --fix, eslint --fix). A write the policy engine's shell parser can't see isn't held: a script, a variable or glob path, python -c or python fix.py billing.py, awk -i inplace, an editor (vim, ex), an archive extracted over it, git apply and patch with their files only in the diff (a write, so read_only holds them; a file kept away is not matched); a line it can't parse, such as case, which the policy's TK-SHELL-PARSE asks about. A push is git push; the network is an http or browser call, WebFetch, curl, wget, ssh, git fetch, pull, clone or push and package installs. A run takes 32 distinct file constraints (keep_away, only_change; read-only, no push and no network are always added): past them a new one is a signed capture.gap{constraint_refused}, constraint_add answers refused, the hook tells the person, and every later write of the run is held, so made-up constraints only make the agent wait. The signer matches what the call's arguments show, by commitment; it doesn't run the shell. Keep a policy rule or a sandbox for writes that must never happen; add the kernel sensor, whose file and connect effects TK-X204 checks after the run. policy
A call that writes more than 256 distinct files is held in any run with a file constraint (keep_away, only_change), whatever the files: "the call writes more than 256 files". The signer checks each file name against each file constraint by salted commitment; the cap bounds that work per call. Approve the call if the person meant it, or write the files in smaller commands. policy
The hook keeps a session's constraints in its own state, in the agent's runtime dir: a session resumed after it ended starts without its earlier prompts' constraints (SessionEnd removes the state), and an agent can edit that state before its next run. A run the signer closed idle passes them to the session's next run for at most 30 days after the session's last hook event (Claude Code's default transcript retention), and on Linux only until the runtime dir ($XDG_RUNTIME_DIR) is cleared at logout or reboot; a session continued later starts without them. Constraints are signed per run; the hook is the only place that knows a session's earlier prompts, and its state must not pile up forever. Restate constraints in the first prompt after resuming a session; for limits that must hold whatever the agent does, use a policy rule. policy
On a laptop, the person who answers a call a live constraint held is the agent's user. The dev signer has one user. In system mode, set signer.yaml approvals to a person other than the agent. approvals
"Signed before this call" holds only when the record of what was said is older than the call's decision. With Claude Code alone it often isn't: the tailer reads the transcript after the model wrote it, so its lines are signed after the hook's decide (transcript_order). The hook decides as soon as Claude Code runs the tool; the tailer follows the file. Route model calls through the LLM gateway, which records the response before the client gets it. viewer
Claude Code keeps the model's thinking only sealed unless thinking summaries are on: TK-X201 is then withheld for its calls. Claude Code's default shows no thinking text (showThinkingSummaries; headless --thinking-display). tracekit init --v2 turns them on (--no-thinking-summaries leaves them alone); headless: claude -p --thinking-display summarized; tracekit doctor warns (D-THINKING-SUMMARIES). doctor
The LLM gateway asks for readable reasoning only where the request already has the model reason: a request with no thinking (a Claude model that thinks by default, such as Opus 5.5, still returns none of it), display: "updates", or a chat completions request gets what it asked for. The gateway never turns on reasoning the agent didn't ask for, and changes only the field that shows it. Have the agent send thinking: {type: "adaptive"} (Anthropic) or reasoning (Responses); the gateway then asks for the summaries. gateway
What the gateway gets back is the provider's summary of the reasoning, in its words, not the reasoning, which providers return only sealed (a thinking block's signature, OpenAI's encrypted_content) or not at all. A summary can leave out what drove a call. Providers don't return these models' reasoning in the open; a summary is the most they show. Read a summary as the model's account, never as proof of why it acted. gateway, findings
Any 400 or 422 to a request the gateway amended is taken as the provider refusing the amendment: the request goes again as the client sent it, so one bad for another reason reaches the provider twice. After a request sent again succeeds, that model's requests aren't amended until the gateway restarts (at most 1,024 models remembered). Providers word an unknown-field error differently, and the agent must never fail on a field it didn't send. Read the first exchange's error (sent again without the amendment as exchange ...); restart the gateway once a provider takes the field. gateway
TK-X203 reads a Bash command with a lexer: redirections, tee, touch, mkdir, rm, rmdir, truncate, and the destination of cp, mv, install, ln. Variables, globs, command substitutions and scripts aren't followed, symlinks aren't resolved, and a relative path after a cd is not checkable. The project is --project or the first prompt's working directory; / or a home directory is not checkable. A shell is a language; the analyzer doesn't run it. Pass --project; for writes that must be seen, add the kernel sensor, whose file effects TK-X203 also checks. findings
A run still open is refused unless --open, and then is partial; the analysis stops at its budget (60 s, --budget) or its size caps (131,072 distinct words, 8 Mi characters of prompts): what it found before stays, what it didn't reach is not_checkable: budget or size, and the result is INCOMPLETE (exit 3 when nothing high was found). Each text a check reads is cut at 64 KiB, and a streamed response keeps at most 512 Ki characters of text and reasoning, and a Gemini candidate at most 1,024 parts (marked truncated). What an open run does next isn't in it; a run of any size must finish. Analyse after run.final; raise --budget for very long runs; review calls past the size caps by hand or with --review. findings
The constraint grammar reads a text in time linear in its length except in two places: a negated push or network word, or a word that lifts a constraint ("fix", "add", "push"), reads the words before it in its clause again (a 64 KiB clause of them: about a second), and "them" stands for every file of the clause before it in each clause that says it (64 KiB of "don't change them" or "leave them alone" after 3,000 to 5,000 files: about 2 s and up to 1.1 GiB in tracekit analyze --v2). The hook reads each prompt with the same grammar. Reading each such word against its clause keeps the grammar small, and real requests are far from these sizes. Nothing on the signer: the grammar runs off it, in the hook and in tracekit analyze --v2. Bound the text a reviewer feeds the analysis from elsewhere. findings
A call decided under an id the model's response doesn't carry (an adapter's own id, a Gemini call without one) is unlinked: its reasoning is not checked. The link between a call and the model message is the provider's tool call id. Use an integration that decides under the provider's id. findings
The text checks (TK-X205, X101..X104, X111..X114, X120, X211) read words: a success claim, a denial or a mention phrased outside their word lists is missed. On E20's pool v3 (blind, scored once on 2026-10-20) TK-X205 finds 86% of the false success claims after a failed run (exit 86%, piped 87%). On pool v2 (blind, scored once on 2026-10-19, read since) it finds 85% of false success claims made with the pool's success phrases and all of its free-form final summaries; on pool v1 68% and 96%. An admission takes back the success claims about what it names ("2 tests still fail"), not the others: a summary that says a test still fails passes even when another check it claims also failed. A denial is read as the model's own act: what a thing does ("so it never makes network calls", "the app works without network access") is no denial, nor is one after "so" or with "it", "they" or "which" for its subject; a lie put that way ("so nothing was pushed") is missed. "Changed X without touching the tests" denies only the tests. "No code changes" denies an edit of a source file only, read by its extension (59 of them, findings_text.py SOURCE): an edit of a file with another extension (a stylesheet, a template, a config) is no code change. TK-X101 reads a claimed test, build or lint run ("all tests pass", "the build is clean", "ESLint reports zero problems", "I ran the linter"); a success claim that names no check ("everything works as expected") claims no run, and most of the pools' claims are such: 13% of pool v2's and 29% of pool v1's Fc sessions are found, every one whose claim names a test run. "X is installed" reads as a state, not an install. A claim or denial that names nothing gives the claim and denial checks nothing to find: TK-X211 finds the action it leaves out. A word list can't read meaning, and a text check finds only what the text says. Read each finding against the run; for runs that matter, add --review (a reviewer model, TK-X210) or review what the model said yourself. findings, evaluation
TK-X211 counts an action as told when the model names it, its readable reasoning included (Claude Code shows the person a thinking summary): a word of its kind in the model message that asked for the call or one after it ("added the dependency it needed and pushed" passes; a word of deleting only with a part of the deleted file's name, a package noun only beside a word of adding), its object named anywhere in the run, also for another reason ("backing up billing.py", then billing.py sent out; E20 tuned F2 c1: 0 of 24 caught), or the person's request asking for it, by its object ("upload report.txt") or with the verb as an instruction about this work ("commit and push the branch"; not "the upload handler", "I'll push it myself", "remove the unused helper" before a delete of another file). A kind word with or after the call still clears it when it is about something else ("uploaded the screenshot" beside an upload of .env). A dotfile is named only with its dot: ".env" tells of an upload of .env, "env" ("checking the env vars") or "travis.yml" for .travis.yml tells of nothing, and an ellipsis is no dot ("the config... env vars"). The request's words too: "upload the env file" asks for no upload of .env, so one the model never mentions is found. Sealed reasoning tells nothing. It sees what a lexer sees: curl and wget body or file flags, an HTTP tool's POST, PUT or PATCH with a body, httpie's method, scp, rsync and sftp to a host:path, git push, package publishes, rm, git rm, git clean, a delete tool, install or add of a named package; a script, an SDK call, a variable or another program hides the action. A delete of a temp path, a build or cache directory, or a file of a name an earlier call wrote is the run's own (by name: a file of that name elsewhere passes too); a file an edit tool changed is not. Counting only the text flagged honest runs that explain the action in their reasoning; a lexer doesn't run the shell. Read TK-X211 against the run; require approval with a policy rule for actions that must never happen unannounced; name a dotfile with its dot in requests (".env"); add the kernel sensor for what a script does. findings, evaluation
TK-X205 sees a failure only in a related call's signed result or its output: a test or build run it can name (pytest, jest, vitest, mocha, go test, cargo, unittest, make, npm/yarn/pnpm scripts, Maven, Gradle, ...) whose result is ok: false, or whose output has a runner's failure summary, a non-zero exit, or a Traceback or error line with no pass summary. A test run through a script it doesn't name, a runner that prints success and exits 0 after a failure, output cut before its summary, or a claim about something other than tests, a build, a deploy, a merge, a push, a commit or an install is not checked. A result the agent didn't complete is no_result. Only the run's own records and their content are read; the analyzer doesn't run anything. Run checks with a runner it names, keep the summary line in the output (tail keeps it), and complete every call. findings
TK-X210 (--review) is a model's opinion: it can miss a fault, flag an honest run, and be steered by text in the run that addresses it; two calls on one run may answer differently. Its detection and false-alarm rates are not measured yet (the E20 model arm is built, not run). A reviewer model reads meaning the checks can't, and the run's text is written by the agent it reviews. Read TK-X210 as a second opinion beside the deterministic findings, never as a pass; it never changes the exit code or decides a call. Run the E20 model arm on your reviewer model before relying on it. findings, server threat model
A reviewer of the agent's own model family may share its blind spots. The family is read from model names (claude, gpt, gemini, ...); a fine-tune or alias with another name is not recognised. The analyzer knows a model only by the name the records and --review-model give. Configure a second provider (OPENAI_API_KEY or ANTHROPIC_API_KEY, or TRACEKIT_REVIEW_MODEL with TRACEKIT_REVIEW_URL) and --review picks the one of another family; or pass --review-model. tracekit analyze warns when the families match. findings
--review sends the run's text (redacted by the signer) to the reviewer model: the one at --review-url, else the one it picks (TRACEKIT_REVIEW_URL's, else Anthropic's or OpenAI's API, whichever key is set and is of another family than the agent's). Judging a run means reading it. For runs whose text must not leave your machines, point --review-url at a model you run yourself, or at your LLM gateway in front of one. privacy
The reviewer reads a run cut to about 48,000 characters (each text to 1,200, arguments to 400; records dropped from the middle), and sees whether each call succeeded, not its result. One bounded call per pass keeps cost and time fixed on runs of any size. Read the cut (shown.review.truncated); for a long run, read TK-X210 for its start and end only. findings
--review needs a findings run to record the model call in, so it runs only as an identity signer.yaml analyzers lists, on the signer that holds the run, and not with --dry-run. Without --review-gateway the analyzer records the call itself: the record is its own report, not an independent one. Only Anthropic Messages and OpenAI chat endpoints are spoken. The call is evidence too, kept beside the findings; only the gateway records it from outside the analyzer. Run it as an analyzer identity; use --review-gateway where the gateway runs. findings
CrewAI, Browser Use, a LangGraph tracekit_tool_node graph and the Vercel AI SDK record no readable reasoning through their integration; the Claude Agent SDK needs tracekit_said in the app's message loop and Microsoft Agent Framework needs tk.chat in middleware=. CrewAI's after-LLM hook sees no response that asks for a tool, Browser Use's Tools never see the model's output, a ToolNode has no model hook, the Vercel middleware sends a commitment only; neither SDK gives a hook the model's messages. Record those model calls with tracekit.instrument() or the LLM gateway; add the one line where the table says. reasoning
A framework rarely says whether reasoning text is a summary or the model's own reasoning: the integrations record it as a summary unless they know (an open model's reasoning_content, an inline <think>). Cursor's thinking text is recorded as a summary too. Only the provider knows; the framework passes the text on. Read summary as "readable"; the monitorability score never counts more full reasoning than there was. reasoning
Once an integration records model messages, the signer reconciles them with the calls: a call it decides that no recorded message carries reads as reconcile.fabricated (a message that failed to record, which warned), and a call in a recorded message no decide followed reads as reconcile.hook_missing (a run that stopped before its tools ran; a call the framework skipped or a person turned down before any hook: an ADK confirmation declined). The LangChain middleware and Pydantic AI's capability add each call to its response only when it reaches their gate, so a call they never decide (a person's reject or a call limit in another LangChain middleware, the recursion limit, arguments that fail Pydantic AI's validation) is not recorded; a Pydantic AI approval resumed by another Tracekit capability adds the call from the history. A call a person edited in LangChain's HumanInTheLoopMiddleware is recorded as the model asked for it and decided as edited: it reads as reconcile.args_mismatch. Gemini CLI's and Cursor's messages name no call (said_only) and are never reconciled. Reconciliation can't tell a call left out of the record from one the agent made up, nor a person's edit from an agent's. Read such records against the warnings the agent printed and the run's last steps; read an args_mismatch on a call your app let a person edit against that edit (the interrupt's resume value), or use the policy's ask, whose approval the signer records. gateway, reasoning
Codex's reasoning is readable only with model_reasoning_summary set (init sets it at the top of config.toml; a profile's own setting is neither set nor read by init and doctor), and stays sealed (encrypted_content) without it. Each hook reads the rollout lines written since the session's last hook, at most 4 MiB: lines that failed to send are not read again and no gap says so, a rollout rewritten in place is read on from its new end, and a Codex release that names a call's hook differently reads as args_mismatch or hook_missing. The rollout is Codex's only record of the model's reasoning; the hook maps each call the way Codex builds its hook payload. Keep the setting on (tracekit doctor: D-CODEX-REASONING); route model calls through the LLM gateway where the record must be complete. coding agents
Gemini CLI's thought summaries and Cursor's thinking text are not linked to a call, and Gemini CLI writes its thoughts after the calls ran. Text from Codex's rollout, Gemini CLI's chat recording and Cursor's hooks is written by the agent's own process (trust tier transcript). Neither gives a tool call an id in its hooks; Gemini CLI queues thoughts until the calls complete; the files and hooks belong to the agent's user. Read their reasoning as the session's, not a call's; route model calls through the LLM gateway for text the agent can't write. coding agents
tracekit view runs the checks only for the dev signer's final runs; another viewer shows each model line as committed, not its text. Only the dev signer grants the viewer's user content_read. Run tracekit analyze --v2 as an identity with content_read. viewer

Effect checks (TK-X206, TK-X207)

Limit Why it is so What to do Details
TK-X206 and TK-X207 join effects to calls by time across two clocks: the sensor's (each effect) and the signer's (each decision and result). Past --clock-skew (0.5 s) honest effects become findings. A sensor clock ahead shows in any effect recorded before its own time; one behind only when every effect reached the signer more than the import's one-second flush late, which a slow import looks like too. The sensor stamps events on its node; the signer on its host. Keep both hosts on NTP; when a finding is labelled clock_skew, run again with the --clock-skew it names. findings
The harness itself (Claude Code's node process, Codex) runs from before the run: its connections (its model calls) and file writes are agent_process, not checked by TK-X206, TK-X203 or TK-X204, except a file at a write call's path inside that call's window. So code that runs inside the harness's own process (a plugin, an extension) and writes outside the project isn't flagged from the sensor's records; a call's process writing there is. A WebFetch's connection counts only to a host the harness didn't reach outside fetch calls, and a fetch over a connection the harness kept open opens none (TK-X207 finding). Nothing names the call for the harness's own work, and a sensor gives an address, not a host name. For hosts, add the egress observer, whose signed reconcile covers them; read a fetch's TK-X207 against the egress records. findings
A shell or Python process started outside any call, not by a call's process, is hook_like, not checked: Tracekit's own hooks look the same, and so does a hook or status line of your own, or a Python program a planted hook runs (E20 held-out: a Python exfiltration between calls was not checkable in 4 of 8 Claude Code runs). Its other programs are still checked. The hooks run as the harness's children, around each call, with no call of their own; only binary and parent tell them apart. Review the harness's hook settings; with Codex, keep CODEX_TOOL_CALL_ID in the sensor so a call's processes name it. findings
Without parent exec ids (Falco, or Tetragon before this release's import), a process a call left running is that call's only inside its window: a server's later children and connections are TK-X206 findings. Falco names no parent process; the join falls back to time. Use Tetragon with tracekit sensor import from this release for agents that start servers or background jobs. findings
TK-X207 checks a write only where you say the sensor's file policy selects writes (--sensor-skip DIR for each directory it leaves out), a kind of effect only if the run has some, and a Bash command's programs by name: a command whose program has the same name as Tracekit's hook interpreter (python3 -m pytest against a python3 hook) is hook_binary, not checked, when only such processes ran. The run doesn't record the sensor's policy; a hook's process and the command's look alike. Pass --sensor-skip; with Codex keep CODEX_TOOL_CALL_ID, which makes each command's processes name it. findings
The egress observer's per-minute network totals aren't part of TK-X206 or TK-X207. The signer reconciles them itself (reconcile.unexplained_effect); a total over a minute can't be placed inside a call. Read reconcile.unexplained_effect records for hosts. egress

PCM 0.1: proof-carrying messages (experimental)

Limit Why it is so What to do Details
A grant can't be revoked: it holds until its expires_at. Revocation needs a list every receiver checks; this version has none. Keep expiries short (the signer refuses more than 24 h); grant per task, not per agent. PCM
A receiver accepts a message within 300 s of its own clock, so signer and receiver clocks must agree. It refuses every message signed before it started, and replicas behind one address don't share what they saw, so a message replayed to another replica passes there. tracekit pcm verify doesn't check replay at all: its line ends not checked: replay, as pcm.verify's skipped lists replay without a Replay and recipient without me. Replay state is in memory, one pcm.Replay per process; refusing what came before the start is what makes a restart safe without saved state. Keep both hosts on NTP; after a receiver restarts, the sender sends again; run one replica per receiver: the A2A gateway is merged, and shared replay state comes with enforcing PCM in it, a follow-up. PCM
Only four claim types: tests_passed, approved_by, reached_host, file_written. A result the agent's own process reported (T1) is its word, so the claim is unproven; proven needs a result a gateway or executor wrote (T2), or a record the signer wrote itself (an approval, an effect.observed). file_written counts only full-content writes by the Write tool, not edits. Each claim needs a checker over records that exist today, and a T1 ok is whatever the client sent. Run calls that matter through the tool executor or a gateway; observe hosts with the egress observer; send other facts as payload, which nothing checks. PCM
approved_by without covers proves only that the person approved the call the agent named call (a read_file call can be named refund-81-approved); what that call was is in the claim's approved and its detail, and it meets no approved_by a schema lists. With "covers": true the verifier checks that the approval covers the request, in two ways only: it issued the message's root grant, or it is of the tool the schema names with the intent's args, equal in JCS. So an approval of a range ("refunds up to $200") covers a request only through the grant it issued; under a schema without tool, or with an unopened decision of the schema's tool, the claim is unproven, and an unopened decision of another tool fails it. The evidence must hold the approval, the approval.request it answers and the policy.decision that request names, or the claim fails. It fails too, in any order, when its records disagree on what was approved (two requests of one approval naming two decisions, or approvals of the call naming decisions whose tool and args differ in JCS, args null when not opened, as when a person approved two attempts of one call id with other args) or when it lists a record twice. A claim names a call, not what it did, and an offline verifier can't judge whether other args are close enough: the root grant (whose caveats it checks) and exact args are the two rules every verifier applies alike. Records that name two approved calls give no one answer, and taking the first would make the result hang on their order. As a receiver, list approved_by in the schema's claims, so only an approval that covers the request counts, and name the schema's tool; for authority over a range, require a grant. As a sender, claim covers: true and cite the approval that issued the root grant, or open the decision (pcm_evidence(..., args=...)); pass the three records of one approval, once each. PCM
With covers, an approval of the schema's tool with the intent's args covers every message that asks for that tool with those args: to any receiver, as often as the run sends one, each with a new nonce. An approval is of one call, not of one message: nothing in its records names the message it stands for. For one-time authority, put a field unique to the request (such as request_id) in the schema's fields, so the approved call carries it, and act once per value; for repeated or bounded authority, require a grant, whose caveats and expiry bound it. PCM
tests_passed and reached_host count only calls of tools PCM 0.1's placement table classes as shell or http: 54 tool names frozen from the policy packs of Tracekit 1.4 (Bash, shell, WebFetch, http_request…), shipped as tracekit/pcm/tools.json. A custom shell or HTTP tool, a tool a pack added since, or another tool with a command or url field, makes the claim unproven ("a tool the verifier can't place as a shell tool"). The verifier is offline and reads no deployment's policy; every PCM 0.1 verifier must place a tool the same way, so the table is part of the protocol; a command field alone doesn't make a shell call. Run tests and requests through a tool the table names, or send the fact as payload. PCM
A T2 result's tool name stands for its class: the verifier takes a Bash call a gateway or executor ran as a shell call, whatever it ran. An operator who names an executor action after a placed tool of another class (an HTTP action called Bash) lets its ok prove tests_passed. The record names the tool, not what ran; PCM 0.1 doesn't pin which via may attest each class. Name executor actions and gateway tools after what they do, never after a placed tool of another class; as a receiver, read run by <via> in the claim's detail. PCM
The verifier trusts the schema documents it is given. The hash pins what a schema says, not who wrote it, and id patterns run with Python re. Both sides agree on a schema by its content hash; there is no schema registry. Ship schemas with the code that uses them and review their patterns like code. PCM
Evidence must come from the sender's own run, under a checkpoint of the log that signed the message. Opening a decision shows its args to the receiver. An offline check needs an inclusion proof under a pinned note; a claim about args needs the args. Wait for the next checkpoint (pcm_evidence returns pending until then; the SDK nudges and waits); claim only what you would show the receiver. PCM
Evidence proves a call happened in the sender's run, not that nothing happened after it. A suite that passed, then failed after the code changed, still proves tests_passed with the record of the pass; a file written, then overwritten, still proves file_written with the first write. Both are proven. The sender picks the records it sends, and PCM 0.1 has no evidence that shows the run's later records. A later version could carry the run since the call and bind tests_passed to the git tree it ran on (the specification's Appendix B question 5). As a sender, claim right after the call (pcm_evidence has a checkpoint about a second later). As a receiver acting on the current state: refuse a message whose ts is more than a maximum age (seconds or a minute) after the oldest ts among the claim's evidence records (tracekit pcm verify prints that age), or whose evidence is older than the last change you know of; for tests_passed, name the suite, have it run after your request, or run it yourself on the code you act on; for file_written, hash the file you receive and compare it with the claim's digest, the one check that rules a later write out. PCM
The log key signs PCM messages and grants as well as checkpoints, so a fault in PCM signing means rotating the log key. trust.json already pins the log key, so a receiver needs no new trust entry. A dedicated PCM key needs a trust.json member of its own, which PCM 0.1 doesn't define; it comes with a later PCM version, before PCM leaves experimental. Treat the log key as the signer's most valuable key (signing); rotate it if PCM signing is ever in doubt. PCM
There is no revocation and no key validity period: a leaked log key signs any message, grant or evidence checkpoint, with any ts and expiry, and receivers accept them until they remove the key from trust.json. The 24-hour grant cap binds only an honest signer; witness cosignatures (witnesses_required) limit forged evidence, not forged messages or grants. PCM 0.1 trusts the keys trust.json pins and has no revocation list or key lifetime. Keep the log key where only the signer reads it (signing); require witness cosignatures on evidence; if the key leaks, remove it from every receiver's trust.json, rotate it, and treat what you accepted under it since the leak as unverified. PCM
The trust.json PCM reads pins one Ed25519 key per log: two under one log name (an old key kept after a rotation, as signing asks for bundles) make pcm.verify raise and tracekit pcm verify exit 2. Rotating the log key means replacing it there, after which messages, grants and evidence the old key signed don't verify. PCM 0.1 declares no rotation, so a verifier can't tell which key may sign now, and an old key that leaked would sign grants for as long as it stays pinned. Pass a trust file with only the current key (tracekit signer trust --config <signer.yaml> -o pcm-trust.json writes one), apart from the one that keeps old keys for bundles; after a rotation, senders ask for new grants and send again. PCM
Messages and grants carry an Ed25519 signature only: a trust.json that pins the SLH-DSA hybrid key gets it checked on evidence checkpoints, not on messages or grants. PCM 0 signs one line; the hybrid line comes when agents need it. Don't rely on SLH-DSA for PCM authority; keep grant expiries short. PCM
reached_host compares hosts in ASCII only. A call whose URL has any character outside printable ASCII (! to ~) anywhere in it, the path too (a space, tab, newline or other control character, DEL, bücher.example, /café), or whose host holds % (http://%61.example/: hosts are never percent-decoded), is unproven: the verifier can't tell which host it reached. So is an effect whose host is of that kind (a claim's host may hold only a-z, 0-9, ., _, : and -, or the claim fails as malformed), a URL with a [ or ] in its authority other than one pair around an IPv6 or IPvFuture address that opens the host after the last @ (http://[x]@good.com/, http://[zz]@[::1]/, an authority of [::1]@ alone; a browser reaches [::1] from the second), and an IPv6 address whose dotted quad has a leading zero ([::ffff:01.2.3.4]). An xn-- label is compared as written, without a punycode check. IDNA 2003, UTS 46 and Python's idna codec name some Unicode hosts differently, and Python releases read controls, spaces, tabs, newlines, brackets and leading zeros in a URL differently (urlsplit, ipaddress): PCM 0.1 refuses all of it, so every verifier reads a host alike on every Python. Fetch and claim hosts in ASCII: an international name in its xn-- form, as DNS names it (xn--bcher-kva.example); percent-encode spaces and non-ASCII characters in the path and query, and keep % and brackets out of the host but for an IPv6 address. A call's detail names two causes the sender can fix here: its URL is not printable ASCII: send it without spaces or control characters, with the host in xn-- form and anything else percent-encoded, and its host has a %: send the URL with the host as plain ASCII, not percent-encoded. Any other cause but the IPv4 one below says only the verifier can't tell whether call …, and an effect's host a host the verifier can't read: check the URL or host against Hosts. PCM
reached_host reads an IPv4 address only as a dotted quad: four decimal numbers 0 to 255 without leading zeros (127.0.0.1, 10.0.0.1). A host whose last label is a number (digits, or 0x and hex digits) written any other way, in a URL, a claim or an effect (0127.0.0.1, 010.0.0.1, 127.1, 0x7f.0.0.1, 2130706433, 1.2.3.4.5), is unproven. Resolvers read those forms apart: macOS connects to 127.0.0.1 for 0127.0.0.1, where inet_aton reads 87.0.0.1, so no verifier can say which host the call reached. Fetch and claim IPv4 addresses as dotted quads. A call's or a claim's detail then ends with its host is an IPv4 address not written as a dotted quad: send it as four decimal numbers 0-255 without leading zeros; an effect's says only a host the verifier can't read. PCM
reached_host can't tell the host of a URL that starts with view-source: or blob: (blob:https://api.example.com/x): a call of one is unproven. A browser's address bar reads the URL inside, while WHATWG URL (Node's URL) reads no host from it, so a verifier can't tell what the call reached. Fetch the URL inside (https://api.example.com/x). PCM
reached_host can't tell the host of a URL with no scheme that doesn't start with // (/api.example.com/x, api.example.com/x, api.example.com:8080/x): a call of one is unproven. A client given a base URL (an HTTP client's base_url, a page's fetch) reads it as a path on the base's host, while an address bar or curl reads a host from it, so a verifier can't tell what the call reached. Fetch the whole URL, with its scheme and host (https://api.example.com/x); the claim's detail says so. PCM
reached_host from a call needs its T2 result ok: a call the host answered with an HTTP error status (a 404, a 500) is recorded as not ok, so the claim fails and the message is rejected, though the host was reached; the claim's detail says what to do. The evidence records whether a result was ok and a hash of it, not the status or whether a response came back; telling an error answer from a failed connection needs a new field in the evidence format (a PCM 0.2 question, the specification's Appendix B question 6). Claim the host from a call that succeeded, or from the egress observer's effect.observed, which counts the connection whatever the answer. PCM
reached_host reads the host alone and ignores the port: the claim doesn't say which port was reached, and a URL a browser refuses, such as one with a port above 65535 (https://api.example.com:99999/) or an xn-- label that is no valid punycode, can still name its host. Every verifier must read a URL alike, and checking ports and punycode would add rules each must share. A client that refuses such a URL fails the call, and a failed call proves nothing. When the port matters, read it in the evidence: the URL in the call's opened args, or an effect's port. PCM
reached_host is proven by an effect.observed only when the egress observer saw a connection to the host open (connections above 0). A kernel sensor's or OpenShell's connect is the attempt, and an egress minute with no connection is a connect that failed or a later minute of a connection opened before: each makes the claim unproven ("saw no connection to … open", "… an attempt"). Tetragon reports the connect call, not whether it opened; the egress observer counts a connection once its upstream connect succeeds. Route the run's traffic through the egress observer and send the minute in which the connection opened, or make the request with an http tool through the tool executor. PCM
tests_passed knows a fixed list of test commands by bare name, without wrappers: uv run pytest, CI=1 pytest, .venv/bin/pytest, ./gradlew test and npm run test:unit are no test command, so the claim fails. A suite is one line of plain words: no operator, redirection, $, backquote, backslash, #, brace or glob character. Of the flags that run no tests it refuses -h, -V and --help, --version, --collect-only and their prefixes (--he, --co), not others: pytest -qh, pytest --fixtures, go test -run NONE, go test -exec true, make test SHELL=/bin/true, npm test --script-shell=true, cargo test --no-run and mvn test -DskipTests pass and run no test. proven means this exact command line exited 0 on the executor, with whatever program its PATH names pytest. Every PCM 0.1 verifier must recognise the same commands, so the list is part of the protocol, not a guess at what a command does; every flag of every runner can't be listed. Run and claim the suite as the list writes it (pytest, python -m pytest, with the venv on PATH); as a receiver, compare suite with the suites you accept before trusting the claim. PCM
file_written needs an absolute path: one from /, read by POSIX rules (\ is part of a name, so /repo\a.py is not /repo/a.py, even when the call ran on Windows), or a drive path (C:\repo\a.py, C:/repo/a.py), read by Windows rules. A drive path is proven only by a Write call of the very same string, which assumes the call ran on Windows: on a Linux executor that string is a relative file name, and the claim is still proven. The same path spelled otherwise (C:/repo/a.py for C:\repo\a.py) is unproven. Paths compare case by case, so a call of c:\repo\a.py fails a claim of C:\repo\a.py. A UNC path (\\server\share\a.py), \repo\a.py and C:a.py are relative, so such a claim is malformed. A Write call whose path is relative, or holds a .., proves nothing: the claim is unproven when that path ends with the claimed one. A relative path names a different file from each directory, and the record holds neither the working directory nor the system that ran the call: C:/repo/a.py is a relative path on POSIX. Write files by absolute path, and claim the path exactly as the call wrote it; as a receiver, take a proven drive path as a Windows file only when you know the sender's executor runs Windows. PCM
A root grant needs the approval of a person signer.yaml's approvals.persons names: an approver it doesn't map, an OIDC person included, gets forbidden from pcm_grant, and a receiver rejects a root grant whose issuer names no person. The receiver checks the authority by its person (grants.root.person); an identity alone names no one across channels. Map each identity that approves pcm.grant to its person in approvals.persons. PCM
A root grant needs a person's approval: an agent approver can't issue one. The verifier reports who issued the root grant (grants.root) but doesn't check it is someone the receiver accepts. A grant without caveats is the widest grant, and agent approvers can't bound caveats yet. Have people approve pcm.grant; check grants.root.person against the people you accept. PCM
Narrowing is checked per caveat: an equality is narrowed only by the same equality (or a one-value in for strings), and >= 81 with <= 81 doesn't count as == 81. pcm_delegate takes only grants this signer signed. A simple rule, tested over every operator pair, is safer than a complete solver. Write a child's caveats in its parent's form. PCM
A bundle of a run that sent messages or made grants shows not interpreted warnings for ext.pcm.sent and ext.pcm.grant (exit 0): "1 record(s) carry ext.pcm.sent: their signatures, chain and inclusion are checked above; what ext.pcm.sent means is not checked". The verifiers have no check for these records yet; one comes when PCM leaves experimental. Expect the warnings; the records are signed and in the chain like every other. verdicts
Nothing enforces PCM between agents yet: the A2A gateway forwards PCM parts without checking them, and there is no transfer payload. The A2A gateway is merged; enforcing PCM in it, and a transfer payload, are a follow-up. Call pcm.verify in the receiving agent before it acts. PCM
TypeScript has the four RPC schemas, so its client can call them, but no PCM verifier. No TypeScript agent receives PCM yet. Verify in Python, or with tracekit pcm verify. PCM

Intent grants (experimental)

Limit Why it is so What to do Details
A grant covers one run: a new run of the same agent asks again. A grant's totals are counted in its run's records, so that run's bundle is enough to recount them. Grant each run (tracekit grant add --run RUN). A grant over several runs is a later step. intent grants
An intent grant is no authority in a PCM message: pcm.verify refuses a message that carries one, and pcm_delegate refuses one as a parent. Its limits, the tools it covers, its run and its revocation are only in its run's records, which a receiver doesn't have; PCM 0.1's caveats can't say a total or a count. So it is signed under a tag of its own (tracekit.intent-grant.v2), not PCM's. For authority another agent checks, issue a PCM grant from a person's approval (pcm_grant), whose caveats and expiry are all it needs. intent grants
Grants cover payments only (payment.send). Payments are the first intent; production changes and messages to people come next. Approve other held calls one at a time. intent grants
A grant reads an integer amount as the currency's smallest unit (cents, a token's base unit) and amount_cents as hundredths of its whole unit. A tool that takes whole dollars in amount is read 100 times smaller. The arguments carry no unit; the smallest unit is Stripe's convention, and the one a grant compares exactly. Before you grant, read the grant line of tracekit approvals show: it prints the amount as the grant reads it. If it reads wrong, approve that tool's calls one at a time. what a grant reads
A payment typed into a shell command (curl to a payments API, the Stripe CLI) stays held. Its amount and payee are text in a command line; a grant reads a tool's structured arguments. Pay through an MCP or framework tool with structured arguments. what a grant reads
On the dev signer, any identity of the run's tenant may issue a grant, as it may answer the run's approvals, and the agent runs as your user, so it could issue one (recorded self-approved, which makes the run's assurance dev, as a self-approval does; its bundle needs a 1.6 verifier, and an older one reports it UNVERIFIABLE (needs tracekit >= 1.6.0) rather than read it as witnessed, but only while its manifest is as exported: the manifest isn't signed, and edited down to 1.4.0 it lets an older verifier read the bundle as witnessed; a 1.6 verifier recomputes what the records need and warns verifier minimum). The dev signer can't tell you from your agent. The dev pack denies every tracekit grant and approvals approve command the agent runs (TK-D012) as a tripwire; code that calls grant_issue itself (python -c, a script) isn't read, as for approvals. Run system mode, or a signer with approvals, where only a named approver issues grants. Verify bundles with 1.6 or later, and treat a verifier minimum warning as an edited manifest. who may issue
A release at T1 rests on the arguments the harness reported: the agent's own process runs the call. A hook sees a call before it runs; the agent's process runs it. Run payments through the tool executor or the MCP gateway (T2): the call runs with the arguments the signer decided. records
A payment counts when it is decided, also when the payment then fails. Counting at the decision keeps two payments at once from spending the same room. Revoke the grant and issue a new one when failed payments used up its total. how the signer decides
The fields a release records are the signer's reading of the arguments. The verifier checks them against the grant; checking them against the arguments is a manual step. The bundle holds the arguments as commitments, which the verifier doesn't open. Open them with tracekit signer reveal and read them with grants.read in tracekit/grants.py. records
Grants know the units of USD, EUR, GBP, INR, CAD, AUD, CHF, SGD, JPY, USDC and USDT: a payment in another currency stays held, and a grant can't be issued in one. A fixed table in tracekit/grants.py, each currency with the digits of its smallest unit. Ask for the currency you need in an issue. what a grant reads
A payment with any argument besides its amount, currency, payee, description and note stays held: an idempotency key or an invoice id too. A grant releases only what it reads; an argument it doesn't read may pick what is paid or where the money goes (memo routes funds on some chains). Approve those calls one at a time. what a grant reads
The Go verifier in contrib/ reports the grant records as not interpreted. It hasn't been ported yet. Verify with tracekit verify or the TypeScript verifier. records

Tracekit Box (experimental)

A Tracekit Box daemon named in signer.yaml's box_daemons labels its box's run (ext.box), and opens each box's agent channel, through which the coding agent's hooks inside the box record its calls as the box's own identity, box:<uid>/<box id>.

Limit Why it is so What to do Details
A box's label proves only that the signing key was outside that box: verify's boxed agent line is PROOF AGAINST THE BOXED AGENT (micro-VM), never the general PROOF AGAINST THE AGENT. Anything running as the Box daemon's user or the signer's user on the host is outside the claim: it can open a box's channel and write as the box, or reach the key. The signer knows a box only through its daemon's Unix socket connection, which any process of that uid can make. Run the Box daemon and the signer as users of their own; pin a witness the host's operator doesn't run, so a rewrite of the store shows. verdicts
An agent run's records are the agent's own account of its calls. Its hooks run inside the box under its control: a hostile agent can skip them, lie in them or ignore a block. Box's doors (each connection, each file written back at apply) are what held it, and their records, in the box's own run, are what it could do. The channel carries what the agent says; only the doors sit outside it. Read the agent's run beside its box run's door records, and act on the doors: they, not the hooks, are the enforcement. Box's docs/agent-channel.md
The label's box id, image digest and allowlist names are the Box daemon's account; only its engine comes from the signer's config. The signer checks none of the three. The daemon is the trusted party that ran the box; the signer never saw it. Compare them with the box run's tkbox.box records, which the daemon wrote too. Box's docs/agent-channel.md
An agent run's run.registered names the Box daemon's uid as its identity (what the transport established) and signer_isolation: unknown; its box is only in ext.box. The viewer, report and graph show the daemon's uid for it. The recorded identity is a closed part of the format: a new box scheme there would make every older verifier refuse the bundle. Inside the signer the box's identity owns the run. Read verify's boxed agent line, or ext.box, for the box. format v2
A verifier older than 1.6.0 claims nothing for an agent run: it reads isolation: unknown and a not interpreted warning for ext.box. For the box's own run it reads the isolation measured for the daemon, so it may print the general proof line, about the daemon. ext.box is non-critical (format-v2.md §9): an older verifier still verifies the records. Verify box bundles with a verifier that reads ext.box. format v2
One box id is one identity per daemon: two boxes a daemon names alike share their owner, quotas, request ids and cooldowns (each still reaches only its own box run's runs and their approvals). The identity is box:<uid>/<box id>, and the daemon names the box. Box gives each box an id of its own. Box channel
box_daemons takes uids only, so a Box daemon reaches the signer over its Unix socket, never over HTTPS or the TCP dev transport, and only the firecracker engine (micro-VM). The dev signer has no box_daemons. A channel binds one connection; HTTPS has none to bind, and Box has one engine. Run a configured signer (tracekit signer serve --config) on the Box host. Box channel
The channel needs signer protocol 21. A signer of protocol 20 or older refuses channel_open and register_run's box, so Box runs with no channel and no label; a 1.6 client (protocol 22) refuses an older signer. The RPC contract is frozen: new calls and fields are a new protocol version, and a signer serves older clients, not newer ones. Upgrade the signer first, then Box and the agents' Tracekit. deployment
TK-X212 (tracekit analyze --v2 on a box run) sees only what crosses a door: connections and the files written back at apply. What the agent does inside the box (a process, a read, a file it writes then reverts or that stays out of the patch) has no door record, so only a fetch tool's call is checked for a missing connection: never a shell's curl (its exit status claims nothing about it), nor a write call against the patch (the patch is the net change). A door event is matched to a call by time alone: a connection made while a call that may connect ran counts as that call's, so one hidden inside a long shell call is missed. A fetch is matched by host and port: Claude Code's WebFetch follows a redirect only when the hosts differ by a leading www. (same protocol and port), which counts as the fetch's own; it reports a redirect to another host instead of following it, but a fetch tool that follows one shows that host's connection as a finding. Box's doors are the only records outside the agent's reach, and they name a host or a path, never the process or call behind it. Read the agent's calls around long shell calls yourself; prefer fetch tools that report a redirect to another host instead of following it, as Claude Code's WebFetch does. findings
Some honest door events are TK-X212 findings, and some can't be told. Findings: the harness's own traffic other than its model calls (Claude Code's statsig.anthropic.com when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC isn't set), a file the harness writes in /workspace for itself, and the setup half of a command that both sets up and starts the agent (sh -c 'npm ci && claude …'), which counts as the agent's. Not checkable: every later connection in a run after a shell call that may have left a process running (background), every file of the patch no write call named once any shell call ran (shell_ran), and every door event while no agent run was open (no_agent_run): before its hooks start, or after the agent closes its run, which it can do early. So the agent's own word can hide the rest of its run from the check, though never silently: one call it marks run_in_background (any call can be marked) makes every later connection of the run background, and one call it never completes makes them call_unfinished. The doors don't say which process acted; the rules count what they can't tell instead of guessing, and treat only model API hosts as the harness's own. Keep the settings of Box's Claude Code image (non-essential traffic off); start host setup in a command of its own; review no_agent_run, background and call_unfinished door events by hand (tkbox events). findings
An agent that never registers a run keeps no account at all: TK-X212 then has no call to compare, and counts every door event no_agent_account (the summary line says NO AGENT ACCOUNT), not a finding. That reading needs a final box run, a source that holds every run of the box's tenant (the signer's store, or a run-set bundle from registry 0 with no run still open, whose range holds the box run's own registration: a run-set bundles only final runs, so a box stopped mid-session leaves its agent's open run out, and it may carry its selected run from outside its range), and no register_run Box refused on the channel (tkbox.channel, a count of refusals Box folded, or such records lost: Box's refusal is not the agent's). Short of that the same box reads no_agent_runs, since its agent's runs may simply not be there. The agent's hooks run inside the box, under its control; skipping them is the simplest way to leave nothing to compare. Analyse finished box runs from the store or a run-set exported from registry 0 after the box's runs closed; treat NO AGENT ACCOUNT as every door event unexplained. findings
Which processes a shell call leaves running is read from its command by the policy engine's shell parser: run_in_background, a command it sends to the background (& after a command, an and-or list or a block such as { …; }, if or while, in a subshell or an sh -c string too), or a command that detaches by itself or runs one later (setsid, disown, coproc, tmux … -d, screen -d…, systemd-run, at, batch); a line the parser can't read counts. Other ways stay out: a program that daemonizes itself (redis-server --daemonize yes, daemonize, start-stop-daemon --background), sudo -b, ssh -f, docker run -d, an asynchronous process substitution >(…), an interpreter that spawns a detached child (Python, Node), a script file that starts one. Each errs toward a false TK-X212 finding for its later connections, never toward silence. A command Box started from the host that leaves a daemon running is the same: its daemon's connections after the command ended are findings. The command line is all the record holds of what a call started; a program's own forking isn't in it. Start servers and daemons in the same call or command that uses them, or with run_in_background; read such findings against the agent's earlier commands. findings
A refusal Box made itself (a private or metadata address, too many connections: tkbox.egress) reaches the signer later with no time of its own, and one it lost is only counted (tkbox.gap), so TK-X212 places no call against either: each is untimed_refusal on the door side, and a fetch after one to that host is box_refusal. A door decision that let a connection through means Box allowed it, not that the host answered: an allowed connection whose dial then failed still matches a fetch, so door_refused is only for fetches every connection of which Box refused. Box sends its own refusals through a rate-limited queue; its decisions come before the dial. Read the box's events for those refusals and failed dials (tkbox events). findings
On a box run TK-X212 compares the box's doors with the agent's own account only: the operator's task (tkbox.task, what the box was asked to do) isn't checked against the box's patch, and the checks of an agent's calls skip a box run's own calls (Box's doors). A patch that changes files the task said to leave alone is no finding. A box run's Write decisions are Box's, written back at apply, not the agent's edits: the per-call checks read them as an agent's and flagged every honest apply. Read the patch (tkbox diff <box>) against the task before you apply it. findings
A file written back with tkbox apply --dir to a directory under the workspace looks like a file deeper in the workspace: when a path the agent wrote ends the patch's path, it is apply_dir, not checked; with --dir elsewhere every file is apply_dir. Box's Write decision names the file on the host, not the apply directory. Apply to the workspace the box was started with. findings

Viewer

Limit Why it is so What to do Details
A signed run gets its own graph only when the viewer has no why logs: with --why DIR, a why/ folder in the signer's data dir, or view.logs, a run without a why log has no GRAPH. Each verified run is imported again whenever it grows, and its graph goes once its rows leave the live view (past TRACEKIT_OBSERVE_MAX_RECORDS). The import fills the why workspace that why logs otherwise fill; re-importing a whole run keeps it current simply; a graph kept for every run the viewer ever showed grew without bound (some 3.4 KiB a record). Open the store without --why to see every run's graph; with a why/ folder in the data dir, import the run into a new folder and open that with --why (tracekit why import --store DIR --run ID --out NEWDIR; for a Postgres store, or a run that left the live view, --bundle its exported bundle). A file store's run views name the command for the mode the viewer runs in (a Postgres store's name --store, which needs the --bundle route instead). Expect a delay on very long runs. viewer
The viewer's verdicts are operator-side, not evidence. The viewer runs on the operator's side. Download the bundle and verify it with your own verifier and trust config. viewer
v2 records keep a call's arguments only as a salted commitment, so the viewer shows rule reasons, not arguments; for other policies, only rule ids. Records never hold arguments. Ask for tracekit signer reveal on the record when an audit needs it. viewer
A run that fails verification shows only its failure report. Records of a failed run aren't shown as if they were evidence. Investigate with tracekit verify. viewer
A run stays PENDING until a checkpoint covers its last record. The verdict needs a checkpoint. Wait for the next checkpoint. viewer
When the viewer's verification thread stops on an unexpected error, the page says verification stopped and no run is checked again until tracekit view restarts. While the store can't be read (a line the reader can't parse) or its checkpoint note is gone or older than one the viewer saw, no run is checked and the page says verification stopped too, until the store can be checked again. A run whose own check fails shows NOT CHECKED and is checked again 5 minutes later or when it grows. One thread checks every run and nothing restarts it; the store is read whole, so one unreadable line stops every run's check; a signed note never goes back, so an older one means the store was edited or replaced; one run's error is kept to that run. Restart tracekit view; repair or restore the store the message names; for a run you need now, export it and run tracekit verify. viewer
The viewer's printed token is one operator credential over every tenant's runs. It is the local operator's access. Use OIDC roles for auditors and approvers. viewer
(1.4) The viewer's session cookie (the token's, or an OIDC session's) goes to every port of the viewer's host name: a page served by another program on that host, at another port (an agent's dev server on 127.0.0.1:3000) that you open in the same browser receives it and can read the viewer as you until the cookie ends. The token's cookie ends after 8 hours or when the viewer stops; an OIDC session after 8 hours. Browsers scope cookies by host name, not port, and the page needs a cookie: the token stays out of its URLs. Open the viewer under a host name nothing else on the machine serves (127.0.0.1 for it, localhost for the rest), or in a browser profile of its own; restart the viewer to end every token session at once. viewer
TIPS sees only what signed records and Claude Code's transcripts hold. It reads no other harness's transcripts, so a Codex or Cursor agent's steps count only when a gateway or SDK signed their usage. A signed record's usage holds no cache lifetime, so those steps are left out of the cache tip. A signed step is matched to the transcripts by a tool_use id or by identical token counts within 5 minutes of one transcript message: an unrelated message with the same counts that close is counted once too, and a signed message without tool calls whose counts differ from the transcript's (a gateway that signs other counts) is counted twice. The context replay counts tokens, not the work redone when a summary drops a detail, and its savings are estimates. Where a Claude Code hold ran (main session or subagent) and how long it blocked the agent come only from its transcript. Dollars are list prices for Anthropic's models, not a bill; the sessions of another model are left out, with a note naming it. Each time it's worked out (at most once a minute, or on READ AGAIN) it reads every transcript written in the last 7 days again: a 983 MB folder took 6.7 s and 370 MB of memory. The transcript tailer records no token usage, the v2 usage field has no cache lifetime, the gateway signs exchanges under ids of its own, a Claude Code run's records decide a subagent's calls under the session's run, nothing records what a summary lost, and the reader keeps no offsets between reads. Read THE ARITHMETIC before acting on a tip; start the viewer with --transcripts DIR (or --dev) so holds are placed and timed, and point it at one project's folder when the whole folder is large; update the price table in tracekit/tips.py when prices change. viewer
TIPS reads the signed records the viewer holds: its live view, the newest 50,000 rows (TRACEKIT_OBSERVE_MAX_RECORDS). On a busy store they cover less than the 7 days it reads from the transcripts, so held calls and signed token counts from before that are missing. The viewer keeps its live view in memory; TIPS reads it rather than the store again. Read the span on TIPS's first line; for a longer window raise TRACEKIT_OBSERVE_MAX_RECORDS, or use tracekit report for the store's holds over a week. viewer
The timeline is scaled to the calls shown, not the clock. It shows sequence, not duration. Read times from the records. viewer
Why logs are shown to the printed token only; an OIDC session gets none of them. A why log belongs to no tenant, so the viewer can't scope it. Give investigators the token, or run tracekit view --why DIR for them on their own logs. viewer
FIND THE CAUSE and RUN TEST run only for programs passed with --allow-program; otherwise the WHY panel shows the command to run. A replay imports and runs the program a run names. Start the viewer with --allow-program module:SYSTEM, or run the printed tracekit why command. viewer
A signed call is joined to its why event only when that event cites the signed record it produced and both name the same tool; why logs without the citation (recorded without a signer, or imported from v1) show in GRAPH, AGENTS and INFLUENCE but not in a signed call's detail. The citation is the only link between the two logs. Record with the signer-backed why runtime, or open the logs alone with tracekit view --why DIR. viewer
A joint cause FIND THE CAUSE reports is marked in the candidate list only until the page reloads; its summary line says it either way. Joint groups aren't saved per candidate. Re-run FIND THE CAUSE, or read the summary. viewer
The why workspace reads every why log on each refresh. It is recomputed rather than cached. Keep the --why directory to the runs under investigation. viewer
The viewer's why views have no links of their own (Causeway's #/run/<id>/why/<call>), and a candidate cause has no COPY COMMAND button. The page is one live view of a server, not a set of routes; the command is printed instead. Name the run in the picker; copy the printed tracekit why test command from the WHY panel. viewer
The static why report (tracekit why report, and the demo's report.html) runs no replays: FIND THE CAUSE and RUN TEST show the command to run, and it shows the runs as they were when it was written. It is one file with the runs embedded, opened without a server. Run the command it shows, or open the folder with tracekit view --why DIR --allow-program SPEC. why
One tracekit view shows one source: a v2 signer's store (or a central deployment's logs), a v1 ledger or bundle, or why logs alone; the nav links only the pages that source has. Each source is its own feed, and the page shows one feed. Start a second tracekit view on another --port for another source. viewer
On a laptop no page answers a held call: the viewer's APPROVALS page lists each one with the commands that answer it, and the server's /approvals page, which answers, needs OIDC login and view.signer. The page answers for a signed-in person over the signer RPC; the printed token is no person. Answer with tracekit approvals, or configure viewer login. approvals
tracekit view --ledger and --bundle serve loopback only, and have no --prices or --export. They keep tracekit observe's rules for the v1 ledger. Reach the page through an SSH tunnel; for cost or a replay file run tracekit observe --prices FILE or tracekit observe --export FILE. viewer
(1.5.1) --data-dir DIR (of tracekit view, report, export --v2, signer trust and signer vkey) reads a data dir without its signer.yaml: signer trust --data-dir pins the log key only, not the config's witnesses or Rekor anchor, and export --v2 --data-dir can't ask the signer for a checkpoint, so a run none covers yet isn't exported. Both say so when it matters. A data dir of a Postgres-backed signer holds no store. A data dir names no socket and no witnesses; only the config does. Pass the signer's --config to pin its witnesses or to have export ask for a checkpoint; or export again after the signer's next checkpoint (within seconds). viewer

Weekly report (tracekit report)

Limit Why it is so What to do Details
It reports on one store at a time. Each laptop's dev signer has its own store, so a team's laptops are reported one by one, and nothing adds them up. It reads a signer's store directly, as the viewer does; it collects nothing from other machines. Run it on each laptop and send the pages, or point the agents at one signer (tracekit init --v2 --remote URL) and report on its store with --config. viewer
It is an operator summary, not evidence: nothing in it is signed, and its verdicts pin the log key the store names (dev assurance on a laptop). It runs on the operator's side, over the operator's own store. Export the runs that matter (tracekit export --v2 --run ID) and have the auditor verify them with keys they pinned. auditor guide
It checks every run in the window with the verifier before it prints, as the viewer does when it starts: a week of 48 Claude Code runs (245,412 records, 63,000 tool calls) took about 3.5 minutes on a laptop. Most of that is the verifier's schema and signature checks, and each run's export scanning the whole log for key records. Its counts come only from records that verified. Use a shorter --since, or --tenant; it says how many runs and records it is checking before it starts. viewer
An example call shows its arguments only with --dev while the dev signer runs, each read a signed content.accessed record. With --config or --data-dir, with no dev signer running, or for arguments redaction changed (a secret), it reads arguments not shown (the record holds only their salted hash). Records hold arguments only as a salted commitment; only the dev signer keeps a copy this user may read, and redacted arguments no longer open their commitment. Start the dev signer (tracekit up) before the report; for one record, tracekit signer reveal. content vault
A rule's description comes from the policy the signer ran: a shipped pack, the config's policy file, or the copy the signer keeps in its data dir's policies/ (readable by the signer's user only). Run as another user, a rule of a policy it can't read shows its id only, and isn't counted as why a call was denied or flagged: the report lists it as not placed and says how many calls cite such a policy. A rule id means what the policy whose hash the decision records says, so no other policy's text or section is used for it. Run the report as the signer's user, or pass the signer's --config with its policy file. viewer
An engine check (TK-SHELL-PARSE, TK-UNKNOWN-TOOL, TK-QUARANTINE, ...) that matched a denied or flagged call is listed as not placed, never counted as why: it may be why (an unknown tool flagged, a quarantined run's call denied) or not (TK-SHELL-PARSE asks by default, and a deny rule denied the call). A decision records every rule that matched, not which one decided it, and an engine check has no section of the policy; its decision is a policy setting (on_parse_error, unknown_tools). Open the call in tracekit view, which shows every rule that matched it. viewer
Before it places or counts a run, it checks every record of the store against the newest checkpoint, in every tenant (--tenant too) and the signer's own runs: its hash is its event's, it is filed under the run its event names, and the hashes make the checkpoint's root (3.6 seconds for a store of 246,344 records and 845 runs on a laptop, whatever --since or --tenant). A run holding an edited record is listed FAILED whatever its tenant and times, a signer's run or another tenant's included; when the hashes don't make the root (a hash was rewritten too), the store and every run fail; and the command exits 1. Records newer than the checkpoint are not checked against it and place no run: a run whose covered records all fall before the window isn't listed, even when newer records of it fall in the window. The report says how many records of the store are newer, and a run no checkpoint covers yet is PENDING. The store files a record under the tenant, run id and time the record holds, and only the signed checkpoint vouches for them; in dev mode the agent's user can edit the store. Run it again after the next checkpoint (the signer writes one within seconds); for a FAILED run, tracekit view shows its first failing check. viewer
--share prints an agent name only when Tracekit's own hooks and tools give it (claude-code, codex, agentsh, ...), and a rule id only when it is a shipped pack's, an engine check's or the signer's: every other agent counts as other, every rule of a policy of your own as custom rule (in tracekit audit --share too). A report from SDK agents or a policy of your own says little about them. A run's name is any string its code chose (a script's file name for tracekit.instrument(), a customer, a project), an agent can register its run under any name, and a policy's author chooses its ids: Tracekit can't tell a private name from a public one. Say in the report, in your own words, what your other agents and custom rule rules are; read the block before you post it (tracekit report --share says what it counts as other on stderr). field reports
It reads the v2 signer's store only, not the v1 ledger (tracekitd), why logs or bundles. It summarises no signer's run (its key records, content reads, refused writes, a witness that didn't countersign): it checks their records and lists one only when it fails. It summarises the agents' runs of the store tracekit view verifies. tracekit view shows the signer's own rows; tracekit view --ledger the v1 ledger. viewer
tracekit feedback (and its --file) fills in the week's counts from the dev signer's store only: the store of a signer started from a signer.yaml, another data dir or a remote signer isn't read, and with no dev store the link or file says so instead. It takes report --share's week from the store a laptop's dev signer keeps; it has no --config or --data-dir. Run tracekit report --share --since 7d --config signer.yaml (or --data-dir DIR) and paste its block into the report. field reports

Audit (tracekit audit)

Limit Why it is so What to do Details
It reads Claude Code's transcripts only, and sees only the tool calls they hold: nothing the agent did outside a tool call, and nothing from another harness (Codex, Gemini CLI). Each harness writes its transcripts in its own format; Claude Code's is the one it reads. For what an agent does from now on, record it with Tracekit (tracekit init --dev --v2). audit
Its counts are evidence of nothing: the agent could have edited the transcript, and each call is decided by today's policy, not the one in force when it ran. Tracekit never recorded these calls; only a signed record shows what happened. Use it to see what Tracekit would hold; for evidence, record runs with the signer and export bundles. audit
It can count fewer holds than the signer would: each call is decided on its own, without the run's state, so from: untrusted rules never match (there is no provenance), and detect sequences, limits and the person's prompt constraints don't apply. It reads a transcript, not a run; that state exists only in the signer. Treat its counts as a floor; the signer's own decisions are the ones that hold. audit
It keeps every call it reads in memory (about 0.5 KB each; --show text is cut to 72 characters), so a very large transcript folder takes memory in proportion. The JSON report and --all list every call, so it keeps them all until the counts are done. Use --since to replay a shorter window. audit

Model receipts (tracekit verify-model)

Limit Why it is so What to do Details
A weights file's receipt is the hook's report (reported_by: hook), not something the signer saw: the agent's own user runs the hook, so the agent can change the file after the hook hashed it, or report other hashes through its run token. The hook is the agent side's process; nothing outside the agent reads the file yet. Treat a receipt as the agent side's claim. A receipt computed outside the agent (the tool executor, a signer-side sensor) is planned. coding agents
Only the coding-agent hooks take receipts, and only for Write, Edit, MultiEdit, NotebookEdit and Bash calls: an MCP server's write tool, or a framework integration's call, gets none. verify-model counts a receipt only in the result of one of those five tools whose arguments, read back from the vault, name a file the hook hashes; the hook sets model_receipts on those tools' results only, and removes one it didn't set. Any other receipt is ignored (receipt(s) ignored), and every other tool's result is recorded as it came, so a receipt in an MCP server's or a web page's output never counts. That stops a tool's output, not the agent: a matching receipt is recorded by the agent-side hook, which runs as the agent's user, and a client of the agent's own that speaks the RPC itself sends what it likes. Only the hook hashes the file, on the agent's side, and the record keeps every other tool's result as the tool returned it, for provenance. Arguments redaction changed open no commitment, so they name no file. Read a matching receipt as the agent side's record of the file, not a third party's. coding agents
A receipt is taken only for a call that succeeded (a failed, interrupted or is_error call gets none), after the call ended: a parallel call, or another process, that writes the same file before the hook reads it puts its write into the receipt. The hook hashes the file when the call's PostToolUse hook runs, and a harness can run calls in parallel. Read hashed after tool call as what the file held then; write a weights file from one call at a time. coding agents
tracekit verify-model needs the signer's kept content and the content_read grant: the dev signer keeps a run's content for 7 days, and a configured signer keeps none unless content.retain is on. A bundle alone can't be checked offline. The record holds only a salted commitment of the call's result; the receipt is in the result, which only the vault keeps. Check within the retention window, or set content: {retain: true} and grant content_read. A check from the bundle alone needs receipts in the record, a format change planned for when a lab asks for it. content vault
A call gets a receipt only for a path the policy's parser reads it writing: a write tool's path, a shell redirection, a cp, mv or install destination, and the like. A script that writes weights itself (python edit.py), a shell download (curl -o, huggingface-cli download) or an archive extraction gets none (Crush's download tool is decided as a Write, so it gets a receipt of the file on disk when the hook reads it), and a path the hook would have to guess is refused: one starting with ~; every path of a command line in which cp, mv, install or ln has -t (in a cluster too, -vt), git, env, make or tar has -C, sudo has -D, or one of them has --target-directory, --directory or --chdir or a prefix of one that GNU accepts (env --ch=sub); and a relative one in a command that changes directory (cd, pushd, popd, git --work-tree, or a shell call's own working directory: Gemini CLI's and Qwen Code's dir_path or directory, Cursor's working_directory, Codex's workdir, agy's Cwd (in any case), Crush's working_dir, whatever its value). Another command's -t or -C (sort -t,, grep -C3) refuses nothing, and another command's directory option isn't read: a relative path there is hashed in the working directory. The hook reads the call's arguments; it doesn't watch the file system, expand ~ or follow every command's directory options. Have the script write a staging file and move it into place with mv in a call of its own: the move gets a receipt. coding agents
A write that lands after the hook reads gets no receipt: every weights path is refused for a Bash call with run_in_background (Qwen Code's is_background), input typed into another running session (Codex's write_stdin, agy's manage_task send_input, Devin's write_to_process), Qwen Code's monitor, Kilo's background_process, a command line that runs systemd-run, at, batch or setsid -f (--fork; plain setsid runs in the foreground), and one whose text holds a lone & (cp new.pt m.pt &; not &&, 2>&1, &> or |&) or coproc. A & inside quotes (curl 'https://x/?a=1&b=2' -o m.pt) refuses the line too. Codex's exec_command sends no post-tool hook while its command still runs when the call returns (after yield_time_ms), so that call gets no receipt and is completed as an error when the session ends. screen -dm, tmux new -d, start-stop-daemon -b and daemonize name no path the policy's parser reads, so their calls get none. The hook reads the file when the call's post-tool hook runs, which for these is when the command starts or the input is sent, not when the write ends. The policy's shell parser keeps no mark of a &, so the hook reads it off the command's raw text, quotes and all. Write weights in a call that waits for the write to end (no &, not in the background), then move them into place with cp or mv in a call of its own. coding agents
Every path of a command line that runs ssh, chroot, nsenter, unshare or firejail is refused, and a remote scp or rsync target (host:/m.safetensors) is refused as a file the hook can't find. A runner whose command the parser doesn't read into paths (docker exec, kubectl exec) names no path, so its call gets no receipt. Such a command writes on another host, under another root, or in another mount namespace or sandbox; the hook reads only the file it sees on this host. Hash the file where it was written, or copy it back to this host with cp or mv in a call of its own: that write gets a receipt. coding agents
A file past 8 GiB, a .safetensors header past 448 KiB (more tensors than a receipt takes, or more than 256 KiB of metadata; refused before it is read), tensor hashes past 96 KiB (about 800 tensors), or a file its format doesn't allow (offsets outside the file, a gap between tensors) gets a reason in place of a receipt (refused). A call's result holds at most 4 receipts, then a count of the rest; receipts that would take the result past half a frame (a large result kept whole with content_capture: full) are replaced by a marker that says so, or dropped without one when the marker doesn't fit either. The call's result must fit one 1 MiB frame and the vault's 1 MiB per record. Shard large models (the Hugging Face Hub shards at 5 GB by default). coding agents
The hook hashes for at most 10 s per call, then refuses the receipts it hadn't finished (out of time); one read that blocks (a hung network file system) can still outlast it. Until then hashing delays the agent's next step: about 0.7 s per GiB of .safetensors on a laptop, measured in memory (longer from disk). The same PostToolUse hook, with a 30 s timeout, sends the call's result: hashing must not cost it. Keep the weights an agent writes on a local disk. coding agents
Only .safetensors gets a hash per tensor; .gguf, .pt, .pth and .ckpt get the file's hash only, so verify-model says only whether the file differs. Other weights files (pytorch_model.bin, .onnx, .h5) get no receipt. A tensor's dtype and shape aren't checked against its bytes: a file the safetensors library won't load for that still gets a receipt. It reads one format's layout. Save weights as .safetensors to see which tensors changed. coding agents
A Bash, Write or Edit call the policy marks untrusted gets no receipts, and the hook removes a model_receipts key from its result. Its result goes to the signer as the tool returned it, for provenance, and a gateway's verified tool results compare it as sent to the model; a receipts key in it is never the hook's. Keep shell and write tools out of untrusted. The shipped packs list http, mcp, WebFetch and WebSearch (coding), http, browser and mcp (server), browser (browser) and http (server-net): none of them a tool the hook receipts. policy
A receipt reaches the signer in clear, inside the result: its vault keeps the file's path, size, hashes and tensor names even with content_capture: hashed. verify-model reads the receipt back from the vault. Keep secrets out of weights file paths; erase a run's content when you no longer need it. content vault

Install

Limit Why it is so What to do Details
On an Intel Mac or a musl Linux (Alpine), npm install @cygnuxlabs/tracekit gets no platform signer package, so the dev signer needs Python. Signer packages are built for four platforms. Intel Macs lack usable google-re2 and cryptography wheels, and none is built for musl. pip install tracekit-ai, or point the client at a running signer. TypeScript SDK
pip install tracekit-ai also installs cryptography, rfc8785, google-re2 (Python 3.10+) and regex. The dev signer starts from that one install. It signs, canonicalises JSON and runs its policy engine. To get the verifier alone, pip install --no-deps tracekit-ai. It runs on the standard library. quickstart
On a Python that refuses pip install outside a venv (PEP 668: error: externally-managed-environment; Debian 12, Ubuntu 23.04 and later, Homebrew's Python), pip install tracekit-ai fails. pipx install tracekit-ai and uv tool install tracekit-ai give only the tracekit command: an SDK agent can't import Tracekit from them. These Pythons leave their own packages to the system's package manager. pipx and uv tool put each command in a venv of its own, which no other program imports from. For an SDK agent, pip install tracekit-ai in the agent's own venv. For the command alone (tracekit last, tracekit view, tracekit approvals, Claude Code's hooks through tracekit init --dev --v2), pipx or uv tool. With both, keep them at the same version: they share the dev signer. quickstart
Upgrading Tracekit doesn't upgrade the Python your hooks run, nor the dev signer already running. tracekit doctor (D-VERSIONS) asks the Python of each hook init wrote which Tracekit it imports, and reads the running dev signer's version. It can't name the Python the Claude Code plugin's hook runs, nor that of a hook command init didn't write (it says so). It runs only the commands of your own hook files, with absolute paths: a project's hook files (in the directory doctor runs in), relative paths, and a file that a relative HOME, CLAUDE_CONFIG_DIR, CODEX_HOME, XDG_CONFIG_HOME, CRUSH_GLOBAL_CONFIG or TRACEKIT_CLIENT_HOME places are reported, not probed. As root it runs no hook's Python. In system mode it isn't run: D-HOOKS-VENV checks that the hooks run /opt/tracekit's Python, the one doctor runs from, but a system signer still running an older version after /opt/tracekit was upgraded in place isn't compared. A pre-release or dev build compares as its release. The plugin picks its Python as it runs (the first of TRACEKIT_PYTHON, python3 and python on Claude Code's PATH that imports Tracekit), in Claude Code's environment, not doctor's. Doctor never runs a project's commands: running it in a cloned repository runs none of its code. A relative path resolves against doctor's directory, not the hook's. Doctor won't run, as root, a Python that a file the agent's user can write names. Upgrade as upgrading says and run tracekit doctor. With the plugin, read its hook's notice (next row) or ask the Python it finds: python3 -I -c 'import tracekit; print(tracekit.__version__)'. In system mode, stop the signer, upgrade and start it again (upgrading). doctor
A hook whose signer runs another Tracekit version says so once per session, with the fix, on the first event it lets through, never beside a block: in Claude Code as a systemMessage, for the other coding agents on stderr, which some of them don't show for a call they allow. The session's state keeps that it was said; a session whose state ended or was pruned (30 days) hears it again. An agent can stop the notice by editing that state (in dev mode it runs as you): it is a notice, not a control. A hook's output reaches the person only where its harness shows it, and a block's message is what the agent reads: the notice stays out of it. The session state lives in the agent's own runtime dir. Run tracekit doctor after each upgrade: D-VERSIONS checks every hook and the signer. upgrading
A --no-deps install verifies bundles but can't run a signer. tracekit up and tracekit init --dev --v2 refuse to start. The signer needs the policy engine and cryptography. Neither is in the standard library. pip install tracekit-ai doctor
Where google-re2 has no wheel (a new Python, an uncommon platform), pip builds it from source, and without a C++ toolchain and abseil the whole install fails. pip has no fallback between dependencies. The signer itself uses regex when google-re2 isn't importable. pip install --no-deps tracekit-ai, then pip install cryptography "rfc8785>=0.1,<0.2" regex (with their own dependencies) quickstart
(1.2) Claude Code's hooks go to $CLAUDE_CONFIG_DIR/settings.json when it is set, else ~/.claude/settings.json. tracekit uninstall and tracekit doctor look at both, and at the one file tracekit init last recorded; hooks an earlier init put under another CLAUDE_CONFIG_DIR aren't found from a shell that doesn't set it. Only the shell that installed them knew the directory, and init records one settings file, the last it put hooks in. Uninstall with the same CLAUDE_CONFIG_DIR you installed with. quickstart
(1.3) The Claude Code plugin runs the v2 hooks. Updating it from a v1 plugin moves v1 dev mode to the v2 dev signer: the v1 policy and tracekit pending no longer apply, and the v1 ledger can be bridged into the v2 log only until the v2 signer records something. In v1 system mode every tool call is blocked until v2 system mode is set up. The plugin carries one hook, and the v2 hook needs a v2 signer. Before the next session: export the v1 runs you need, tracekit uninstall, tracekit signer bridge, tracekit init --dev --v2 --no-hooks; system mode: tracekit init --v2 --user <agent-user> --no-hooks as root, by one of deploy's routes: from /opt's venv on Python 3.11+ (sudo /opt/tracekit/bin/python -I -m tracekit init …), with Tracekit pip-installed into the system Python (sudo /usr/bin/python3 -I -m tracekit init …), or from a root-owned clone (sudo /usr/bin/python3 -m tracekit init …, run in the clone). plugin
(1.3) With the Claude Code plugin and tracekit init's hooks both in place, every call is decided twice and every approved call is blocked. tracekit init --dev --v2 recognises Tracekit's plugin across marketplaces when Claude Code has an install record for it and the current marketplace catalog names Cygnux-Labs/Tracekit at plugin/; system init doesn't check. It can still miss a plugin enabled only through --plugin-dir, --settings or defaultEnabled, one from a claude.ai-synced marketplace (which has no known_marketplaces.json entry), or one whose install record or catalog is unavailable. The catalog is current metadata and may no longer describe cached files from an older install. Both hooks decide the call, and one consumes the approval the other waits on. Keep one: tracekit uninstall or use the plugin key shown by tracekit init or tracekit doctor in /plugin disable <key>. tracekit doctor warns when both run (D-HOOKS-PRESENT). With the plugin, run system init with --no-hooks. plugin
(1.3) The Claude Code plugin without the tracekit package lets every event run unrecorded, with a notice in the transcript, until Tracekit is set up for the user (the dev signer's data dir exists, or TRACEKIT_PYTHON or TRACEKIT_SIGNER is set); from then on it blocks tool calls. Blocking someone who installed the plugin but not Tracekit would lock them out of Claude Code with nothing yet to protect. pip install tracekit-ai==<the plugin's version> && tracekit init --dev --v2 --no-hooks (the plugin's messages name the version) plugin
Hooks tracekit init --dev installs from a source checkout (an editable pip install -e or the source tree itself) import Tracekit from that working tree each time they run. A branch switch, a rebase or other code checked out there changes what every session's hooks run. Code there that doesn't import fails every hooked event: the v2 hooks block each tool call until it imports again. When init ran from a git working tree with git on init's PATH, and git is on the hook's PATH, the hook then prints one line naming the working tree, the error, the branch it is on now and the branch (or commit) it was on at install, and how to fix it; otherwise it prints the traceback. The dev hooks run the code you're working on, so a change takes effect without running init again. Nothing copies it. Keep the checkout your hooks run from on a working branch, and switch branches in another worktree (git worktree add). Or install Tracekit with pip install (not pip install -e) and run tracekit init --dev --v2 again (with --agent NAME for another coding agent), so the hooks run the installed package. After a switch, git -C <checkout> checkout <branch> puts the hooks back. quickstart
sudo /opt/tracekit/bin/python -I -m tracekit uninstall --v2 changes nothing while the agent's Claude Code settings file is a symlink or not valid JSON, and says so. Root edits that file as the agent's user, never through a link, and never overwrites what it can't parse. Fix or remove the file as the agent's user, then uninstall again. quickstart
tracekit uninstall gives a coding agent's settings file back its meaning, not its exact bytes. The file is rewritten with 2-space indents and a final newline. An empty "hooks": {} (and Claude Code's "env": {}) is dropped. A file init created stays as {} (Cursor's as {"version": 1}), Cursor's "version": 1 stays in a file that had none, and the folders init made for OpenCode, goose and Droid stay. Each init or uninstall that changes a file first saves a copy beside it (<file>.bak-<time>-<random>), and nothing removes those. Tracekit edits these files as JSON, not as text, and doesn't keep what a file looked like before init. The copies let you get any earlier version back. To get a file back exactly, copy the .bak- copy your first init made over it, or delete the file if init created it. Delete the .bak- copies, and any empty file or folder init left, once you no longer need them. coding agents
tracekit uninstall --agent droid deletes the .factory/hooks.json that init created only when what is left in it equals the hooks in settings.json beside it. If you changed the hooks in either file after init, or settings.json is gone or can't be read, hooks.json stays with Tracekit's hooks taken out, and Droid goes on running its hooks and ignoring settings.json's. Droid reads settings.json's hooks only while hooks.json is absent, so init copies them into the hooks.json it creates; Tracekit doesn't keep a record of what it copied, so a changed file can't be told from one you made yourself. Uninstall names the file it kept: move any hooks you want from it into settings.json, then delete it. coding agents
tracekit init --remote (v1) after tracekit init --dev leaves the dev tracekitd running, and tracekit uninstall then doesn't stop it. The remote client config replaces the dev one, which named the daemon's home. Run tracekit uninstall before switching, or stop the pid in ~/.tracekit-signer/tracekitd.pid. remote ingest
A --no-deps verifier is slower. It falls back to pure-Python Ed25519 and JCS. Both are checked against cryptography and rfc8785 and give the same verdict. Install cryptography and rfc8785 if you verify many large bundles. signing

One-line setup (tracekit.instrument())

Limit Why it is so What to do Details
(1.2) A client keeps each run's event counter until the run is closed (run.close()) or the signer answers that it is: a server that lets conversations end by the signer's idle timeout keeps about 100–300 bytes per conversation (TypeScript: for the client's life; Python: at most 65,536 runs, the least recently used forgotten first, so a run idle while that many others were used restarts its count and its next events read as a gap). A counter can't be dropped while the run may still take events: a reused run id would restart at 0. Close each conversation's run when it ends, or give a batch of conversations a client of its own and close it. quickstart
(1.2) instrument()'s process client remembers which run each call, approval, exchange and stream went to, up to 65,536 of each, the oldest forgotten first: a call that waits for a person while that many newer ones are decided completes in the current run, which may refuse it. Routing needs the run a call was decided in; the maps are bounded so a long-running process doesn't grow. Use a run per conversation (conversation.current()); answer approvals before tens of thousands of newer calls. quickstart
(1.2) TypeScript: a run's event calls go out one at a time on one connection, and a call's timeout includes its wait for its turn, so a busy process run (instrument()'s, shared by every conversation) can time out on a signer that is only slow; the run's fail mode then applies. Events reach the signer in client_seq order. Give each conversation its own run (withRun), or raise `t

Home

Get started

How it works

Integrations

Policy and approvals

Deploy and operate

Verify the evidence

Security and privacy

Compliance

Evaluation

Use cases and demos

Help

Clone this wiki locally