## 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": {}
}
```

| Field       | Type   | Required | Description                                                                 |
|-------------|--------|----------|-----------------------------------------------------------------------------|
| `hook_type` | string | Yes      | `session_start`, `session_end`, `user_prompt_submit`, `stop`, `pre_tool_use`, `post_tool_use` |
| `session_id` | string | Yes      | Agent session identifier                                                    |
| `session_ref` | string | Yes      | Agent-specific session reference (typically a file path)                  |
| `timestamp` | string | Yes      | RFC 3339 timestamp                                                         |
| `user_prompt` | string | No       | User’s prompt text                                                         |
| `tool_name` | string | No       | Tool name (from tool use hooks)                                           |
| `tool_use_id` | string | No       | Tool invocation ID                                                         |
| `tool_input` | object | No       | Raw tool input JSON                                                        |
| `raw_data`   | object | No       | Agent-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": []
}
```

| Field          | Type          | Description                                                                  |
|----------------|---------------|------------------------------------------------------------------------------|
| `session_id`   | string        | Agent session identifier                                                     |
| `agent_name`   | string        | Agent registry name                                                         |
| `repo_path`    | string        | Absolute path to the repository                                             |
| `session_ref`  | string        | Path to session in agent’s storage                                         |
| `start_time`   | string        | RFC 3339 timestamp                                                          |
| `native_data`  | bytes/null    | Opaque session content in agent’s native format                             |
| `modified_files` | string[]     | Files modified during the session                                           |
| `new_files`    | string[]      | Files created during the session                                            |
| `deleted_files` | string[]      | 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:**

| Value | Name             | Description                                                            |
|-------|-----------------|------------------------------------------------------------------------|
| 1     | SessionStart     | Agent session has begun                                               |
| 2     | TurnStart        | User submitted a prompt                                              |
| 3     | TurnEnd          | Agent finished responding                                            |
| 4     | Compaction       | Context window compression (triggers save + offset reset)          |
| 5     | SessionEnd       | Session terminated                                                   |
| 6     | SubagentStart    | A subagent was spawned                                              |
| 7     | SubagentEnd      | A 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.