cap-pro 1.0.0

package/commands/cap/trace.md

@@ -0,0 +1,133 @@
+---
+name: cap:trace
+description: "Print the call graph for a single acceptance criterion across all contributing files. Resolves primary file via @cap-feature(...primary:true) or tag-density heuristic."
+argument-hint: "<AC-N | F-NNN/AC-N> [--depth N] [--restrict] [--json]"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<!-- @cap-context CAP v2.0 trace command -- shows where an AC is implemented across files and what it depends on. Read-only. -->
+<!-- @cap-decision Trace is read-only -- no Feature Map writes, no session updates. Safe to run repeatedly. -->
+<!-- @cap-feature(feature:F-045) /cap:trace renders TraceResult from cap-trace.cjs as a tree. -->
+<!-- @cap-todo(ac:F-045/AC-4) /cap:trace AC-N shall print the call graph from the primary file across referenced files for a given acceptance criterion. -->
+
+<objective>
+Print a structured trace for a single acceptance criterion:
+
+- Which file is the primary implementation (designated via `@cap-feature(...primary:true)` or inferred via tag density)
+- Which other files contribute to the same AC
+- Static call graph (require/import edges) walked outward from the primary file up to N hops
+
+This makes multi-file ACs navigable when a single AC spans more than one source file.
+
+**Argument formats:**
+- `F-NNN/AC-M` -- fully qualified
+- `AC-M` -- short form, requires an active feature in `.cap/SESSION.json`
+
+**Flags:**
+- `--depth N` -- max BFS depth for the call graph (default 3)
+- `--restrict` -- only follow edges into other AC-contributing files (suppresses non-AC neighbors)
+- `--json` -- emit raw `TraceResult` JSON instead of formatted output
+</objective>
+
+<context>
+$ARGUMENTS
+
+@.cap/SESSION.json
+</context>
+
+<process>
+
+## Step 0: Parse arguments
+
+Read `$ARGUMENTS`. Extract:
+- The first non-flag token as `ac_arg`
+- `--depth N` -> `depth` (integer, default 3)
+- `--restrict` -> `restrict_to_ac_files` (boolean)
+- `--json` -> `json_output` (boolean)
+
+If `ac_arg` is missing, print usage and stop:
+
+```
+Usage: /cap:trace <AC-N | F-NNN/AC-N> [--depth N] [--restrict] [--json]
+```
+
+## Step 1: Resolve AC reference
+
+If `ac_arg` already contains `/` (e.g. `F-045/AC-4`), use it as-is.
+
+Otherwise, read the active feature from SESSION.json and prefix it:
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const s = session.loadSession(process.cwd());
+console.log(s.activeFeature || '');
+"
+```
+
+If the active feature is empty, print:
+
+```
+No active feature in SESSION.json. Pass a fully-qualified AC reference like F-045/AC-1, or run /cap:start to set an active feature.
+```
+
+and stop. Otherwise build `ac_ref = "<activeFeature>/<ac_arg>"`.
+
+## Step 2: Run the trace
+
+```bash
+node -e "
+const tr = require('./cap/bin/lib/cap-trace.cjs');
+const acRef = process.argv[1];
+const _parsedDepth = parseInt(process.argv[2], 10);
+const depth = Number.isFinite(_parsedDepth) ? _parsedDepth : tr.DEFAULT_MAX_DEPTH;
+const restrict = process.argv[3] === 'true';
+const result = tr.traceAc(process.cwd(), acRef, { maxDepth: depth, restrictToAcFiles: restrict });
+const json = process.argv[4] === 'true';
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(tr.formatTraceResult(result));
+}
+" '<AC_REF>' '<DEPTH>' '<RESTRICT>' '<JSON>'
+```
+
+Display the output verbatim.
+
+## Step 2b: Append Design-Usage for the AC's feature (F-063)
+
+<!-- @cap-todo(ac:F-063/AC-5) /cap:trace shall emit a Design-Usage line per feature whose usesDesign is non-empty. -->
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const d = require('./cap/bin/lib/cap-design.cjs');
+const trace = require('./cap/bin/lib/cap-trace.cjs');
+const featureId = process.argv[1];
+// @cap-todo(ac:F-081/AC-4 iter:2) Migrated to {safe: true} opt-in to preserve CLI on duplicate-ID FEATURE-MAP.
+// @cap-decision(F-081/iter2) Warn on parseError; continue with partial map for read-only display.
+const map = fm.readFeatureMap(process.cwd(), undefined, { safe: true });
+if (map && map.parseError) {
+  console.warn('cap: trace — duplicate feature ID detected, lookup uses partial map: ' + String(map.parseError.message).trim());
+}
+const feature = map.features.find(f => f.id === featureId);
+if (!feature) process.exit(0);
+const design = d.readDesignMd(process.cwd());
+const designIdx = design ? d.parseDesignIds(design) : { byToken: {}, byComponent: {} };
+const line = trace.formatDesignUsage(feature, designIdx);
+if (line) console.log('Design-Usage: ' + line);
+" '<FEATURE_ID>'
+```
+
+## Step 3: Suggest next action (only when not in --json mode)
+
+Inspect the trace result and suggest one of:
+
+- If `primary.role === 'inferred'` AND `allFiles.length > 1` -> "Designate the canonical file with `@cap-feature(feature:<id>, primary:true)` to suppress the heuristic warning."
+- If `allFiles.length === 0` -> "No tags reference this AC. Add `@cap-todo(ac:<ref>)` at the implementation site, then re-run /cap:scan."
+- If `callGraph.length === 0` AND `primary.file` is set -> "Primary file has no resolvable internal imports. The AC may be self-contained, or imports use dynamic require() / TS path aliases that the static walker cannot resolve."
+- Otherwise -> "Trace looks complete."
+
+</process>

