# Wire Protocol

> Generated by `scripts/gen_protocol_doc.py`. **Do not edit manually.**

## Transport

- TCP loopback `127.0.0.1:7437` (override via `KAMA_HOST` / `KAMA_PORT`)
- Each message is one `\n`-terminated JSON line (NDJSON)
- Commands use JSON-RPC 2.0 (client → server); Events use `kind=event` envelope (server → client)

## Commands

All commands are sent as JSON-RPC 2.0 requests. The `type` field inside `params` is used for routing.

### PingCommand

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `client` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "core.ping",
      "default": "core.ping",
      "title": "Type",
      "type": "string"
    },
    "client": {
      "title": "Client",
      "type": "string"
    }
  },
  "required": [
    "client"
  ],
  "title": "PingCommand",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-1",
  "method": "core.ping",
  "params": {
    "client": "cli/0.0.1"
  }
}
```

### PongResult

| Field | Type | Required |
|---|---|---|
| `server_version` | `string` | yes |
| `uptime_ms` | `integer` | yes |
| `received_at` | `string` | yes |

```json
{
  "properties": {
    "server_version": {
      "title": "Server Version",
      "type": "string"
    },
    "uptime_ms": {
      "title": "Uptime Ms",
      "type": "integer"
    },
    "received_at": {
      "title": "Received At",
      "type": "string"
    }
  },
  "required": [
    "server_version",
    "uptime_ms",
    "received_at"
  ],
  "title": "PongResult",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-1",
  "result": {
    "server_version": "0.2.0",
    "uptime_ms": 12,
    "received_at": "2026-05-16T10:00:00.001Z"
  }
}
```

### AgentRunCommand

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `goal` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "agent.run",
      "default": "agent.run",
      "title": "Type",
      "type": "string"
    },
    "goal": {
      "title": "Goal",
      "type": "string"
    }
  },
  "required": [
    "goal"
  ],
  "title": "AgentRunCommand",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-2",
  "method": "agent.run",
  "params": {
    "goal": "\u603b\u7ed3 README.md \u7684\u4e3b\u8981\u7ae0\u8282"
  }
}
```

### AgentRunResult

| Field | Type | Required |
|---|---|---|
| `run_id` | `string` | yes |

```json
{
  "properties": {
    "run_id": {
      "title": "Run Id",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "title": "AgentRunResult",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-2",
  "result": {
    "run_id": "20260516-100000-abc123"
  }
}
```

### EventSubscribeCommand

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `topics` | `array` | yes |
| `scope` | `string` | no |
| `replay_from_run` | `string | null` | no |

```json
{
  "properties": {
    "type": {
      "const": "event.subscribe",
      "default": "event.subscribe",
      "title": "Type",
      "type": "string"
    },
    "topics": {
      "items": {
        "type": "string"
      },
      "title": "Topics",
      "type": "array"
    },
    "scope": {
      "default": "global",
      "title": "Scope",
      "type": "string"
    },
    "replay_from_run": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Replay From Run"
    }
  },
  "required": [
    "topics"
  ],
  "title": "EventSubscribeCommand",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-3",
  "method": "event.subscribe",
  "params": {
    "topics": [
      "run.*",
      "step.*",
      "tool.*",
      "llm.token"
    ],
    "scope": "global",
    "replay_from_run": null
  }
}
```

### EventSubscribeResult

| Field | Type | Required |
|---|---|---|
| `subscription_id` | `string` | yes |
| `replayed_count` | `integer` | no |

```json
{
  "properties": {
    "subscription_id": {
      "title": "Subscription Id",
      "type": "string"
    },
    "replayed_count": {
      "default": 0,
      "title": "Replayed Count",
      "type": "integer"
    }
  },
  "required": [
    "subscription_id"
  ],
  "title": "EventSubscribeResult",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-3",
  "result": {
    "subscription_id": "sub-abc123",
    "replayed_count": 0
  }
}
```

### SessionCreateCommand

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `mode` | `string` | no |
| `title` | `string` | no |

```json
{
  "properties": {
    "type": {
      "const": "session.create",
      "default": "session.create",
      "title": "Type",
      "type": "string"
    },
    "mode": {
      "default": "chat",
      "enum": [
        "one_shot",
        "chat"
      ],
      "title": "Mode",
      "type": "string"
    },
    "title": {
      "default": "",
      "title": "Title",
      "type": "string"
    }
  },
  "title": "SessionCreateCommand",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-4",
  "method": "session.create",
  "params": {
    "mode": "chat",
    "title": ""
  }
}
```

### SessionCreateResult

| Field | Type | Required |
|---|---|---|
| `session_id` | `string` | yes |
| `status` | `string` | yes |

