context-guard: scaffold plugin + statusline tee with per-session snapshots

[kyle-sexton]

Parent

Source: PLAN Phase A1, topic plugin-audit-port — plan locked at commit 40a64b5c on
feat/plugin-audit-port (read the full phase spec in the topic's PLAN.md on the task branch;
the contract slice is pruned at close-out, so cite this issue, not the path, downstream).

What to build

New context-guard plugin scaffold plus a transparent statusline tee that writes per-session
context-window snapshots. The tee wraps any existing statusline command byte-for-byte (stdout and
exit code unchanged, no tee failure may ever alter the wrapped output), and on every refresh writes
captured_at + session_id + the stdin context_window object copied verbatim to
~/.claude/context-guard/context/<session_id>.json via atomic temp-file+rename with a bounded
Windows rename retry. Reuse the rate-limit-guard statusline-tee PATTERN (bounded stdin read,
jq-missing visible degrade, standalone minimal-statusline mode) — not the plugin. Sanitize
session_id to [A-Za-z0-9_-] before filename use (skip the tee otherwise). Prune stale sibling
snapshots on write: never .tmp.* in-flight files, cutoff much larger than the reader contract's
staleness window (live-but-idle sessions must survive). Statusline schema was re-verified
2026-07-23 (all five Brief fields exist verbatim, plus remaining_percentage; used_percentage
and current_usage may be null early and current_usage is null right after /compact — copy
whatever is present). Re-verify the statusline doc fresh at implementation (fresh-docs mandate).
Test-first (Red-Green-Refactor) on the rate-limit-guard .test.sh harness pattern, all tests under
sandboxed HOME=$(mktemp -d). No userConfig in v1. plugin.json at version: 0.1.0.

Acceptance criteria

• bash plugins/context-guard/scripts/statusline-tee.test.sh exits 0 (sandboxed HOME; covers
  pass-through fidelity, snapshot shape, missing jq notice, missing context_window,
  unwritable dir silent skip, pruning incl. tmp-file exclusion and idle-session survival,
  session_id sanitization)
• Under HOME=$(mktemp -d): printf '{"session_id":"t1","context_window":{"used_percentage":50}}' | bash plugins/context-guard/scripts/statusline-tee.sh cat
  echoes the exact input bytes, exits 0, and $HOME/.claude/context-guard/context/t1.json
  passes jq -e '.captured_at and .session_id and .context_window'
• No tee failure path (missing jq, unwritable dir, failed rename) alters wrapped stdout/exit code

Blocked by

None — can start immediately (lane A opener).

[kyle-sexton]

[kyle-sexton]

Closed by PR #1241 (squash 7a868728). Evidence: statusline-tee.test.sh 43 assertions green under sandboxed HOME (incl. >1MiB byte-complete passthrough, no-regression guard + plausibility ceiling, prune re-check); manual printf smoke exact-bytes + snapshot jq-verified; shellcheck clean; live-seam smoke wrote a real snapshot for the executing session.