foundation.protocols.ai.claude.* — Claude Session Recording

Design Notes

All 42 events use the foundation.protocols.ai.claude namespace prefix — nested under ai to make clear that Claude is one specific AI vendor within the broader foundation.protocols.ai.* governance framework. Other AI vendors follow the same pattern (e.g., foundation.protocols.ai.mistral.*).

Sessions are threads — a session is a Matrix thread rooted on a session.start event. All subsequent events use m.relates_to with rel_type: "m.thread".
Cost values are strings — Matrix canonical JSON (spec §11.2) forbids floating-point numbers. All cost fields use string encoding (e.g., "0.042000").
Governance integration — for high-risk operations, Claude events can be wrapped in ai.intention → ai.decision → ai.effect sequences from the governance layer.

1. Session Lifecycle

6 events tracking the full lifecycle of a Claude Code session — from start to end, interruption, export, and replay.

Timeline Event

foundation.protocols.ai.claude.session.start

Sent when a Claude Code session is initiated. This event is the thread root for all subsequent events in the session.

Field	Type	Description
session_id	string	Unique session identifier
model	string	Model identifier (e.g., `claude-sonnet-4-20250514`)
initiated_by	string	Matrix user ID who started the session
working_directory	string	Filesystem path of the project root
environment	object	Platform, shell, runtime versions
system_prompt_hash	string	SHA-256 hash of the system prompt
tools_enabled	string[]	List of enabled built-in tools
mcp_servers_connected	string[]	MCP servers available at session start
extended_thinking_enabled	boolean	Whether extended thinking is on
max_tokens	integer	Max output tokens per turn
timestamp	integer	Unix millisecond timestamp

{
  "type": "foundation.protocols.ai.claude.session.start",
  "content": {
    "session_id": "sess_01ABC...",
    "model": "claude-sonnet-4-20250514",
    "initiated_by": "@user:matrix.openearth.network",
    "working_directory": "/project/root",
    "environment": {
      "platform": "linux",
      "shell": "bash",
      "node_version": "20.11.0",
      "python_version": "3.12.0"
    },
    "system_prompt_hash": "sha256:abc123...",
    "tools_enabled": ["bash", "read_file", "write_file", "web_search"],
    "mcp_servers_connected": ["github", "postgres"],
    "extended_thinking_enabled": false,
    "max_tokens": 8096,
    "timestamp": 1711800000000
  }
}

Timeline Event

foundation.protocols.ai.claude.session.end

Sent when a session terminates normally. Includes total cost (string-encoded), token counts, and duration.

Field	Type	Description
session_id	string	Session identifier
reason	string	Termination reason (e.g., `completed`)
duration_ms	integer	Total session duration in milliseconds
total_input_tokens	integer	Cumulative input tokens
total_output_tokens	integer	Cumulative output tokens
totalCost	string	Total cost as decimal string (e.g., `"0.042000"`)
currency	string	ISO 4217 currency code
turns	integer	Number of prompt-response turns

