|
| 1 | +{ |
| 2 | + "$schema": "https://json-schema.org/draft/2020-12/schema", |
| 3 | + "$id": "https://github.com/agentic-workforce-framework/schemas/v1/audit_event.schema.json", |
| 4 | + "title": "AuditEvent", |
| 5 | + "description": "Canonical per-event AWF audit shape. Every tool call, authorization decision, and approval the framework observes produces exactly one audit event in this shape. The v4.4.2 enhancement carries the per-event enterprise fields (user_id on every event, per-tool-call policy_decision, numeric risk_score, tool_name, args_redacted, before_state / after_state, jit_token, approval_id) that regulators require to answer who authorized which agent to take which action. The hash chain that makes events tamper-evident is enforced at the audit service layer (not in this schema) — this schema describes the event payload that gets hashed. See AWF Sprint Plan v4.4.2 §Audit Event Schema Enhancement.", |
| 6 | + "version": "1.0", |
| 7 | + "type": "object", |
| 8 | + "required": [ |
| 9 | + "event_id", |
| 10 | + "timestamp_utc", |
| 11 | + "correlation_id", |
| 12 | + "agent_id", |
| 13 | + "agent_run_id", |
| 14 | + "user_id", |
| 15 | + "tool_name", |
| 16 | + "policy_decision", |
| 17 | + "risk_score", |
| 18 | + "status", |
| 19 | + "runtime_provider", |
| 20 | + "evidence_strength" |
| 21 | + ], |
| 22 | + "properties": { |
| 23 | + "event_id": { |
| 24 | + "type": "string", |
| 25 | + "description": "Unique identifier for this audit event. Free-form string (e.g. 'evt_01HW2YA6NXBZ4S0K3K9C5R8RQ7') so adopters can use ULID, UUID, or a prefixed scheme. The audit service guarantees uniqueness and links event_id into the hash chain." |
| 26 | + }, |
| 27 | + "timestamp_utc": { |
| 28 | + "type": "string", |
| 29 | + "format": "date-time", |
| 30 | + "description": "ISO 8601 timestamp in UTC when the event was recorded. The audit chain orders events by this timestamp; clock skew across producers MUST be resolved before write." |
| 31 | + }, |
| 32 | + "correlation_id": { |
| 33 | + "type": "string", |
| 34 | + "description": "Correlation ID linking this event to the session, the Runtime Authorization Decision, the Task Risk Profile, and any sibling tool-call events in the same agent run." |
| 35 | + }, |
| 36 | + "agent_id": { |
| 37 | + "type": "string", |
| 38 | + "description": "Identifier of the agent that produced or attempted the action. The framework role / agent name (e.g. 'fix-agent', 'orchestrator', 'qa-agent'), not the runtime substrate." |
| 39 | + }, |
| 40 | + "agent_run_id": { |
| 41 | + "type": "string", |
| 42 | + "description": "Identifier of the specific agent run / session this event belongs to. Multiple events share an agent_run_id when they come from the same session; agent_id may repeat across runs." |
| 43 | + }, |
| 44 | + "user_id": { |
| 45 | + "type": "string", |
| 46 | + "description": "The human who invoked the agent session. Present on EVERY audit event in the chain, not only on HUMAN_APPROVAL_RECORDED. This is the accountable human, not the agent. Regulators do not ask what the agent did — they ask which human authorized the agent to do it; user_id on every event is the answer." |
| 47 | + }, |
| 48 | + "trust_subject_id": { |
| 49 | + "type": ["string", "null"], |
| 50 | + "format": "uuid", |
| 51 | + "description": "Foreign key to trust_subjects.id for the subject that produced this event. Nullable during the Sprint 3 rollout (some adapters populate trust_subject_id only after the trust_subjects table is live), but SHOULD be non-null once Sprint 3 migrations 011 and 012 are in effect." |
| 52 | + }, |
| 53 | + "tool_name": { |
| 54 | + "type": "string", |
| 55 | + "description": "Explicit name of the tool the agent invoked (e.g. 'Bash', 'Edit', 'Agent', 'Read'). Top-level and indexed — the audit service treats this as a primary query axis. Previously buried inside the event payload; v4.4.2 lifts it for retrieval performance." |
| 56 | + }, |
| 57 | + "policy_decision": { |
| 58 | + "type": "string", |
| 59 | + "enum": ["allowed", "denied", "pending_approval"], |
| 60 | + "description": "Per-tool-call policy outcome. allowed = the tool call ran. denied = the tool call was rejected by policy and did not run. pending_approval = the tool call is paused waiting on a human approval (jit_token / approval_id refer to that pending approval). Distinct from session-level approval state." |
| 61 | + }, |
| 62 | + "risk_score": { |
| 63 | + "type": "number", |
| 64 | + "minimum": 0.0, |
| 65 | + "maximum": 1.0, |
| 66 | + "description": "Per-tool-call risk score, normalized 0.0 - 1.0. Additive to the session-level D1-D4 scoring; this is the granular per-action risk that drove the policy_decision." |
| 67 | + }, |
| 68 | + "approval_id": { |
| 69 | + "type": ["string", "null"], |
| 70 | + "description": "Identifier of the specific approval record that authorizes this tool call. Null when no approval was required. Links a particular human-approval record to a particular tool call — currently session-scoped in AWF; v4.4.2 makes it per tool call." |
| 71 | + }, |
| 72 | + "jit_token": { |
| 73 | + "type": ["string", "null"], |
| 74 | + "description": "Just-in-time approval token issued for this specific tool call. Null when policy_decision is allowed without approval. Pairs with approval_id; the token expires after the tool call completes so the same approval cannot be replayed against a different call." |
| 75 | + }, |
| 76 | + "status": { |
| 77 | + "type": "string", |
| 78 | + "enum": ["executed", "blocked", "pending"], |
| 79 | + "description": "Execution status of the tool call AFTER policy was applied. executed = tool call ran to completion. blocked = tool call was prevented (typically when policy_decision is denied). pending = tool call is waiting on a jit_token / approval_id resolution and may yet execute or be blocked." |
| 80 | + }, |
| 81 | + "args_redacted": { |
| 82 | + "type": ["object", "null"], |
| 83 | + "description": "Tool call arguments with sensitive fields replaced by '***'. Identifiers are preserved so events still join across the chain (e.g. user_id, file paths, table names remain readable). Null when the tool takes no arguments. Inner shape is tool-specific and not constrained by this schema." |
| 84 | + }, |
| 85 | + "before_state": { |
| 86 | + "type": ["object", "string", "null"], |
| 87 | + "description": "State snapshot taken immediately before the tool executed. Granularity is per tool call (more granular than the session-level files_changed AWF already captures). String permitted for tools whose state is naturally a scalar (e.g. a file's content hash); object permitted for structured snapshots. Null when before-state is not meaningful for the tool (e.g. a read-only operation)." |
| 88 | + }, |
| 89 | + "after_state": { |
| 90 | + "type": ["object", "string", "null"], |
| 91 | + "description": "State snapshot taken immediately after the tool executed. Symmetric with before_state. Diffing before_state and after_state yields the per-tool-call change set the audit service exposes to reviewers." |
| 92 | + }, |
| 93 | + "error": { |
| 94 | + "type": ["object", "string", "null"], |
| 95 | + "description": "Error payload when the tool call raised. Null on success. String for short error messages; object for structured errors (e.g. {code, message, stack_hash}). The hash chain hashes the error payload alongside the rest of the event so post-hoc redaction is detectable." |
| 96 | + }, |
| 97 | + "runtime_provider": { |
| 98 | + "type": "string", |
| 99 | + "description": "Execution substrate that produced this event (e.g. claude_code, codex, cursor, devin, langgraph, multica, openclaw, maggy). Mirrors the runtime_provider on the Trust Capability Profile." |
| 100 | + }, |
| 101 | + "evidence_strength": { |
| 102 | + "type": "string", |
| 103 | + "enum": ["E0", "E1", "E2", "E3"], |
| 104 | + "description": "Evidence strength of this specific event. E0 = post-hoc / session-outcome only. E1 = session-outcome plus surfaced telemetry. E2 = per-decision evidence from runtime hooks. E3 = full per-action evidence including pre-tool and post-tool hook coverage. An event sourced from a PreToolUse/PostToolUse hook is E3; an event reconstructed from a session transcript alone is E0." |
| 105 | + } |
| 106 | + }, |
| 107 | + "additionalProperties": false, |
| 108 | + "examples": [ |
| 109 | + { |
| 110 | + "event_id": "evt_01HW2YA6NXBZ4S0K3K9C5R8RQ7", |
| 111 | + "timestamp_utc": "2026-05-22T10:14:31Z", |
| 112 | + "correlation_id": "corr_ex_b_cursor_ui_refactor", |
| 113 | + "agent_id": "fix-agent", |
| 114 | + "agent_run_id": "run_2026_05_22_001", |
| 115 | + "user_id": "user_alice@example.com", |
| 116 | + "trust_subject_id": "33333333-3333-4333-a333-333333333333", |
| 117 | + "tool_name": "Edit", |
| 118 | + "policy_decision": "allowed", |
| 119 | + "risk_score": 0.12, |
| 120 | + "approval_id": null, |
| 121 | + "jit_token": null, |
| 122 | + "status": "executed", |
| 123 | + "args_redacted": { |
| 124 | + "file_path": "src/components/HeaderButton.tsx", |
| 125 | + "old_string": "***", |
| 126 | + "new_string": "***" |
| 127 | + }, |
| 128 | + "before_state": { "content_hash": "sha256:aaaa1111..." }, |
| 129 | + "after_state": { "content_hash": "sha256:bbbb2222..." }, |
| 130 | + "error": null, |
| 131 | + "runtime_provider": "cursor", |
| 132 | + "evidence_strength": "E3" |
| 133 | + }, |
| 134 | + { |
| 135 | + "event_id": "evt_01HW2YB7PZD2T6Q4M5L7B6S3X9", |
| 136 | + "timestamp_utc": "2026-05-22T13:46:00Z", |
| 137 | + "correlation_id": "corr_ex_a_codex_db_migration", |
| 138 | + "agent_id": "executor", |
| 139 | + "agent_run_id": "run_2026_05_22_002", |
| 140 | + "user_id": "user_alice@example.com", |
| 141 | + "trust_subject_id": "11111111-1111-4111-a111-111111111111", |
| 142 | + "tool_name": "Bash", |
| 143 | + "policy_decision": "denied", |
| 144 | + "risk_score": 0.93, |
| 145 | + "approval_id": null, |
| 146 | + "jit_token": null, |
| 147 | + "status": "blocked", |
| 148 | + "args_redacted": { "command": "psql -f migrations/2026_05_22_add_index.sql" }, |
| 149 | + "before_state": null, |
| 150 | + "after_state": null, |
| 151 | + "error": { |
| 152 | + "code": "RUNTIME_AUTHORIZATION_BLOCKED", |
| 153 | + "message": "Required trust tier HIGH not met; current tier PROVISIONAL on (codex, db_migration)." |
| 154 | + }, |
| 155 | + "runtime_provider": "codex", |
| 156 | + "evidence_strength": "E2" |
| 157 | + } |
| 158 | + ] |
| 159 | +} |
0 commit comments