Skip to main content

Audit Log Schema

Audit logs are newline-delimited JSON objects (JSONL), one event per handled request. They are written only to the configured local file and are not uploaded by OTerminus.

Default path​

  • ~/.oterminus/audit.jsonl (overridable)

Event fields​

  • timestamp (ISO8601 UTC)
  • user_input
  • direct_command_detected (bool)
  • ambiguity_detected (bool)
  • ambiguity_reason (nullable string)
  • ambiguity_safe_options (string array)
  • planner_invoked (bool)
  • planner_skipped (bool)
  • planner_skip_reason (nullable string; e.g. direct_command, ambiguity_blocked, deterministic_shortcut)
  • proposal_origin (nullable string; e.g. direct_command, deterministic_shortcut, llm_planner, unknown)
  • routed_category (nullable string)
  • proposal_mode (nullable string)
  • command_family (nullable string)
  • rendered_command (nullable string)
  • argv (string array)
  • validation_accepted (nullable bool)
  • warnings (string array)
  • rejection_reasons (string array)
  • confirmation_result (nullable string; includes statuses such as confirmed, cancelled, skipped_auto_execute_safe, skipped_dry_run, skipped_explain, not_prompted_rejected, and blocked_ambiguous)
  • auto_execute_safe_enabled (bool)
  • auto_execute_safe_eligible (nullable bool)
  • auto_execute_safe_reason (nullable bounded string reason code)
  • execution_exit_code (nullable int)
  • stdout_truncated (bool)
  • stderr_truncated (bool)
  • stdout_original_chars (nullable int)
  • stderr_original_chars (nullable int)
  • stdout_visible_chars (nullable int)
  • stderr_visible_chars (nullable int)
  • rerun_source_history_id (nullable int)
  • recovery_source_history_id (nullable int)
  • recovery_request (bool)
  • duration_ms (nullable int)
  • timings_ms (object mapping stage names to non-negative integer milliseconds)

Ambiguity outcomes​

Natural-language ambiguity detection runs after direct-command detection and before planner setup. When an ambiguous request is blocked, the event records:

  • ambiguity_detected: true
  • ambiguity_reason with the matched phrase or broad-scope reason
  • ambiguity_safe_options with read-only inspection alternatives
  • confirmation_result: "blocked_ambiguous"
  • planner_invoked: false
  • planner_skipped: true
  • planner_skip_reason: "ambiguity_blocked"

Planner, validator, confirmation, and executor fields remain unset because the request stops before those stages.

When a direct command is handled without the LLM planner, the event records:

  • planner_invoked: false
  • planner_skipped: true
  • planner_skip_reason: "direct_command"

When a non-ambiguous natural-language request uses the planner:

  • planner_invoked: true
  • planner_skipped: false
  • planner_skip_reason: null

When a non-ambiguous natural-language request uses an enabled deterministic shortcut:

  • planner_invoked: false
  • planner_skipped: true
  • planner_skip_reason: "deterministic_shortcut"
  • proposal_origin: "deterministic_shortcut"

timings_ms stores local, approximate stage durations (perf-counter based) for observability, such as direct_command_detection_ms, ambiguity_detection_ms, routing_ms, deterministic_shortcut_ms, planner_ms, validation_ms, execution_ms, and total_duration_ms. Skipped stages are omitted.

Rerun lineage​

When a REPL user invokes rerun <history_id>, OTerminus reprocesses the original input as a new request event. The new event sets rerun_source_history_id to the source history entry ID. Normal validation/policy/confirmation rules still apply.

Safe auto-execute outcomes​

When OTERMINUS_AUTO_EXECUTE_SAFE=true and an execute-mode request qualifies, OTerminus still records the previewed/validated command metadata and sets:

  • confirmation_result: "skipped_auto_execute_safe"
  • auto_execute_safe_enabled: true
  • auto_execute_safe_eligible: true
  • auto_execute_safe_reason: "eligible"
  • proposal_origin to the direct-command or deterministic-shortcut source

Ineligible execute-mode requests keep the normal confirmation flow and may record auto_execute_safe_eligible: false with a bounded reason code. Dry-run and explain mode do not use safe auto-execution and keep skipped_dry_run or skipped_explain outcomes.

Redaction​

When audit redaction is enabled (the default), text and argv fields are passed through redaction helpers before writing. Audit events intentionally do not include raw stdout/stderr command output; they store only truncation flags, character counts, and exit-code metadata for command output. Redaction is best-effort, so do not share audit logs blindly.

User-facing audit commands​

  • audit status: reports enabled/disabled state, configured path, file existence, and redaction.
  • audit tail [n]: shows most recent events from the local JSONL file (default n=10). Review output before sharing it because it can include local paths and command context.
  • audit clear: asks for exact confirmation (CLEAR AUDIT) before clearing the local log.

When audit is disabled, tail and clear commands do not create a new log file.

Example (illustrative)​

{
  "timestamp": "2026-04-28T12:00:00+00:00",
  "user_input": "show disk space",
  "direct_command_detected": false,
  "routed_category": "metadata_inspect",
  "proposal_mode": "structured",
  "proposal_origin": "deterministic_shortcut",
  "command_family": "df",
  "rendered_command": "df -h",
  "argv": ["df", "-h"],
  "validation_accepted": true,
  "warnings": [],
  "rejection_reasons": [],
  "confirmation_result": "skipped_auto_execute_safe",
  "auto_execute_safe_enabled": true,
  "auto_execute_safe_eligible": true,
  "auto_execute_safe_reason": "eligible",
  "execution_exit_code": 0,
  "duration_ms": 73
}

Note: persistent REPL history uses a separate local JSONL file (OTERMINUS_HISTORY_PATH) and is not an audit log replacement; reruns from persisted history still emit normal audit events. History is disabled by default and, when enabled, should be reviewed before sharing because it may contain paths and command context.

Failure explanations (opt-in)​

When enabled, failure explanation sends only redacted/truncated command, stdout, and stderr context to the configured local Ollama model. Suggested next actions are displayed only and are never executed automatically. Audit events may include:

  • failure_explanation_requested
  • failure_explanation_generated
  • failure_explanation_error
  • failure_suggested_next_action (redacted/bounded)
  • failure_stderr_summary (redacted/bounded)

See Configuration reference for enablement and limits.

  • planner_skip_reason values: direct_command, ambiguity_blocked, deterministic_shortcut, or null when planner ran.