Files
msd-core/hooks/gsd-context-monitor.js
Behruz Nassre Esfahani 3ad75a6d59 enhance(#4285): resolve context-monitor fire-points from .planning/config.json (#4366)
* enhance(#4285): resolve context-monitor fire-points from .planning/config.json

The monitor's WARNING (35%) and CRITICAL (25%) fire-points were module
constants, so the only way to tune them was editing gsd-context-monitor.js —
a file in the MANAGED hooks registry, whose body the next install re-stages,
silently discarding the edit. The alternative was turning the safety net off.

Both are now readable from the config block the hook already opens:
hooks.context_warning_threshold and hooks.context_critical_threshold. Absent
keys resolve to today's 35/25, so every existing project is byte-identical.

Resolution is total and never throws — this hook must not block the tool call
it rides in on. A value is usable only if Number.isFinite (type-strict, so the
string "30" and true are rejected) and inside the 0-100 domain of the
remaining_percentage it is compared against; anything else falls back to the
default. The PAIR falls back together: critical >= warning has no coherent
reading, and honouring one side silently picks which of the operator's two
numbers to discard. That also covers a single override contradicting the other
key's default.

config-set validates the domain per key so accept and honour agree, but
deliberately does not enforce the pair — it writes one key per call, so a
two-step retune is transiently inconsistent on disk and refusing it there
would block a legitimate configuration.

Registration follows the statusline.show_git precedent: schema manifest plus
src/config.cts validation, not config-defaults.manifest.json and not
buildNewProjectConfig — emitting 35/25 into every new project would pin the
defaults at creation time for a setting nobody has tuned.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DsUAawHKUy9pCpnye1Jzd2

* enhance(#4285): address Codex review — per-key fallback docs, discriminating tests

Codex full-PR review (gpt-6-astra, read-only) returned five findings. Each was
verified against source before acting; all five are real.

1. docs/CONFIGURATION.md described the wrong fallback. An out-of-domain value
   falls back PER KEY; both defaults apply only when the RESOLVED pair violates
   critical < warning. warning 150 with critical 30 resolves to 35/30, not
   35/25 — at remaining 28 that difference changes the severity emitted. The
   table now states the two rules in the order they compose, and
   docs/context-monitor.md gains the same worked example.

2. The inconsistent-pair test could not prove the CRITICAL side reverts: its
   pair was 20/25, and 25 is already the default, so an implementation that
   reset only `warning` passed it. A 45/50 pair — both halves away from their
   defaults — now pins each side with its own reading, and an equal 45/45 pair
   pins that the rule is strict (`<`, not `<=`).

3. The rejection table's rows could not tell rejection from acceptance: an
   accepted -5 pairs with the default critical 25, trips the pair check, and
   produces the same silence. Two rows now separate those: a below-domain
   critical must escalate remaining 20 to CRITICAL (proving -5 was rejected,
   not honoured), and an unusable critical beside a usable warning 45 must
   still fire WARNING at remaining 40 (proving per-key fallback rather than
   reset-both). The over-claiming comments are narrowed to what each row
   actually shows.

4. Scope, reproduced rather than assumed: config-set writes through
   planningDir(), so under GSD_WORKSTREAM it lands in
   .planning/workstreams/<name>/config.json while this hook reads only
   <cwd>/.planning/config.json. That is the pre-existing root-only scope
   hooks.context_warnings has always had, but this PR advertises the setter
   route, so both docs now say the keys are root-project settings.

5. Four other English docs still stated 35/25 as fixed: the REQ-CTX-02/03
   requirements fragment, ARCHITECTURE.md's hook table and threshold table,
   and INVENTORY.md's hook row. All now name them as defaults and point at the
   config keys; docs/FEATURES.md is regenerated from its fragment via
   scripts/gen-features.cjs --write, not hand-edited.

Four new mutations, each reverted after: resetting only the warning half on an
inconsistent pair (1 red), resetting both on any unusable key (1), dropping the
>= 0 bound (1), and accepting critical == warning (1). perf-317 is 116/0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DsUAawHKUy9pCpnye1Jzd2

* enhance(#4285): tighten claims after Codex round 2 — scoped paths, one more discriminator

Confirmation round found no runtime defect and confirmed the five round-1 fixes
landed. Four precision items, all real, all fixed here.

1. The scoped-write note named the wrong path for GSD_PROJECT. planningDir()
   composes three distinct shapes, confirmed by running config-set under each:
   .planning/<project>/config.json, .planning/workstreams/<ws>/config.json, and
   .planning/<project>/workstreams/<ws>/config.json. docs/context-monitor.md
   now tabulates all four cases instead of collapsing them into one.

2. The 45/50 silence row asserted empty stdout without pinning the exit code.
   runMonitorRaw turns a spawn failure, a non-zero exit or a timeout into empty
   stdout as well, so the row could have passed on a dead child. It asserts
   exitCode === 0 first now, like the equal-pair row already did.

3. The sibling row's message claimed it proved critical fell back to 25. It
   does not: coercing '30' to 30 yields WARNING at remaining 40 too, so the row
   pins the WARNING side surviving and nothing more. Message narrowed, and a
   new row reads the same config at remaining 28, where the two candidate
   resolutions diverge — rejected gives (45, 25) and WARNING, coerced gives
   (45, 30) and CRITICAL. Mutation-verified: swapping Number.isFinite for the
   coercing global reds it.

4. "Accept and honour must agree" was too absolute in the src/config.cts and
   tests/config.test.cjs comments. The agreement holds on the DOMAIN and per
   key: an accepted value can still lose to the hook's pair check at read time,
   and a scoped write never reaches the hook at all. Likewise a two-step retune
   only CAN be transiently inconsistent — 35/25 to 20/10 is valid throughout if
   critical moves first — so the docs now say what a setter-side pair check
   would actually cost: rejecting that intermediate write and forcing an order.

The same over-absolute phrasing is in b7d179c89's message, which is left as
written rather than rewriting history; this commit and the PR body carry the
precise claim.

perf-317 117/0, config 192/0, config-field-docs 47/0, features-index-gate 84/0,
lint:ci clean cold.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DsUAawHKUy9pCpnye1Jzd2

* chore(#4285): add changeset

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DsUAawHKUy9pCpnye1Jzd2

* enhance(#4285): address review — planning-config rows, resolveThresholds properties

Two Minor findings from the maintainer review, no behaviour change.

Minor 1: gsd-core/references/planning-config.md's "Hook Fields" table gains
rows for hooks.context_warning_threshold and hooks.context_critical_threshold,
in that table's 5-column form, carrying the same per-key-fallback,
pair-reversion and root-config-scope claims docs/CONFIGURATION.md already
makes. hooks.workflow_guard's absence from that table is pre-existing and
out of scope here.

Minor 2: resolveThresholds() gets fast-check property coverage, which ADR 456
requires of a threshold/limit contract. Reaching it needed a require-time
seam: the resolver was previously observable only by spawning the hook, and a
subprocess per case cannot drive 200 runs — the same conclusion CONTEXT-INDEX
records for the ROADMAP Requirements parser. The stdin adapter therefore moves
into main() behind `require.main === module`, mirroring
gsd-cursor-subagent-start.js and gsd-statusline.js, and module.exports exposes
the resolver plus both default constants so a test asserts fallback against
the source of truth rather than a second copy of 35/25. Spawned behaviour is
unchanged: the 10s stdin timeout still arms per invocation (stdinTimeout is
now a module-scope let assigned in main(), still cleared by the end handler),
and the try/catch crash(ON_CRASH) path is untouched.

Seven properties: totality, ordering, exactness, togetherness, non-vacuity,
per-key fallback, non-object argument. Exactness is stated PER KEY — a mixed
result (one key honoured, one fallen back) is legal and is the documented
contract; the property falsified a per-pair phrasing of it in 4 runs.

Verified: cold lint:ci 0; perf-317 file 125/0; seven mutations killed and
restored, one of which (upper bound widened to 120) is invisible to the 17
hand-written cases and caught only by a property.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UZw5UhR474YLyE4knjHrte

* enhance(#4285): close the Codex-found gap in the property coverage

Codex whole-PR review of round 3 returned no Blocker and no Major. Two items,
both in the tests added this round, both verified against source before acting.

Minor — the per-key fallback property was asymmetric: it required a usable
warning to survive an unusable critical, but never the reverse. A resolver
that reverted BOTH keys the moment warning was unusable passed all seven
properties. Reproduced exactly: that mutant answers 35/25 for
{warning: 150, critical: 30} where the resolver answers 35/30, and the file
stayed green at 125/0. The mirrored property closes it — with the mutant
re-applied it is now the single failing row, and it is the only row that
fails, so it is load-bearing rather than incidental.

Nit — the ordering property's comment credited it with catching a
half-honoured pair, which it does not: 45/50 "repaired" by resetting only
critical yields 45/25, perfectly ordered. That case belongs to togetherness.
The same comment claimed the behavioural rows sample an inconsistent pair at
exactly one point; stale — they cover 20/25, 45/50 and the 45/45 equality
boundary. Both claims corrected in place.

Verified: cold lint:ci 0; perf-317 file 126/0; the mutant above killed by the
new property alone and the hook restored byte-identical afterwards.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UZw5UhR474YLyE4knjHrte

* enhance(#4285): name the installed-monitor prerequisite; close the negative-critical gap

Second Codex whole-PR pass, run because the base moved: the author's three
"Update branch" merges pulled ~26 upstream commits in, so the previously
reviewed diff sat on a base that no longer exists. No Blocker, no Major, two
Minor — both verified against source before acting.

Minor 1, and only reachable because of what the merge brought in: #2586
(03738824d) landed in that window and stops staging
hooks/gsd-context-monitor.js for Codex, since the metrics bridge it reads is
written only by hooks/gsd-statusline.js, which Codex never installs
(bin/install.js: "gsd-context-monitor.js is deliberately NOT copied for
Codex"). These two keys are read by that hook and nothing else, so on such a
runtime config-set stores and validates them and nothing consumes them — a
claim the docs this PR adds did not make. docs/context-monitor.md now carries
the explanation and both key tables carry a clause pointing at it; the FEATURES
and INVENTORY entries already link through to those two files, so they are not
edited again. The changeset says it too, because it is user-facing.

Accepting the keys on every runtime is kept deliberately: config is shared
across runtimes, so validation stays runtime-independent and the runtime
caveat lives in documentation rather than in the setter.

Minor 2: the per-key fallback property's junk generator had no negative arm,
though its mirror did — and that asymmetry hid a gap. A resolver reverting
BOTH keys whenever critical is negative answers 35/25 for {45, -5} where the
resolver answers 45/25, and it passed all 126 tests. With the negative arm
added it is the single failing row.

Verified: cold lint:ci 0; perf-317 126/0; both mutants above killed and the
hook restored byte-identical; 538/0 across the config, changeset, doc-parity
and emitted-attribution gates.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UZw5UhR474YLyE4knjHrte

* enhance(#4285): refuse the two dead threshold endpoints; resolve absent keys

Maintainer review round 2 raised two Minors and a nit.

Minor 1 — `hooks.context_warning_threshold: 0` was accepted and stored but can
never take effect: `critical < warning` must hold and both sides are clamped to
0-100, so nothing can sit below a warning of 0. Verifying it surfaced the MIRROR
case the review did not name: `critical: 100` is equally dead, since nothing can
sit above it. Both confirmed against the real resolver for partners {absent, 0,
50, 100}, with 0.001 and 99.999 honoured as controls.

`config-set` now refuses both, because storing a value the reader always
discards is the accept-then-discard shape this codebase refuses elsewhere. The
hook is unchanged and still total — it degrades to defaults rather than
throwing, so a project that already carries one of these on disk still loads.
The old "accepts the domain bounds 0 and 100" row asserted the misleading half
and is replaced by tables that make the asymmetry the point (0 is legal for
critical and illegal for warning; 100 is the reverse), plus a control row so
"refuse both endpoints outright" would not pass in its place.

Minor 2 — the keys are absent from config-defaults.manifest.json /
buildNewProjectConfig where the sibling `hooks.context_warnings` lives. Kept
that way: buildNewProjectConfig writes a hooks object into every NEW project's
config.json, which would freeze today's fire-points as an explicit per-project
override everywhere — the opposite of this PR's premise. But the underlying
complaint was real, so the actual symptom is fixed: `config-get` on an absent
key returned "Key not found" while the hook silently used 35/25. It now resolves
through SCHEMA_DEFAULTS. Restated rather than derived because CONFIG_DEFAULTS is
re-exported flattened and has no `hooks` member at runtime; the one resulting
copy of 35/25 outside the hook is pinned against the hook's exported constants
by a drift test (red-checked: moving the literal to 40 reds it).

Nit — PR-body counts unverifiable from the diff. Noted, no code change.

Codex round 3 then found a broken doc link (`context-monitor.md` resolved
inside gsd-core/references/, where it does not exist; the emitted tree's own
convention is `../../docs/...`) and a stale comment still describing the
manifest-derived approach I had backed out. Both fixed. It also corrected my
rationale on a point of fact: manifest entries alone would NOT have reached new
project configs, since buildNewProjectConfig builds its own literal — the
freezing argument applies to that function, not to the manifest. The comment now
says so rather than running the two together.

Verified: cold lint:ci 0; full suite 36,082 / 0 fail before these two fixes,
config + perf-317 321/0 after; drift pin red-checked.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UZw5UhR474YLyE4knjHrte

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
2026-09-09 04:31:14 +00:00

568 lines
31 KiB
JavaScript

#!/usr/bin/env node
// gsd-hook-version: {{GSD_VERSION}}
// Context Monitor - PostToolUse/AfterTool hook (Gemini uses AfterTool)
// Reads context metrics from the statusline bridge file and injects
// warnings when context usage is high. This makes the AGENT aware of
// context limits (the statusline only shows the user).
//
// How it works:
// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
// 2. This hook reads those metrics after each tool use
// 3. When remaining context drops below thresholds, it injects a warning
// as additionalContext, which the agent sees in its conversation
//
// Thresholds:
// WARNING (remaining <= 35%): Agent should wrap up current task
// CRITICAL (remaining <= 25%): Agent should stop immediately and save state
// Both fire-points are overridable per project via .planning/config.json
// (hooks.context_warning_threshold / hooks.context_critical_threshold, #4285);
// the values above are the defaults used when the keys are absent or unusable.
//
// Debounce: 5 tool uses between warnings to avoid spam
// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
const fs = require('fs');
const os = require('os');
const path = require('path');
const { spawn } = require('child_process');
const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
// This hook only injects an advisory context-usage warning; it never blocks
// the tool call it rides in on. A crash here (e.g. a malformed bridge file)
// must not turn a PostToolUse advisory into a blocked tool call — losing a
// context warning is far cheaper than stalling the agent's work (#3911).
const ON_CRASH = HOOK_ON_CRASH.ALLOW;
const WARNING_THRESHOLD = 35; // remaining_percentage <= 35% (default, see resolveThresholds)
const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25% (default, see resolveThresholds)
const STALE_SECONDS = 60; // ignore metrics older than 60s
const DEBOUNCE_CALLS = 5; // min tool uses between warnings
// How long after a PreCompact readings stay suspect. The watermark records the
// compaction's START; the compaction keeps running after it, and a statusline
// render during it stamps the PRE-compaction reading with a CURRENT timestamp
// (Codex review of #3808, round 3) — so "newer than the watermark" alone still
// admits it. Everything inside this window is dropped instead. The cost is
// bounded: a healthy reading dropped here behaves identically to an accepted
// one (it would exit above-threshold anyway). A genuine exhaustion reading
// inside the window is SKIPPED, not queued — its warning and its #1974
// breadcrumb both fire on the next reading after the window, so they are
// delayed by at most this window plus the accepted skew below when a later
// reading comes, and lost when
// none does, i.e. when the session ends inside the window (review of #3808,
// round 9). That loss is accepted over the alternative, which is trusting a
// reading that may be the pre-compaction value under a fresh timestamp.
const COMPACT_GRACE_SECONDS = 60;
// How far AHEAD of this process's clock a watermark may be and still be
// honored. PreCompact stamps it from the same clock as the reader, so the
// legitimate skew is 0; this tolerance only absorbs a clock step. It is a
// THRESHOLD, so it is named rather than inlined and carries its own boundary
// trio (Codex review of #3808, round 4). Note it also extends the mute: a
// watermark this far ahead pushes first recovery from +61 to +66 (measured).
const WATERMARK_SKEW_SECONDS = 5;
// Resolve the two fire-points from the project's `.planning/config.json`
// (#4285). The constants above are the DEFAULTS; a project overrides either one
// through `hooks.context_warning_threshold` / `hooks.context_critical_threshold`,
// which is what keeps a tuned fire-point alive across updates — this file is in
// the MANAGED registry, so an edit to the constants is re-staged away by the
// next install.
//
// TOTAL and never-throwing: this hook must not block the tool call it rides in
// on, so every unusable input degrades to the default instead of raising.
// Unusable is decided by Number.isFinite, which is type-strict (the string
// "30" and true are both rejected, unlike the global isFinite), plus the 0-100
// domain of the remaining_percentage these are compared against.
//
// The PAIR is validated too, and falls back TOGETHER. `critical >= warning` has
// no coherent reading — critical fires deeper into the window than warning —
// and honouring one side of an inconsistent pair silently picks which of the
// operator's two numbers to discard. This also rejects a single override that
// contradicts the OTHER key's default (warning 20 with critical absent, i.e.
// 25); the resulting pair is the same nonsense either way. Set-time validation
// cannot stand in for this check: `config-set` writes one key per call, so
// tuning both (warning first, then critical) is transiently inconsistent on
// disk, and refusing it there would block a legitimate configuration.
function resolveThresholds(hooks) {
const defaults = { warning: WARNING_THRESHOLD, critical: CRITICAL_THRESHOLD };
if (!hooks || typeof hooks !== 'object') return defaults;
const usable = (value, fallback) =>
(Number.isFinite(value) && value >= 0 && value <= 100) ? value : fallback;
const warning = usable(hooks.context_warning_threshold, WARNING_THRESHOLD);
const critical = usable(hooks.context_critical_threshold, CRITICAL_THRESHOLD);
return critical < warning ? { warning, critical } : defaults;
}
// One DEFINITION of what counts as a lifecycle event name, shared by the #3709
// PreCompact reset and the #2289 output-envelope allowlist. Two call sites, one
// rule — so the two cannot drift into disagreeing about what "no event name" is.
// TOTAL, and STRICT about type: only an actual string is an event name. The old
// inline expression threw on a truthy non-string, and hoisting it ahead of the
// pipeline would have moved that throw ahead of the side effects #2289
// documents as always running; a String() coercion is no better — it renders
// ['PreCompact'] as 'PreCompact' and would run the reset off a malformed
// payload, and a hostile toString still throws (Codex review of #3808,
// round 3). typeof does neither: any non-string reads as "no event" — silent,
// side effects intact — on both call sites.
function readEventName(data) {
const name = data && data.hook_event_name;
if (typeof name === 'string') return name.trim();
// ABSENT vs MALFORMED are not the same event (Codex review of #3808, round 7,
// measured base-vs-head). A MISSING name is the documented pre-#2289 Gemini
// fallback: under GEMINI_API_KEY it means AfterTool and still emits. A name
// that is PRESENT but not a string is a malformed payload and must not
// inherit that fallback — at the merge-base it threw on `.trim()` after the
// side effects, so no envelope was ever produced, and collapsing both onto ''
// silently turned `42`, `{}` and `['PreCompact']` into emitting AfterTool
// events. Measured: base silent, head emitted, for both `42` and
// `['PreCompact']`. null keeps them distinguishable while staying unequal to
// every event name, so the PreCompact reset and the allowlist below are
// byte-for-byte unchanged for every well-formed payload.
return (name === undefined || name === null) ? '' : null;
}
// SENTINEL WRITE HARDENING (review of #3808, round 7). `warnPath` lives in
// os.tmpdir(), which may resolve to a shared sticky directory — not guaranteed
// per-user, and the file persists across invocations — so an object already
// sitting there may be a planted symlink. The three routine debounce-accounting writes were bare
// writeFileSync, which follows one and writes through to its target, while the
// PreCompact clear and the compaction watermark in this same file already
// refuse to. Unlink-then-O_EXCL is the watermark's own shape (the watermark
// write itself now calls this helper — review round 10): the unlink
// removes any existing object (regular file or link) and O_EXCL then refuses
// to create through one, so the write can only ever land on a fresh regular
// file this process made. Best effort by design — a lost sentinel write costs
// only debounce accounting, which is never worth breaking the hook over, so
// every failure is swallowed exactly as the watermark write's is.
// NOT an atomic read-modify-write, and not claimed to be (Codex review of
// #3808, round 7): two concurrent invocations can read the same state and race
// through unlink/create, so one invocation's accounting can be lost — the same
// lost-update race the bare writeFileSync already had, not a class this change
// introduces. What a lost write leaves behind is whatever the competing writer
// wrote, which may be a perfectly valid sentinel; it does not reliably mean
// "defaults on the next call". Advisory debounce bookkeeping is the right place
// to accept that.
// The read-side twin of writeSentinel (review of #3808, round 9). Both
// sentinel files this hook reads — the compaction watermark and the warn
// state — must be read the same way: lstat first so a planted link, FIFO or
// directory is refused before any open; O_NOFOLLOW so a link raced in between
// is refused by the kernel too (0 on Windows, where lstat already carries the
// check); a 4096-byte bound so a planted large file cannot stall a
// synchronous read. Rounds 4 and 7 each wrote that sequence inline at their
// own call site, which left two copies to keep in step by hand. One place
// now. Refusal THROWS; every caller already wraps the read in a try/catch and
// degrades to "no file", which is the same behaviour the inline copies had.
function readSentinel(target) {
const st = fs.lstatSync(target);
if (!st.isFile() || st.size > 4096) throw new Error('not a plain sentinel');
const fd = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
try {
const buf = Buffer.alloc(st.size);
// The RETURN VALUE, not just the call (review of #3808, round 11). A file that shrinks
// between the lstat above and this read — a concurrent legitimate writer truncating
// mid-write, not the planted-object case the rest of this function guards — leaves the tail
// of `buf` zero-filled, and those NULs reach JSON.parse as garbage. Every caller already
// treats a throw here as "no file", so refusing a short read is both safer and the same
// outcome the caller would reach one line later, stated on purpose rather than by accident.
const bytesRead = fs.readSync(fd, buf, 0, st.size, 0);
if (bytesRead !== st.size) throw new Error('sentinel shrank under the read');
return buf.toString('utf8');
} finally { fs.closeSync(fd); }
}
function writeSentinel(target, payload) {
try {
try {
fs.unlinkSync(target);
} catch (e) {
if (!e || e.code !== 'ENOENT') throw e;
}
const fd = fs.openSync(
target,
fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL
);
try {
// LOOP, and check progress (Codex review of round 11). A single `fs.writeSync` is
// permitted to write fewer bytes than it was given, and the return value was discarded —
// a short write left a truncated sentinel that JSON.parse rejects, silently defeating the
// debounce accounting or the compaction watermark this write exists to record. Node's own
// `writeFileSync` loops for exactly this reason; the explicit no-progress guard keeps a
// pathological fd from spinning. Symmetric with the bytesRead check in readSentinel.
const buf = Buffer.from(payload, 'utf8');
let written = 0;
while (written < buf.length) {
const n = fs.writeSync(fd, buf, written, buf.length - written);
if (!(n > 0)) throw new Error('sentinel write made no progress');
written += n;
}
} finally { fs.closeSync(fd); }
} catch (e) { /* best effort — see above */ }
}
let input = '';
// Assigned by main(); the handler below clears it. Declared out here rather
// than inside main() because the handler closes over it.
let stdinTimeout = null;
const handleStdinEnd = () => {
clearTimeout(stdinTimeout);
try {
const data = JSON.parse(input);
const sessionId = data.session_id;
if (!sessionId) {
allow(undefined);
}
// Reject session IDs that contain path traversal sequences or path separators.
// session_id is used to construct file paths in /tmp — an unsanitized value
// could escape the temp directory and read or write arbitrary files.
if (/[/\\]|\.\./.test(sessionId)) {
allow(undefined);
}
const tmpDir = os.tmpdir();
const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
const watermarkPath = path.join(tmpDir, `claude-ctx-${sessionId}-compacted.json`);
// #3709: a compaction RESTARTS the context lifecycle, so neither the warn
// sentinel nor the pre-compaction statusline reading may survive it. Full
// rationale — what dies when the sentinel outlives a compaction, why the
// reset sits ahead of the config gate and the metrics read, and why an
// aborted compaction deliberately stays cleared — lives in ONE place:
// docs/context-monitor.md, "PreCompact reset". Constraints the code itself
// must keep are stated at their lines below.
if (readEventName(data) === 'PreCompact') {
// ORDERING ASSUMPTION, stated rather than enforced (review of #3808,
// round 9): this reset and the debounce writeSentinel(warnPath) further
// down are two writers to the same file, and nothing here serialises
// them. A debounce invocation that read the pre-compaction state and
// lands its write AFTER this unlink would resurrect exactly the stale
// sentinel this block removes. The hook relies on the host dispatching a
// session's hooks one at a time, which Claude Code does; the other
// runtimes this hook is installed for are assumed to, and that is not
// tested. A lock file would close it at the cost of a second file to
// harden on every platform; not taken here.
// BOTH files: with the sentinel gone but the bridge still holding the
// pre-compaction reading (fresh for STALE_SECONDS), the next PostToolUse
// would fire a spurious CRITICAL off a context the compaction just freed
// (review of #3709).
for (const stale of [warnPath, metricsPath]) {
try {
fs.unlinkSync(stale);
} catch (e) {
if (e && e.code === 'ENOENT') continue; // already absent — that IS the reset
// Best-effort fallback for a held handle (Windows EPERM/EBUSY):
// truncate to EMPTY — the one state both readers treat exactly like
// deletion, because JSON.parse('') throws. A well-formed "neutral"
// value is NOT equivalent: '{}' debounces the first post-compaction
// warning, '{"timestamp":0}' is never stale (falsy guard) and emits
// "undefined%" (review of #3808). Never through a LINK: lstat
// rejects non-regular files on every platform (Windows has no
// effective O_NOFOLLOW — libuv defines it as 0 — and TEMP/TMP means
// its tmpdir is not guaranteed per-user); O_NOFOLLOW additionally
// closes the lstat→open substitution race where honored. Every
// refusal lands in this give-up arm — including a Windows runner
// refusing the write-open of a freshly written file outright —
// which is why the fallback is best-effort, never asserted-on.
try {
if (fs.lstatSync(stale).isFile()) {
fs.closeSync(fs.openSync(
stale,
fs.constants.O_WRONLY | fs.constants.O_TRUNC | (fs.constants.O_NOFOLLOW || 0)
));
}
} catch (e2) { /* give up, never throw */ }
}
}
// COMPACTION WATERMARK (review of #3808, round 3). Deleting the bridge
// only NARROWS the stale-reading window: the statusline is an
// uncoordinated process that re-writes the bridge on every render, so a
// render landing between this clear and the compaction's completion
// re-creates the PRE-compaction reading with a CURRENT timestamp — and
// it would sail past STALE_SECONDS as freshly valid. The watermark makes
// the pre-compaction reading identifiable rather than merely absent: the
// metrics read drops any reading not strictly newer than it. Written
// through writeSentinel (review of #3808, round 10 — this block was the
// shape writeSentinel was lifted from in round 7 and kept its own copy):
// unlink-then-O_EXCL so an existing file — or a planted symlink — is
// never followed or overwritten in place; failure to write degrades to
// the old narrowing, never throws.
writeSentinel(watermarkPath, JSON.stringify({ at: Math.floor(Date.now() / 1000) }));
// allow(), not raw process.exit: #3911/ADR-3889 moved this hook onto the
// declared-policy exit vocabulary while this PR was in review, and the
// PreCompact branch is new here, so it needs the same conversion.
// A compaction is never blocked by this hook — ALLOW is the policy the
// rest of the file already declares.
allow(undefined);
}
// Check if context warnings are disabled via config, and resolve the two
// fire-points from the same read (#4285 — one config read, not two).
// Collapsed existsSync+readFileSync into a single read guarded by try/catch
// (ENOENT or parse error → use defaults, same as old "planningDir absent" branch).
const cwd = data.cwd || process.cwd();
let thresholds = { warning: WARNING_THRESHOLD, critical: CRITICAL_THRESHOLD };
try {
const configPath = path.join(cwd, '.planning', 'config.json');
const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
if (config.hooks?.context_warnings === false) {
allow(undefined);
}
// After the disable check, not before: a disabled monitor exits above and
// never reaches a threshold, so resolving first would only add work to the
// path that does nothing. allow() exits the process (it does not throw),
// so this line is unreachable when warnings are off.
thresholds = resolveThresholds(config.hooks);
} catch (e) {
// Missing or unparseable config → proceed with defaults (context warnings
// enabled, thresholds at the constants above, which `thresholds` already holds)
}
// If no metrics file, this is a subagent or fresh session -- exit silently.
// Collapsed existsSync+readFileSync: ENOENT → exit 0 (identical to old !existsSync branch),
// other errors rethrow to the outer catch (swallowed → exit 0, as before).
//
// Through readSentinel, like the other two (review of #3808, round 11). This read was the
// asymmetry left in this file: `metricsPath` is built one line away from `warnPath` and
// `watermarkPath` (same tmpdir, same predictable `claude-ctx-{sessionId}` shape), it is the
// only one of the three read on EVERY invocation, and it was the only one still reached by a
// bare readFileSync — so the symlink-to-FIFO stall the other two are hardened against was
// still reachable here, on the highest-traffic path in the file. The 4096-byte bound is
// ample: the statusline writes four fixed fields (`gsd-statusline.js`, ~140 bytes with a
// UUID session id), so no legitimate bridge approaches it. A refusal throws and lands in the
// rethrow below exactly as an unreadable or malformed bridge already did.
let metricsRaw;
try {
metricsRaw = readSentinel(metricsPath);
} catch (e) {
if (e && e.code === 'ENOENT') allow(undefined);
throw e;
}
const metrics = JSON.parse(metricsRaw);
const now = Math.floor(Date.now() / 1000);
// #3709 (round 3): a reading not clearly PAST the compaction is suspect,
// whatever its timestamp says — the statusline re-writes the bridge on
// every render, and a render during the compaction stamps the OLD
// remaining_percentage with a current time. The watermark records the
// compaction's START, so "newer than the watermark" alone still admits a
// mid-compaction render (Codex review of #3808, round 3): the grace
// window covers the compaction's own duration. `!(>)` rather than `<=` so
// a missing/zero/garbage timestamp is also dropped once a compaction has
// happened — an unstamped reading cannot prove it is post-compaction.
//
// The watermark itself must be SANE to count: one stamped in the future
// (a clock step backwards, a stray file) would otherwise drop every
// reading indefinitely and silently self-disable monitoring — so it is
// honored only when its own timestamp is not ahead of this process's
// clock (small skew allowed). No watermark, an unreadable one, or an
// insane one all degrade to the plain STALE_SECONDS behaviour below.
//
// READ HARDENING (Codex review of #3808, round 4). The WRITE side already
// refuses to follow or overwrite a planted object (unlink-then-O_EXCL
// above), but this read was a bare readFileSync — so on any write-side
// give-up the planted object survived and every later invocation followed
// it. In a shared sticky os.tmpdir() that is a mute primitive (a planted
// recent watermark suppresses monitoring) and a stall primitive (a symlink
// to a FIFO blocks this synchronous read indefinitely; measured: such a
// read is still running after 300ms). The same lstat + O_NOFOLLOW pair the
// sentinel path uses, plus a size bound, applied to the file this PR adds.
// Every refusal degrades to "no watermark", never throws.
try {
const watermark = JSON.parse(readSentinel(watermarkPath));
if (
watermark && typeof watermark.at === 'number'
&& watermark.at <= now + WATERMARK_SKEW_SECONDS
&& !(metrics.timestamp > watermark.at + COMPACT_GRACE_SECONDS)
) {
// Same #3911/ADR-3889 conversion as the PreCompact branch above: this
// gate is new in this PR, so it did not exist to be migrated.
allow(undefined);
}
} catch (e) { /* no watermark — nothing to compare against */ }
// Ignore stale metrics
if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
allow(undefined);
}
const remaining = metrics.remaining_percentage;
const usedPct = metrics.used_pct;
// No warning needed
if (remaining > thresholds.warning) {
allow(undefined);
}
// Debounce: check if we warned recently. `warnPath` is resolved above, next to
// metricsPath, because the PreCompact reset needs it before this point.
let warnData = { callsSinceWarn: 0, lastLevel: null };
let firstWarn = true;
// Collapsed existsSync+readFileSync: ENOENT or parse error → keep default warnData
// (same as old "file absent" branch). firstWarn tracks whether we read a valid sentinel.
//
// READ HARDENING (self-found while addressing round 7; same class, same
// file). Hardening the writes above leaves this read as a bare
// readFileSync on warnPath, which is the exact asymmetry round 7 asks be
// removed from the write side — and the watermark's read was hardened in
// round 4 for this same reason, so leaving this one recreates it. It was
// not the LAST bare read in the file: the statusline bridge kept its own
// until round 11 found it. All three go through readSentinel now. The
// exposure is real but bounded: the writes now unlink any planted object,
// so only a read reaching this line BEFORE the first write of an
// invocation can follow one, and re-planting reopens it every invocation.
// Following it is a mute primitive — attacker-chosen callsSinceWarn keeps
// the debounce arm below taken so no warning is ever emitted — and a
// symlink to a FIFO stalls this synchronous read, the same two primitives
// measured on the watermark. Same lstat + O_NOFOLLOW + size bound; every
// refusal degrades to the default warnData this catch already produces,
// so a normal regular file behaves exactly as before.
try {
warnData = JSON.parse(readSentinel(warnPath));
firstWarn = false;
} catch (e) {
// Missing or corrupted sentinel → firstWarn stays true, warnData stays at defaults
}
warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
const isCritical = remaining <= thresholds.critical;
const currentLevel = isCritical ? 'critical' : 'warning';
// Emit immediately on first warning, then debounce subsequent ones
// Severity escalation (WARNING -> CRITICAL) bypasses debounce
const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
// Update counter and exit without warning
writeSentinel(warnPath, JSON.stringify(warnData));
allow(undefined);
}
// Reset debounce counter
warnData.callsSinceWarn = 0;
warnData.lastLevel = currentLevel;
writeSentinel(warnPath, JSON.stringify(warnData));
// Detect if GSD is active (has .planning/STATE.md in working directory)
const isGsdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
// On CRITICAL with active GSD project, auto-record session state as a
// breadcrumb for /gsd:resume-work (#1974). Fire-and-forget subprocess —
// doesn't block the hook or the agent. Fires ONCE per CRITICAL session,
// guarded by warnData.criticalRecorded to prevent repeated overwrites
// of the "crash moment" record on every debounce cycle.
if (isCritical && isGsdActive && !warnData.criticalRecorded) {
try {
// Runtime-agnostic path: this hook lives at <runtime-config>/hooks/
// and gsd-tools.cjs lives at <runtime-config>/gsd-core/bin/.
// Using __dirname makes this work on Claude Code, OpenCode, Gemini,
// Kilo, etc. without hardcoding ~/.claude/.
const gsdTools = path.join(__dirname, '..', 'gsd-core', 'bin', 'gsd-tools.cjs');
// Coerce usedPct to a safe number in case bridge file is malformed
const safeUsedPct = Number(usedPct) || 0;
const stoppedAt = `context exhaustion at ${safeUsedPct}% (${new Date().toISOString().split('T')[0]})`;
spawn(
process.execPath,
[gsdTools, 'state', 'record-session', '--stopped-at', stoppedAt],
{ cwd, detached: true, stdio: 'ignore', windowsHide: true }
).unref();
warnData.criticalRecorded = true;
// Persist the sentinel so subsequent debounce cycles don't re-fire
writeSentinel(warnPath, JSON.stringify(warnData));
} catch { /* non-critical — don't let state recording break the hook */ }
}
// Build advisory warning message (never use imperative commands that
// override user preferences — see #884)
let message;
if (isCritical) {
message = isGsdActive
? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
'GSD state is already tracked in STATE.md. Inform the user so they can run ' +
'/gsd:pause-work at the next natural stopping point.'
: `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';
} else {
message = isGsdActive
? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
'Context is getting limited. Avoid starting new complex work. If not between ' +
'defined plan steps, inform the user so they can prepare to pause.'
: `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
'starting new complex work.';
}
// #2289: the hookSpecificOutput.additionalContext envelope is only a valid
// output shape for the context-injection events (PostToolUse, and AfterTool
// for the Gemini dialect). This hook is also wired to other lifecycle events
// on some hosts — Codex registers it under Stop / SubagentStart /
// SubagentStop / PreCompact (#772) — and those reject the envelope
// ("hook returned invalid stop hook JSON output"). Use a POSITIVE allowlist:
// emit only for injection-capable events; every other event, and a
// missing/unrecognized name, exits 0 with no stdout. A Stop-only blacklist is
// not enough — a missing name would still fall through to the injection path.
// All side effects above (debounce counter, one-time critical-session
// recording) have already run regardless of whether output is emitted.
const eventName = readEventName(data);
// Preserve the pre-#2289 Gemini fallback: a missing event name under a
// Gemini-dialect runtime (GEMINI_API_KEY set) still means AfterTool, so its
// advisory output is unchanged. A missing name on any other host is silent.
const geminiFallback = eventName === "" && !!process.env.GEMINI_API_KEY;
const injectionSupported = eventName === "PostToolUse" || eventName === "AfterTool" || geminiFallback;
if (injectionSupported) {
const output = {
hookSpecificOutput: {
hookEventName: eventName || "AfterTool",
additionalContext: message,
severity: currentLevel
}
};
process.stdout.write(JSON.stringify(output));
}
} catch (e) {
// Silent fail -- never block tool execution.
// ON_CRASH is declared ALLOW at module top: this preserves today's
// exit(0) fail-open behavior exactly (#3911).
crash(ON_CRASH, undefined);
}
};
// The stdin adapter is the only side-effecting statement in this file, so it is
// the only thing that must not run on `require()`. Gating it lets a test import
// `resolveThresholds` and drive it directly — the repo's own conclusion for a
// seam like this (CONTEXT-INDEX, on the ROADMAP Requirements parser: a closure
// reachable only by spawning the CLI is one "no fast-check property can do").
// A spawn-per-case property test is not the same test: it would exercise the
// resolver at whatever pairs survive to an observable severity, not over its
// whole numeric domain.
/* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
function main() {
// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
// Windows/Git Bash, or slow Claude Code piping during large outputs),
// exit silently instead of hanging until Claude Code kills the process
// and reports "hook error". See #775, #1162.
stdinTimeout = setTimeout(() => allow(undefined), 10000);
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', handleStdinEnd);
}
if (require.main === module) {
main();
}
// Exported for the #4285 property test only. The two constants ride along so a
// test asserts the fallback pair against the SOURCE of truth rather than
// re-hardcoding 35/25 — a test carrying its own copy of the defaults would stay
// green if the constants were edited.
module.exports = { resolveThresholds, WARNING_THRESHOLD, CRITICAL_THRESHOLD };