Audit Trails for Tool Calls

The route

4 steps to Done

1. 01

   Define the audit record and scope

   Decide what is auditable and what each record must answer.

   Preview prompt + verify gate ▾ Hide ▴

   Design the audit record. SCOPE: audit consequential actions - state mutations (writes, deletes), external effects (network calls, sends, spends), permission decisions, and security-relevant events (blocks, escalations); read-only trivia need not be audited (avoid drowning the trail). RECORD FIELDS: timestamp, actor (agent id + session), action (tool + operation), arguments (scrubbed, but specific - which file, which record), AUTHORITY (what permitted it: auto-allow tier, session grant, user approval with reference, or policy), triggering context (task id, the user request that led here, provenance/trust of any content involved), and OUTCOME (success/failure, effect summary). Define which fields are mandatory. The test: could an investigator answer who/what/when/why/outcome from one record plus its links?

   • ✓ Consequential actions scoped; trivia excluded
   • ✓ Authority and triggering request captured
   • ✓ Who/what/when/why/outcome answerable
2. 02

   Write records reliably and scrubbed

   Non-suppressible, secret-free, at the moment of action.

   Preview prompt + verify gate ▾ Hide ▴

   Implement audit writing in the action path. Every consequential tool execution writes its audit record at execution time (before returning), sourced from harness state (the permission decision, the request lineage) - not from anything the model can fabricate or omit; the model cannot disable auditing. Run record content through the secrets scrubber (from secrets hygiene) so the trail is safe to retain, while keeping specific non-secret identifiers needed to investigate. Handle write failures safely: if the audit write fails, the action should fail closed for high-sensitivity operations (no audit, no action) rather than proceeding unlogged. Test that a consequential action always yields a record and that a secret in its arguments is redacted in the record.

   • ✓ Records sourced from harness state, not model claims
   • ✓ Auditing not suppressible by the model
   • ✓ High-sensitivity actions fail closed if audit fails
3. 03

   Make the trail tamper-evident

   An alterable audit trail is not evidence.

   Preview prompt + verify gate ▾ Hide ▴

   Add tamper-evidence to audit storage. Options by environment: hash-chaining (each record includes the hash of the previous, so any alteration or deletion breaks the chain and is detectable) is a strong self-contained choice; or a write-once/append-only store (WORM storage, an append-only table with restricted permissions, or shipping records to a separate system the agent's host cannot rewrite). Implement chain verification: a command that walks the trail and confirms integrity, reporting any break with its location. Restrict who/what can write to the audit store to the audit path alone. Test tamper detection by altering a past record and confirming verification flags it.

   • ✓ Integrity chaining or write-once storage in place
   • ✓ Verification detects alterations and deletions
   • ✓ Write access restricted to the audit path
4. 04

   Enable investigation and set retention

   The trail proves its worth when someone has to ask hard questions of it.

   Preview prompt + verify gate ▾ Hide ▴

   Make the trail usable and governed. INVESTIGATION: build queries that answer real questions - all actions in a session, full history affecting a given resource (every write/delete to file/record X, with who/why), all actions authorized by a specific approval, and all security events in a window; support reconstructing an incident timeline from the records. RETENTION & ACCESS: set retention appropriate to sensitivity/compliance; restrict who can read the trail (it may contain sensitive operational detail even scrubbed of secrets); log reads of the audit trail itself for high-sensitivity contexts. VALIDATE with a drill: pose an incident question ('what did the agent do to the production config yesterday, and what authorized each action?') and answer it purely from the trail. Fix any question the trail cannot answer.

   • ✓ Resource-history and authority queries work
   • ✓ Retention and read-access controls set
   • ✓ Incident drill fully answered from the trail

Research-backed

Sources behind this flow