OTEL telemetry attach replaces proxy capture for Claude Code (LLP 0262) (#818)

* RFC 0245: OTEL telemetry replaces proxy attach for Claude Code

The deliberation record for the change set tracked by #798.
Committed unchanged as the branch's design record; status stays Draft because
acceptance is the author's call, not a pipeline step.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* LLP 0251-0256: the decisions RFC 0245 promises on acceptance

One narrow decision per settled choice, so implementation code can cite the
choice it realizes instead of restating the reasoning: the settings env block
as the injection surface, the events-first plus bodies-for-gaps split, the
spool's cap and sweep duties, ingest-time settlement in place of the flush-time
pass, the claude_telemetry_events dataset, and the session-ignore control route
on the listener.

All six are Draft. RFC 0245 gains a Spawns line naming them; nothing here flips
a status, because acceptance is the author's.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* LLP 0257: spec for the claude telemetry listener source

The requirements the listener implementation and its tests answer to: what the
source registers, what its endpoint accepts, how events and body files combine
at ingest, the two datasets it writes, its status and capture-health duties,
its failure modes, and the seams its tests use. Composes decisions 0251-0256
and cites them rather than repeating why.

Draft, like the RFC that spawns it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Forward-ref LLP 0245 from the proxy-attach docs it displaces

Mechanical forward refs only, on the parts the claude client's mode switch
displaces: the RFC (0231), the proxy attach keys (0232), the CA lifecycle and
trust (0235, 0237, 0238), the launchd environment delivery (0239), and the
fresh-install and migration path (0242, 0243, 0244). Each is phrased "on
acceptance of 0245" so it stays honest while 0245 is Draft, and each says what
survives for the clients still routed through the proxy.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* RFC 0245 names all six decisions it spawns

The header Spawns line already listed LLP 0251 to 0256 plus 0257, but the
prose "On acceptance" section still enumerated only five choices and left out
session-ignore transport (LLP 0256), the choice open question 4 in the same
file resolves. Name each decision next to its number so the two lists agree.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Carry the 0245 back-reference in Related, not a new header field

The seven new docs each carried a Spawned-by header field that appears nowhere
else in the corpus. The corpus already has a way to say this: LLP 0168, spawned
by RFC 0167, glosses its parent inside Related ("LLP 0167 (the accepted RFC
this decision realizes)"), and the parent RFC carries the one-way Spawns line.
Fold the same gloss into Related here and drop the field. LLP 0256 keeps the
"settled in #798" fact on a Tracker line, which LLP 0245 and LLP 0257 already
use.

No information is lost: every doc already listed LLP 0245 in Related, and the
Spawns line on 0245 records that all seven stay Draft until it is accepted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* LLP 0251 renumbered to 0258: open PR #817 claimed 0251

The number was taken on origin/integration/proxy-mode-default-attach
(llp/0251-proxy-mode-default-attach.design.md, Status Active), so whichever
branch merged second would have gone red on the uniqueness check. 0258 is the
next number free across master and every remote branch.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* The OTLP http/json listener becomes shared core machinery (LLP 0257)

A second plugin is about to host an OTLP listener of its own, so the
transport half of @hypaware/otel's receiver moves to src/core/otlp:
signal routing, json-only content-type enforcement, gzip and deflate
decoding, the per-signal partialSuccess envelopes, and bind-and-resolve.
The shared server never looks inside `data`, so payload interpretation
stays with whichever plugin hosts the listener.

Pure prefactor. @hypaware/otel keeps its banner text, its bind error
prefix, its config keys, its wire responses and its self-telemetry loop
guard, which never left the collector. The one new option, a signal
subset, defaults to all three signals, so today's listener is unchanged.

The transport contract is now pinned by test/core/otlp-json-server.test.js
rather than only by the two otel smokes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* A live producer that is not the proxy records through the gateway (LLP 0252)

`ai_gateway_messages` is about to have a third producer, so the gateway
capability grows the one call such a producer needs:
`recordProjectedExchange`. It takes a finished
`AiGatewayProjectedExchange` and owns everything after it - the shared
row expansion, `part_id` identity, the schema strip, the table path -
so an OTEL-projected row cannot drift from the proxy's row for the same
content.

The write is preceded by a pre-write `part_id` dedupe seeded from both
committed partitions and the spool, restricted to the batch in hand.
That is what makes producer overlap harmless: a part the proxy or a
backfill run already stored is skipped, not appended a second time. The
spool scan is the same one backfill does and stays forbidden on the
flush path, where the rows being tested ARE the spool.

Purely additive on the capability surface, so every adapter's `^2.0.0`
requirement still resolves and the proxy recorder's path is untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The claude plugin hosts a listener for Claude Code's own telemetry (LLP 0257)

`@hypaware/claude` contributes a `claude-telemetry` source through the
kernel source registry: an OTLP http/json listener on loopback, on its
own port (default 4319, config `claude.telemetry.listen_port`, `0` for
dynamic), built on the shared core server so the transport is not
copied. Only the logs and metrics routes are served; metrics are
accepted and dropped so the exporter is not left retrying a 404, and a
non-json content type is refused exactly as the otel receiver refuses
it.

Payload interpretation is claude-owned. `user_prompt` and
`assistant_response` each carry their own `message.uuid`, so they
project once, with native identity, and no settlement enricher has
anything to repair. `api_request` carries no content and no uuid: it is
the usage record for the `request_id` an assistant response names, and
is folded onto that message's `attributes.usage` in the same shape the
proxy path writes. The index that holds it spans batches, because the
exporter flushes on a timer, and evicts oldest-first at a cap.

Rows go out through the gateway's `recordProjectedExchange`, so OTEL is
a third producer of `ai_gateway_messages`, not a new table. cwd and git
identity still come from the SessionStart hook record; `query_source`
and `agent.name` carry attribution, and parent_uuid,
logical_parent_uuid, user_type and permission_mode read null by design.

The daemon's own exports are dropped by resource marker, and another
exporter that finds the port is ignored by scope rather than
half-parsed. Registration is feature-detected against the capability, so
an older gateway degrades to "no listener" instead of failing boot, and
the source is registered rather than auto-started, so a CLI activation
never binds a port.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* A hermetic smoke drives the telemetry listener end to end (LLP 0257)

Content in at the HTTP endpoint, rows out of `hyp query sql`: the smoke
activates the gateway and the claude plugin in a temp HypAware home,
drives the SessionStart hook, starts the listener on a dynamic port, and
POSTs one real-shaped Claude Code batch (the three content events plus
two behavioral ones the listener does not model yet, so skipping them is
proven rather than assumed).

It then asserts the rows: native uuid identity, prompt and response
text, model, the usage the `api_request` event carried, the cwd the hook
recorded, the OTEL producer marker, and the transcript-only columns
reading null. A replayed batch adds nothing. `hyp backfill claude` over
a transcript carrying the same uuids also adds nothing, which is the
proxy-to-OTEL overlap window in miniature. A `text/plain` POST is
refused with 415. The capture spans and the batch log carry the counts
that prove the intended path ran.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The claude settings writer gains an otel mode behind a version floor (LLP 0258)

A third attach mode beside base_url and proxy: `otel` merges the LLP 0258
#env-keys telemetry block into the settings env block and writes nothing
that routes traffic, so the endpoint stays first party and Remote Control
needs no override keys. The mode reuses the whole marker machinery
unchanged (managed env, prev_env backups, atomic mtime-gated writes, JSONC
refusal, releaseUnmanagedKeys for mode switches), records the spool
directory on the marker for detach and purge to sweep (LLP 0258
#marker-and-spool, LLP 0253), and refuses below Claude Code 2.1.193 with a
`claude update` hint, leaving any existing attach byte-identical (LLP 0258
#version-floor, no fallback to any other mode).

claude_version.js owns the floor: numeric triple parse and compare
("2.1.193" must not sort below "2.1.9"), unknown-is-not-old, a best-effort
`claude --version` probe, and the HYP_CLAUDE_CODE_VERSION override that
keeps hermetic smokes independent of whatever binary the machine carries.
telemetry/spool.js owns the spool path contract: <hyp-home>/spool/
claude-bodies, created 0700 (LLP 0253 #spool-location).

Adopted from the crash-debris-806 stash after review; the malformed mode
doc block in types.d.ts is repaired.

Part of #806 (spec #798, RFC LLP 0245).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* hyp attach claude writes the telemetry env block in otel mode (LLP 0258)

The adapter's attach handler switches its non-proxy branch from base_url
to otel: with no local CA (no proxy-mode gateway) it probes the Claude
Code version, resolves the listener port, and hands the writer the otel
mode. The spool directory is created owner-only right after the settings
write. A CA-bearing install still attaches by proxy; migrating it to otel
is ticket #807.

The endpoint's port resolves in trust order: the live daemon's bound port
from status.json (pid-gated, via the new core
resolveLiveSourceListenPortFromStatus, the generic sibling of the gateway
endpoint resolver), then a configured fixed telemetry.listen_port, then
the well-known default. That is the promise that makes the listener's
default-port bind fallback safe. The marker keeps recording the gateway
port, so the attach-drift check is unchanged.

Smokes pin the new surface: claude_attach_detach golden-compares the
exact nine-key env block, the absence of every routing key (the Remote
Control predicate as absences), the marker's mode and spool_dir, and the
0700 spool; client_attach_idempotent adds a below-floor refusal leg
(exit 1, `claude update` hint, settings byte-identical) beside the
attach/detach cycles; client_attach_on_join proves the daemon's org-driven
attach delivers the same block and that drift now shows in the marker
port; the walkthrough asserts init's real attach lands otel. All four pin
HYP_CLAUDE_CODE_VERSION so no flow depends on the machine's own claude.

Closes #806 (spec #798, RFC LLP 0245).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Spooled body files fill the projection gaps events never carry (LLP 0252)

Body events (api_request_body / api_response_body) join the projection
through their body_ref: the request body supplies system_text, the tools
list, and canonical message ordering; gap blocks (tool_use with
untruncated args, tool_result, thinking with its signature) become their
own projected messages with a minimized pointer-only raw_frame, matching
the proxy path's excerpt policy. Text blocks are never re-projected: the
events already delivered them once under native uuid identity. A ref
outside the spool is refused (the listener deletes what it reads, so an
uncontained ref would be a read-and-delete primitive over the whole
filesystem), a missing body counts as evicted, and an unparseable one is
deleted rather than retried forever. Session-level body facts carry
across exporter batches, bounded oldest-first.

Ticket: #804 (spec #798, RFC 0245).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The daemon caps the body spool and the listener consumes it (LLP 0253)

The listener repairs the spool to owner-only on every start, enforces
the byte cap (telemetry.spool_max_bytes, default 512 MB) at start and on
a timer, and evicts strictly oldest-first (mtime, then name) when the
cap is exceeded: the sweep exists exactly for the window where Claude
Code writes bodies and nothing consumes them. At ingest the referenced
bodies are read, projected, and deleted only after the dataset write
succeeded, so a failed write becomes an HTTP error the exporter retries
against the same files. Status details gain the spool byte size and the
projected / evicted / missing body counts, and eviction is logged with a
count so a machine routinely losing detail to backfill is visible.

Ticket: #804 (spec #798, RFC 0245).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The telemetry smoke joins body fixtures and recovers an evicted session (LLP 0257)

The hermetic flow now drops real-shaped request and response body files
into the spool and proves the join end to end: system_text and the tools
list on every row, the full 600-char tool args the event-side clip would
have truncated, the tool result, the thinking signature, a pointer-only
raw_frame, and both files DELETED after projection. A pre-staged
over-cap body is evicted by the startup sweep (config-driven cap,
oldest-first, visible in status and logs) and its session still
completes: the events land at ingest and transcript backfill recovers
exactly the tool rows the evicted body held, under native identity. The
spool directory a client created loose is tightened to 0700.

Ticket: #804 (spec #798, RFC 0245).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Behavioral events land in their own claude_telemetry_events dataset (LLP 0255)

The first dataset @hypaware/claude owns: a manifest contributes.datasets
entry plus a registration at activation, with the claude_telemetry
source signal so central forwarding never falls back to the dataset
name. One row per event, hot fields typed (event name, timestamp,
session id, tool name, decision, source, cost), every remaining
attribute preserved in a JSON column; a hot key whose value does not
fit its typed column stays in the JSON rather than vanishing, and an
event name we do not model still lands (LLP 0257 S20).

The split is behavioral-vs-conversation: user_prompt and
assistant_response stay in ai_gateway_messages, the body-pointer events
are transport, and everything else becomes a row - including the
metrics half of the exporter config, which the listener previously
dropped: claude-scope metric data points (cost, lines of code, active
time) flatten into the same event shape, one row per data point.

The listener writes the behavioral rows only after the message write
succeeded, so an exporter retry after a failure re-attempts a write
that never happened; there is deliberately no pre-write dedupe (single
producer, one POST per batch), and the lost-success-response window
produces byte-identical rows compaction's content-hash layer collapses.

No localOnlyContentColumns declaration: the LLP 0105 wrapper would null
the attributes column for every ordinary caller (no row here carries a
cwd to prove itself with); this dataset's privacy seam is the inline
ingest drop of LLP 0254 #policy-inline, ticketed as #808.

The activation-context test stubs gain the query registry the real
kernel always wires in.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The telemetry smoke reads behavioral events back from claude_telemetry_events (LLP 0255)

The batch grows tool_decision (reject, with its source) and the hook
execution pair beside the existing permission_mode_changed and
tool_result, then hyp query sql asserts the behavioral half: one row
per event in timestamp order, content and body events absent, hot
fields typed and lifted out of the attributes JSON, the unpromoted
attributes (from_mode/to_mode, hook identity and outcome, token counts)
readable through JSON_VALUE. A /v1/metrics POST lands its two data
points as rows named by their metrics, value and unit joined.

The registration surfaces are asserted too: hyp query status enumerates
the dataset beside ai_gateway_messages, and the registration carries
the claude_telemetry source signal. The replayed batch's behavioral
rows double by design (no pre-write dedupe; compaction's content-hash
layer owns the collapse), asserted explicitly so a future dedupe is a
conscious change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The session-ignore control handler becomes shared core machinery (LLP 0256)

A second recorder is about to host the same /_hypaware/ignore/session
route the gateway proxy hosts, and LLP 0256 wants one route shape with
one set of tests rather than a copy per plugin. So the handler (and the
reserved-prefix recognizer) moves from ai-gateway/src/control.js to
src/core/control/session_ignore.js, the same way LLP 0257 S2 moved the
OTLP http/json server into core. The mutation log's event name and
identity fields become caller-supplied so each host keeps its own signal
shape; the defaults keep the gateway's exactly, and no behavior changes.

The route test moves to test/core with it, per LLP 0256's consequence
that the route's tests live at the shared shape.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The claude listener hosts session ignore and drops the session at ingest (LLP 0256)

The shared OTLP http/json server gains the same reserved-prefix seam the
gateway proxy has: an optional control handler owns /_hypaware/* before
any OTLP routing. The claude telemetry listener registers the shared
session-ignore handler over its own in-memory set (nothing on disk, dies
with the process), so /_hypaware/ignore/session answers identically on
both recorders.

Ingest enforces the set on both signals: events whose session.id is in
the set are partitioned out before the spool is read, so nothing of the
session reaches ai_gateway_messages or claude_telemetry_events, and the
dropped session's spooled bodies are DELETED unread under the same
spool-containment rule as the read path (LLP 0253 delete-on-drop). Each
drop emits the usage_policy_drop signal with policy_source
session_opt_out, and the source status reports the live set size plus
the drop counters.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* hyp session ignore posts to every recorder that offers the route (LLP 0256)

A recorder that hosts the session-ignore route now says so itself: the
claude listener advertises control_routes in its status details, and a
new core resolver reads every such advertisement out of a LIVE daemon
snapshot. The mutations address the gateway (its own two-rung
resolution, unchanged) plus every advertised recorder, so the
client-agnostic verb never carries a list of client plugins, and a
listener that is not running is simply not addressed - it records
nothing, so its absence is not a failure.

Each outcome is reported: the receipt keeps its legacy top-level fields
(the gateway's answer) and gains a recorders array naming every write;
the human output prints one line and one responder-trust disclosure per
addressed endpoint. An addressed recorder that refuses makes the verb
report partial and exit unknown - the refusing recorder is the one still
recording, so the write must not read as done. Single-recorder installs
keep byte-identical receipts apart from the new array.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* A privacy smoke drives session ignore through both recorders (LLP 0257 S25)

claude_telemetry_session_ignore boots the real daemon, ignores a session
through hyp session ignore (asserting the receipt names the gateway and
the claude listener, and that each control route confirms membership
directly, so the gateway's own route is proven undisturbed), then posts
the ignored session's events, bodies, and metrics: zero rows land in
either dataset, the spooled body is deleted unread, and the drop signal
fires with policy_source session_opt_out. unignore restores capture for
the same session, whose resumed body is projected then deleted normally.
A clean session lands beside the drop throughout, isolating the effect.

PRIVACY.md's pausing-a-session passage now names both recorders and the
listener's delete-not-skip duty for spooled bodies.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* hyp status renders a capture-health line for otel-attached clients (LLP 0257 S17)

On the otel path capture is best-effort, so a stale endpoint, a down
daemon, and upstream event drift all fail into the same silence while
every other status line stays healthy. This is RFC 0245 open question
1's duty: the gap becomes a line, and past a threshold a diagnostic.

The comparison has two sides. The listener source now publishes
last_event_at unconditionally (null before the first event), so its
presence marks the snapshot as the telemetry listener's, the same
self-advertisement pattern as control_routes; status reads it from
status.json without a liveness gate (the LLP 0164 argument: last seen
at T survives its daemon, and the dead-daemon window is precisely the
gap to surface). The client's own side is a new manifest-declared
activity_probe (dir + file suffix, the settings_file home-relative
contract) that core stats fresh for the newest transcript mtime, so a
daemon that was down while the user worked cannot hide the loss.

assessCaptureHealth is pure: the baseline is the newer of the last
event and the marker's attached_at, so months of pre-attach
transcripts prove nothing right after a migration, and a listener
that never saw an event is measured from the attach. Fifteen minutes
past baseline is a warning; two hours escalates to an error that
degrades overall, because an attached machine silently losing
sessions is an outage, not an unfinished setup. The attach probe also
reads the marker's mode and attached_at, gating the section to
otel-attached configured clients and carrying mode into --json.

Part of #810 (spec #798, RFC LLP 0245).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* A capture-health smoke drives hyp status through lockstep, gap, and detached (LLP 0257 S17)

Modeled on status_diagnostics: one otel-attached claude install (marker
plus transcript trail under a fake $HOME, listener detail under
status.json, no daemon alive - the comparison must survive its daemon)
driven through three states. Lockstep renders the line and stays
healthy; transcripts hours past the last event turn --json's
capture_health entry to gap, fire the capture_gap diagnostic at error
severity with the attach repair hint, and degrade overall while the
text surface tags the line; removing the marker empties the array and
silences the section. Span assertions pin the healthy and degraded
status.render runs.

Part of #810 (spec #798, RFC LLP 0245).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* hyp attach claude migrates a proxy attach to otel in one command (LLP 0245)

The adapter stops choosing proxy mode off the CA on disk: otel is the
claude client's only attach mode now, so an attach on a proxy-attached
machine IS the migration. The settings write releases the proxy keys
through the ordinary mode-switch rule and reports the prior marker mode;
on 'proxy' the adapter unwinds the launchd environment (darwin,
best-effort, mirroring the detach undo's release) and prints the
migration story, ending with the one residue that stays the user's call:
the CA trust, offered as 'hyp detach claude --purge' and never run for
them. Below the version floor the refusal still fires before any I/O, so
a too-old client keeps its working proxy attach byte for byte.

The proxy-only attach machinery this retires from the adapter
(ensureDarwinProxyTrust, the CA preflight read, the Cmd-Q relaunch note)
goes with it; detach's own launchd release and the purge path are
untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* hyp status names the attach mode on the text surface (LLP 0245)

--json has carried client_attach[].mode since the marker grew one; the
text line a human reads still said only 'attached', so a machine the
migration just moved from proxy to otel looked unchanged from the surface
that matters. The mode now rides the attached state ('attached (otel)');
markers that predate modes keep the bare word, and the not-attached and
probe-error shapes are untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The migration overlap window collapses to one row set (LLP 0245)

Sessions started before the mode flip keep proxying while new events
arrive over OTEL, so for a while both producers capture the same session.
These tests pin what makes that harmless: the proxy projector's native
transcript identity and the telemetry projection's message.uuid identity
yield the same part_ids for the same content, and the OTEL producer's
pre-write dedupe therefore drops every part the proxy already stored,
whole or half. Either arrival order collapses, because the proxy's
flush-time dedupe asks the same committed-part_id membership question.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The migration's CA offer stops claiming a trust it never verified (LLP 0245)

A proxy attach whose keychain dialog was refused still ran and still left
the CA on disk, so the migration telling that user their CA "is still
trusted in your login keychain" is the one false line in an otherwise
honest story. The offer now names the CA and any trust it was granted,
which is exactly what 'hyp detach claude --purge' removes either way.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* hyp status proves the migrated mode through the real collector (LLP 0245)

The migration tests probed the marker directly and the renderer tests fed
themselves fabricated client rows, so nothing joined the two: the claim
that 'hyp status reflects the new attach mode' held only if the collector
in between happened to carry `mode` through. The rig now writes the
install config a real machine has, and one test drives
collectHypAwareStatus plus renderStatusText over the same temp home before
and after the one command: 'attached (proxy)' becomes 'attached (otel)'.

The three non-migrating attach shapes (floor refusal, re-attach, base-URL
switch) also assert no launchd line, which is what the residue unwind
prints on darwin when it runs at all - the negative half of "the unwind
happens on a proxy migration and nowhere else".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* hyp purge and detach empty the raw-body spool (LLP 0253)

The spool holds raw request and response bodies no row has been made from yet,
so the two verbs that exist to get rid of captured data have to reach it: a
purge that leaves it lets the next received batch write back rows the user just
deleted, and a detach that leaves it strands raw prompts in our own directory.

Core learns the root (`<hyp-home>/spool`) and the claude plugin's directory
becomes a child of it, so `hyp purge` empties every client's spool without
naming a plugin. Detach takes the path off the attach marker instead, because
the config that produced it is gone by then - which makes it settings-file
input, so it is honored only when it is a direct child of this install's spool
root. Without that gate, "empty the directory the marker names" would be a
recursive delete pointed anywhere a hand edit chose.

Every purge target sweeps, targeted ones included: a spooled body has not been
read, so nothing about it says which directory or session it belongs to.
Neither sweep can fail its caller - the destructive work has already landed by
the time it runs, so an unreadable entry is a reported count, not a thrown
error.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The folder usage policy decides at ingest on the OTEL path (LLP 0254)

.hypignore and the machine-local list are resolved per session from the cwd the
SessionStart hook recorded, before the spool is read and before either dataset
is written. An ignored session's events project nothing and its spooled bodies
are deleted unread, so the transport keeps working and the content goes.

The machine-local list is threaded from the SHARED state root, the same path
the export and query seams read. The per-plugin state directory has no list
file, so a resolver built from it silently sees `.hypignore` dotfiles only, and
a `--private` directory would have recorded here after being dropped everywhere
else.

A session with no hook record has no cwd and so no verdict. It is withheld
rather than recorded: writing first and resolving later is the fail-open window
LLP 0085 exists to patch, and this path has no flush-time late drop to patch it
with. The content is still in the Claude Code transcript, which is what the
signal names as the recovery path, and the withhold is counted in status so a
machine whose hook is missing reads as blind rather than idle.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* A privacy smoke drives .hypignore through the telemetry listener (LLP 0257 S25)

The OTEL-path analog of hypignore_capture_drop, with four sessions posted at a
live listener: one clean, one under a `.hypignore`, one on the machine-local
list with no dotfile anywhere near it, and one with no SessionStart record at
all. Only the clean session's rows land, in either dataset, every suppressed
session's staged body is gone from the spool, and each drop signal names what
governed it.

The machine-local case is the one that catches a wiring regression nothing else
would: its verdict is only reachable if the listener reads the list from the
shared state root. The hookless case pins the fail-open window closed.

PRIVACY.md gains the spool as a named surface, since it is a directory of raw
prompts under the user's own home: what it is for, that a dropped session's
bodies are deleted unread, that it is capped, and that purge and detach empty
it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The glossary stops saying attach rewrites a base URL (LLP 0258)

The client-source gloss described one attach mechanism as if it were the
only one; it has been wrong since proxy mode shipped and is wrong twice
over now that the claude client attaches by telemetry. The gloss now says
what attach means and defers the how to a new Attach entry that names the
three modes and what each one costs the user.

Also records the distinction the OTEL path invites a reader to get wrong:
`@hypaware/claude` running an OTLP listener does not make claude an `otel`
source. It stays a client source, autodetected and configured for the
user; the `otel` picker source is what someone turns on for their own app.

Discharges the glossary duty in the RFC's implementation spec
(#798, #811).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* A release gate checks the OTEL shapes against the installed Claude Code

LLP 0245 open question 5 leaves flag stability detected two ways: the
`hyp status` capture-health line in production, and a shape assertion
against the real client at release time (LLP 0257 S21). The second one
had no written form until now.

`claude_otel_shape_check` walks a human through it: assert the nine-key
env block on disk, take a raw body sample with the daemon deliberately
stopped (the only way to read a file the listener otherwise deletes on
sight), assert the body fields the projector fills its column gaps from,
then hold a real conversation and read the event names, the event
attributes, the message columns, and the capture-health line back out.

The event-name query doubles as the drift detector, because an event the
listener does not model is recorded rather than dropped: the step asks
for the whole list in the release notes, not a verdict, so the next
release has something to diff against.

The release checklist now names it for any release touching the claude
adapter, and says why the hermetic smoke cannot stand in for it: a smoke
POSTs a fixture we wrote, so it agrees with itself no matter what
upstream did. Also lists `openclaw_capture`, which has had a written
procedure for a while without appearing here.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The README describes the attach Claude Code actually gets (LLP 0245)

The proxy-mode section opened by telling the reader that `hyp attach
claude` points ANTHROPIC_BASE_URL at the gateway and that proxy mode is
the opt-in that saves Remote Control. Neither is true on this branch:
claude has one attach mode, `otel`, and Remote Control survives it for
free because no base URL and no proxy are written at all.

Claude Code gets its own section covering what attach writes, where the
raw bodies go and when they are deleted, the version floor and its
refusal, and the proxy-to-OTEL migration. The proxy-mode section keeps
everything true of a client that still proxies (the CA, the decryption
aperture, the corporate-proxy chain) with the claude-specific framing
taken out.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The shape check waits out an export interval before calling it broken

Claude Code batches its OTLP exports, and the metrics exporter runs on a
longer interval than the logs one. Checking the spool or the event list
immediately reads "not yet" as "the listener is not consuming", which is
the one wrong answer a release gate must not give. The two steps now wait
and say why.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* RFC 0245 renumbered to 0262: open PR #815 claimed 0245

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* RFC 0262 and the docs it spawns are Accepted

Phil accepted the RFC and its spawned decisions and spec on 2026-08-17; the
conditional forward-ref phrasing in the displaced proxy-attach docs is firmed
up to match.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The 0245 renumber reaches the test tree's @refs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Review round 1: the daemon stops minting the body spool, and status stops printing a raw marker mode

Three review findings on the OTEL attach path, all narrow:

- The telemetry listener called `ensureClaudeBodySpool` on every source
  start, so a daemon created `<hyp-home>/spool/claude-bodies` on machines
  that never attached the claude client, against whatever HYP_HOME the
  activation context resolved. `activatePlugins` does not thread the
  daemon's env, so ctx.env is `process.env`: running `npm test` without
  `HYP_HOME` demonstrably created the directory in the developer's real
  `~/.hyp`. Attach is what mints the spool (the same write tells Claude
  Code where to put bodies), so the daemon now repairs a directory it
  finds (`tightenClaudeBodySpool`) and creates none.

- `hyp attach claude` ran the spool mkdir inside the same try as the
  settings write, so an unwritable spool root reported a failed attach
  after the settings file had already been rewritten, and swallowed the
  migration notes with it - including the `hyp detach claude --purge`
  line a migrated machine needs. It is now its own try; the failure rides
  the existing warnings list, counted apart from
  `malformed_blocks_repaired` so that count keeps meaning one thing.

- `hyp status` interpolated the attach marker's `mode` into the clients
  row raw. The mode is read back off the client's own settings file, so
  it is a captured label, not an in-process constant; it now goes through
  the same `printable` every other disk-derived label on that surface
  uses (LLP 0225).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Review round 2: hyp status compares where claude exports against where the listener listens

An `otel` attach writes one `OTEL_EXPORTER_OTLP_ENDPOINT` into the client's
settings and nothing ever rewrites it. Two ordinary sequences move the
listener out from under it:

- attach ran with no live daemon, so `resolveAttachTelemetryPort` could only
  write the well-known default, and the daemon later found that port taken
  and fell back to an ephemeral bind (LLP 0114 #ephemeral-fallback);
- `telemetry.listen_port: 0` plus a daemon-down attach, where the default is
  written for a port the config guarantees will never be bound.

Either way Claude Code keeps POSTing at the port it was told about, with
`OTEL_LOG_USER_PROMPTS` and `OTEL_LOG_ASSISTANT_RESPONSES` on, and every
other line in `hyp status` stays healthy. `client_attach_stale` does not
cover it: that comparison watches the gateway, which this mode never talks
to. The capture-health gap line eventually notices the silence, but only
after fifteen minutes of transcript activity and without naming the cause.

Both ports are already on disk. The probe now lifts the marker's managed
`OTEL_EXPORTER_OTLP_ENDPOINT` port (the live value the client is using, not
a parallel field that could disagree with it), and the capture-health block
compares it against the listener's live `listen_port`, raising a
non-degrading `client_telemetry_stale` naming both ports and the repair.
Liveness-gated, unlike `last_event_at` beside it: a dead daemon's snapshot
cannot say where anything is bound now, and a restart is what moves the port
back. A marker with no endpoint, or one that does not parse to an in-range
port, makes no claim at all.

This is LLP 0114 #fallback-is-visible applied to the new listener - the half
of that decision the listener had adopted the fallback without - and LLP 0257
gains S17b to record it.

Does not prevent the exposure, only makes it loud: whether attach should
refuse to write an endpoint no daemon has confirmed is a design call, left
for a human.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Review round 2: a restarted daemon stops reporting a month-long capture gap, and a failed listener start owns nothing

Two defects in the new listener, both found by re-reading the start path.

The capture-health baseline could not survive a daemon restart.
`state.lastEventAt` lives only in the listener's process, so every restart
republishes `last_event_at: null` however long capture has been healthy.
`assessCaptureHealth` then fell back to the attach timestamp, which on a
machine attached a month ago and used an hour ago yields a month-long gap:
severity `error`, degrading `overall`, on an install that is capturing
perfectly. The first repair the diagnostic prints is `hyp daemon restart`,
so the advice reproduced the finding. The listener now publishes
`listener_started_at`, and the gap is measured from the newest of the last
event, the attach, and a LIVE listener's start - live only, because on a
dead daemon the last one's start bounds nothing and the growing gap is
exactly what the line exists to surface. The null-events message stops
saying "after the attach", which is no longer always the baseline it used.
`listener_started_at` rides the capture-health report and `--json` so the
reason a gap is or is not claimed is readable.

The spool sweep timer was armed before the bind. `stop()` is the only thing
that clears it, and a `start()` that throws never returns a handle to call
`stop()` on, so an explicit-port bind failure (LLP 0114
#explicit-listen-fails-loudly) left an interval scanning the spool every
minute for the life of the daemon on behalf of a source that does not
exist. `unref()` kept it from holding the process open, which is why it
would never have been noticed. The one-shot sweep still runs before the
bind - bodies already on disk are over the cap either way - and only the
repeating one waits for a listener to be behind it.

LLP 0257 gains S17c for the restart baseline. Tests: five in
test/core/status-capture-health.test.js covering the restart, a listener up
long enough for the gap to be real, an event outranking the listener start,
the live-daemon and dead-daemon halves end to end; and a new
test/plugins/claude-telemetry-start-failure.test.js that counts `setInterval`
arming across a failed start, because an unref'd timer does not appear in
process.getActiveResourcesInfo() - verified to fail against the old order.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Review round 2: otel attach names the OTLP keys that outrank the endpoint it wrote

In the OTLP environment-variable contract a per-signal key beats the generic
one, so `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` decides where log records go
whatever `OTEL_EXPORTER_OTLP_ENDPOINT` says. Nothing in the tree mentioned
those keys.

That leaves one shape worth saying out loud: a machine already exporting to
its own collector through a per-signal key gets `OTEL_LOG_USER_PROMPTS`,
`OTEL_LOG_ASSISTANT_RESPONSES` and `OTEL_LOG_TOOL_DETAILS` switched on by
this attach, and its prompts and assistant responses start flowing THERE,
while `hyp status` reports `attached (otel)` and the listener sees nothing.
`OTEL_EXPORTER_OTLP_HEADERS` is the same hazard from the other side: it
carries a collector's credentials and would now ride requests aimed at our
loopback listener.

The managed set is untouched - LLP 0258 #env-keys is "exactly these keys,
and only these", and it is Accepted. Attach now warns per offending key
instead, on the same warnings list every other attach notice rides. A
warning rather than a refusal because attach cannot see a key exported from
the user's shell, so refusing on the half it can see would buy a false sense
of completeness. Values are never echoed: an endpoint or a headers value is
exactly where a collector token lives, and this string is printed, logged,
and serialised into `--json`.

Two tests in test/plugins/claude-settings-otel-attach.test.js: the warning
fires per key, echoes neither the collector nor the credential, and leaves
the keys themselves untouched and unmanaged; and an ordinary attach still
warns about nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* The client hook enforces the body spool cap too, so a down daemon is bounded (LLP 0263)

LLP 0253 #byte-cap named the daemon-down window as the reason the spool's
byte cap exists, then shipped every enforcement inside the listener source,
so the window it named was the one window nothing swept. Claude Code keeps
writing raw request and response bodies whether or not the daemon reads them,
at roughly 145 KB per request, and the daemon is legitimately absent for a
crashed service, a machine where one was never started, an uninstall that
skipped detach, and the attach-before-first-start path the port resolver
deliberately supports. With OTEL_LOG_USER_PROMPTS and
OTEL_LOG_ASSISTANT_RESPONSES on, that is unbounded retention of raw prompts,
not just a disk nit.

`hyp claude-hook session-context` now enforces the same cap on its way out.
It is the right second enforcer because attach already installs it on
SessionStart, CwdChanged, UserPromptSubmit and PostToolUse/Bash (LLP 0085),
so it runs at exactly the cadence bodies are written and the spool cannot
outrun it, and because it needs nothing the daemon owns. It deletes only what
the daemon's sweep would have deleted: the same enforceClaudeBodySpoolCap,
same directory, same oldest-first order, same operator cap read from the same
telemetry.spool_max_bytes key. The hook never widens the rule, it runs the
existing one while the daemon cannot.

The sweep goes last so it can never delay the session-context records the
projector waits on (LLP 0085), and runs on every invocation including the
ones that record nothing, because a malformed event says nothing about
whether the spool is filling. A sweep failure is swallowed, as is the
recording half, so the hook still exits 0.

LLP 0263 carries the decision and 0253 gains the Extended-by forward-ref.
Nine tests drive the hook with no daemon anywhere: four of them fail if the
sweep call is removed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* LLP 0263 is Accepted

The last Draft in this change set joins LLP 0252-0258 and 0262 at Accepted,
so every doc PR #818 lands is approved for implementation and the code
already on the branch cites settled decisions rather than a draft.

Accepted, not Active: the lifecycle reserves Active for built AND merged,
and #818 is still an unmerged draft. All nine flip together at merge.

Status only. Nothing 0263 settles was edited, and it carries no [inferred]
claims to retire.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: test <test@test.com>

Author: 3 people

AGENTS.md

@@ -96,6 +96,16 @@ Written acceptance procedures:
   Proves Desktop traffic reaches `ai_gateway_messages` by both the live
   gateway route and the `~/.codex/sessions` backfill route, and is
   attributable via `entrypoint`. See `docs/ACCEPTANCE.md`.
+- `openclaw_capture`: opt-in/manual, needs OpenClaw with both `anthropic` and
+  `openai` credentials. Proves both capture lanes (live gateway and the
+  scheduled transcript sweep) and that a turn both lanes observe settles to
+  one row. See `docs/ACCEPTANCE.md`.
+- `claude_otel_shape_check`: opt-in/manual, needs a real Claude Code 2.1.214
+  or newer. The release gate against upstream drift on the OTEL attach path:
+  proves the installed Claude Code still honors the managed `env` block and
+  still emits the event names, attributes, and raw body fields the telemetry
+  listener reads, then checks the rows and the `hyp status` capture-health
+  line agree. See `docs/ACCEPTANCE.md`.
 
 Good acceptance smoke candidates (no written procedure yet):
 
@@ -171,6 +181,7 @@ src/
     cli/                # dispatch, walkthrough, core_commands
     config/             # v2 schema, validator
     daemon/             # platform installers (launchd / systemd) + lifecycle
+    otlp/               # shared OTLP http/json listener machinery
     plugin_install/     # resolver, fetch, lock, update_check
     sinks/              # cron driver + encoder utility
 hypaware-core/
@@ -210,6 +221,7 @@ hyp smoke walkthrough_picker_to_first_query
 hyp smoke client_attach_idempotent
 hyp smoke gateway_claude_capture
 hyp smoke gateway_codex_capture
+hyp smoke claude_telemetry_capture
 hyp smoke hypignore_capture_drop
 hyp smoke local_only_export_withhold
 hyp smoke source_optout_export_withhold
@@ -236,6 +248,18 @@ If the release touched a client adapter, run the matching procedure in
 [`docs/ACCEPTANCE.md`](docs/ACCEPTANCE.md) and record the result in the
 release notes.
 
+If the release touched the **claude** adapter (`@hypaware/claude`, the
+telemetry listener, the body spool, or the attach settings writer), the
+matching procedure is
+[`claude_otel_shape_check`](docs/ACCEPTANCE.md#claude_otel_shape_check). It is
+not optional for those releases and it is not substitutable by the hermetic
+smokes: `claude_telemetry_capture` POSTs a fixture we wrote, so it agrees with
+itself no matter what upstream did. Only a real Claude Code can tell you it
+renamed an event, dropped a flag, or changed the raw body format, and the
+failure mode is silent (null columns, not an error). Record the observed
+`claude --version` and the full event-name list in the release notes so the
+next release has a baseline to diff against.
+
 <!-- neutral:llp-conventions -->
 ## LLP conventions
 

CONTEXT.md

@@ -15,10 +15,9 @@ offers `claude`, `codex`, and `otel`, the two raw proxy rows being **hidden**
 
 - **Client source**: a known tool HypAware configures for you. `claude` and
   `codex` are the client sources. Picking one adds its gateway upstream *and*
-  its adapter plugin (`@hypaware/claude` / `@hypaware/codex`), which attaches
-  the tool (rewrites its base URL), installs hooks/skills, and can backfill
-  its local history. Client sources are the only sources that can be
-  [[autodetect]]ed.
+  its adapter plugin (`@hypaware/claude` / `@hypaware/codex`), which
+  [[attach]]es the tool, installs hooks/skills, and can backfill its local
+  history. Client sources are the only sources that can be [[autodetect]]ed.
 - **Raw proxy source**: `raw-anthropic` / `raw-openai`. Picking one opens the
   gateway with that provider upstream but configures no client; the user
   points their own SDK app or script at the local gateway by hand. Serves the
@@ -31,6 +30,38 @@ offers `claude`, `codex`, and `otel`, the two raw proxy rows being **hidden**
 OpenTelemetry signals. Like a raw proxy source, it is manual and not
 autodetectable.
 
+An `otel` picker source is not the same thing as "a source that speaks OTLP".
+`@hypaware/claude` runs its own OTLP listener to receive Claude Code's
+telemetry ([[attach]] mode `otel`, LLP 0257), on its own port, with its own
+payload rules and its own datasets. That listener is claude-owned: a machine
+attached that way still has `claude` as a **client source** here, autodetected
+and configured for the user, and nothing about it turns on the `otel` source.
+Picking `otel` is what a user does for *their own* app's telemetry.
+
+### Attach
+
+Writing a reversible block into a **client source**'s own configuration so that
+what the tool does reaches HypAware, and being able to take it back out.
+`hyp attach <client>` writes it, `hyp detach <client>` removes exactly those
+keys and restores anything they displaced, and the undo record (the `_hypaware`
+marker) lives in the file that was edited.
+
+Attach is not one mechanism. Each client adapter picks a **mode**, and
+`hyp status` names it (`claude  [configured, attached (otel)]`):
+
+- **`base_url`**: point the tool's API base URL at the local gateway. `codex`
+  attaches this way.
+- **`proxy`**: set `HTTPS_PROXY` and trust a machine-local CA, so the gateway
+  sees the tool's TLS traffic without its base URL being touched (LLP 0232).
+- **`otel`**: turn on the tool's own OpenTelemetry export and point it at a
+  HypAware listener (LLP 0258). No base URL, no proxy, no CA: the tool still
+  talks straight to its provider and HypAware receives a copy of what it did.
+  `claude` attaches this way.
+
+The mode is worth naming because it decides what being attached costs: only
+`proxy` installs CA trust, and only `base_url` and `proxy` put the HypAware
+daemon on the request path.
+
 ### Autodetect
 
 The first-run wizard inspecting the system for the presence of a **client

README.md

@@ -276,16 +276,46 @@ client's own config file (for example `~/.claude/settings.json` for
 Claude, a `hypaware` provider entry in `~/.codex/config.toml` for
 Codex); unrelated keys in every file are preserved.
 
-### Proxy mode (keeps Claude Code's Remote Control working)
-
-By default `hyp attach claude` points `ANTHROPIC_BASE_URL` at the local
-gateway. Claude Code disables **Remote Control** whenever that variable
-points anywhere other than `api.anthropic.com`, so an attached machine
-loses it.
-
-Proxy mode avoids that by leaving the base URL alone and routing Claude
-Code through the gateway as an HTTPS proxy instead. Turn it on in the
-`ai-gateway` section of `~/.hyp/hypaware-config.json` and restart the
+### Claude Code attaches by telemetry, not by proxy
+
+`hyp attach claude` writes one reversible `env` block into
+`~/.claude/settings.json` that turns on Claude Code's own OpenTelemetry
+export and points it at a loopback listener the daemon runs. It leaves
+`ANTHROPIC_BASE_URL` alone, sets no proxy, and installs no certificate
+authority, so Claude Code still talks straight to `api.anthropic.com`,
+**Remote Control keeps working**, and a daemon that is down or wedged costs
+you capture rather than your session. Nothing has to be quit and reopened:
+Claude Code reads the `env` block at launch, on every launch path.
+
+Two things ride along with the conversation rows:
+
+- **Raw request and response bodies** land in `~/.hyp/spool/claude-bodies`
+  (owner-only) until the listener projects them and deletes them. They carry
+  what the events do not: the system prompt, the tool list, and untruncated
+  tool arguments. The directory is capped (512 MB by default, oldest evicted
+  first), and both `hyp purge` and `hyp detach claude` empty it.
+- **Behavioral signals the wire never showed** land in their own
+  `claude_telemetry_events` table: tool accept and reject decisions,
+  permission mode changes, per-request cost, hook and MCP health.
+
+Claude Code **2.1.193 or newer** is required (2.1.214 for the full
+tool-decision detail). Below the floor, attach refuses the switch, leaves any
+existing attach exactly as it is, and prints `claude update`, rather than
+silently capturing less.
+
+`hyp detach claude` removes exactly those keys, restores anything they
+displaced, and sweeps the spool.
+
+If this machine was attached by proxy before, `hyp attach claude` is also the
+migration: it releases the proxy keys, unwinds the launchd environment, and
+tells you how to end the CA trust that it will not end for you
+(`hyp detach claude --purge`).
+
+### Proxy mode (TLS interception for the clients that still proxy)
+
+Claude Code no longer uses this path. It remains how the gateway captures a
+client that cannot simply be pointed at a different base URL. Turn it on in
+the `ai-gateway` section of `~/.hyp/hypaware-config.json` and restart the
 daemon:
 
 ```json
@@ -294,37 +324,35 @@ daemon:
 
 ```sh
 hyp daemon restart
-hyp attach claude
 ```
 
-On the next attach, HypAware sets `HTTPS_PROXY` and `NODE_EXTRA_CA_CERTS`
-instead of the base URL. What this changes:
+Such a client is then pointed at the gateway with `HTTPS_PROXY` and
+`NODE_EXTRA_CA_CERTS` rather than a base URL. What that changes:
 
 - **A machine-local certificate authority is generated** under
   `~/.hyp/hypaware/tls`, readable only by you, and name-constrained so it
   cannot vouch for any host outside the provider set HypAware intercepts.
-  On macOS, attach also adds it to your **login keychain** as a user-domain
-  trusted root, because Claude Code's Remote Control transport trusts only
-  the keychain: macOS raises its own password dialog, and declining it
-  leaves capture working with Remote Control's inbound channel off. No admin
-  rights are needed and the machine-wide system keychain is not touched. On
-  other platforms trust stays file-scoped to Claude Code's own settings.
-  `hyp status` shows the fingerprint and whether the keychain still trusts
-  it. `hyp detach claude` keeps the CA and the trust, so re-attaching does
-  not ask again; `hyp detach claude --purge` and `hyp daemon uninstall`
-  remove both.
-- **Only `api.anthropic.com` is decrypted**, because that is the only host
-  a registered upstream names. Every other host Claude Code talks to is
-  tunnelled through without being decrypted.
-- **What gets recorded does not change.** Only `/v1/messages` is recorded,
-  exactly as before; the other paths Claude Code calls on that host are
-  passed through without being stored.
+  On macOS it can also be added to your **login keychain** as a user-domain
+  trusted root, for a client whose transport trusts only the keychain: macOS
+  raises its own password dialog, and declining it leaves capture working
+  with that inbound channel off. No admin rights are needed and the
+  machine-wide system keychain is not touched. On other platforms trust
+  stays file-scoped to the client's own settings. `hyp status` shows the
+  fingerprint and whether the keychain still trusts it.
+  `hyp detach <client>` keeps the CA and the trust, so re-attaching does not
+  ask again; `hyp detach <client> --purge` and `hyp daemon uninstall` remove
+  both.
+- **Only the hosts a registered upstream names are decrypted.** Every other
+  host the client talks to is tunnelled through without being decrypted.
+- **What gets recorded does not change.** Only the recorded API paths are
+  stored; the other paths a client calls on the same host are passed through
+  without being stored.
 
 Two things to know before turning it on:
 
-- If the daemon is not running, Claude Code's HTTPS all fails, not just its
-  model calls. Attach refuses to write the settings unless proxy mode is
-  actually running, and `hyp detach claude` is the escape hatch.
+- If the daemon is not running, a proxied client's HTTPS all fails, not just
+  its model calls. Attach refuses to write the settings unless proxy mode is
+  actually running, and `hyp detach <client>` is the escape hatch.
 - If you already use a corporate proxy, set `upstream_proxy` to it so
   traffic still chains through it. Attach warns and backs up your existing
   `HTTPS_PROXY` (restored on detach) rather than silently replacing it: