ADR-415: A session event record, written by the ways hooks to a per-session spool and read by attend, ways sensors and sensor conditions¶
Summary¶
- Decided: the ways hooks write every Claude Code event they receive as one normalised record, appended to a per-session JSONL spool under the session's runtime directory. One schema serves three readers: attend's new
claude-codecrate sensor, which reads new lines on each poll from a stored offset; #846's ways sensors, whose rules select records by section and condition; and #843'swhere:conditions, which test record fields. A record carries the event name, its #846 section, a sequence number, a timestamp, the session and agent ids, the agent type, the permission mode, the tool's raw name with its abstract type and primary field value (ADR-706), and a capped excerpt of the event's own fields. Events that only a sensor needs are wired as asynchronous hooks, so they never block. The sensor reports subagent starts and finishes, workflows and background tasks finishing, compaction, model switches, permission waits and completed tasks. - Trades away: a spawn per newly wired event, and one file append per event on every session whether or not anything reads it. Session content (the first 512 characters of commands, paths, prompts and replies) sits unredacted in a per-user file for the session's life. A tool the ways hooks are not wired for, such as Read or an MCP tool by default, leaves no record. Faster in-process routes, such as the attend mod's own handlers, become optimisations over the file rather than sources.
- One-way? No. The spool is a file under the session directory, and its writer is one call per adapter. The field names become a contract once #846 lets consumers outside this repo read them; the
vfield allows a later schema beside this one. - Probes: Confident (sensor): attend notices subagents and workflows finishing, compaction, model switches and permission prompts in any session with ways installed, with or without the attend mod, because the ways hooks write each event down and attend reads it on its poll. Not confident (excerpt): each record keeps up to 512 characters of the command, path, prompt or final reply it describes, in a file only you can read under the session's runtime directory, with nothing redacted. Is that acceptable, or should prompts and replies stay out until a redaction rule exists?
- Inversion: at one end, every consumer hooks Claude Code for itself (attend's hooks, #846's hooks, a mod), each with its own schema and its own spawns. At the other, one resident process that every event must pass through and that loses events when it is down. This decision uses the hooks that already run and a file that needs nothing running.
Context¶
attend learns about the session it serves by polling. Its context and disclosure sensors shell out to ways context --json; nothing tells it that a subagent finished, that a background Workflow completed, that the session compacted or changed model, or that the agent is waiting on a permission prompt. Claude Code announces each of these as a hook event (ADR-705), and hooks push one process per event, while sensors pull on a poll.
The ways hooks already receive the payloads. Issue #846 builds on that: ways sensors that select records of the session's own activity (prompts, replies, tool calls) and dispatch them to consumers outside ways, such as an audit log or a policy checker, with or without attend. It names a section vocabulary and the fields every record carries. Issue #843 specifies attend's sensors, whose triggers test where: conditions against fields of what a sensor observes. A tool-call event seen by an attend sensor, a ways-sensor rule and a sensor condition is the same event, and each of the three needs a stable shape for it.
The operator asked for a Claude Code sensor crate for attend "in addition to ways triggers", and chose one record schema now over a narrower attend-only spool first. The tool catalog (ADR-706) gives the schema harness-neutral tool fields. The tool-call adapter (ADR-188) is the writer for tool events.
Decision¶
-
The writer. Each event has exactly one recording hook command. Where a ways adapter already runs on the event, it writes the record before its own matching:
check-tool.shfor the tool events and for UserPromptExpansion, a typed skill or command (ADR-188),check-prompt.shfor UserPromptSubmit,check-response.shfor Stop,inject-subagent.shfor SubagentStart,check-state.shfor SessionStart. A new adapter,hooks/ways/record-event.shoverways hook record, is wired withasync: truefor the events that carry no ways matching: SubagentStop, TaskCreated, TaskCompleted, PreCompact, PostCompact, PostModelSwitch, StopFailure, PermissionRequest, PermissionDenied, Notification, CwdChanged and SessionEnd. MessageDisplay and PostToolBatch are never wired: they fire on every streamed chunk and every step. The engine also appends away_eventrecord when it logs a fire or a suppression for the session. A failure to write is counted and never fails the hook. -
The record. One JSON object per line, schema version 1:
| Field | Content |
|---|---|
v |
1 |
seq |
per-session sequence number |
ts |
UTC timestamp with milliseconds |
event |
the literal hook event name |
section |
#846's section: user_prompt, queued_message, assistant_response, tool_call, tool_result, subagent, compaction, session_start, session_end, way_event; and permission, model_switch, task, turn_end and notification for the events #846 does not name |
session_id, agent_id, agent_type |
from the payload; agent_id and agent_type are null in the main session |
permission_mode, cwd |
from the payload |
tool_name |
the tool's name as the payload gives it (tool events and permission events) |
tool_type |
the catalog's type, or unmapped |
tool_use_id |
pairs a call with its result |
field, value |
the abstract field (command, path, url, agent, skill, tool) and its value |
status |
on a tool result: ok, error for PostToolUseFailure, or the response's own status where it reports one, such as a Workflow's async_launched |
x |
the event's excerpt, below |
truncated |
the fields that were cut |
The excerpt takes a fixed list of fields per event and nothing else:
- UserPromptSubmit: prompt, source.
- Stop: background_tasks, each as id, type, status and name, up to 32; the count of session_crons; last_assistant_message.
- StopFailure: error.
- SubagentStop: last_assistant_message.
- PreCompact, PostCompact: trigger; PostCompact also compact_summary.
- PostModelSwitch: from_model, to_model, source, context_tokens.
- PermissionDenied: reason.
- Notification: notification_type.
- TaskCreated, TaskCompleted: task_subject, teammate_name, team_name.
- SessionStart: source, transcript_path. SessionEnd: reason.
- Tool events: nothing beyond the primary field. Tool output, file contents and the rest of tool_input are never copied.
-
Size. Each excerpted string and
valueis cut to 512 bytes at a character boundary. A record is at most 4,096 bytes; past that,xis dropped and listed intruncated. Each record is onewriteof line and newline on an append handle, asappend_jsonl_linedoes today, so parallel hooks never interleave. -
Location and retention. The spool is
spool/in the session's directory under the sessions root:$XDG_RUNTIME_DIR/claude-sessions/<session>/spool/on Linux, the per-user fallbacks elsewhere. Subagents write into their parent session's spool;agent_idtells them apart. Records go into numbered segments (000001.jsonl, …). The writer starts a new segment at 4 MiB and keeps the newest 8, so a session holds at most 32 MiB.seqis assigned under an advisory lock onspool/lock, held for the increment and the append. A writer that waits more than 50 ms writes the record withseq: nulland counts the miss. Files are created with mode 0600. The spool is removed with the session's other state, and the runtime directory goes at logout. A consumer that needs history beyond the session copies what it needs, as a #846filerule does. -
Excerpts are not redacted. The spool stays on the machine, in a per-user directory, readable only by its owner. Sending records anywhere else is #846's dispatch, which owns the redaction decision for what leaves the machine.
-
attend's
claude-codesensor. A crate sensor, registered beside the existing crate sensors and moved under #843's spec when that lands. It reads the spool of the session attend runs for. On each poll it reads lines from its stored segment and byte offset, kept throughexport_state. If its segment has been dropped, it resumes at the oldest segment and reports theseqgap. It emits transitions, not states: - a subagent started or finished, with its type (SubagentStart, SubagentStop);
- a Workflow, background shell or monitor finished: a task id in one Stop record's
background_taskswhose status has left running, or which is gone, in the next; - the session compacted (PostCompact), which is ground truth for the context sensor;
- the model and window changed (PostModelSwitch);
- the agent is waiting on a permission (PermissionRequest, or a Notification of type
permission_prompt) or on its human (idle_prompt); - a task completed (TaskCompleted);
- a turn failed (StopFailure), a plan was approved (ExitPlanMode's tool result), the working directory changed (CwdChanged).
Magnitudes and the lane each signal rides are set in the sensor's configuration, under #843 and #139.
-
#846 and #843 read the same records. A ways-sensor rule selects by
sectionand awhere:condition over these fields, and its dispatcher reads the spool. Where that dispatcher runs is #846's decision. A #843 condition tests the same fields:where: { tool_type: shell, value: { like: "git push*" } }. Neither defines a second shape for a session event. -
The attend mod is a fast path. When the mod is loaded, in-process handlers may wake attend before the next poll. Its
session.*andturn.completehandlers see those events today; itstool.callhandlers cover only attend's own tools, so a fast path for other tool calls needs handlers registered on them. The spool stays the source of the record, and the sensor drops a duplicate byseqortool_use_id.
Consequences¶
Positive¶
- attend sees subagent, workflow, compaction, model and permission events in every session with ways installed, with or without the mod.
- One schema serves the sensor, the ways sensors and sensor conditions, so a condition written for one reads the others' records.
- The record is harness-neutral where it matters: tool fields come from the catalog, and the raw name stays beside them.
- The spool doubles as a per-session event trace for debugging hooks: the record of what Claude Code sent, with sequence numbers.
Negative¶
- Twelve event types gain an asynchronous spawn each, and every session pays one append per event even when nothing reads the spool.
- Unredacted excerpts of commands, prompts and replies sit in a per-user file for the session's life.
- Tools the ways hooks are not wired for leave no record. Reads and MCP calls are invisible to the sensor unless a user wires them.
- The
seqlock adds a small serial step to every hook that records. A writer that loses the race past 50 ms leaves a record without a sequence number. - Comparing
background_tasksbetween Stop records misses a task that starts and finishes inside one turn, and Stop does not fire on a user interrupt.
Neutral¶
- The writer adds one call to each existing adapter. The hooks stay single-binary invokers.
events.jsonlkeeps its role as the global telemetry log.way_eventrecords in the spool repeat, per session, what it already logs.- The record's field names follow Claude Code's payload keys where one exists (
tool_name,permission_mode), so a reader of both sees one name per value.
Alternatives Considered¶
- The attend mod's in-process handlers as the source. The mod already registers
session.*andturn.complete, andtool.callfor its own five tools. Rejected as the source: mods run only behind Claude Code's preview flag, which is off by default, so most sessions would record nothing. Kept as a fast path (item 8). - Hooks call
attenddirectly. Rejected: one more process per event; attend must be installed and running for the event to exist anywhere; the hooks would gain logic; and #846's ways sensors must work with attend absent. - An attend-only spool first. A narrower format for the sensor alone, with #846 deciding its own later. Not chosen: the operator picked one schema now. Two shapes for the same event would leave #843's conditions written against one of them.
- Tail the Claude Code transcript. It records tool calls, results and messages, but not hook-only events such as PermissionRequest, PostModelSwitch or Notification. Its format is internal to Claude Code and changes between builds, which is the coupling ADR-706 removes for tools.
- Reuse
events.jsonl. Rejected: it is global across sessions, so every reader filters by session; it is compacted at 32 MiB, which breaks stored offsets; and it carries telemetry in another shape. - A resident process receives events over a socket (the ways agent, ADR-502). Rejected for now: events are lost while it is down, and it adds a dependency to every hook. A later transport can carry this same schema.
- Store whole payloads. Rejected: Write and Edit inputs carry whole files, tool results carry whole outputs, and both carry secrets. The excerpt keeps what the named signals need.