Audit Trail
The audit trail provides a complete record of every tool call made by your agents, including policy decisions and approval outcomes. Use it for compliance reviews, debugging policy behavior, and understanding agent activity across devices.
What Gets Logged
Every agent hook event is recorded with the following information:
| Field | Description |
|---|---|
| Tool Name | The tool that was invoked (e.g., Bash, Edit, Write) |
| Event Type | The hook event name (e.g., PermissionRequest, SessionEnd) |
| Tool Input | First 120 characters of the tool's input parameters |
| Device | The hostname of the device running the agent |
| Timestamp | Exact time of the event |
| Permission Status | Whether the call was allowed, denied, pending, or expired |
| Policy Info | Which policy matched and what action it specified |
| Decision Source | Whether the decision came from a policy or manual approval |
Filtering Events
The audit trail includes four filters to narrow down results:
| Filter | Description |
|---|---|
| Device | Filter by device hostname (default: All devices) |
| Tool Name | Filter by specific tool (default: All tools) |
| Date From | Show events after this date |
| Date To | Show events before this date |
By default, the audit trail shows the last 7 days of events. Use the Clear filters button to reset all filters.
Browsing Results
Events are displayed in reverse chronological order (newest first), 25 per page. Click Load More at the bottom to fetch the next page of results.
Status Badges
Each event displays colored badges indicating what happened:
Permission status:
| Badge | Color | Meaning |
|---|---|---|
| Allowed | Green | The tool call was permitted |
| Denied | Red | The tool call was blocked |
| Pending | Amber | The tool call is awaiting approval |
| Expired | Gray | The approval request timed out |
Decision source:
| Badge | Color | Meaning |
|---|---|---|
| Policy | Blue | A policy rule made the decision |
| Manual | Purple | A human approved or denied the request |
Exporting Data
Export your filtered audit trail data for external analysis or compliance records. Exports respect your current filters and include up to 10,000 records.
| Format | Best For |
|---|---|
| JSON | Programmatic analysis, preserves full data structure |
| CSV | Spreadsheets, reporting tools, sharing with non-technical stakeholders |
The CSV export includes these columns:
| Column | Description |
|---|---|
timestamp | When the event occurred |
device_hostname | Device that generated the event |
device_os | Operating system of the device |
session_id | External session identifier |
tool_name | Tool that was called |
tool_input | Full tool input parameters |
hook_event_name | Type of hook event |
cwd | Working directory at time of call |
permission_status | Allow, deny, pending, or expired |
policy_decision_source | Policy or manual |
policy_name | Name of the matched policy |
policy_action | Action the policy specified |
policy_action_reason | Reason for the policy action |
source | Source of the event |
Export files are named audit-trail-YYYY-MM-DD.csv or audit-trail-YYYY-MM-DD.json using the date of export.
Next Steps
- Sessions - View detailed session timelines
- How Policies Work - Understand policy evaluation
- Creating Policies - Automate common decisions