context-guard: zone capture is statusline-teed and silent in cloud/headless sessions

[kyle-sexton]

Context

Surfaced in aihero-course lane 1 (#2899, 2026-08-17) while deciding handoff trigger criteria. context-guard's snapshot capture rides the statusline tee (scripts/statusline-tee.sh writing ~/.claude/context-guard/context/<session_id>.json on each statusline refresh). Verified in a live Claude Code on the web container: no statusLine is configured and ~/.claude/context-guard/ does not exist, so context-zone.sh resolves unknown and every zone consumer takes its conservative path. Consequence: the instrument-driven handoff trigger (zone says fork) is structurally silent exactly where sessions are most disposable (cloud), and session-flow:handoff's model-invocable proactivity loses its measurement there.

Proposed work

• Investigate a cloud/headless-compatible capture path: whether cloud sessions ever refresh a statusline; whether a hook-based capture (e.g. PostToolBatch reading the same stdin fields, if available to hooks) or another documented mechanism can write the per-session snapshot without a statusline; verify against current official docs what context-window telemetry is available outside the statusline channel.
• If a viable path exists, design it as an additive capture source honoring the existing reader contract (same snapshot path pattern, atomicity, staleness rule, fail-open posture). If none exists, record the limitation explicitly in reference/reader-contract.md and in the zone-consumer guidance so cloud consumers know unknown is expected, not an error.

Acceptance criteria

• Verdict recorded: viable cloud capture path exists (with design) or does not (with documented limitation and its basis in current official docs)
• Reader contract updated accordingly
• Lane 3 (session-flow: aihero course lane 3: compaction doctrine (fork-beats-compaction, auto-compact stance, evidence-degraded marker) #2901) informed: zone-signal availability affects the compaction-doctrine discussion

References

• session-flow/handoff: aihero course lane 1: use-case boundaries, purpose argument, expiry #2899 (lane 1 decision record); session-flow: aihero course lane 3: compaction doctrine (fork-beats-compaction, auto-compact stance, evidence-degraded marker) #2901 (lane 3, compaction doctrine)
• plugins/context-guard/README.md, plugins/context-guard/reference/reader-contract.md

Metadata

Field	Value
Category	unspecified
Area	context-guard
Ecosystem	unspecified