TraceRookNormalized event v1
{
"schema_version": 1,
"event_id": "sample-event-id",
"agent": "claude_code",
"source_session_id": "sample-session-id",
"agent_sub_id": null,
"source_turn_id": null,
"source_tool_call_id": "sample-tool-call-id",
"kind": "pre_tool_use",
"occurred_at": "2026-10-08T12:00:00Z",
"cwd": "/Users/dev/projects/widget",
"repo_root": "/Users/dev/projects/widget",
"tool_name": "Bash",
"action_type": "shell_exec",
"args_summary": "Proposed outbound transfer referencing a credential",
"risk_features": ["sensitive_file_reference", "outbound_upload"],
"redaction_count": 2,
"raw_input_truncated": false,
"action_fingerprint": "sha256-of-canonical-original-action",
"metadata": {"host_permission_mode": "default"}
}This is a sanitized illustrative envelope, not an accepted live request. Supported event kinds are session_start, user_prompt, pre_tool_use, post_tool_use, post_tool_failure, session_end, and instruction_loaded. Action types include shell_exec, file_read, file_write, file_edit, network, mcp, subagent, and other.
Live IPC v2 contracts
MVP2.0 implements the additive v2 codec and DTOs. It does not start a socket listener. The planned Unix endpoint has a private 0700 directory and 0600 socket; real peer checks and transport cancellation are MVP2.1 work.
A frame is a four-byte network-order length followed by exactly one JSON payload. Bounds are 1 MiB per request, 16 KiB per reply, depth 32, 64 KiB of encoded string content, 1,024 members per object, and 2,048 elements per array. Duplicate decoded keys, unexpected typed fields, invalid UTF-8, unknown versions and unsupported precision are rejected.
The v2 request carries protocol_version, request_id, request_kind, adapter, adapter_version, received_at_ms, hard_deadline_ms, host_version, invocation_nonce and host_payload. Original host input stays transient; it must never be copied into logs, SQLite or a remote request.
Replies carry a matching request_id and only no_override or deny, plus a bounded reason, explanation, optional incident ID, decision source and tool class. execution_observed is always unknown. No override preserves host permissions; it is not an execution grant.
The codec checks a 100 ms default monotonic decode deadline. Checks around Foundation are cooperative rather than preemptive. Runtime waits, read deadlines, peer identity and request deduplication still require service implementation. Legacy event schema v1 and fixture readers remain unchanged.
Exact action binding
Canonical SHA-256 input contains provider, session, optional turn, tool-call ID, tool name, working directory, and original tool input. MVP2 requires a fresh 128-bit system-random invocation nonce even when the host provides a call ID. Include subagent identity in the approval’s exact scope and isolate simultaneous sessions.
The digest uses original input, not a model-generated title or redacted command summary. Foundation numeric parsing rejects values outside supported exact decimal bounds rather than allowing distinct originals to round to the same action representation.
A fingerprint binds the observed invocation. It does not grant cryptographic control over later nested processes or transport continuations.
Authenticated UI mutations
The planned native control plane uses NSXPCConnection to a signed endpoint; it is not active in this build. Approval and trust mutations require validated peer audit tokens and code-signing identity. Such mutations must not be exposed on the CLI’s UID-checked event socket.
Approval state changes must verify exact binding, pending state, deadline, and invocation liveness, then commit one terminal transition. An event observation channel is not an authorization channel.
Provider verdict contract
AnalysisProvider offers availability and deadline-bound analysis with explicit modes: anthropicBYOK, traceRookCloudDemo, and localRulesOnly. A model verdict contains schema version, category, severity, confidence, suspicious flag, rationale, evidence, recommended action, drift, and limitations.
Production decoding enumerates values, caps lengths, rejects additional properties, validates confidence, and refuses execution instructions. The demo provider only accepts demo-origin requests; it cannot truthfully analyze a real session.
Provisional Cloud API
CloudAPIClient has a fixture implementation in MVP1. Future account, device-registration, usage, plans, analysis, and incident routes are provisional versioned contracts. They are not endpoints implemented by this static site or by a real TraceRook Cloud service.
No auth, login, enrollment, billing, or subscription behavior is implied by a sample account screen.