sessionpipe protocol v1

This document is part of the sessionpipe protocol and is licensed under CC BY 4.0. The words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as in RFC 2119. Status: Draft (see VERSIONING.md).

1. What this is

A coding-agent harness (Claude Code, Codex, Gemini CLI, Antigravity, Devin, Cursor, …) fires hooks as a session runs. sessionpipe turns those hooks into a small, uniform stream of events about the session — started, working on a tool, needs you, ended — filtered to a privacy tier the person chose per destination, and delivers them to any receiver over HTTP (or to a file, or to stdout). A receiver may send control messages back (answer a permission prompt, queue a message for the next turn).

The protocol carries facts and timestamps. It never carries a verdict: what "stale" means, when a session that never said goodbye is "done", and what a session is about are a receiver's readings, made from the facts.

This document defines the envelope, the session block, the event vocabulary and the tiers. HTTP.md is the wire binding, PRIVACY.md the tiers and rulesets in detail, CONTROL.md the channel back, ADAPTERS.md the per-harness mapping, VERSIONING.md how this changes.

2. Envelope

Every event is one JSON object with exactly these top-level members. The normative shape is schema/v1/event.json, generated from the reference implementation's types.

{
  "protocol": 1,
  "id": "01K6ABCXYZ0123456789ABCDEF",
  "type": "tool.ended",
  "time": "2026-09-28T01:03:11.204Z",
  "tier": 1,
  "harness": { "name": "claude-code", "version": "2.1.290", "event": "PostToolUse" },
  "session": {
    "id": "8c132906-8c3f-4814-870a-afc3d05e1d2e",
    "seq": 412,
    "machine": "misha-air", "cwd": "~/spacesheep",
    "repo": "github.com/micmmakarov/spacesheep", "branch": "main",
    "model": "claude-fable-5-1",
    "title": "Open-source session hooks", "title_source": "harness",
    "url": "https://claude.ai/code/session_01…", "account_id": "a1b2…",
    "attended": true, "parent_id": null
  },
  "privacy": { "rulesets": ["secrets@1"], "pii": false },
  "data": { "tool": "Bash", "call_id": "toolu_01…", "ms": 1830, "ok": true }
}

3. The session block

Every event carries the session as the sender knows it at that moment. A hook fired a second after start may know only the id and the folder; the worker learns the title, the model and the link later from the harness's own files. A receiver MUST merge with COALESCE semantics: a later event whose field is absent or empty never blanks an earlier full value.

Short id. Where a session is named to a person (a log line, a notification, a search box), senders and receivers use its short id: the first 8 hex digits, lowercase, of sha256("sessionpipe.session:" + harness.name + ":" + session.id). It is derived from fields every event carries and is never sent. The id's own prefix is not a short form: Codex ids are time-ordered (UUIDv7), so two sessions started in the same minute share their first eight characters. A receiver SHOULD accept a typed prefix of a short id and resolve it against its sessions newest first, and MUST list the candidates rather than pick one when more than one matches. Vectors: claude-code with 8c132906-8c3f-4814-870a-afc3d05e1d2e → 58ab6602; codex with 01a10860-a43f-7ce2-b12f-a7911ae8a880 → ae08c6ab.

4. Event vocabulary

Tier is the lowest tier that carries the type; a sink below it never sees it. Per-type data shapes are normative in schema/v1/event-data.json.

Rules for all types:

• A sender MUST emit at least session.started (or session.backfill) before any other event of a session, and SHOULD emit turn.started / turn.ended for every prompt its harness reports.

• A sender MUST NOT emit a type at a tier below the type's tier (a tool.ended in a tier-0 event is a protocol error; a receiver MAY reject it with reason tier_type).

• attention_id, turn_id, call_id, agent_id are opaque strings the sender chooses; when the harness provides one (tool_use_id, prompt_id) it SHOULD be used as is.

