← All Event Families
OpenEarth

foundation.protocols.ai.observation.*

Bridge-native observation of AI coding agent actions. Tool use interception, file operations with content hashing, command execution, security block/guidance decisions, cost snapshots, privacy sensitivity flags, and subagent lifecycle tracking. The bridge observation layer (AGPL-3.0) — parallel to ai.gryph.* (Go, Apache-2.0) and ai.claude.* self-report.

15
Events
15
Timeline
0
State

The Three Observation Layers

These events are the bridge's own audit trail — emitted by the Kotlin bridge daemon as it proxies Claude API traffic. They run in parallel with ai.claude.* (self-report) and ai.gryph.* (external Go hooks).

Propertyai.claude.*ai.observation.*ai.gryph.*
SourceBridge (API conversation)Bridge (Kotlin daemon)System hooks (Go binary)
TrustSelf-reportBridge observationIndependent observation
Can blockNoNoYes (PreToolUse hook)
Tracks subagentsVia agent.spawnVia subagent_id on every eventVia SubagentStart hook
LicenseAGPL-3.0 (bridge)AGPL-3.0 (bridge)Apache-2.0 (gryph)
Correlation engine. The ai.certification.* events correlate observation vs gryph events to produce PASS/FAIL/GAP verdicts.

Contents

1. Session Lifecycle

2 events — bridge-observed session boundaries

Timeline Event

foundation.protocols.ai.observation.session.start

Bridge-observed session start. Includes bridge version for provenance.

FieldTypeDescription
session_idstringSession UUID (links to claude.session.start)
agent_namestringAgent identifier (default: "claude-code")
bridge_versionstring?Bridge daemon version
timestampintegerUnix epoch milliseconds
 
{
  "type": "foundation.protocols.ai.observation.session.start",
  "content": {
    "session_id": "3f057459-de35-4b1a-84d7-484a38194b6a",
    "agent_name": "claude-code",
    "bridge_version": "1.0.0",
    "timestamp": 1776199855184
  }
}
Timeline Event

foundation.protocols.ai.observation.session.end

Bridge-observed session end with aggregate statistics.

FieldTypeDescription
session_idstringSession UUID
duration_msintegerWall-clock session duration
total_eventsintegerTotal observation events emitted
blocked_countintegerActions blocked by security checks
guidance_countintegerActions with guidance issued
actual_input_tokensinteger?Actual input tokens (from transcript)
actual_output_tokensinteger?Actual output tokens (from transcript)
timestampintegerUnix epoch milliseconds

2. Tool Observation

3 events — pre-use, post-use, and failure

Timeline Event

foundation.protocols.ai.observation.tool.pre

Tool about to be used. Emitted before execution starts.

FieldTypeDescription
session_idstringSession UUID
tool_namestringTool identifier (Bash, Read, Write, etc.)
action_typestringAction category (CommandExec, FileWrite, etc.)
descriptionstring?Human-readable description of intended action
working_directorystring?Working directory at time of call
subagent_idstring?Subagent ID if from a spawned agent
timestampintegerUnix epoch milliseconds
Timeline Event

foundation.protocols.ai.observation.tool.post

Tool execution completed. Includes exit code and duration.

FieldTypeDescription
session_idstringSession UUID
tool_namestringTool identifier
action_typestringAction category
exit_codeinteger?Process exit code (0 = success)
duration_msinteger?Execution duration in milliseconds
subagent_idstring?Subagent ID if from a spawned agent
timestampintegerUnix epoch milliseconds
Timeline Event

foundation.protocols.ai.observation.tool.failure

Tool execution failed with error.

FieldTypeDescription
session_idstringSession UUID
tool_namestringTool identifier
action_typestringAction category
errorstringError message
exit_codeinteger?Process exit code
subagent_idstring?Subagent ID if from a spawned agent
timestampintegerUnix epoch milliseconds

3. File Operations

2 events — read and write with content hashing

Timeline Event

foundation.protocols.ai.observation.file.read

File read observed. Includes content hash for integrity verification.

FieldTypeDescription
session_idstringSession UUID
pathstringAbsolute file path
size_bytesinteger?File size in bytes
content_hashstring?SHA-256 of file content
subagent_idstring?Subagent ID if from a spawned agent
timestampintegerUnix epoch milliseconds
Timeline Event

foundation.protocols.ai.observation.file.write

File write observed. Includes diff metrics and content hash.

FieldTypeDescription
session_idstringSession UUID
pathstringAbsolute file path
size_bytesinteger?File size after write
content_hashstring?SHA-256 of content after write
lines_addedinteger?Lines added
lines_removedinteger?Lines removed
subagent_idstring?Subagent ID if from a spawned agent
timestampintegerUnix epoch milliseconds

4. Command Execution

