Skip to main content

​
HookInput

Passed via stdin to get-session-id and read-session. 
{
  "hook_type": "stop",
  "session_id": "abc123",
  "session_ref": "/path/to/transcript.jsonl",
  "timestamp": "2026-01-13T12:00:00Z",
  "user_prompt": "Fix the login bug",
  "tool_name": "Write",
  "tool_use_id": "toolu_abc123",
  "tool_input": {"path": "/src/main.go"},
  "raw_data": {}
}
FieldTypeRequiredDescription
hook_typestringYessession_start, session_end, user_prompt_submit, stop, pre_tool_use, post_tool_use
session_idstringYesAgent session identifier
session_refstringYesAgent-specific session reference (typically a file path)
timestampstringYesRFC 3339 timestamp
user_promptstringNoUser’s prompt text
tool_namestringNoTool name (from tool use hooks)
tool_use_idstringNoTool invocation ID
tool_inputobjectNoRaw tool input JSON
raw_dataobjectNoAgent-specific extension data

​
AgentSession

Used as input to write-session and output from read-session. 
{
  "session_id": "abc123",
  "agent_name": "myagent",
  "repo_path": "/path/to/repo",
  "session_ref": "/path/to/transcript.jsonl",
  "start_time": "2026-01-13T12:00:00Z",
  "native_data": null,
  "modified_files": ["src/main.go"],
  "new_files": [],
  "deleted_files": []
}
FieldTypeDescription
session_idstringAgent session identifier
agent_namestringAgent registry name
repo_pathstringAbsolute path to the repository
session_refstringPath to session in agent’s storage
start_timestringRFC 3339 timestamp
native_databytes/nullOpaque session content in agent’s native format
modified_filesstring[]Files modified during the session
new_filesstring[]Files created during the session
deleted_filesstring[]Files deleted during the session

​
Event

Returned by parse-hook. Represents a normalized lifecycle event. 
{
  "type": 3,
  "session_id": "abc123",
  "session_ref": "/path/to/transcript.jsonl",
  "prompt": "Fix the login bug",
  "model": "claude-sonnet-4-20250514",
  "timestamp": "2026-01-13T12:00:00Z"
}
Event types:
ValueNameDescription
1SessionStartAgent session has begun
2TurnStartUser submitted a prompt
3TurnEndAgent finished responding
4CompactionContext window compression (triggers save + offset reset)
5SessionEndSession terminated
6SubagentStartA subagent was spawned
7SubagentEndA subagent completed
Optional event fields: previous_session_id, session_ref, prompt, model, timestamp, tool_use_id, subagent_id, tool_input, subagent_type, task_description, response_message, metadata. Only type and session_id are required.