|
| 1 | +# NDJSON Events |
| 2 | + |
| 3 | +When running `aictrl run --format json`, the CLI emits newline-delimited JSON (NDJSON) events to stdout. Each line is a self-contained JSON object with the following base shape: |
| 4 | + |
| 5 | +```json |
| 6 | +{ |
| 7 | + "type": "<event_type>", |
| 8 | + "timestamp": 1741500000000, |
| 9 | + "sessionID": "session_01abc..." |
| 10 | +} |
| 11 | +``` |
| 12 | + |
| 13 | +## Lifecycle Events |
| 14 | + |
| 15 | +### `session_start` |
| 16 | + |
| 17 | +Emitted once when the session begins. |
| 18 | + |
| 19 | +```json |
| 20 | +{ |
| 21 | + "type": "session_start", |
| 22 | + "model": "anthropic/claude-sonnet-4-20250514", |
| 23 | + "agent": "default" |
| 24 | +} |
| 25 | +``` |
| 26 | + |
| 27 | +### `session_complete` |
| 28 | + |
| 29 | +Emitted once when the session ends (success or failure). |
| 30 | + |
| 31 | +```json |
| 32 | +{ |
| 33 | + "type": "session_complete", |
| 34 | + "durationMs": 12345, |
| 35 | + "error": null |
| 36 | +} |
| 37 | +``` |
| 38 | + |
| 39 | +`error` is `null` on success, or a string describing the failure. |
| 40 | + |
| 41 | +## Message Events |
| 42 | + |
| 43 | +### `message_complete` |
| 44 | + |
| 45 | +Emitted when an assistant message finishes (one per LLM turn). |
| 46 | + |
| 47 | +```json |
| 48 | +{ |
| 49 | + "type": "message_complete", |
| 50 | + "modelID": "claude-sonnet-4-20250514", |
| 51 | + "providerID": "anthropic", |
| 52 | + "agent": "default", |
| 53 | + "cost": { "input": 0.003, "output": 0.012, "cache": { "read": 0, "write": 0 } }, |
| 54 | + "tokens": { "input": 1024, "output": 512, "cache": { "read": 0, "write": 0 } }, |
| 55 | + "finish": "tool-calls" |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +`finish` values: `"tool-calls"` (model wants to call tools), `"end_turn"` (model is done), `"max_tokens"` (output truncated). |
| 60 | + |
| 61 | +### `text` |
| 62 | + |
| 63 | +Emitted when a text block from the assistant is complete. |
| 64 | + |
| 65 | +```json |
| 66 | +{ |
| 67 | + "type": "text", |
| 68 | + "part": { |
| 69 | + "type": "text", |
| 70 | + "text": "Here is the result...", |
| 71 | + "time": { "start": 1741500000, "end": 1741500001 } |
| 72 | + } |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +### `reasoning` |
| 77 | + |
| 78 | +Emitted when extended thinking content is complete (requires `--thinking` flag). |
| 79 | + |
| 80 | +```json |
| 81 | +{ |
| 82 | + "type": "reasoning", |
| 83 | + "part": { |
| 84 | + "type": "reasoning", |
| 85 | + "text": "Let me think about this...", |
| 86 | + "time": { "start": 1741500000, "end": 1741500001 } |
| 87 | + } |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +## Tool Events |
| 92 | + |
| 93 | +### `tool_use` |
| 94 | + |
| 95 | +Emitted when a tool call completes (success or error). |
| 96 | + |
| 97 | +```json |
| 98 | +{ |
| 99 | + "type": "tool_use", |
| 100 | + "part": { |
| 101 | + "type": "tool", |
| 102 | + "tool": "bash", |
| 103 | + "state": { |
| 104 | + "status": "completed", |
| 105 | + "input": { "command": "ls" }, |
| 106 | + "metadata": { "exit": 0, "output": "..." } |
| 107 | + } |
| 108 | + } |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +`state.status` is `"completed"` or `"error"`. On error, `state.error` contains the error message. |
| 113 | + |
| 114 | +### `step_start` / `step_finish` |
| 115 | + |
| 116 | +Emitted at step boundaries during multi-step tool use. |
| 117 | + |
| 118 | +```json |
| 119 | +{ "type": "step_start", "part": { "type": "step-start" } } |
| 120 | +{ "type": "step_finish", "part": { "type": "step-finish" } } |
| 121 | +``` |
| 122 | + |
| 123 | +## Skill Events |
| 124 | + |
| 125 | +Skills are loaded progressively. The model first sees skill names and descriptions in the tool schema. Full skill content only enters context when the model explicitly invokes the skill tool. |
| 126 | + |
| 127 | +### `skill_discovered` |
| 128 | + |
| 129 | +Emitted per skill when the skill tool is initialized and skill descriptions are registered in the tool schema. This happens at the start of each LLM turn. |
| 130 | + |
| 131 | +```json |
| 132 | +{ |
| 133 | + "type": "skill_discovered", |
| 134 | + "name": "commit", |
| 135 | + "description": "Create well-structured git commits", |
| 136 | + "location": "/home/user/.claude/skills/commit/SKILL.md" |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +### `skill_loaded` |
| 141 | + |
| 142 | +Emitted when the model invokes the skill tool and the full SKILL.md content enters context. |
| 143 | + |
| 144 | +```json |
| 145 | +{ |
| 146 | + "type": "skill_loaded", |
| 147 | + "name": "commit", |
| 148 | + "location": "/home/user/.claude/skills/commit/SKILL.md" |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +### `skill_resource_loaded` |
| 153 | + |
| 154 | +Emitted when the model reads a file that belongs to a skill directory (e.g., a script, template, or reference file bundled with the skill). |
| 155 | + |
| 156 | +```json |
| 157 | +{ |
| 158 | + "type": "skill_resource_loaded", |
| 159 | + "skillName": "commit", |
| 160 | + "filePath": "/home/user/.claude/skills/commit/templates/conventional.md" |
| 161 | +} |
| 162 | +``` |
| 163 | + |
| 164 | +## Subagent Events |
| 165 | + |
| 166 | +### `subagent_start` |
| 167 | + |
| 168 | +Emitted when a child session (subagent) is spawned. |
| 169 | + |
| 170 | +```json |
| 171 | +{ |
| 172 | + "type": "subagent_start", |
| 173 | + "subagentSessionID": "session_01xyz...", |
| 174 | + "parentSessionID": "session_01abc...", |
| 175 | + "title": "Research codebase" |
| 176 | +} |
| 177 | +``` |
| 178 | + |
| 179 | +### `subagent_complete` |
| 180 | + |
| 181 | +Emitted when a child session completes. |
| 182 | + |
| 183 | +```json |
| 184 | +{ |
| 185 | + "type": "subagent_complete", |
| 186 | + "subagentSessionID": "session_01xyz...", |
| 187 | + "parentSessionID": "session_01abc..." |
| 188 | +} |
| 189 | +``` |
| 190 | + |
| 191 | +## Error Events |
| 192 | + |
| 193 | +### `error` |
| 194 | + |
| 195 | +Emitted when a session error occurs. |
| 196 | + |
| 197 | +```json |
| 198 | +{ |
| 199 | + "type": "error", |
| 200 | + "error": { |
| 201 | + "name": "Unknown", |
| 202 | + "data": { "message": "Something went wrong" } |
| 203 | + }, |
| 204 | + "sourceSessionID": "session_01abc..." |
| 205 | +} |
| 206 | +``` |
| 207 | + |
| 208 | +### `permission_rejected` |
| 209 | + |
| 210 | +Emitted when a permission request is auto-rejected (headless mode has no user to approve). |
| 211 | + |
| 212 | +```json |
| 213 | +{ |
| 214 | + "type": "permission_rejected", |
| 215 | + "permission": "bash", |
| 216 | + "patterns": ["rm -rf /"] |
| 217 | +} |
| 218 | +``` |
0 commit comments