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, 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…",
    "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.

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.

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.
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.