1 event — shell command with output preview

Timeline Event

foundation.protocols.ai.observation.command.exec

Shell command execution observed. Includes truncated stdout/stderr previews.

FieldTypeDescription
session_idstringSession UUID
commandstringShell command executed
descriptionstring?Human-readable description
exit_codeinteger?Process exit code
duration_msinteger?Execution duration
stdout_previewstring?Truncated stdout (500 chars)
stderr_previewstring?Truncated stderr (500 chars)
subagent_idstring?Subagent ID if from a spawned agent
timestampintegerUnix epoch milliseconds

5. Notification

1 event — generic bridge notification

Timeline Event

foundation.protocols.ai.observation.notification

Generic notification from the bridge observation layer.

FieldTypeDescription
session_idstringSession UUID
notification_typestringNotification category
messagestringNotification message
timestampintegerUnix epoch milliseconds

6. Security Decisions

2 events — blocked actions and guidance advisories

Timeline Event

foundation.protocols.ai.observation.security.blocked

An action was blocked by a security check.

FieldTypeDescription
session_idstringSession UUID
tool_namestringTool that was blocked
action_typestringAction category
check_namestringName of the Check that blocked
reasonstringHuman-readable block reason
timestampintegerUnix epoch milliseconds
Timeline Event

foundation.protocols.ai.observation.security.guidance

A security check issued guidance (advisory, not blocking).

FieldTypeDescription
session_idstringSession UUID
tool_namestringTool receiving guidance
action_typestringAction category
check_namestringName of the Check
guidancestringAdvisory message
timestampintegerUnix epoch milliseconds

7. Cost Observation

1 event — token usage and cost snapshot

Timeline Event

foundation.protocols.ai.observation.cost.observed

Token usage and cost snapshot from the bridge observation layer.

FieldTypeDescription
session_idstringSession UUID
input_tokensintegerInput tokens consumed
output_tokensintegerOutput tokens generated
cache_read_tokensintegerCache read tokens
cache_write_tokensintegerCache write tokens
modelstring?Model identifier
estimated_cost_usdstring?Estimated cost in USD
timestampintegerUnix epoch milliseconds

8. Privacy

1 event — sensitive content detection

Timeline Event

foundation.protocols.ai.observation.privacy.sensitive

Sensitive content detected (credentials, keys, PII). Reports whether content was redacted.

FieldTypeDescription
session_idstringSession UUID
tool_namestringTool handling sensitive content
pathstring?File path if applicable
sensitivity_typestringCategory: credentials, pii, api_key, etc.
redactedbooleanWhether content was redacted before recording
timestampintegerUnix epoch milliseconds

9. Subagent Lifecycle

2 events — subagent spawn and completion

Timeline Event

foundation.protocols.ai.observation.subagent.start

A subagent was spawned. All subsequent tool events from this agent carry the agent_id in their subagent_id field.

FieldTypeDescription
session_idstringParent session UUID
agent_idstringSubagent identifier
agent_typestringSubagent type (Explore, Plan, general-purpose)
timestampintegerUnix epoch milliseconds
Timeline Event

foundation.protocols.ai.observation.subagent.stop

A subagent completed or was terminated.

FieldTypeDescription
session_idstringParent session UUID
agent_idstringSubagent identifier
agent_typestringSubagent type
agent_transcript_pathstring?Path to per-subagent JSONL transcript
last_assistant_messagestring?Final output (truncated)
timestampintegerUnix epoch milliseconds

Cross-Reference: observation.* vs gryph.* vs claude.*

How the three observation layers relate

ai.claude.*ai.observation.*ai.gryph.*Relationship
session.startsession.startsession.startTriple-parallel: same session, three observers
session.endsession.endsession.endTriple-parallel: gryph has actual tokens
tool.calltool.pretool.preObservation + gryph fire before execution
tool.resulttool.posttool.postTriple-parallel: all report exit code
tool.errortool.failuretool.failureTriple-parallel: different error detail
file.changefile.writefile.writeObservation + gryph add content_hash
—file.readfile.readClaude doesn't emit explicit file reads
—command.execcommand.execDetailed command execution (stdout/stderr preview)
usage.checkpointcost.observedcost.observedObservation = bridge estimate, gryph = actual
—security.blockedsecurity.blockedBoth layers report blocks
—security.guidancesecurity.guidanceBoth layers report guidance
—privacy.sensitiveprivacy.sensitiveBoth layers detect sensitive content
agent.spawnsubagent.startsubagent.startTriple-parallel: subagent tracking
agent.resultsubagent.stopsubagent.stopTriple-parallel: subagent completion
Key differentiator: observation.* events carry subagent_id on every tool/file/command event, enabling per-subagent attribution without the cross-reference hop that gryph requires.