package/commands/cap/ui.md

@@ -0,0 +1,167 @@
+---
+name: cap:ui
+description: CAP-UI local read-only server (--serve, default) or standalone HTML snapshot (--share) of Feature Map, Memory, Threads and DESIGN.md. Optional --editable unlocks DESIGN.md write endpoints (F-068). Zero deps. Node-builtin http + SSE only.
+argument-hint: "[--serve | --share] [--port N] [--editable]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+<!-- @cap-context CAP F-065 /cap:ui command — orchestrates cap-ui.cjs. No agent is spawned: this is deterministic infrastructure with no wizard. -->
+<!-- @cap-context CAP F-068 adds a --editable flag to --serve. It unlocks a DESIGN.md-only write surface (color picker, spacing sliders, component variants). FEATURE-MAP.md and Memory stay read-only even in edit mode. -->
+<!-- @cap-decision Command layer parses flags and calls cap-ui.cjs directly. No Task()/agent spawn — there is nothing conversational here. -->
+<!-- @cap-decision --serve is the default because developers running /cap:ui interactively expect a browser view, not a snapshot-only export. -->
+<!-- @cap-decision(F-068) --editable is opt-in. Default --serve stays fully read-only to match F-065/AC-5. --share never embeds the edit UI (no server to write to). -->
+<!-- @cap-constraint Zero external deps. Do not introduce npm packages at any point in this command. -->
+<!-- @cap-constraint SECURITY: --editable exposes DESIGN.md PUT/DELETE endpoints on localhost. Do NOT use on shared hosts, tunnels (ngrok), or anywhere the loopback is reachable by other users. -->
+
+<!-- @cap-feature(feature:F-065) CAP-UI Core — Local Server + Static Export -->
+<!-- @cap-feature(feature:F-068) CAP-UI Visual Design Editor — DESIGN.md-only edit surface -->
+
+<objective>
+<!-- @cap-todo(ac:F-065/AC-1) /cap:ui --serve starts local Node http server on configurable port (default 4747), zero deps, node builtins only. -->
+<!-- @cap-todo(ac:F-065/AC-2) The served UI renders Feature-Map + Memory + Threads + DESIGN.md as a readable HTML view. -->
+<!-- @cap-todo(ac:F-065/AC-3) File-watcher observes FEATURE-MAP.md, DESIGN.md, .cap/memory/, .cap/SESSION.json → UI refreshes via SSE. -->
+<!-- @cap-todo(ac:F-065/AC-4) /cap:ui --share generates standalone HTML snapshot at .cap/ui/snapshot.html with inline CSS/JS. -->
+<!-- @cap-todo(ac:F-065/AC-5) UI is read-only for Feature-Map and Memory; DESIGN.md edit capability is introduced in F-068. -->
+<!-- @cap-todo(ac:F-065/AC-6) Server logs all events (start, SSE connect, file changes) on stdout with ISO timestamps. -->
+
+Runs one of two flows:
+- `--serve` (default) — starts a local HTTP server on port 4747 (or `--port N`) that renders the Feature Map, Memory, Threads, and DESIGN.md. Broadcasts file changes to the browser via Server-Sent Events.
+- `--share` — writes a standalone HTML snapshot to `.cap/ui/snapshot.html` with inline CSS/JS, safe to share via PR/Slack.
+
+Optional flags:
+- `--editable` (F-068, only valid with `--serve`) — unlocks the DESIGN.md Visual Editor:
+  - Color-pickers for each DT-NNN color token
+  - Range sliders for spacing + typography scales
+  - Variant add/remove per DC-NNN component
+  - Edits are atomic (temp+rename), Git-friendly (single-line diffs), and restricted to DESIGN.md.
+  - FEATURE-MAP.md and Memory remain read-only even in edit mode.
+  - **Security**: write endpoints are exposed on localhost. Do not use on shared hosts, tunnels, or multi-user machines.
+
+**Key guarantees:**
+- Zero runtime dependencies. Only `node:` builtins (`http`, `fs`, `path`, `url`, `os`).
+- Read-only by default: no POST/PUT/DELETE routes, no forms, no edit endpoints without `--editable` (F-065/AC-5).
+- `--editable` only unlocks `/api/design/*` PUT/DELETE; FEATURE-MAP + Memory always 405 on writes (F-068/AC-6).
+- SSE-only for live updates (no WebSockets).
+- Port auto-increments up to +10 if the default is taken; fails loudly otherwise.
+- `--share` snapshot contains no external URLs (no Google Fonts, no CDN, no fetch calls) — safe for offline sharing.
+- `--share` NEVER embeds the edit UI, even when run in a session where `--editable` was set — snapshots are static and have no server to write against.
+
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+<!-- @cap-todo(ac:F-065/AC-1) Parse --serve (default), --share, --port N from $ARGUMENTS. -->
+<!-- @cap-todo(ac:F-068/AC-1) Parse --editable flag. Only valid with --serve; --share ignores it. -->
+
+Inspect `$ARGUMENTS`:
+- `--share` — set `mode = "share"`
+- `--serve` — set `mode = "serve"`
+- `--port N` — capture `port` (integer)
+- `--editable` — set `editable = true` (ignored with `--share`)
+- If no mode flag, default to `mode = "serve"`
+
+Log: `cap:ui | mode: {mode}`{ " | port: " + port if mode === 'serve' && port }{ " | editable" if editable }
+
+## Step 1: Dispatch by mode
+
+### Step 1a: --share (snapshot flow)
+
+<!-- @cap-todo(ac:F-065/AC-4) --share writes .cap/ui/snapshot.html via createSnapshot(). -->
+
+```bash
+node -e "
+const ui = require('./cap/bin/lib/cap-ui.cjs');
+const out = ui.createSnapshot({ projectRoot: process.cwd() });
+console.log(JSON.stringify(out));
+"
+```
+
+Report:
+
+```
+cap:ui --share complete.
+
+Snapshot:  .cap/ui/snapshot.html
+Bytes:     {bytes}
+
+Next steps:
+  - Open .cap/ui/snapshot.html in any browser (no server required).
+  - Share via PR comment / Slack DM — inline CSS/JS, no external fetch.
+  - Re-run /cap:ui --share to refresh.
+```
+
+Stop here. Do not run Step 1b.
+
+### Step 1b: --serve (live server flow)
+
+<!-- @cap-todo(ac:F-065/AC-1) --serve starts the local HTTP server. -->
+<!-- @cap-todo(ac:F-065/AC-3) File watcher attached, SSE broadcasts change events to browser clients. -->
+<!-- @cap-todo(ac:F-065/AC-6) Every server event is logged to stdout via cap-ui.logEvent. -->
+
+Start the server in the foreground and print the URL. The server blocks until the user hits Ctrl+C (SIGINT).
+
+```bash
+node -e "
+const ui = require('./cap/bin/lib/cap-ui.cjs');
+const port = {PORT_OR_DEFAULT};
+const editable = {EDITABLE};
+(async function(){
+  const { url, port: actual, stop } = await ui.startServer({ projectRoot: process.cwd(), port, editable });
+  console.log('cap:ui listening on ' + url + '  (port ' + actual + ')' + (editable ? '  [EDITABLE — DESIGN.md writes enabled]' : ''));
+  console.log('Ctrl+C to stop.');
+  process.on('SIGINT', async function(){
+    console.log('\\ncap:ui stopping…');
+    await stop();
+    process.exit(0);
+  });
+})().catch(function(err){ console.error('cap:ui server failed:', err.message); process.exit(1); });
+"
+```
+
+Final report appears only after the user stops the server (Ctrl+C):
+
+```
+cap:ui --serve stopped.
+Port:           {actual_port}
+Session saved:  .cap/SESSION.json (lastCommand updated)
+```
+
+## Step 2: Update session state (both modes, fire-and-forget)
+
+<!-- @cap-decision Session write happens after the main action so a failing --serve still reports the attempt. -->
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:ui',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'ui-{mode}'
+});
+"
+```
+
+</process>
+
+## Notes
+
+- **No agent is spawned.** cap:ui is pure infrastructure — no LLM call is required.
+- **Mind-Map (F-066), Thread Navigator (F-067), DESIGN.md editor (F-068)** are all shipped.
+- **Port conflicts**: if 4747 is taken, the server auto-tries 4748, 4749, …, up to 4757; then fails with a clear error.
+- **File watcher caveats**: `fs.watch` is platform-specific. Linux fires multiple events per write (inotify); macOS coalesces via FSEvents. A 100ms debounce smooths the difference.
+- **Read-only guarantee (default)**: the HTML has no `<form>`, no POST targets, and the server rejects non-GET/HEAD methods with 405. Only `--editable` unlocks PUT/DELETE on `/api/design/*`.
+- **Edit scope (F-068/AC-6)**: `--editable` is strictly DESIGN.md. FEATURE-MAP.md and Memory endpoints always respond 405 on writes — collaboration there stays Git-based.
+- **Atomic writes (F-068/AC-5)**: each edit writes a temp file and renames it over DESIGN.md, so a crashed process never leaves a truncated file.
+- **Path-traversal guard (F-068)**: `createSnapshot(outputPath)` now refuses paths that escape the project root; the same guard gates DESIGN.md edits.

package/hooks/dist/cap-check-update.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// @cap-feature(feature:F-009) Hooks System — background update checker (SessionStart hook)
+// cap-hook-version: {{CAP_VERSION}}
+// Check for CAP updates in background, write result to cache
+// Called by SessionStart hook - runs once per session
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const homeDir = os.homedir();
+const cwd = process.cwd();
+
+// Detect runtime config directory (supports Claude, OpenCode, Gemini)
+// Respects CLAUDE_CONFIG_DIR for custom config directory setups
+function detectConfigDir(baseDir) {
+  // Check env override first (supports multi-account setups)
+  const envDir = process.env.CLAUDE_CONFIG_DIR;
+  if (envDir && fs.existsSync(path.join(envDir, 'cap', 'VERSION'))) {
+    return envDir;
+  }
+  for (const dir of ['.config/opencode', '.opencode', '.gemini', '.claude']) {
+    if (fs.existsSync(path.join(baseDir, dir, 'cap', 'VERSION'))) {
+      return path.join(baseDir, dir);
+    }
+  }
+  return envDir || path.join(baseDir, '.claude');
+}
+
+const globalConfigDir = detectConfigDir(homeDir);
+const projectConfigDir = detectConfigDir(cwd);
+const cacheDir = path.join(globalConfigDir, 'cache');
+const cacheFile = path.join(cacheDir, 'cap-update-check.json');
+
+// VERSION file locations (check project first, then global)
+const projectVersionFile = path.join(projectConfigDir, 'cap', 'VERSION');
+const globalVersionFile = path.join(globalConfigDir, 'cap', 'VERSION');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Run check in background (spawn background process, windowsHide prevents console flash)
+const child = spawn(process.execPath, ['-e', `
+  const fs = require('fs');
+  const path = require('path');
+  const { execSync } = require('child_process');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const projectVersionFile = ${JSON.stringify(projectVersionFile)};
+  const globalVersionFile = ${JSON.stringify(globalVersionFile)};
+
+  // Check project directory first (local install), then global
+  let installed = '0.0.0';
+  let configDir = '';
+  try {
+    if (fs.existsSync(projectVersionFile)) {
+      installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
+      configDir = path.dirname(path.dirname(projectVersionFile));
+    } else if (fs.existsSync(globalVersionFile)) {
+      installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+      configDir = path.dirname(path.dirname(globalVersionFile));
+    }
+  } catch (e) {}
+
+  // Check for stale hooks — compare hook version headers against installed VERSION
+  // Hooks live inside cap/hooks/, not configDir/hooks/
+  let staleHooks = [];
+  if (configDir) {
+    const hooksDir = path.join(configDir, 'cap', 'hooks');
+    try {
+      if (fs.existsSync(hooksDir)) {
+        const hookFiles = fs.readdirSync(hooksDir).filter(f => (f.startsWith('gsd-') || f.startsWith('cap-')) && f.endsWith('.js'));
+        for (const hookFile of hookFiles) {
+          try {
+            const content = fs.readFileSync(path.join(hooksDir, hookFile), 'utf8');
+            const versionMatch = content.match(/\\/\\/ (?:gsd|cap)-hook-version:\\s*(.+)/);
+            if (versionMatch) {
+              const hookVersion = versionMatch[1].trim();
+              if (hookVersion !== installed && !hookVersion.includes('{{')) {
+                staleHooks.push({ file: hookFile, hookVersion, installedVersion: installed });
+              }
+            } else {
+              // No version header at all — definitely stale (pre-version-tracking)
+              staleHooks.push({ file: hookFile, hookVersion: 'unknown', installedVersion: installed });
+            }
+          } catch (e) {}
+        }
+      }
+    } catch (e) {}
+  }
+
+  let latest = null;
+  try {
+    latest = execSync('npm view code-as-plan version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
+  } catch (e) {}
+
+  const result = {
+    update_available: latest && installed !== latest,
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000),
+    stale_hooks: staleHooks.length > 0 ? staleHooks : undefined
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  stdio: 'ignore',
+  windowsHide: true,
+  detached: true  // Required on Windows for proper process detachment
+});
+
+child.unref();

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

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// @cap-feature(feature:F-009) Hooks System — context window monitor (PostToolUse hook)
+// cap-hook-version: {{CAP_VERSION}}
+/**
+ * Context Monitor - PostToolUse/AfterTool hook (Gemini uses AfterTool)
+ *
+ * Reads context metrics from the statusline bridge file and injects
+ * advisory hints 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 an advisory
+ *      hint as additionalContext, which the agent sees in its conversation
+ *
+ * Behavior changes (vs. earlier revisions):
+ *   - Tonality is **advisory**, not imperative. Messages no longer say
+ *     "Inform the user…" — they say "Hinweis (vom CAP-Framework, vom
+ *     User-Prompt unabhängig): … Der Agent kann den User informieren falls
+ *     relevant für die Aufgabe." This avoids overriding user preferences
+ *     such as "terse responses, no summaries".
+ *   - Warning threshold lowered from 35% → 30% to reduce early warnings;
+ *     focus is on the truly critical 25% escalation.
+ *   - New ENV `CAP_DISABLE_CONTEXT_MONITOR=1` silences the hook entirely
+ *     (for power users who don't want any advisory injection).
+ *
+ * Thresholds:
+ *   WARNING  (remaining <= 30%): advisory hint, agent decides whether to surface
+ *   CRITICAL (remaining <= 25%): stronger advisory, agent decides whether to surface
+ *
+ * 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 WARNING_THRESHOLD = 30;  // remaining_percentage <= 30% (was 35%)
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+
+// Power-user kill switch: if set, hook is fully silent regardless of context state.
+if (process.env.CAP_DISABLE_CONTEXT_MONITOR === '1' ||
+    process.env.CAP_DISABLE_CONTEXT_MONITOR === 'true') {
+  process.exit(0);
+}
+
+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(() => process.exit(0), 10000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    // Check if context warnings are disabled via config
+    const cwd = data.cwd || process.cwd();
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (config.hooks?.context_warnings === false) {
+          process.exit(0);
+        }
+      } catch (e) {
+        // Ignore config parse errors
+      }
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently
+    if (!fs.existsSync(metricsPath)) {
+      process.exit(0);
+    }
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {
+        // Corrupted file, reset
+      }
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    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
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(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'));
+
+    // Build advisory message (no imperative commands — see #884).
+    // The framework-prefix makes it explicit that this is metadata
+    // independent of the user prompt, so user preferences like
+    // "terse responses" are not violated by the agent itself.
+    const PREFIX = 'Hinweis (vom CAP-Framework, vom User-Prompt unabhängig): ';
+    const SUFFIX = ' Der Agent kann den User informieren falls relevant für die Aufgabe.';
+
+    let message;
+    if (isCritical) {
+      message = isGsdActive
+        ? `${PREFIX}CONTEXT CRITICAL — Auslastung bei ${usedPct}%, verbleibend ${remaining}%. ` +
+          'Context ist nahezu erschöpft. GSD-State ist bereits in STATE.md getrackt; ' +
+          'es ist nicht nötig, autonom Handoff-Dateien zu schreiben oder neue komplexe Arbeit zu starten.' +
+          SUFFIX
+        : `${PREFIX}CONTEXT CRITICAL — Auslastung bei ${usedPct}%, verbleibend ${remaining}%. ` +
+          'Context ist nahezu erschöpft. Autonomes Speichern von State oder Handoff-Dateien ' +
+          'ist nicht erforderlich, sofern der User nicht ausdrücklich danach fragt.' +
+          SUFFIX;
+    } else {
+      message = isGsdActive
+        ? `${PREFIX}CONTEXT WARNING — Auslastung bei ${usedPct}%, verbleibend ${remaining}%. ` +
+          'Context-Budget wird knapp. Größere neue Arbeit zwischen definierten Plan-Schritten ' +
+          'ist günstig zu vermeiden.' +
+          SUFFIX
+        : `${PREFIX}CONTEXT WARNING — Auslastung bei ${usedPct}%, verbleibend ${remaining}%. ` +
+          'Context-Budget wird knapp. Unnötige Exploration oder das Anstoßen neuer komplexer ' +
+          'Arbeit ist günstig zu vermeiden.' +
+          SUFFIX;
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: process.env.GEMINI_API_KEY ? "AfterTool" : "PostToolUse",
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});