```json
{
  "properties": {
    "session_id": {
      "title": "Session Id",
      "type": "string"
    },
    "status": {
      "enum": [
        "active",
        "waiting_for_input",
        "closed"
      ],
      "title": "Status",
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "status"
  ],
  "title": "SessionCreateResult",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-4",
  "result": {
    "session_id": "sess-abc123def456",
    "status": "active"
  }
}
```

### SessionSendMessageCommand

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `session_id` | `string` | yes |
| `content` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "session.send_message",
      "default": "session.send_message",
      "title": "Type",
      "type": "string"
    },
    "session_id": {
      "title": "Session Id",
      "type": "string"
    },
    "content": {
      "title": "Content",
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "content"
  ],
  "title": "SessionSendMessageCommand",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-5",
  "method": "session.send_message",
  "params": {
    "session_id": "sess-abc123def456",
    "content": "\u603b\u7ed3 README.md"
  }
}
```

### SessionSendMessageResult

| Field | Type | Required |
|---|---|---|
| `run_id` | `string` | yes |

```json
{
  "properties": {
    "run_id": {
      "title": "Run Id",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "title": "SessionSendMessageResult",
  "type": "object"
}
```

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": "u-5",
  "result": {
    "run_id": "20260516-100000-abc123"
  }
}
```

### SessionGetHistoryCommand

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `session_id` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "session.get_history",
      "default": "session.get_history",
      "title": "Type",
      "type": "string"
    },
    "session_id": {
      "title": "Session Id",
      "type": "string"
    }
  },
  "required": [
    "session_id"
  ],
  "title": "SessionGetHistoryCommand",
  "type": "object"
}
```

### SessionGetHistoryResult

| Field | Type | Required |
|---|---|---|
| `messages` | `array` | yes |

```json
{
  "properties": {
    "messages": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Messages",
      "type": "array"
    }
  },
  "required": [
    "messages"
  ],
  "title": "SessionGetHistoryResult",
  "type": "object"
}
```

### SessionCloseCommand

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `session_id` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "session.close",
      "default": "session.close",
      "title": "Type",
      "type": "string"
    },
    "session_id": {
      "title": "Session Id",
      "type": "string"
    }
  },
  "required": [
    "session_id"
  ],
  "title": "SessionCloseCommand",
  "type": "object"
}
```

### SessionCloseResult

| Field | Type | Required |
|---|---|---|
| `status` | `string` | yes |

```json
{
  "properties": {
    "status": {
      "enum": [
        "active",
        "waiting_for_input",
        "closed"
      ],
      "title": "Status",
      "type": "string"
    }
  },
  "required": [
    "status"
  ],
  "title": "SessionCloseResult",
  "type": "object"
}
```

## Server Push

Events pushed from daemon to subscribed clients over the same TCP connection.

### EventPushEnvelope

| Field | Type | Required |
|---|---|---|
| `kind` | `string` | no |
| `event` | `object` | yes |

```json
{
  "properties": {
    "kind": {
      "const": "event",
      "default": "event",
      "title": "Kind",
      "type": "string"
    },
    "event": {
      "additionalProperties": true,
      "title": "Event",
      "type": "object"
    }
  },
  "required": [
    "event"
  ],
  "title": "EventPushEnvelope",
  "type": "object"
}
```

**Example:**

```json
{
  "kind": "event",
  "event": {
    "type": "step.started",
    "run_id": "20260516-100000-abc123",
    "step": 1,
    "ts": "2026-05-16T10:00:00.001Z"
  }
}
```

## IPC Events

Events sent over the IPC socket (daemon → client).

### CoreStartedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `listen_addr` | `string` | yes |
| `version` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "core.started",
      "default": "core.started",
      "title": "Type",
      "type": "string"
    },
    "listen_addr": {
      "title": "Listen Addr",
      "type": "string"
    },
    "version": {
      "title": "Version",
      "type": "string"
    }
  },
  "required": [
    "listen_addr",
    "version"
  ],
  "title": "CoreStartedEvent",
  "type": "object"
}
```

## Run Events

Events written to `runs/<run_id>/events.jsonl` and forwarded over IPC to subscribed clients.

### RunStartedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `goal` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "run.started",
      "default": "run.started",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "goal": {
      "title": "Goal",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "goal",
    "ts"
  ],
  "title": "RunStartedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "run.started",
  "run_id": "20260516-100000-abc123",
  "goal": "\u603b\u7ed3 README.md",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### RunFinishedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `status` | `string` | yes |
| `reason` | `string | null` | no |
| `steps` | `integer` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "run.finished",
      "default": "run.finished",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "status": {
      "title": "Status",
      "type": "string"
    },
    "reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Reason"
    },
    "steps": {
      "title": "Steps",
      "type": "integer"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "status",
    "steps",
    "ts"
  ],
  "title": "RunFinishedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "run.finished",
  "run_id": "20260516-100000-abc123",
  "status": "success",
  "reason": null,
  "steps": 2,
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### StepStartedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `step` | `integer` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "step.started",
      "default": "step.started",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "step": {
      "title": "Step",
      "type": "integer"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "step",
    "ts"
  ],
  "title": "StepStartedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "step.started",
  "run_id": "20260516-100000-abc123",
  "step": 1,
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### StepFinishedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `step` | `integer` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "step.finished",
      "default": "step.finished",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "step": {
      "title": "Step",
      "type": "integer"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "step",
    "ts"
  ],
  "title": "StepFinishedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "step.finished",
  "run_id": "20260516-100000-abc123",
  "step": 1,
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### ToolCallStartedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `tool_use_id` | `string` | yes |
| `tool_name` | `string` | yes |
| `params` | `object` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "tool.call_started",
      "default": "tool.call_started",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "tool_use_id": {
      "title": "Tool Use Id",
      "type": "string"
    },
    "tool_name": {
      "title": "Tool Name",
      "type": "string"
    },
    "params": {
      "additionalProperties": true,
      "title": "Params",
      "type": "object"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "tool_use_id",
    "tool_name",
    "params",
    "ts"
  ],
  "title": "ToolCallStartedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "tool.call_started",
  "run_id": "20260516-100000-abc123",
  "tool_use_id": "toolu_01",
  "tool_name": "read_file",
  "params": {
    "path": "README.md"
  },
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### ToolCallFinishedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `tool_use_id` | `string` | yes |
| `tool_name` | `string` | yes |
| `elapsed_ms` | `integer` | yes |
| `output` | `string` | no |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "tool.call_finished",
      "default": "tool.call_finished",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "tool_use_id": {
      "title": "Tool Use Id",
      "type": "string"
    },
    "tool_name": {
      "title": "Tool Name",
      "type": "string"
    },
    "elapsed_ms": {
      "title": "Elapsed Ms",
      "type": "integer"
    },
    "output": {
      "default": "",
      "title": "Output",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "tool_use_id",
    "tool_name",
    "elapsed_ms",
    "ts"
  ],
  "title": "ToolCallFinishedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "tool.call_finished",
  "run_id": "20260516-100000-abc123",
  "tool_use_id": "toolu_01",
  "tool_name": "read_file",
  "elapsed_ms": 3,
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### ToolCallFailedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `tool_use_id` | `string` | yes |
| `tool_name` | `string` | yes |
| `error_class` | `string` | yes |
| `error_message` | `string` | yes |
| `elapsed_ms` | `integer` | yes |
| `attempt` | `integer` | no |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "tool.call_failed",
      "default": "tool.call_failed",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "tool_use_id": {
      "title": "Tool Use Id",
      "type": "string"
    },
    "tool_name": {
      "title": "Tool Name",
      "type": "string"
    },
    "error_class": {
      "title": "Error Class",
      "type": "string"
    },
    "error_message": {
      "title": "Error Message",
      "type": "string"
    },
    "elapsed_ms": {
      "title": "Elapsed Ms",
      "type": "integer"
    },
    "attempt": {
      "default": 1,
      "title": "Attempt",
      "type": "integer"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "tool_use_id",
    "tool_name",
    "error_class",
    "error_message",
    "elapsed_ms",
    "ts"
  ],
  "title": "ToolCallFailedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "tool.call_failed",
  "run_id": "20260516-100000-abc123",
  "tool_use_id": "toolu_02",
  "tool_name": "read_file",
  "error_class": "runtime_error",
  "error_message": "file not found",
  "elapsed_ms": 1,
  "attempt": 1,
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### LlmModelSelectedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `model` | `string` | yes |
| `strategy` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "llm.model_selected",
      "default": "llm.model_selected",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "model": {
      "title": "Model",
      "type": "string"
    },
    "strategy": {
      "title": "Strategy",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "model",
    "strategy",
    "ts"
  ],
  "title": "LlmModelSelectedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "llm.model_selected",
  "run_id": "20260516-100000-abc123",
  "model": "claude-sonnet-4-6",
  "strategy": "static",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### LlmTokenEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `token` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "llm.token",
      "default": "llm.token",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "token": {
      "title": "Token",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "token",
    "ts"
  ],
  "title": "LlmTokenEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "llm.token",
  "run_id": "20260516-100000-abc123",
  "token": "The ",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### LlmUsageEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `input_tokens` | `integer` | yes |
| `output_tokens` | `integer` | yes |
| `cache_read_input_tokens` | `integer` | yes |
| `cache_creation_input_tokens` | `integer` | yes |
| `context_pct` | `number` | no |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "llm.usage",
      "default": "llm.usage",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "input_tokens": {
      "title": "Input Tokens",
      "type": "integer"
    },
    "output_tokens": {
      "title": "Output Tokens",
      "type": "integer"
    },
    "cache_read_input_tokens": {
      "title": "Cache Read Input Tokens",
      "type": "integer"
    },
    "cache_creation_input_tokens": {
      "title": "Cache Creation Input Tokens",
      "type": "integer"
    },
    "context_pct": {
      "default": 0.0,
      "title": "Context Pct",
      "type": "number"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "input_tokens",
    "output_tokens",
    "cache_read_input_tokens",
    "cache_creation_input_tokens",
    "ts"
  ],
  "title": "LlmUsageEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "llm.usage",
  "run_id": "20260516-100000-abc123",
  "input_tokens": 512,
  "output_tokens": 48,
  "cache_read_input_tokens": 490,
  "cache_creation_input_tokens": 0,
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### LogLineEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `run_id` | `string` | yes |
| `level` | `string` | yes |
| `source` | `string` | yes |
| `message` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "log.line",
      "default": "log.line",
      "title": "Type",
      "type": "string"
    },
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "level": {
      "title": "Level",
      "type": "string"
    },
    "source": {
      "title": "Source",
      "type": "string"
    },
    "message": {
      "title": "Message",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "level",
    "source",
    "message",
    "ts"
  ],
  "title": "LogLineEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "log.line",
  "run_id": "20260516-100000-abc123",
  "level": "INFO",
  "source": "kama_claude.core.loop",
  "message": "step 1 started",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

## Session Events

### SessionCreatedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `session_id` | `string` | yes |
| `mode` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "session.created",
      "default": "session.created",
      "title": "Type",
      "type": "string"
    },
    "session_id": {
      "title": "Session Id",
      "type": "string"
    },
    "mode": {
      "title": "Mode",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "mode",
    "ts"
  ],
  "title": "SessionCreatedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "session.created",
  "session_id": "sess-abc123def456",
  "mode": "chat",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### SessionMessageReceivedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `session_id` | `string` | yes |
| `content` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "session.message_received",
      "default": "session.message_received",
      "title": "Type",
      "type": "string"
    },
    "session_id": {
      "title": "Session Id",
      "type": "string"
    },
    "content": {
      "title": "Content",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "content",
    "ts"
  ],
  "title": "SessionMessageReceivedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "session.message_received",
  "session_id": "sess-abc123def456",
  "content": "\u603b\u7ed3 README.md",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### SessionWaitingForInputEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `session_id` | `string` | yes |
| `last_run_id` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "session.waiting_for_input",
      "default": "session.waiting_for_input",
      "title": "Type",
      "type": "string"
    },
    "session_id": {
      "title": "Session Id",
      "type": "string"
    },
    "last_run_id": {
      "title": "Last Run Id",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "last_run_id",
    "ts"
  ],
  "title": "SessionWaitingForInputEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "session.waiting_for_input",
  "session_id": "sess-abc123def456",
  "last_run_id": "20260516-100000-abc123",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### SessionResumedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `session_id` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "session.resumed",
      "default": "session.resumed",
      "title": "Type",
      "type": "string"
    },
    "session_id": {
      "title": "Session Id",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "ts"
  ],
  "title": "SessionResumedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "session.resumed",
  "session_id": "sess-abc123def456",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

### SessionClosedEvent

| Field | Type | Required |
|---|---|---|
| `type` | `string` | no |
| `session_id` | `string` | yes |
| `ts` | `string` | yes |

```json
{
  "properties": {
    "type": {
      "const": "session.closed",
      "default": "session.closed",
      "title": "Type",
      "type": "string"
    },
    "session_id": {
      "title": "Session Id",
      "type": "string"
    },
    "ts": {
      "title": "Ts",
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "ts"
  ],
  "title": "SessionClosedEvent",
  "type": "object"
}
```

**Example:**

```json
{
  "type": "session.closed",
  "session_id": "sess-abc123def456",
  "ts": "2026-05-16T10:00:00.001Z"
}
```

## Error Codes

| Code | Name | Meaning |
|------|------|---------|
| -32700 | Parse Error | Invalid JSON received |
| -32600 | Invalid Request | Missing required JSON-RPC fields |
| -32601 | Method Not Found | Unknown method |
| -32602 | Invalid Params | Parameter validation failed |
| -32603 | Internal Error | Handler raised an unhandled exception |
| -32000 | Application Error | e.g. another run already in progress |
