Skip to content

agent-events.md

Latest commit

 

History

History
147 lines (105 loc) · 4.45 KB

agent-events.md

File metadata and controls

147 lines (105 loc) · 4.45 KB

Agent Events

Real-time visibility into what the agent is doing. Events stream to clients and persist in Redis for replay.

Event types

  • Tool events - when the agent uses tools (Read, Edit, Bash, etc.)
  • File changes - files created, modified, or deleted
  • Commands - shell command execution with output
  • Thinking - extended reasoning content (for supported models)
  • Connection events - agent connect/disconnect status

Tool Events

Tool events track the lifecycle of tool invocations.

TOOL_START

Emitted when the agent begins using a tool.

Field Type Description
tool string Tool name (e.g., "Read", "Edit", "Bash")
tool_use_id string Unique ID for this invocation
parent_tool_use_id string? Set when tool runs inside a Task/subagent
input object? Full tool input (if available at start)

TOOL_INPUT

Emitted as tool input is streamed (for large inputs).

Field Type Description
tool_use_id string Correlates to TOOL_START
input_delta string Partial input chunk

TOOL_INPUT_COMPLETE

Emitted when tool input streaming finishes.

Field Type Description
tool_use_id string Correlates to TOOL_START
input object Complete tool input as JSON

TOOL_END

Emitted when tool execution completes.

Field Type Description
tool string Tool name
tool_use_id string Correlates to TOOL_START
result string? Tool output (on success)
error string? Error message (on failure)
duration_ms int64? Execution time in milliseconds

Example

TOOL_START     tool=Bash, id=abc123
TOOL_INPUT     id=abc123, delta="npm "
TOOL_INPUT     id=abc123, delta="install"
TOOL_INPUT_COMPLETE id=abc123, input={"command": "npm install"}
... (command runs) ...
TOOL_END       id=abc123, result="added 150 packages", duration_ms=4523

File Change Events

Emitted when the agent modifies files.

Field Type Description
path string File path relative to workspace
action enum CREATE, EDIT, or DELETE
lines_added int32? Lines added (for EDIT)
lines_removed int32? Lines removed (for EDIT)

Command Events

COMMAND_START

Field Type Description
command string The command being executed
cwd string? Working directory

COMMAND_END

Field Type Description
command string The command that ran
exit_code int32? Exit code (0 = success)
output string? Command output (may be truncated)

Thinking Events

Emitted when the model uses extended thinking (Claude Opus, etc.).

Field Type Description
thinking_id string Unique ID for this thinking block
content string Thinking content (delta if partial)
partial bool true for streaming deltas, false for final

Thinking content streams in chunks. Accumulate content for the same thinking_id until partial=false.

Other Events

Kind Description
REPO_CLONE Repository clone progress (STARTING/CLONING/DONE/ERROR)
PORT_EXPOSED Port exposed for preview (port, preview_url)
PORT_UNEXPOSED Port exposure removed (port)
AGENT_DISCONNECTED Agent lost connection
AGENT_RECONNECTED Agent reconnected

Nested Tool Calls

When the agent uses the Task tool to spawn a subagent, events include parent_tool_use_id:

TOOL_START     tool=Task, id=task_1
  TOOL_START   tool=Read, id=read_1, parent=task_1
  TOOL_END     tool=Read, id=read_1, parent=task_1
  TOOL_START   tool=Edit, id=edit_1, parent=task_1
  TOOL_END     tool=Edit, id=edit_1, parent=task_1
TOOL_END       tool=Task, id=task_1

Persistence

Events stored in Redis Stream: session:{id}:stream. Cursor-based reading handles reconnection without missing events.

CLI

netclode events <session-id>                    # List events
netclode events <session-id> --kind tool_start  # Filter by kind
netclode events tail <session-id>               # Stream in real-time
netclode events <session-id> --json             # JSON output

iOS App

Events appear in the activity feed with expandable tool input/output, file diffs, and collapsible thinking blocks.