{
  "type": "foundation.protocols.ai.claude.session.end",
  "content": {
    "session_id": "sess_01ABC...",
    "reason": "completed",
    "duration_ms": 45200,
    "total_input_tokens": 12400,
    "total_output_tokens": 3200,
    "totalCost": "0.042000",
    "currency": "USD",
    "turns": 12,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.session.interrupted

Sent when a session is force-killed, crashes, or is abandoned.

Field	Type	Description
session_id	string	Session identifier
reason	string	Interruption reason
Values: `user_killed`, `crash`, `timeout`, `network_failure`, `process_exit`
signal	string	Unix signal (e.g., `SIGINT`)
last_event_id	string	Event ID of the last known event before interruption
duration_ms	integer	Session duration before interruption
total_input_tokens	integer	Cumulative input tokens
total_output_tokens	integer	Cumulative output tokens

{
  "type": "foundation.protocols.ai.claude.session.interrupted",
  "content": {
    "session_id": "sess_01ABC...",
    "reason": "user_killed",
    "signal": "SIGINT",
    "last_event_id": "$last_known_event_id",
    "duration_ms": 12000,
    "total_input_tokens": 4200,
    "total_output_tokens": 800,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.session.exported

Sent when a session transcript is exported to an external system or file.

Field	Type	Description
session_id	string	Session identifier
exported_by	string	Matrix user ID who exported
format	string	Export format (e.g., `json`)
destination	string	Where exported (e.g., `file`)
mxc_uri	string	MXC URI of the exported file
timestamp	integer	Unix millisecond timestamp

{
  "type": "foundation.protocols.ai.claude.session.exported",
  "content": {
    "session_id": "sess_01ABC...",
    "exported_by": "@user:matrix.openearth.network",
    "format": "json",
    "destination": "file",
    "mxc_uri": "mxc://matrix.openearth.network/exportfile123",
    "timestamp": 1711900000000,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.session.replayed

Sent when a prior session is replayed for review or debugging.

Field	Type	Description
original_session_id	string	Session being replayed
replayed_by	string	Matrix user ID who initiated replay
replay_session_id	string	New session ID for the replay
timestamp	integer	Unix millisecond timestamp

{
  "type": "foundation.protocols.ai.claude.session.replayed",
  "content": {
    "original_session_id": "sess_01ABC...",
    "replayed_by": "@user:matrix.openearth.network",
    "replay_session_id": "sess_02DEF...",
    "timestamp": 1711950000000
  }
}

State Event

foundation.protocols.ai.claude.session.active

Tracks the currently active session in a room. Updated as sessions start/stop.

Field	Type	Description
session_id	string	Active session identifier
started_at	integer	Unix millisecond start time
started_by	string	Matrix user ID
model	string	Model identifier
status	string	Current session status
Values: `running`, `paused`, `idle`, `terminated`

{
  "type": "foundation.protocols.ai.claude.session.active",
  "state_key": "",
  "content": {
    "session_id": "sess_01ABC...",
    "started_at": 1711800000000,
    "started_by": "@user:matrix.openearth.network",
    "model": "claude-sonnet-4-20250514",
    "status": "running"
  }
}

2. Prompt & Response

5 events covering user prompts, AI responses, streaming chunks, interruptions, and extended thinking.

Timeline Event

foundation.protocols.ai.claude.prompt

A user or system prompt sent to Claude, with optional file attachments, images, and documents.

Field	Type	Description
session_id	string	Session identifier
prompt_id	string	Unique prompt identifier
turn	integer	Turn number within the session
role	string	Message role (e.g., `user`)
text	string	Prompt text content
attachments	object[]	File attachments (path, hash, MXC URI)
images	object[]	Image references
documents	object[]	Document references

{
  "type": "foundation.protocols.ai.claude.prompt",
  "content": {
    "session_id": "sess_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "turn": 3,
    "role": "user",
    "text": "Refactor the authentication module to use JWT",
    "attachments": [
      {
        "type": "file",
        "path": "src/auth/auth.ts",
        "content_hash": "sha256:def456...",
        "mxc_uri": "mxc://matrix.openearth.network/file123"
      }
    ],
    "images": [],
    "documents": [],
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.response

Claude’s complete text response to a prompt, with token counts and stop reason.

Field	Type	Description
session_id	string	Session identifier
prompt_id	string	The prompt this responds to
turn	integer	Turn number
text	string	Response text content
input_tokens	integer	Input tokens for this turn
output_tokens	integer	Output tokens for this turn
cache_read_input_tokens	integer	Tokens read from prompt cache
cache_creation_input_tokens	integer	Tokens written to prompt cache
stop_reason	string	Why generation stopped
Values: `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `interrupted`

{
  "type": "foundation.protocols.ai.claude.response",
  "content": {
    "session_id": "sess_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "turn": 3,
    "text": "I'll refactor the auth module. Let me start by reading the current implementation...",
    "input_tokens": 1840,
    "output_tokens": 320,
    "cache_read_input_tokens": 400,
    "cache_creation_input_tokens": 0,
    "stop_reason": "tool_use",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$prompt_event_id" }
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.response.chunk

An incremental streaming chunk from Claude’s response. Used when streaming is enabled.

Field	Type	Description
session_id	string	Session identifier
prompt_id	string	Prompt being responded to
chunk_index	integer	Sequential chunk index
delta_text	string	Incremental text content

{
  "type": "foundation.protocols.ai.claude.response.chunk",
  "content": {
    "session_id": "sess_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "chunk_index": 4,
    "delta_text": "...let me read the current file first",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$response_event_id" }
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.response.interrupted

Sent when a user interrupts Claude’s streaming response mid-flight.

Field	Type	Description
session_id	string	Session identifier
prompt_id	string	Prompt being responded to
interrupted_by	string	Matrix user ID who interrupted
partial_text	string	Text generated before interruption
chunks_received	integer	Number of chunks received before stop
timestamp	integer	Unix millisecond timestamp

{
  "type": "foundation.protocols.ai.claude.response.interrupted",
  "content": {
    "session_id": "sess_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "interrupted_by": "@user:matrix.openearth.network",
    "partial_text": "I'll refactor the auth module. Let me start by...",
    "chunks_received": 4,
    "timestamp": 1711800005000,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.thinking

Claude’s internal reasoning block when extended thinking is enabled.

Field	Type	Description
session_id	string	Session identifier
prompt_id	string	Prompt being reasoned about
thinking_text	string	Internal reasoning content
thinking_tokens	integer	Tokens used for thinking

{
  "type": "foundation.protocols.ai.claude.thinking",
  "content": {
    "session_id": "sess_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "thinking_text": "The user wants to refactor auth to use JWT. I should first understand the current implementation...",
    "thinking_tokens": 540,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$prompt_event_id" }
    }
  }
}

3. Multimodal Input

2 events for images and documents provided as context to Claude.

Timeline Event

foundation.protocols.ai.claude.input.image

A user-provided image sent as part of a prompt. Stored via Matrix content repository (MXC URI).

Field	Type	Description
session_id	string	Session identifier
prompt_id	string	Associated prompt
mxc_uri	string	MXC URI of the uploaded image
media_type	string	MIME type (e.g., `image/png`)
filename	string	Original filename
width	integer	Image width in pixels
height	integer	Image height in pixels
size_bytes	integer	File size in bytes
description	string	Human-readable description

{
  "type": "foundation.protocols.ai.claude.input.image",
  "content": {
    "session_id": "sess_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "mxc_uri": "mxc://matrix.openearth.network/image123",
    "media_type": "image/png",
    "filename": "screenshot.png",
    "width": 1920,
    "height": 1080,
    "size_bytes": 204800,
    "description": "Screenshot of the error in the browser console",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$prompt_event_id" }
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.input.document

A user-provided document (PDF, text file, etc.) sent as context.

Field	Type	Description
session_id	string	Session identifier
prompt_id	string	Associated prompt
mxc_uri	string	MXC URI of the uploaded document
media_type	string	MIME type (e.g., `application/pdf`)
filename	string	Original filename
size_bytes	integer	File size in bytes
page_count	integer	Number of pages (if applicable)
description	string	Human-readable description

{
  "type": "foundation.protocols.ai.claude.input.document",
  "content": {
    "session_id": "sess_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "mxc_uri": "mxc://matrix.openearth.network/doc123",
    "media_type": "application/pdf",
    "filename": "architecture.pdf",
    "size_bytes": 512000,
    "page_count": 12,
    "description": "System architecture document",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$prompt_event_id" }
    }
  }
}

4. Tool Use (Built-in Tools)

3 events for built-in tool calls (bash, read_file, write_file, web_search), results, and errors.

Timeline Event

foundation.protocols.ai.claude.tool.call

Claude invoking a built-in tool (bash, read_file, write_file, web_search, etc.).

Field	Type	Description
session_id	string	Session identifier
tool_use_id	string	Unique tool use identifier
prompt_id	string	Associated prompt
tool_name	string	Name of the tool (e.g., `bash`)
tool_source	string	Source: `builtin`
input	object	Tool input parameters
requires_approval	boolean	Whether human approval was required

{
  "type": "foundation.protocols.ai.claude.tool.call",
  "content": {
    "session_id": "sess_01ABC...",
    "tool_use_id": "toolu_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "tool_name": "bash",
    "tool_source": "builtin",
    "input": {
      "command": "cat src/auth/auth.ts"
    },
    "requires_approval": false,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$response_event_id" }
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.tool.result

The result returned to Claude from a built-in tool call.

Field	Type	Description
session_id	string	Session identifier
tool_use_id	string	Links to the tool call
tool_name	string	Tool name
tool_source	string	Source: `builtin`
output	string	Tool output text
exit_code	integer	Process exit code (for bash)
is_error	boolean	Whether the result indicates an error
duration_ms	integer	Execution duration in milliseconds

{
  "type": "foundation.protocols.ai.claude.tool.result",
  "content": {
    "session_id": "sess_01ABC...",
    "tool_use_id": "toolu_01ABC...",
    "tool_name": "bash",
    "tool_source": "builtin",
    "output": "import jwt from 'jsonwebtoken';\n...",
    "exit_code": 0,
    "is_error": false,
    "duration_ms": 42,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$tool_call_event_id" }
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.tool.error

A tool call that failed with an error (distinct from a tool result with is_error: true).

Field	Type	Description
session_id	string	Session identifier
tool_use_id	string	Links to the tool call
tool_name	string	Tool name
tool_source	string	Source: `builtin`
error_type	string	Error classification
Values: `timeout`, `permission_denied`, `not_found`, `execution_error`, `serialization_error`, `network_error`
error_message	string	Human-readable error message
exit_code	integer	Process exit code
duration_ms	integer	Time until failure in milliseconds

{
  "type": "foundation.protocols.ai.claude.tool.error",
  "content": {
    "session_id": "sess_01ABC...",
    "tool_use_id": "toolu_01ABC...",
    "tool_name": "bash",
    "tool_source": "builtin",
    "error_type": "timeout",
    "error_message": "Command timed out after 30000ms",
    "exit_code": 124,
    "duration_ms": 30000,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$tool_call_event_id" }
    }
  }
}

5. MCP (Model Context Protocol) Interactions

5 events for MCP server connections, tool calls, results, prompt templates, and resource reads.

Timeline Event

foundation.protocols.ai.claude.mcp.server.connected

An MCP server was connected to the session. Lists available tools, resources, and prompts.

Field	Type	Description
session_id	string	Session identifier
server_name	string	MCP server name
server_url	string	MCP server URL
tools_available	string[]	Tools provided by this server
resources_available	string[]	Resources provided by this server
prompts_available	string[]	Prompt templates provided
protocol_version	string	MCP protocol version

{
  "type": "foundation.protocols.ai.claude.mcp.server.connected",
  "content": {
    "session_id": "sess_01ABC...",
    "server_name": "github",
    "server_url": "https://mcp.github.com/sse",
    "tools_available": ["create_issue", "list_prs", "get_file"],
    "resources_available": ["repo://owner/repo/main"],
    "prompts_available": ["summarize_pr"],
    "protocol_version": "2024-11-05",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.mcp.tool.call

A tool call made specifically to an MCP server.

Field	Type	Description
session_id	string	Session identifier
tool_use_id	string	Unique tool use identifier
prompt_id	string	Associated prompt
mcp_server	string	MCP server name
tool_name	string	Tool being invoked
input	object	Tool input parameters
requires_approval	boolean	Whether human approval was required

{
  "type": "foundation.protocols.ai.claude.mcp.tool.call",
  "content": {
    "session_id": "sess_01ABC...",
    "tool_use_id": "toolu_mcp_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "mcp_server": "github",
    "tool_name": "create_issue",
    "input": {
      "owner": "openearth",
      "repo": "auth-service",
      "title": "Refactor auth to JWT",
      "body": "As discussed, migrating from session-based to JWT auth."
    },
    "requires_approval": false,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$response_event_id" }
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.mcp.tool.result

Result returned from an MCP server tool call.

Field	Type	Description
session_id	string	Session identifier
tool_use_id	string	Links to the MCP tool call
mcp_server	string	MCP server name
tool_name	string	Tool that was invoked
output	object	Tool output data
is_error	boolean	Whether the result indicates an error
duration_ms	integer	Execution duration in milliseconds

{
  "type": "foundation.protocols.ai.claude.mcp.tool.result",
  "content": {
    "session_id": "sess_01ABC...",
    "tool_use_id": "toolu_mcp_01ABC...",
    "mcp_server": "github",
    "tool_name": "create_issue",
    "output": {
      "issue_number": 42,
      "url": "https://github.com/openearth/auth-service/issues/42"
    },
    "is_error": false,
    "duration_ms": 380,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$mcp_tool_call_event_id" }
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.mcp.prompt.used

An MCP-provided prompt template was invoked.

Field	Type	Description
session_id	string	Session identifier
mcp_server	string	MCP server name
prompt_name	string	Prompt template name
arguments	object	Arguments passed to the template

{
  "type": "foundation.protocols.ai.claude.mcp.prompt.used",
  "content": {
    "session_id": "sess_01ABC...",
    "mcp_server": "github",
    "prompt_name": "summarize_pr",
    "arguments": {
      "pr_number": 17
    },
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.mcp.resource.read

An MCP resource was read by Claude.

Field	Type	Description
session_id	string	Session identifier
mcp_server	string	MCP server name
resource_uri	string	Resource URI
resource_type	string	MIME type of the resource
size_bytes	integer	Resource size in bytes

{
  "type": "foundation.protocols.ai.claude.mcp.resource.read",
  "content": {
    "session_id": "sess_01ABC...",
    "mcp_server": "github",
    "resource_uri": "repo://openearth/auth-service/main",
    "resource_type": "text/plain",
    "size_bytes": 8192,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

6. Human-in-the-Loop Approval

2 events for requesting and receiving human approval for sensitive operations.

Timeline Event

foundation.protocols.ai.claude.approval.request

The bridge requests a human to approve a sensitive action before execution.

Field	Type	Description
session_id	string	Session identifier
tool_use_id	string	Tool call awaiting approval
tool_name	string	Tool name
tool_source	string	Source: `builtin` or MCP server name
input	object	Tool input to be approved
risk_level	string	Risk classification
Values: `low`, `medium`, `high`, `critical`
description	string	Human-readable description of the action
timeout_ms	integer	Approval timeout in milliseconds

{
  "type": "foundation.protocols.ai.claude.approval.request",
  "content": {
    "session_id": "sess_01ABC...",
    "tool_use_id": "toolu_01ABC...",
    "tool_name": "bash",
    "tool_source": "builtin",
    "input": {
      "command": "rm -rf dist/"
    },
    "risk_level": "high",
    "description": "Claude wants to delete the dist directory",
    "timeout_ms": 60000,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.approval.response

A room member approves or denies the requested action.

Field	Type	Description
session_id	string	Session identifier
tool_use_id	string	Links to the approval request
decision	string	The decision made
Values: `approved`, `denied`, `timed_out`
decided_by	string	Matrix user ID of the decider
note	string	Optional note from the decider
timestamp	integer	Unix millisecond timestamp

{
  "type": "foundation.protocols.ai.claude.approval.response",
  "content": {
    "session_id": "sess_01ABC...",
    "tool_use_id": "toolu_01ABC...",
    "decision": "approved",
    "decided_by": "@user:matrix.openearth.network",
    "note": "OK to delete, this is a clean build step",
    "timestamp": 1711800030000,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$approval_request_event_id" }
    }
  }
}

7. File Change Tracking

1 event recording file mutations made by Claude during a session.

Timeline Event

foundation.protocols.ai.claude.file.change

Records a file mutation made by Claude during a session. Includes before/after hashes and diff.

Field	Type	Description
session_id	string	Session identifier
tool_use_id	string	Tool call that caused the change
change_type	string	Type of file change
Values: `created`, `modified`, `deleted`, `renamed`, `moved`
path	string	File path relative to project root
before_hash	string	SHA-256 hash before change
after_hash	string	SHA-256 hash after change
lines_added	integer	Lines added
lines_removed	integer	Lines removed
diff_mxc_uri	string	MXC URI of the patch file

{
  "type": "foundation.protocols.ai.claude.file.change",
  "content": {
    "session_id": "sess_01ABC...",
    "tool_use_id": "toolu_01ABC...",
    "change_type": "modified",
    "path": "src/auth/auth.ts",
    "before_hash": "sha256:abc123...",
    "after_hash": "sha256:789xyz...",
    "lines_added": 42,
    "lines_removed": 18,
    "diff_mxc_uri": "mxc://matrix.openearth.network/patchfile123",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$tool_call_event_id" }
    }
  }
}

8. Git Operations

3 events for commits, branch operations, and diff viewing.

Timeline Event

foundation.protocols.ai.claude.git.commit

Claude authored or staged a git commit.

Field	Type	Description
session_id	string	Session identifier
commit_hash	string	Git commit hash
branch	string	Branch name
message	string	Commit message
files_changed	string[]	Files included in the commit
insertions	integer	Lines inserted
deletions	integer	Lines deleted
authored_by	string	Author attribution

{
  "type": "foundation.protocols.ai.claude.git.commit",
  "content": {
    "session_id": "sess_01ABC...",
    "commit_hash": "a1b2c3d4...",
    "branch": "feature/jwt-auth",
    "message": "refactor: migrate auth module to JWT",
    "files_changed": ["src/auth/auth.ts", "src/auth/middleware.ts"],
    "insertions": 84,
    "deletions": 36,
    "authored_by": "Claude (claude-sonnet-4-20250514)",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.git.branch

Claude created, switched, deleted, or merged a branch.

Field	Type	Description
session_id	string	Session identifier
action	string	Branch action
Values: `created`, `switched`, `deleted`, `merged`
branch_name	string	Target branch name
from_branch	string	Source branch (for create/switch)
from_commit	string	Source commit hash

{
  "type": "foundation.protocols.ai.claude.git.branch",
  "content": {
    "session_id": "sess_01ABC...",
    "action": "created",
    "branch_name": "feature/jwt-auth",
    "from_branch": "main",
    "from_commit": "a1b2c3d4...",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.git.diff.viewed

Claude read a git diff as context.

Field	Type	Description
session_id	string	Session identifier
diff_type	string	Type of diff viewed
Values: `staged`, `unstaged`, `commit`, `branch_compare`
files_in_diff	string[]	Files included in the diff
lines_added	integer	Total lines added
lines_removed	integer	Total lines removed

{
  "type": "foundation.protocols.ai.claude.git.diff.viewed",
  "content": {
    "session_id": "sess_01ABC...",
    "diff_type": "staged",
    "files_in_diff": ["src/auth/auth.ts"],
    "lines_added": 42,
    "lines_removed": 18,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

9. Context Management

3 events for context window truncation, summarization, and overflow.

Timeline Event

foundation.protocols.ai.claude.context.truncated

The context window was trimmed to fit within limits.

Field	Type	Description
session_id	string	Session identifier
tokens_before	integer	Token count before truncation
tokens_after	integer	Token count after truncation
tokens_dropped	integer	Tokens removed
strategy	string	Truncation strategy used
turns_dropped	integer	Number of turns removed

{
  "type": "foundation.protocols.ai.claude.context.truncated",
  "content": {
    "session_id": "sess_01ABC...",
    "tokens_before": 198000,
    "tokens_after": 160000,
    "tokens_dropped": 38000,
    "strategy": "drop_oldest_turns",
    "turns_dropped": 3,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.context.summarized

Prior conversation was summarized to compress context.

Field	Type	Description
session_id	string	Session identifier
tokens_before	integer	Token count before summarization
tokens_after	integer	Token count after summarization
summary_text	string	The generated summary
turns_summarized	integer	Number of turns summarized

{
  "type": "foundation.protocols.ai.claude.context.summarized",
  "content": {
    "session_id": "sess_01ABC...",
    "tokens_before": 198000,
    "tokens_after": 12000,
    "summary_text": "The user is refactoring the auth module to use JWT. So far, Claude has read auth.ts and middleware.ts and is in the process of rewriting auth.ts.",
    "turns_summarized": 8,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.context.overflow

Context window hard limit was exceeded and session cannot continue without intervention.

Field	Type	Description
session_id	string	Session identifier
token_count	integer	Current token count
token_limit	integer	Maximum token limit

{
  "type": "foundation.protocols.ai.claude.context.overflow",
  "content": {
    "session_id": "sess_01ABC...",
    "token_count": 200001,
    "token_limit": 200000,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

10. Memory

2 events for reading and writing CLAUDE.md / memory files.

Timeline Event

foundation.protocols.ai.claude.memory.read

Claude read from a memory or notes file (e.g., CLAUDE.md).

Field	Type	Description
session_id	string	Session identifier
file_path	string	Path of the memory file
scope	string	Memory scope
Values: `project`, `user`, `global`
content_hash	string	SHA-256 hash of file contents
size_bytes	integer	File size in bytes

{
  "type": "foundation.protocols.ai.claude.memory.read",
  "content": {
    "session_id": "sess_01ABC...",
    "file_path": "CLAUDE.md",
    "scope": "project",
    "content_hash": "sha256:mem123...",
    "size_bytes": 2048,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.memory.write

Claude wrote to a memory or notes file.

Field	Type	Description
session_id	string	Session identifier
file_path	string	Path of the memory file
scope	string	Memory scope
Values: `project`, `user`, `global`
before_hash	string	SHA-256 hash before write
after_hash	string	SHA-256 hash after write
diff_mxc_uri	string	MXC URI of the diff

{
  "type": "foundation.protocols.ai.claude.memory.write",
  "content": {
    "session_id": "sess_01ABC...",
    "file_path": "CLAUDE.md",
    "scope": "project",
    "before_hash": "sha256:mem123...",
    "after_hash": "sha256:mem456...",
    "diff_mxc_uri": "mxc://matrix.openearth.network/memdiff123",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

11. Multi-Agent Interactions

3 events for sub-agent spawning, results, and handoffs.

Timeline Event

foundation.protocols.ai.claude.agent.spawn

A parent agent spawning a sub-agent task.

Field	Type	Description
parent_session_id	string	Parent session identifier
child_session_id	string	Sub-agent session identifier
task	string	Task description for the sub-agent
model	string	Model used by the sub-agent
tools_enabled	string[]	Tools available to the sub-agent
max_tokens	integer	Max output tokens for the sub-agent
child_room_id	string	Matrix room ID for the sub-agent (optional)

{
  "type": "foundation.protocols.ai.claude.agent.spawn",
  "content": {
    "parent_session_id": "sess_01ABC...",
    "child_session_id": "sess_02DEF...",
    "task": "Run the full test suite and return a summary of failures",
    "model": "claude-sonnet-4-20250514",
    "tools_enabled": ["bash"],
    "max_tokens": 4096,
    "child_room_id": "!childroom:matrix.openearth.network",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$parent_session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.agent.result

A sub-agent returning its result to the parent agent.

Field	Type	Description
parent_session_id	string	Parent session identifier
child_session_id	string	Sub-agent session identifier
result	string	Result text from the sub-agent
status	string	Sub-agent completion status
Values: `success`, `failure`, `timeout`, `interrupted`
input_tokens	integer	Input tokens consumed by sub-agent
output_tokens	integer	Output tokens generated by sub-agent
duration_ms	integer	Sub-agent execution duration

{
  "type": "foundation.protocols.ai.claude.agent.result",
  "content": {
    "parent_session_id": "sess_01ABC...",
    "child_session_id": "sess_02DEF...",
    "result": "Test suite completed. 3 failures found in auth.test.ts: ...",
    "status": "success",
    "input_tokens": 3200,
    "output_tokens": 640,
    "duration_ms": 18400,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$parent_session_start_event_id",
      "m.in_reply_to": { "event_id": "$agent_spawn_event_id" }
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.agent.handoff

Control is transferred between agents.

Field	Type	Description
from_session_id	string	Source agent session
to_session_id	string	Target agent session
reason	string	Reason for handoff
context_summary	string	Summary of work done so far

{
  "type": "foundation.protocols.ai.claude.agent.handoff",
  "content": {
    "from_session_id": "sess_01ABC...",
    "to_session_id": "sess_03GHI...",
    "reason": "Delegating test fixing to specialist agent",
    "context_summary": "Auth module refactored. 3 test failures remain in auth.test.ts.",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

12. Errors & Safety

2 events for API errors and safety-blocked requests.

Timeline Event

foundation.protocols.ai.claude.error

A general error occurred during the session (API error, rate limit, timeout, etc.).

Field	Type	Description
session_id	string	Session identifier
error_type	string	Error classification
Values: `api_error`, `rate_limit`, `timeout`, `network_failure`, `authentication_error`, `invalid_request`
error_code	string	API error code
error_message	string	Human-readable error message
http_status	integer	HTTP status code
retryable	boolean	Whether the operation can be retried
retry_after_ms	integer	Suggested retry delay in milliseconds

{
  "type": "foundation.protocols.ai.claude.error",
  "content": {
    "session_id": "sess_01ABC...",
    "error_type": "api_error",
    "error_code": "overloaded_error",
    "error_message": "The API is temporarily overloaded",
    "http_status": 529,
    "retryable": true,
    "retry_after_ms": 5000,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.safety.blocked

A request was blocked by Claude’s safety systems.

Field	Type	Description
session_id	string	Session identifier
prompt_id	string	Prompt that was blocked
block_reason	string	Reason for blocking
Values: `policy_violation`, `content_filter`, `rate_limit`, `permissions`
category	string	Safety category (e.g., `harmful_content`)

{
  "type": "foundation.protocols.ai.claude.safety.blocked",
  "content": {
    "session_id": "sess_01ABC...",
    "prompt_id": "prm_01XYZ...",
    "block_reason": "policy_violation",
    "category": "harmful_content",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id",
      "m.in_reply_to": { "event_id": "$prompt_event_id" }
    }
  }
}

13. Configuration

2 events for mid-session changes to model, tools, and permissions.

Timeline Event

foundation.protocols.ai.claude.config.change

Model, tools, or system prompt changed mid-session.

Field	Type	Description
session_id	string	Session identifier
changed_by	string	Matrix user ID who made the change
changes	object	Map of changed fields with `before`/`after` values

{
  "type": "foundation.protocols.ai.claude.config.change",
  "content": {
    "session_id": "sess_01ABC...",
    "changed_by": "@user:matrix.openearth.network",
    "changes": {
      "model": {
        "before": "claude-haiku-4-5-20251001",
        "after": "claude-sonnet-4-20250514"
      },
      "tools_enabled": {
        "before": ["bash"],
        "after": ["bash", "web_search"]
      }
    },
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.permission.change

Tool permissions or approval requirements changed during a session.

Field	Type	Description
session_id	string	Session identifier
changed_by	string	Matrix user ID who made the change
changes	object	Map of changed permissions with `before`/`after` values

{
  "type": "foundation.protocols.ai.claude.permission.change",
  "content": {
    "session_id": "sess_01ABC...",
    "changed_by": "@user:matrix.openearth.network",
    "changes": {
      "approval_required_for": {
        "before": ["bash", "write_file"],
        "after": ["write_file"]
      }
    },
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

14. Cost & Usage Metering

2 events for periodic cost checkpoints and limit enforcement. All cost values use string encoding per Matrix canonical JSON.

Timeline Event

foundation.protocols.ai.claude.usage.checkpoint

Periodic token and cost snapshot during long-running sessions.

Field	Type	Description
session_id	string	Session identifier
checkpoint_index	integer	Sequential checkpoint number
cumulative_input_tokens	integer	Total input tokens so far
cumulative_output_tokens	integer	Total output tokens so far
cumulative_cache_read_tokens	integer	Total cache-read tokens
cumulativeCost	string	Total cost as decimal string
currency	string	ISO 4217 currency code
timestamp	integer	Unix millisecond timestamp

{
  "type": "foundation.protocols.ai.claude.usage.checkpoint",
  "content": {
    "session_id": "sess_01ABC...",
    "checkpoint_index": 3,
    "cumulative_input_tokens": 48000,
    "cumulative_output_tokens": 9600,
    "cumulative_cache_read_tokens": 12000,
    "cumulativeCost": "0.087000",
    "currency": "USD",
    "timestamp": 1711810000000,
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

Timeline Event

foundation.protocols.ai.claude.cost.limit.reached

Session halted because a configured cost or token limit was reached.

Field	Type	Description
session_id	string	Session identifier
limit_type	string	Type of limit exceeded
Values: `cost`, `input_tokens`, `output_tokens`, `total_tokens`
limitValue	string	Configured limit as decimal string
actualValue	string	Actual value that exceeded the limit
currency	string	ISO 4217 currency code
action_taken	string	Action taken by the system
Values: `session_paused`, `session_terminated`, `warning_only`

{
  "type": "foundation.protocols.ai.claude.cost.limit.reached",
  "content": {
    "session_id": "sess_01ABC...",
    "limit_type": "cost",
    "limitValue": "1.000000",
    "actualValue": "1.003000",
    "currency": "USD",
    "action_taken": "session_paused",
    "m.relates_to": {
      "rel_type": "m.thread",
      "event_id": "$session_start_event_id"
    }
  }
}

15. State Events (Room / Space Level)

2 state events stored as persistent room state. project configures the room; session.active tracks the current session.

State Event

foundation.protocols.ai.claude.project

Associates a room or Space with a Claude Code project. Configures defaults, cost limits, and allowed operators.

Field	Type	Description
name	string	Project name
repository_url	string	Git repository URL
default_model	string	Default model for sessions
default_tools	string[]	Default enabled tools
approval_required_for	string[]	Tools requiring approval
allowed_operators	string[]	Matrix user IDs allowed to run sessions
costLimit	string	Cost limit per session as decimal string
currency	string	ISO 4217 currency code
mcp_servers	string[]	Available MCP servers

{
  "type": "foundation.protocols.ai.claude.project",
  "state_key": "",
  "content": {
    "name": "Auth Service Refactor",
    "repository_url": "https://github.com/openearth/auth-service",
    "default_model": "claude-sonnet-4-20250514",
    "default_tools": ["bash", "read_file", "write_file"],
    "approval_required_for": ["bash", "write_file"],
    "allowed_operators": ["@alice:matrix.openearth.network", "@bob:matrix.openearth.network"],
    "costLimit": "2.000000",
    "currency": "USD",
    "mcp_servers": ["github", "postgres"]
  }
}

State Event

foundation.protocols.ai.claude.session.active

Tracks the currently active session in a room. See Session Lifecycle for full schema.

Field	Type	Description
session_id	string	Active session identifier
started_at	integer	Unix millisecond start time
started_by	string	Matrix user ID
model	string	Model identifier
status	string	Current session status
Values: `running`, `paused`, `idle`, `terminated`

{
  "type": "foundation.protocols.ai.claude.session.active",
  "state_key": "",
  "content": {
    "session_id": "sess_01ABC...",
    "started_at": 1711800000000,
    "started_by": "@user:matrix.openearth.network",
    "model": "claude-sonnet-4-20250514",
    "status": "running"
  }
}

Implementation Status

25 of 42 events are implemented in the openearth-ai-bridge and tested on 3 homeservers (Synapse, Conduit, continuwuity). 17 events require the OpenEarth Messenger for interactive UI.

Event Type	Category	Matrix Type	Status
`session.start`	Session	Timeline	Tier 1
`session.end`	Session	Timeline	Tier 1
`session.interrupted`	Session	Timeline	--
`session.exported`	Session	Timeline	--
`session.replayed`	Session	Timeline	--
`session.active`	Session	State	--
`prompt`	Prompt/Response	Timeline	Tier 1
`response`	Prompt/Response	Timeline	Tier 1
`response.chunk`	Prompt/Response	Timeline	--
`response.interrupted`	Prompt/Response	Timeline	Tier 2
`thinking`	Prompt/Response	Timeline	--
`input.image`	Multimodal	Timeline	Tier 2
`input.document`	Multimodal	Timeline	Tier 2
`tool.call`	Tool Use	Timeline	Tier 1
`tool.result`	Tool Use	Timeline	Tier 1
`tool.error`	Tool Use	Timeline	Tier 1
`mcp.server.connected`	MCP	Timeline	--
`mcp.tool.call`	MCP	Timeline	--
`mcp.tool.result`	MCP	Timeline	--
`mcp.prompt.used`	MCP	Timeline	--
`mcp.resource.read`	MCP	Timeline	--
`approval.request`	Approval	Timeline	Tier 1
`approval.response`	Approval	Timeline	Tier 1
`file.change`	File	Timeline	Tier 2
`git.commit`	Git	Timeline	Tier 2
`git.branch`	Git	Timeline	Tier 2
`git.diff.viewed`	Git	Timeline	Tier 2
`context.truncated`	Context	Timeline	Tier 2
`context.summarized`	Context	Timeline	--
`context.overflow`	Context	Timeline	--
`memory.read`	Memory	Timeline	Tier 2
`memory.write`	Memory	Timeline	Tier 2
`agent.spawn`	Multi-Agent	Timeline	Tier 2
`agent.result`	Multi-Agent	Timeline	Tier 2
`agent.handoff`	Multi-Agent	Timeline	--
`error`	Error	Timeline	Tier 2
`safety.blocked`	Error	Timeline	Tier 2
`config.change`	Config	Timeline	--
`permission.change`	Config	Timeline	--
`usage.checkpoint`	Metering	Timeline	Tier 1
`cost.limit.reached`	Metering	Timeline	Tier 2
`project`	Project	State	--

Family	Relationship
ai.*	Vendor-neutral governance layer. Claude sessions operate within `ai.policy` constraints and can be wrapped in `ai.intention → ai.decision → ai.effect` flows.
ai.cost	Vendor-agnostic cost accumulator. Updated from `usage.checkpoint` and `session.end` events.
data.*	Data consent gates what information reaches Claude. `ai.data_boundary` enforces data types.
eudr.*	EUDR workflow events can trigger Claude sessions for deforestation analysis and DDS generation.
legal.*	Open Law sessions use Claude with MCP law servers; `ai.policy` restricts tool access.

Contents

Design Notes

1. Session Lifecycle

foundation.protocols.ai.claude.session.start

foundation.protocols.ai.claude.session.end

foundation.protocols.ai.claude.session.interrupted

foundation.protocols.ai.claude.session.exported

foundation.protocols.ai.claude.session.replayed

foundation.protocols.ai.claude.session.active

2. Prompt & Response

foundation.protocols.ai.claude.prompt

foundation.protocols.ai.claude.response

foundation.protocols.ai.claude.response.chunk

foundation.protocols.ai.claude.response.interrupted

foundation.protocols.ai.claude.thinking

3. Multimodal Input

foundation.protocols.ai.claude.input.image

foundation.protocols.ai.claude.input.document

4. Tool Use (Built-in Tools)

foundation.protocols.ai.claude.tool.call

foundation.protocols.ai.claude.tool.result

foundation.protocols.ai.claude.tool.error

5. MCP (Model Context Protocol) Interactions

foundation.protocols.ai.claude.mcp.server.connected

foundation.protocols.ai.claude.mcp.tool.call

foundation.protocols.ai.claude.mcp.tool.result

foundation.protocols.ai.claude.mcp.prompt.used

foundation.protocols.ai.claude.mcp.resource.read

6. Human-in-the-Loop Approval

foundation.protocols.ai.claude.approval.request

foundation.protocols.ai.claude.approval.response

7. File Change Tracking

foundation.protocols.ai.claude.file.change

8. Git Operations

foundation.protocols.ai.claude.git.commit

foundation.protocols.ai.claude.git.branch

foundation.protocols.ai.claude.git.diff.viewed

9. Context Management

foundation.protocols.ai.claude.context.truncated

foundation.protocols.ai.claude.context.summarized

foundation.protocols.ai.claude.context.overflow

10. Memory

foundation.protocols.ai.claude.memory.read

foundation.protocols.ai.claude.memory.write

11. Multi-Agent Interactions

foundation.protocols.ai.claude.agent.spawn

foundation.protocols.ai.claude.agent.result

foundation.protocols.ai.claude.agent.handoff

12. Errors & Safety

foundation.protocols.ai.claude.error

foundation.protocols.ai.claude.safety.blocked

13. Configuration

foundation.protocols.ai.claude.config.change

foundation.protocols.ai.claude.permission.change

14. Cost & Usage Metering

foundation.protocols.ai.claude.usage.checkpoint

foundation.protocols.ai.claude.cost.limit.reached

15. State Events (Room / Space Level)

foundation.protocols.ai.claude.project

foundation.protocols.ai.claude.session.active

Event Relationship Graph

Implementation Status

Related Event Families