@opengsd/gsd-core 1.13.0 → 1.14.0

package/gsd-core/workflows/verify-work.md

@@ -33,6 +33,8 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 
 <process>
 
+**Compact Content Gate.** Read and follow `gsd-core/references/compact-content-gate.md` now — it states the `workflow.compact_content` check and the resolution rule this spine defers to. When it directs a Read, read `gsd-core/workflows/verify-work/detail/elaboration.md` in full before continuing past this point; its content elaborates on the resume/reconcile steps and the full gap-closure sub-flow below.
+
 <step name="initialize" priority="first">
 If $ARGUMENTS contains a phase number, load context:
 
@@ -489,50 +491,20 @@ If no more tests → Go to `complete_session`
 </step>
 
 <step name="reconcile_gaps">
-**Reconcile diagnosed gaps against completed gap-closure plans (#1921):**
-
-When verify-work resumes after `/gsd:execute-phase --gaps-only`, the UAT `## Gaps` entries still read `status: failed` even though their fix plans have executed. Without reconciliation verify-work re-diagnoses them as fresh blockers and spawns new gap plans — losing the verification state. This step closes the loop.
-
-Read the UAT `## Gaps` section and the phase dir `*-PLAN.md` frontmatter. For each gap with `status: failed`:
-1. Find a `*-PLAN.md` whose frontmatter `gap_ids` includes the gap's `gap_id` (`G-{phase}-{N}`).
-2. If such a plan exists AND has a matching `*-SUMMARY.md` in the phase dir (the plan was executed by `--gaps-only`), the gap is **resolved** — update its YAML in place:
-   ```yaml
-   - gap_id: G-{phase}-{N}
-     status: resolved        # was: failed
-     resolved_by: {plan basename}
-     resolved_at: {today}
-   ```
-3. If no plan references the `gap_id`, or the plan has no SUMMARY, leave the gap `status: failed` (still open).
+**Reconcile diagnosed gaps against completed gap-closure plans (#1921):** when verify-work resumes after `/gsd:execute-phase --gaps-only`, UAT `## Gaps` entries still read `status: failed` even though their fix plans already executed — without reconciliation they'd be re-diagnosed as fresh blockers. For each `status: failed` gap with a `*-PLAN.md` whose `gap_ids` names it AND a matching `*-SUMMARY.md`, mark it `resolved` (with `resolved_by`/`resolved_at`) in place; otherwise leave it `failed`. Resolved gaps are never re-diagnosed or re-planned; a later regression gets a fresh `gap_id`, not a reopened old one.
 
-Read plan frontmatter directly in-context — do not pipe it through a shell parser. After reconciliation, announce:
-```
-Reconciled gap-closure state: {resolved_count} gap(s) resolved by executed plans, {open_count} still open.
-```
-
-Resolved gaps are NOT re-diagnosed and do NOT spawn new gap plans. If the user later reports the same behavior as still broken, treat it as a new issue (a regression) with a fresh `gap_id`.
+Exact YAML shape and the announcement line: `gsd-core/workflows/verify-work/detail/elaboration.md` § 1.
 </step>
 
 <step name="resume_from_file">
-**Resume testing from UAT file:**
-
-**First run `reconcile_gaps`** (above) so gaps already fixed by `/gsd:execute-phase --gaps-only` are marked `resolved` before testing resumes (#1921).
-
-Read the full UAT file.
+**Resume testing from UAT file:** first run `reconcile_gaps` (above), then read the full UAT file.
 
 Find first test with `result: [pending]`.
 If no `[pending]` test found → go to `complete_session`.
 
-Announce:
-```
-Resuming: Phase {phase} UAT
-Progress: {passed + issues + skipped}/{total}
-Issues found so far: {issues count}
+Otherwise announce progress and continue from that test at `present_test`.
 
-Continuing from Test {N}...
-```
-
-Update Current Test section with the pending test.
-Proceed to `present_test`.
+Exact resume-announcement wording: `gsd-core/workflows/verify-work/detail/elaboration.md` § 2.
 </step>
 
 <step name="complete_session">
@@ -726,138 +698,29 @@ SECURITY: File paths in output are constructed from validated path components on
 </step>
 
 <step name="diagnose_issues">
-**Diagnose root causes before planning fixes:**
-
-```
----
-
-{N} issues found. Diagnosing root causes...
-
-Spawning parallel debug agents to investigate each issue.
-```
-
-- Load diagnose-issues workflow
-- Follow @~/.claude/gsd-core/workflows/diagnose-issues.md
-- Spawn parallel debug agents for each issue
-- Collect root causes
-- Update UAT.md with root causes
-- Proceed to `plan_gap_closure`
-
-Diagnosis runs automatically - no user prompt. Parallel agents investigate simultaneously, so overhead is minimal and fixes are more accurate.
+When UAT testing found issues, this sub-flow (diagnose_issues -> plan_gap_closure -> verify_gap_plans -> revision_loop) runs before present_ready; a session with zero issues never reaches it. Spawn parallel debug agents (one per issue, via diagnose-issues.md) to find root causes with no user prompt, then update UAT.md and proceed to plan_gap_closure.
 </step>
 
 <step name="plan_gap_closure">
-**Auto-plan fixes from diagnosed gaps:**
-
-Display:
-```
-### GSD ► PLANNING FIXES
-
-◆ Spawning planner for gap closure... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
-```
-
-Spawn gsd-planner in --gaps mode:
-
-<!-- #2517 model-omit-on-inherit -->
-
-> **Model omission (#2517).** Omit the `model` parameter entirely when the value it would carry (`planner_model`, `checker_model`) is `"inherit"` or empty. An empty value 404s on runtimes without native tier aliases — the default on non-Claude runtimes. Omitting it inherits the orchestrator's model. See @gsd-core/references/model-profile-resolution.md.
-
-````
-Agent(
-  prompt="""
-<planning_context>
-
-**Phase:** {phase_number}
-**Mode:** gap_closure
-
-<required_reading>
-- {phase_dir}/{phase_num}-UAT.md (UAT with diagnoses)
-- {state_path} (Project State)
-- {roadmap_path} (Roadmap)
-</required_reading>
-
-${AGENT_SKILLS_PLANNER}
-
-</planning_context>
-
-<downstream_consumer>
-Output consumed by /gsd:execute-phase
-Plans must be executable prompts.
-
-<!-- #2508 runtime-aware-dispatch -->
-
-> **Runtime-aware dispatch (#2508 Phase 4).** GSD workflows dispatch specialized subagents by role. Before dispatching on a built-in-only runtime (kimi-code — three built-ins only), resolve the role to a built-in via `gsd_run query resolve-dispatch-type --requested <role> --raw`. On named-dispatch runtimes (Claude/OpenCode/…) the role is returned unchanged; on kimi-code it maps to `coder`/`explore`/`plan` by role-suffix. The persona rides `${AGENT_SKILLS_<ROLE>}` (Phase 3) regardless. See @gsd-core/references/runtime-aware-dispatch.md.
-
-**Gap linkage (#1921):** each created `*-PLAN.md` MUST list the UAT gap ids it addresses in its frontmatter:
-```yaml
----
-gap_closure: true
-gap_ids: [G-{phase}-{N}, ...]   # the ## Gaps gap_id values this plan fixes
----
-```
-This lets `/gsd:verify-work` reconcile resolved gaps on resume (a gap whose plan has a matching `*-SUMMARY.md` is marked `status: resolved`, not re-diagnosed as a fresh blocker).
-</downstream_consumer>
-""",
-  subagent_type="gsd-planner",
-  model="{planner_model}",
-  description="Plan gap fixes for Phase {phase}"
-)
-````
+Spawn gsd-planner in --gaps mode against the UAT (with diagnoses), `{state_path}` (Project State), and `{roadmap_path}` (Roadmap). Each created PLAN.md MUST carry `gap_closure: true` and `gap_ids: [...]` in its frontmatter (#1921) so a later verify-work resume can reconcile it.
 
+<!-- gsd:protected -->
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
-On return:
-- **PLANNING COMPLETE:** Proceed to `verify_gap_plans`
-- **PLANNING INCONCLUSIVE:** Report and offer manual intervention
+PLANNING COMPLETE proceeds to verify_gap_plans; PLANNING INCONCLUSIVE reports and offers manual intervention.
 </step>
 
 <step name="verify_gap_plans">
-**Verify fix plans with checker:**
-
-Display:
-```
-### GSD ► VERIFYING FIX PLANS
-
-◆ Spawning plan checker... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
-```
-
-Initialize: `iteration_count = 1`
-
-Spawn gsd-plan-checker:
-
-```
-Agent(
-  prompt="""
-<verification_context>
-
-**Phase:** {phase_number}
-**Phase Goal:** Close diagnosed gaps from UAT
-
-<required_reading>
-- {phase_dir}/*-PLAN.md (Plans to verify)
-</required_reading>
-
-${AGENT_SKILLS_CHECKER}
-
-</verification_context>
-
-<expected_output>
-Return one of:
-- ## VERIFICATION PASSED — all checks pass
-- ## ISSUES FOUND — structured issue list
-</expected_output>
-""",
-  subagent_type="gsd-plan-checker",
-  model="{checker_model}",
-  description="Verify Phase {phase} fix plans"
-)
-```
+Spawn gsd-plan-checker against the fix plans (iteration_count starts at 1), model="{checker_model}" (omit on inherit/empty, #2517).
 
+<!-- gsd:protected -->
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
 On return:
 - **VERIFICATION PASSED:** Proceed to `present_ready`
 - **ISSUES FOUND:** Count BLOCKER + WARNING entries in the YAML issues block; an entry whose severity is missing or unrecognized counts as a BLOCKER (fail closed). If zero — every entry is explicitly INFO — display `ℹ advisory — {dimension}: {description}` per entry and proceed to `present_ready`; INFO is advisory and never enters the loop (#3724). Otherwise proceed to `revision_loop`
+
+Exact Agent() prompt fields: `gsd-core/workflows/verify-work/detail/elaboration.md` § 2.
 </step>
 
 <step name="revision_loop">
@@ -869,26 +732,6 @@ Display: `Sending back to planner for revision... (iteration {N}/3)`
 
 Spawn gsd-planner with revision context:
 
-```
-Agent(
-  prompt="""
-<revision_context>
-
-**Phase:** {phase_number}
-**Mode:** revision
-
-<required_reading>
-- {phase_dir}/*-PLAN.md (Existing plans)
-</required_reading>
-
-${AGENT_SKILLS_PLANNER}
-
-**Checker issues:**
-{structured_issues_from_checker}
-
-</revision_context>
-
-<instructions>
 Read existing PLAN.md files. Make targeted updates to address checker issues.
 
 `required_property` + evidence + severity BIND. `fix_hint` is ONE non-binding example route: a
@@ -900,14 +743,8 @@ the alternatives rather than applying or working around it. Full contract:
 `gsd-core/references/planner-revision.md`, which you load in revision mode.
 
 Do NOT replan from scratch unless issues are fundamental.
-</instructions>
-""",
-  subagent_type="gsd-planner",
-  model="{planner_model}",
-  description="Revise Phase {phase} plans"
-)
-```
 
+<!-- gsd:protected -->
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
 **If the planner returns `## REVISION_CONFLICT`:** do NOT increment `iteration_count` and do NOT
@@ -938,9 +775,12 @@ Offer options:
 2. Provide guidance (user gives direction, retry)
 3. Abandon (exit, user runs /gsd:plan-phase manually)
 
-Wait for user response.
+Then wait for the user to pick one.
+
+Exact Agent() prompt fields (revision_context, required_reading): `gsd-core/workflows/verify-work/detail/elaboration.md` § 3.
 </step>
 
+
 <step name="present_ready">
 **Present completion and next steps:**
 

package/hooks/dist/gsd-agent-isolation-guard.js

@@ -63,8 +63,8 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch } = require('./lib/isolation-sentinel.js');
-const { REASON_CODE } = require('./lib/isolation-deny-reason.js');
+const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
+const { REASON_CODE, describeSentinelDiscard } = require('./lib/isolation-deny-reason.js');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
 
 // Required at module top, alongside the other ./lib requires — NOT behind
@@ -385,16 +385,20 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
     projectExists = false;
   }
   if (!projectExists) {
-    return { gsdProject: false, isolation: null, harnessFlag: null, error: null };
+    return { gsdProject: false, isolation: null, harnessFlag: null, error: null, sentinelDiscarded: null };
   }
 
   const sentinel = readSentinel(cwd, { clock });
-  if (sentinel.present && !sentinel.stale && sentinelAppliesToDispatch(sentinel, dispatchIds)) {
+  // Hoisted so the "sentinel was present/fresh but did not apply" case below
+  // (#4594 row 15 — Postel's-Law finding) can distinguish itself from
+  // "absent"/"stale" without re-deriving applicability.
+  const applies = sentinelAppliesToDispatch(sentinel, dispatchIds);
+  if (sentinel.present && !sentinel.stale && applies) {
     if (sentinel.isolation !== 'harness-worktree') {
-      return { gsdProject: true, isolation: sentinel.isolation, harnessFlag: null, error: null };
+      return { gsdProject: true, isolation: sentinel.isolation, harnessFlag: null, error: null, sentinelDiscarded: null };
     }
     if (sentinel.harnessFlag) {
-      return { gsdProject: true, isolation: 'harness-worktree', harnessFlag: sentinel.harnessFlag, error: null };
+      return { gsdProject: true, isolation: 'harness-worktree', harnessFlag: sentinel.harnessFlag, error: null, sentinelDiscarded: null };
     }
     // #3045 BLOCKER 2 fix: the sentinel already PROVED this dispatch requires
     // isolation (it resolved harness-worktree) but carries no usable flag —
@@ -423,6 +427,7 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
         'dispatch-isolation sentinel resolved "harness-worktree" but recorded no harness_flag — ' +
         'cannot verify what parameter the dispatch must carry.'
       ),
+      sentinelDiscarded: null,
     };
   }
 
@@ -430,11 +435,19 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
   // conservative fallback (#3045 finding — must still cover fail-closed case
   // (a): a project that opted out of worktrees entirely via
   // workflow.use_worktrees).
+  //
+  // #4594 row 15: a PRESENT, FRESH sentinel that simply does not apply to
+  // THIS dispatch (identifiers disagree) is a distinct case from "absent" or
+  // "stale" — record what was discarded so evaluateDispatch can name it in a
+  // block reason instead of silently falling through to a registry-resolution
+  // message that never mentions the sentinel existed.
+  const sentinelDiscarded = buildSentinelDiscard(sentinel, dispatchIds);
+
   try {
     const { isolation, harnessFlag } = resolveRegistryIsolation(cwd, configPath);
-    return { gsdProject: true, isolation, harnessFlag, error: null };
+    return { gsdProject: true, isolation, harnessFlag, error: null, sentinelDiscarded };
   } catch (err) {
-    return { gsdProject: true, isolation: null, harnessFlag: null, error: err };
+    return { gsdProject: true, isolation: null, harnessFlag: null, error: err, sentinelDiscarded };
   }
 }
 
@@ -464,10 +477,16 @@ function evaluateDispatch(data, { clock = Date } = {}) {
   }
 
   const cwd = data.cwd || process.cwd();
-  // #3045 SECURITY F2: best-effort plan/phase extraction from this
-  // dispatch's own description text, so a fresh sentinel that disagrees
-  // with THIS dispatch is treated as inapplicable rather than trusted.
-  const dispatchIds = extractDispatchIdentifiers(toolInput.description);
+  // #3045 SECURITY F2 / #4594: best-effort plan/phase extraction from this
+  // dispatch's own text, so a fresh sentinel that disagrees with THIS
+  // dispatch is treated as inapplicable rather than trusted. PROMPT FIRST:
+  // `description` is short, model-authored free text that only carries usable
+  // identity when the model happens to reproduce the dispatch template
+  // verbatim, while the canonical `[gsd:dispatch phase="…" plan="…"]` marker
+  // (or, failing that, the prose fallback) lives in the prompt body itself —
+  // `description` is kept only as a fallback for a marker/prose match that
+  // exists solely in it.
+  const dispatchIds = extractDispatchIdentifiers(toolInput.prompt, toolInput.description);
   const state = resolveIsolationState(cwd, { clock, dispatchIds });
 
   if (!state.gsdProject) return { action: 'allow' };
@@ -493,7 +512,8 @@ function evaluateDispatch(data, { clock = Date } = {}) {
         `required — a guard that cannot verify must not answer "safe" (#3050). Retry once the ` +
         `project configuration is readable.`;
     const reasonCode = isBuildFailure ? REASON_CODE.RUNTIME_BUILD_FAILED : REASON_CODE.CONFIG_UNREADABLE;
-    return { action: 'block', reason, reasonCode };
+    const fullReason = state.sentinelDiscarded ? reason + describeSentinelDiscard(state.sentinelDiscarded) : reason;
+    return { action: 'block', reason: fullReason, reasonCode, sentinelDiscarded: state.sentinelDiscarded };
   }
 
   if (state.isolation !== 'harness-worktree') return { action: 'allow' };
@@ -503,13 +523,14 @@ function evaluateDispatch(data, { clock = Date } = {}) {
 
   if (toolInput[parsed.param] === parsed.value) return { action: 'allow' };
 
-  const reason =
+  let reason =
     `Agent isolation guard: this project's dispatch isolation resolves to "harness-worktree", ` +
     `but the Agent() dispatch for subagent_type="${subagentType}" is missing ` +
     `${parsed.param}="${parsed.value}". Add ${parsed.param}="${parsed.value}" to the Agent() ` +
     `call so the executor runs in an isolated worktree instead of the primary checkout ` +
     `(gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md).`;
-  return { action: 'block', reason, reasonCode: REASON_CODE.HARNESS_FLAG_MISSING };
+  if (state.sentinelDiscarded) reason += describeSentinelDiscard(state.sentinelDiscarded);
+  return { action: 'block', reason, reasonCode: REASON_CODE.HARNESS_FLAG_MISSING, sentinelDiscarded: state.sentinelDiscarded };
 }
 
 /* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
@@ -524,7 +545,12 @@ function main() {
       const data = JSON.parse(input);
       const decision = evaluateDispatch(data);
       if (decision.action === 'block') {
-        const out = { decision: 'block', reason: decision.reason, reason_code: decision.reasonCode };
+        const out = {
+          decision: 'block',
+          reason: decision.reason,
+          reason_code: decision.reasonCode,
+          sentinel_discarded: decision.sentinelDiscarded ?? null,
+        };
         // Kimi feeds stderr (not stdout) back to the model on exit 2.
         deny(out, decision.reason);
       }

package/hooks/dist/gsd-context-monitor.js

@@ -14,6 +14,9 @@
 // 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)
@@ -30,8 +33,8 @@ const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
 // 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%
-const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+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
@@ -57,6 +60,41 @@ const COMPACT_GRACE_SECONDS = 60;
 // 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.
@@ -164,14 +202,11 @@ function writeSentinel(target, payload) {
 }
 
 let input = '';
-// 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.
-const stdinTimeout = setTimeout(() => allow(undefined), 10000);
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => input += chunk);
-process.stdin.on('end', () => {
+// 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);
@@ -266,18 +301,26 @@ process.stdin.on('end', () => {
       allow(undefined);
     }
 
-    // Check if context warnings are disabled via config.
+    // 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)
+      // 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.
@@ -352,7 +395,7 @@ process.stdin.on('end', () => {
     const usedPct = metrics.used_pct;
 
     // No warning needed
-    if (remaining > WARNING_THRESHOLD) {
+    if (remaining > thresholds.warning) {
       allow(undefined);
     }
 
@@ -389,7 +432,7 @@ process.stdin.on('end', () => {
 
     warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
 
-    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const isCritical = remaining <= thresholds.critical;
     const currentLevel = isCritical ? 'critical' : 'warning';
 
     // Emit immediately on first warning, then debounce subsequent ones
@@ -491,4 +534,34 @@ process.stdin.on('end', () => {
     // 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 };

package/hooks/dist/gsd-cursor-subagent-start.js

@@ -62,8 +62,8 @@ const { allow } = require('./lib/hook-exit.js');
 // hooks/lib/cursor-workspace.js. Staged next to these scripts by
 // writeCursorHooksJson so the require always resolves post-install.
 const { resolveStatePath } = require('./lib/cursor-workspace.js');
-const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch } = require('./lib/isolation-sentinel.js');
-const { REASON_CODE } = require('./lib/isolation-deny-reason.js');
+const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
+const { REASON_CODE, describeSentinelDiscard } = require('./lib/isolation-deny-reason.js');
 // #3582: gsd-core/bin/lib/*.cjs (runtime-homes.cjs, worktree-safety.cjs,
 // runtime-name-policy.cjs, capability-registry.cjs — required below, inside
 // resolveIsolationEvidence and resolveFallbackIsolation) are tsc build
@@ -491,18 +491,25 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `Refusing to allow this subagent to spawn until the runtime library is built — a guard ` +
         `that cannot verify must not answer "safe" (#3050).`,
       reasonCode: REASON_CODE.RUNTIME_BUILD_FAILED,
+      sentinelDiscarded: null,
     };
   }
 
+  // #3045 BLOCKER fix: a fresh sentinel is authoritative for THIS dispatch's
+  // actual resolved isolation — see the doc comment above.
+  // #3045 SECURITY F2: a fresh sentinel that names a DIFFERENT plan/phase
+  // than this dispatch is not applicable to it — fall through to the
+  // conservative fallback exactly as a stale sentinel would.
+  // Hoisted (readSentinel never throws) so the "present, fresh, but did not
+  // apply" case (#4594 row 15) can be reported on every deny path below
+  // instead of silently discarded.
+  const sentinel = readSentinel(root, { clock });
+  const applies = sentinelAppliesToDispatch(sentinel, dispatchIds);
+  const sentinelDiscarded = buildSentinelDiscard(sentinel, dispatchIds);
+
   let declaredIsolation;
   try {
-    // #3045 BLOCKER fix: a fresh sentinel is authoritative for THIS
-    // dispatch's actual resolved isolation — see the doc comment above.
-    // #3045 SECURITY F2: a fresh sentinel that names a DIFFERENT
-    // plan/phase than this dispatch is not applicable to it — fall through
-    // to the conservative fallback exactly as a stale sentinel would.
-    const sentinel = readSentinel(root, { clock });
-    declaredIsolation = (sentinel.present && !sentinel.stale && sentinelAppliesToDispatch(sentinel, dispatchIds))
+    declaredIsolation = (sentinel.present && !sentinel.stale && applies)
       ? sentinel.isolation
       : resolveFallbackIsolation(root, configPath);
   } catch {
@@ -513,8 +520,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `dispatch-isolation configuration ('.planning/config.json' exists under "${root}"). ` +
         `Refusing to allow this subagent to spawn without being able to verify whether ` +
         `isolation is required — a guard that cannot verify must not answer "safe" (#3050). ` +
-        `Retry once the project configuration is readable.`,
+        `Retry once the project configuration is readable.` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.CONFIG_UNREADABLE,
+      sentinelDiscarded,
     };
   }
 
@@ -530,8 +539,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `GSD subagent isolation guard: this project's dispatch isolation resolves to ` +
         `"harness-worktree", but the subagentStart payload for this dispatch carries no usable ` +
         `subagent_type. Refusing to allow it to spawn without being able to confirm whether it ` +
-        `is a GSD executor — a guard that cannot verify must not answer "safe" (#3050).`,
+        `is a GSD executor — a guard that cannot verify must not answer "safe" (#3050).` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.NO_SUBAGENT_TYPE,
+      sentinelDiscarded,
     };
   }
 
@@ -547,8 +558,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `"harness-worktree", but whether "${root}" is running in an isolated Cursor worktree ` +
         `could not be determined (git did not respond). Refusing to allow subagent_type=` +
         `"${subagentType}" to spawn without being able to verify isolation — a guard that ` +
-        `cannot verify must not answer "safe" (#3050). Retry once git is responsive.`,
+        `cannot verify must not answer "safe" (#3050). Retry once git is responsive.` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.CANNOT_DETERMINE_ISOLATION,
+      sentinelDiscarded,
     };
   }
 
@@ -560,8 +573,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
       `which is not an isolated Cursor worktree — it would edit the user's primary checkout ` +
       `directly, with no consent and no warning. Start an isolated session first (the ` +
       `"--worktree" CLI flag or the "/worktree" chat command; Cursor manages these worktrees ` +
-      `under "~/.cursor/worktrees/") and retry.`,
+      `under "~/.cursor/worktrees/") and retry.` +
+      (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
     reasonCode: REASON_CODE.NOT_ISOLATED_WORKTREE,
+    sentinelDiscarded,
   };
 }
 
@@ -611,7 +626,12 @@ function main() {
         decision = { action: 'allow' };
       }
       if (decision.action === 'deny') {
-        const out = { permission: 'deny', user_message: decision.reason, reason_code: decision.reasonCode };
+        const out = {
+          permission: 'deny',
+          user_message: decision.reason,
+          reason_code: decision.reasonCode,
+          sentinel_discarded: decision.sentinelDiscarded ?? null,
+        };
         if (additionalContext !== null) out.additional_context = additionalContext;
         process.stdout.write(JSON.stringify(out));
         return;