Audit Trails for Tool Calls

PROJECT CONTEXT:
When my agent does something consequential, I cannot reliably answer who triggered it, what exactly it did, and why. Agent audit practice (structured session logs, tamper-evident trails) makes every action accountable and investigable.

GOAL:
Implement an audit trail for agent actions: a structured, append-only, tamper-evident record of every consequential tool call with full context, queryable for investigation.

REQUIREMENTS:
- An audit record per consequential action: actor, action, arguments, authority, outcome, timestamp
- Linkage to the triggering context: session, task, user request, and provenance
- Append-only, tamper-evident storage (integrity chaining or a write-once store)
- Query and reconstruction: answer 'what did the agent do to X and why' quickly
- Retention and access controls appropriate to sensitivity

CONSTRAINTS:
- Audit writes are non-optional and must not be suppressible by the model
- Records must be scrubbed of secrets yet retain enough to investigate

DEFINITION OF DONE:
- Every consequential tool call produces an audit record with full context
- Records link back to the user request and permission decision that authorized them
- Tampering with a past record is detectable
- An investigation query reconstructs a full action history for a resource or session

COMMON FAILURES TO AVOID:
- Logs that show the action but not who/why/what-authorized-it
- Mutable logs an attacker (or the agent) could alter to hide actions
- Audit records so verbose or so sparse they cannot answer real questions
- No linkage between the action and the request/approval that caused it