• Thinned tool events. A harness fires a hook per tool call, and a session that runs a few hundred subagents fires thousands a minute (sessionpipe issue #208: 97 243 events by 10 a.m., 87 % of them subagents' tool calls). A sender MAY thin a sink's tool events, for a subagent's calls (agent_id set; the main thread's all go) or for every call of the session. A thinned thread is sent no tool.started, and of its tool.ended events the first by time that is at least 60 s from the last one the session was sent; the window restarts there. An event a little out of time order falls in the window like any other. Whatever the window says, the sender MUST send a thread's first tool.ended timed at or after its attention.needed (which then carries that agent_id): it is the event that shows the prompt was answered (attention.cleared, above). A sender that thins MUST NOT thin any other type (turns, attention, subagents, files, limits, sessions all go as they come). So a session whose tools keep finishing is seen to work at least once a window plus the time to the next call that finishes. What is thinned is a delivery choice per sink, never what the sender records: it keeps every event. A receiver, which can't tell a thinned sink from another:

  • MUST NOT read a seq gap as a lost event;
  • MUST NOT expect a tool.ended for every tool.started, or the reverse: a call's call_id may be seen once, or not at all;
  • MAY read a session's tool.ended as a sign that it is working, and one of the thread that asked as a sign that its open prompt was answered (CONTROL.md §7: a subagent's tool.ended says nothing about a prompt the main thread opened, nor the main thread's about a subagent's), and MUST NOT present the number it got as the number of tool calls the session made.

  Thinning is the receiver's to ask for, never done on nobody's say-so: a receiver that wants it says tools in its well-known file (HTTP.md §1), and a sender that reads nothing there sends every tool event, so a receiver that reads a subagent's tool calls keeps them across a sender's upgrade. The reference client's setting is the sink's tools: all (every tool event), main (a subagent's thinned), beat (all of them thinned); unset, it is what the receiver's file says, else all.

• Who started a turn. turn.started.submitted_by is the harness's own word for who submitted the prompt (Claude Code: user · sdk · system · loop_wakeup · schedule_wakeup · poll_event). It is a different vocabulary from session.started.source, which is this spec's own enum; a receiver MUST NOT merge the two. turn.started.injected is true when the prompt text is a block the harness wrote around something rather than words a person typed. Both fields are OPTIONAL for senders.

  • A sender whose harness supplies the word MUST forward it verbatim and MUST NOT map it onto a vocabulary of this spec, because a harness may extend its own list at any time. The value is a bare word, [A-Za-z0-9][A-Za-z0-9_.-]{0,39}, because tier 0 is not redacted (PRIVACY.md §2); a sender whose harness supplies something else, or supplies nothing, MUST omit the field rather than guess.
  • injected: true says only that the prompt is not the person's words. It MUST NOT be read as "no person caused this turn": a harness may hand a person's message to a session inside an injected block, as Claude Code does with a <task-notification>. A sender MAY decide it from the prompt's shape, which is a reading and can be wrong in either direction; each sender's gaps belong in ADAPTERS.md.
  • A receiver MUST read an absent field as unknown — never as "a person submitted this" — and MUST keep a value it does not recognise. A receiver that acts on either field MUST NOT read silence as the opposite.
  • A receiver that separates the person's own activity from the harness's (a recency board) MAY act on injected: true together with whatever else it knows about who caused the turn, or on a submitted_by that the sender's harness documents as non-human. A harness MAY fire a further turn.started for a turn_id already seen, when it absorbs a message into a running turn; a receiver MUST NOT let a later injected: true reclassify a turn it has already accepted without it.

5. Tiers

What each tier carries. The full rules, the rulesets and guidance are in PRIVACY.md.

Filtering is a pure function. filter(event, tier, pii) returns the event with fields removed and strings redacted. It removes by allowlist per type, never by denylist, so a field the spec does not name at a tier is not sent at that tier. The same function runs in the conformance runner, so a receiver can prove what a tier-N event may contain.

Tier per sink, capped by the receiver. A sink is configured at a tier; the receiver's well-known file declares max_tier; the sender uses the lower.

6. Invariants a sender keeps

1. Never lose, never duplicate. The outbox is append-only; a sink's cursor advances only on a 2xx; every event carries seq; a receiver deduplicates on (harness.name, session.id, session.seq). An outage costs delay, never an event. A tool event a sink is configured not to be sent (§4, thinned tool events) is skipped by that choice, and stays in the outbox.
2. Secrets never leave. secrets@1 runs on every string above tier 0 before an event reaches the outbox, and cannot be turned off per sink.
3. The hook path is invisible. The process a harness spawns reads stdin, writes one job file, spawns a detached worker and exits 0; it writes to stdout only what the harness requires. Nothing in this protocol may block or alter the harness.
4. No telemetry. A sender reports to the sinks the person configured and to nobody else.

7. Conformance

A sender or receiver is conformant when it passes the fixtures under conformance/: adapter fixtures (real hook payloads → expected events), redaction vectors, and delivery scenarios (HTTP.md §7). sessionpipe-conformance runs them.