> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cynative.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Log: Fail-Closed JSONL Record of Every Tool Call

> Cynative's JSONL audit log records every tool call with agent provenance, decisions, and redacted results. Configure path, rotation, and retention.

Every tool call Cynative makes is recorded to a persistent JSONL audit log at `~/.cynative/audit.log`. The log is on by default and fail-closed: if a call cannot be recorded, the run aborts rather than proceeding without a trail. This gives you a complete, tamper-evident record of every action the model took — what it called, with what arguments, what decision was made, and which agent prompted it.

## What gets logged

Every tool call produces one or more JSONL records. Each record captures:

| Field | Description |
| - | - |
| `time` | UTC timestamp of when the record was written. |
| `seq` | Monotonically increasing sequence number within the session. |
| `session_id` | Identifies the interactive session. |
| `run_id` | Identifies the individual task run within the session. |
| `call_id` | Unique identifier for this specific tool call. |
| `parent_call_id` | For child records (e.g. reads made by an `api_reference` lookup), the call ID of the parent. Empty on all other records. |
| `depth` | Nesting depth of the call (0 for top-level calls). |
| `actor` | The LLM provider and model that made the call (e.g. `anthropic/claude-opus-5`). |
| `agent` | Agent provenance — name, source (`builtin` or `user`), and SHA-256 of the exact agent file bytes. Present when an agent framed the run. |
| `phase` | `attempt` (the call is about to run) or `result` (the call completed). |
| `tool` | Name of the tool called (e.g. `http_request`, `code_execution`). |
| `arguments` | The call's arguments as a JSON object. |
| `decision` | How the call was authorized: `approved` (operator pressed `y`), `approved_session` (operator pressed `a`), `ungated` (an orchestration tool that requires no approval), `unprompted` (a targeted metadata read that runs without a prompt by design), or `denied`. |
| `outcome` | Result of the call: `ok`, `denied`, or `error`. |
| `result` | Redacted tool result (see [Redaction](#redaction) below). |
| `route` | For `http_request` results, the egress route: `direct` or `proxy`. Empty for all other records. |

Every record from an agent run also includes the agent's name, source, and SHA-256 file digest — so any finding can be traced back to the exact prompt revision that produced it.

## Redaction

Tool results are **redacted** before they are written to the log. Cynative's redactor scans the result string for secret-shaped values (API keys, tokens, credentials) and replaces them before the record is persisted.

Approval-prompt arguments are stored **verbatim** — they match exactly what you saw and approved at the prompt. Arguments for calls that were never shown at an approval prompt (inner `code_execution` calls, ungated orchestration tools, and unknown tools) are also redacted before logging, so a resolved secret that a script or the model copied from earlier output is never persisted.

<Warning>
  The log can hold sensitive values from approval-prompt arguments — for example, a URL containing a signed token or a parameter derived from secret output. The log file is created with mode `0600` and is readable only by the user who ran Cynative. Treat it with the same care as other credential material on the host.
</Warning>

## Fail-closed behavior

The audit log is fail-closed by design. If any of the following occur, the run aborts immediately rather than continuing without a complete record:

* A record cannot be marshaled to JSON.
* A record cannot be written to the log file (e.g. disk full, permissions error).
* The log file cannot be opened at startup.

This means you can rely on the absence of a record to mean a call did not happen — the log is not best-effort. The only exception is retention pruning and compression, which run asynchronously and do not affect the fail-closed write path.

## Configuration

Configure the audit log under `audit:` in `~/.cynative/config.yaml`, or via environment variable. Environment variables override the config file.

| Config key | Env var | Default | Description |
| - | - | - | - |
| `audit.enabled` | `CYNATIVE_AUDIT_ENABLED` | `true` | Set to `false` to disable the audit log entirely. |
| `audit.path` | `CYNATIVE_AUDIT_PATH` | `~/.cynative/audit.log` | Path to the JSONL log file. The parent directory is created automatically if it does not exist. |
| `audit.max_size_mb` | `CYNATIVE_AUDIT_MAX_SIZE_MB` | `100` | Maximum size in megabytes before the log rotates. |
| `audit.retention_days` | `CYNATIVE_AUDIT_RETENTION_DAYS` | `30` | Number of days to retain rotated log files. |
| `audit.compress` | `CYNATIVE_AUDIT_COMPRESS` | `false` | Compress rotated log files with gzip. |

Example `~/.cynative/config.yaml` snippet:

```yaml theme={null}
audit:
  enabled: true
  path: ~/.cynative/audit.log
  max_size_mb: 100
  retention_days: 30
  compress: false
```

Rotation and retention are handled by a size-rotating, age-retaining writer. When the active log file reaches `max_size_mb`, it is renamed and a new file is opened. Files older than `retention_days` are pruned on the next rotation. If `compress` is `true`, rotated files are gzip-compressed asynchronously.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.