harness-everything 0.2.2 → 0.3.6

package/hooks/scripts/boundary-guard.js

@@ -1,55 +1,55 @@
-#!/usr/bin/env node
-/**
- * Boundary Guard (PreToolUse: Grep|Glob|Read)
- * Hard-blocks two concrete sources of context bloat / hallucination risk:
- *   1. Reading a large file whole instead of a scoped chunk (offset/limit).
- *   2. Searching inside known noise directories (node_modules, .git, build
- *      output, etc.) that produce huge, low-signal result sets.
- * Fails open on any parse/lookup error - never blocks due to a bug here.
- */
-const fs = require('fs');
-
-const MAX_BYTES_WITHOUT_LIMIT = 512 * 1024; // 512KB
-const NOISE_DIRS = ['node_modules', '.git', 'dist', 'build', 'out', '.next', 'target', 'vendor', '__pycache__', '.venv', 'coverage'];
-
-let inputData = '';
-process.stdin.on('data', chunk => { inputData += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const payload = JSON.parse(inputData);
-    const toolName = payload.tool_name;
-    const input = payload.tool_input || {};
-
-    if (toolName === 'Read') {
-      const filePath = input.file_path;
-      if (filePath && !input.limit && fs.existsSync(filePath)) {
-        const stat = fs.statSync(filePath);
-        if (stat.isFile() && stat.size > MAX_BYTES_WITHOUT_LIMIT) {
-          console.error(`[Boundary Guard] BLOCKED: "${filePath}" is ${(stat.size / 1024).toFixed(0)}KB.`);
-          console.error(`Reading a file this large in one call risks context bloat and "lost in the middle" degradation.`);
-          console.error(`Re-issue the Read with an explicit "offset"/"limit" to pull a targeted slice, or use Grep to locate the relevant section first.`);
-          process.exit(2);
-        }
-      }
-    }
-
-    if (toolName === 'Grep' || toolName === 'Glob') {
-      const searchPath = input.path || '';
-      const pattern = input.pattern || '';
-      const hitsNoiseDir = NOISE_DIRS.some(dir => {
-        const asPathSegment = new RegExp(`(^|[\\\\/])${dir}($|[\\\\/])`);
-        return asPathSegment.test(searchPath) || asPathSegment.test(pattern);
-      });
-      if (hitsNoiseDir) {
-        console.error(`[Boundary Guard] BLOCKED: search targets a noise directory (${NOISE_DIRS.join(', ')}).`);
-        console.error(`These produce huge, low-signal result sets and rarely contain what you're actually looking for.`);
-        console.error(`Scope the search to source directories instead, or state explicitly why this directory must be searched.`);
-        process.exit(2);
-      }
-    }
-
-    process.exit(0);
-  } catch (err) {
-    process.exit(0);
-  }
-});
+#!/usr/bin/env node
+/**
+ * Boundary Guard (PreToolUse: Grep|Glob|Read)
+ * Hard-blocks two concrete sources of context bloat / hallucination risk:
+ *   1. Reading a large file whole instead of a scoped chunk (offset/limit).
+ *   2. Searching inside known noise directories (node_modules, .git, build
+ *      output, etc.) that produce huge, low-signal result sets.
+ * Fails open on any parse/lookup error - never blocks due to a bug here.
+ */
+const fs = require('fs');
+
+const MAX_BYTES_WITHOUT_LIMIT = 512 * 1024; // 512KB
+const NOISE_DIRS = ['node_modules', '.git', 'dist', 'build', 'out', '.next', 'target', 'vendor', '__pycache__', '.venv', 'coverage'];
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    const toolName = payload.tool_name;
+    const input = payload.tool_input || {};
+
+    if (toolName === 'Read') {
+      const filePath = input.file_path;
+      if (filePath && !input.limit && fs.existsSync(filePath)) {
+        const stat = fs.statSync(filePath);
+        if (stat.isFile() && stat.size > MAX_BYTES_WITHOUT_LIMIT) {
+          console.error(`[Boundary Guard] BLOCKED: "${filePath}" is ${(stat.size / 1024).toFixed(0)}KB.`);
+          console.error(`Reading a file this large in one call risks context bloat and "lost in the middle" degradation.`);
+          console.error(`Re-issue the Read with an explicit "offset"/"limit" to pull a targeted slice, or use Grep to locate the relevant section first.`);
+          process.exit(2);
+        }
+      }
+    }
+
+    if (toolName === 'Grep' || toolName === 'Glob') {
+      const searchPath = input.path || '';
+      const pattern = input.pattern || '';
+      const hitsNoiseDir = NOISE_DIRS.some(dir => {
+        const asPathSegment = new RegExp(`(^|[\\\\/])${dir}($|[\\\\/])`);
+        return asPathSegment.test(searchPath) || asPathSegment.test(pattern);
+      });
+      if (hitsNoiseDir) {
+        console.error(`[Boundary Guard] BLOCKED: search targets a noise directory (${NOISE_DIRS.join(', ')}).`);
+        console.error(`These produce huge, low-signal result sets and rarely contain what you're actually looking for.`);
+        console.error(`Scope the search to source directories instead, or state explicitly why this directory must be searched.`);
+        process.exit(2);
+      }
+    }
+
+    process.exit(0);
+  } catch (err) {
+    process.exit(0);
+  }
+});

package/hooks/scripts/context-compact.js

@@ -1,114 +1,114 @@
-#!/usr/bin/env node
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
-
-function main(payload) {
-  try {
-    // Let's run a quick Git check to estimate context size from modified files
-    const statusRaw = execSync('git status --porcelain', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    if (!statusRaw) {
-      process.exit(0);
-    }
-
-    const lines = statusRaw.split('\n').filter(Boolean);
-    const modifiedCount = lines.length;
-
-    let totalDiffLines = 0;
-    try {
-      const diffStat = execSync('git diff --numstat', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-      if (diffStat) {
-        diffStat.split('\n').forEach(line => {
-          const [added, deleted] = line.split('\t');
-          if (added && added !== '-' && deleted && deleted !== '-') {
-            totalDiffLines += parseInt(added) + parseInt(deleted);
-          }
-        });
-      }
-    } catch (err) {
-      // Ignore git errors
-    }
-
-    // Thresholds for warning
-    const HIGH_FILE_LIMIT = 6;
-    const HIGH_LINE_LIMIT = 400;
-
-    const overThreshold = modifiedCount >= HIGH_FILE_LIMIT || totalDiffLines >= HIGH_LINE_LIMIT;
-
-    // Throttle: this hook fires on EVERY Bash/Edit/Write call, and a warning
-    // about context bloat that repeats on every call becomes context bloat
-    // itself (and trains the model to ignore hook output). Warn on the first
-    // crossing, then only every 10th call while still over - or when the diff
-    // has grown another 50% since the last warning.
-    const stateFile = path.join(getSessionDir(getWorkspaceRoot(), payload && payload.session_id), 'context-compact-state.json');
-    let state = { overCount: 0, lastWarnedLines: 0 };
-    try {
-      if (fs.existsSync(stateFile)) state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-    } catch (err) { /* use default */ }
-
-    if (!overThreshold) {
-      if (state.overCount > 0) {
-        try {
-          fs.writeFileSync(stateFile, JSON.stringify({ overCount: 0, lastWarnedLines: 0 }), 'utf8');
-        } catch (err) { /* ignore */ }
-      }
-      process.exit(0);
-    }
-
-    state.overCount += 1;
-    const onBeat = state.overCount === 1 || state.overCount % 10 === 0;
-    const grewALot = totalDiffLines >= (state.lastWarnedLines || 0) * 1.5 && totalDiffLines > state.lastWarnedLines;
-    const shouldWarn = onBeat || grewALot;
-    if (shouldWarn) state.lastWarnedLines = totalDiffLines;
-    try {
-      fs.writeFileSync(stateFile, JSON.stringify(state), 'utf8');
-    } catch (err) { /* ignore */ }
-
-    if (shouldWarn) {
-      // Plain stdout on exit 0 is only surfaced to Claude for UserPromptSubmit/
-      // SessionStart - for PreToolUse it's written to a debug log Claude never
-      // sees. To actually get an advisory (non-blocking) message in front of
-      // Claude here, it has to go through hookSpecificOutput.additionalContext.
-      const message = [
-        `Harness OS - Context Bloat Warning`,
-        `- Modified Files: ${modifiedCount}`,
-        `- Accumulated Diff: ${totalDiffLines} lines`,
-        ``,
-        `Caution: Large number of modified files or big diffs will bloat the Agent context window, leading to:`,
-        `  1. "Lost in the Middle" reasoning degradation`,
-        `  2. Rapidly inflating token costs`,
-        ``,
-        `Recommended Action:`,
-        `  - Run atomic commits or stage completed files.`,
-        `  - Use targeted sub-folders rather than broad searches.`,
-        `  - Ask user to run '/compact' or '/clear' if supported.`
-      ].join('\n');
-
-      console.log(JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "PreToolUse",
-          additionalContext: message
-        }
-      }));
-    }
-  } catch (err) {
-    // Fail open - never block user execution on compaction checker
-  }
-
-  process.exit(0);
-}
-
-let inputData = '';
-const timeout = setTimeout(() => { main(null); }, 200);
-process.stdin.on('data', chunk => { inputData += chunk; });
-process.stdin.on('end', () => {
-  clearTimeout(timeout);
-  let payload = null;
-  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
-  main(payload);
-});
-process.stdin.on('error', () => {
-  clearTimeout(timeout);
-  main(null);
-});
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+function main(payload) {
+  try {
+    // Let's run a quick Git check to estimate context size from modified files
+    const statusRaw = execSync('git status --porcelain', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (!statusRaw) {
+      process.exit(0);
+    }
+
+    const lines = statusRaw.split('\n').filter(Boolean);
+    const modifiedCount = lines.length;
+
+    let totalDiffLines = 0;
+    try {
+      const diffStat = execSync('git diff --numstat', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      if (diffStat) {
+        diffStat.split('\n').forEach(line => {
+          const [added, deleted] = line.split('\t');
+          if (added && added !== '-' && deleted && deleted !== '-') {
+            totalDiffLines += parseInt(added) + parseInt(deleted);
+          }
+        });
+      }
+    } catch (err) {
+      // Ignore git errors
+    }
+
+    // Thresholds for warning
+    const HIGH_FILE_LIMIT = 6;
+    const HIGH_LINE_LIMIT = 400;
+
+    const overThreshold = modifiedCount >= HIGH_FILE_LIMIT || totalDiffLines >= HIGH_LINE_LIMIT;
+
+    // Throttle: this hook fires on EVERY Bash/Edit/Write call, and a warning
+    // about context bloat that repeats on every call becomes context bloat
+    // itself (and trains the model to ignore hook output). Warn on the first
+    // crossing, then only every 10th call while still over - or when the diff
+    // has grown another 50% since the last warning.
+    const stateFile = path.join(getSessionDir(getWorkspaceRoot(), payload && payload.session_id), 'context-compact-state.json');
+    let state = { overCount: 0, lastWarnedLines: 0 };
+    try {
+      if (fs.existsSync(stateFile)) state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    } catch (err) { /* use default */ }
+
+    if (!overThreshold) {
+      if (state.overCount > 0) {
+        try {
+          fs.writeFileSync(stateFile, JSON.stringify({ overCount: 0, lastWarnedLines: 0 }), 'utf8');
+        } catch (err) { /* ignore */ }
+      }
+      process.exit(0);
+    }
+
+    state.overCount += 1;
+    const onBeat = state.overCount === 1 || state.overCount % 10 === 0;
+    const grewALot = totalDiffLines >= (state.lastWarnedLines || 0) * 1.5 && totalDiffLines > state.lastWarnedLines;
+    const shouldWarn = onBeat || grewALot;
+    if (shouldWarn) state.lastWarnedLines = totalDiffLines;
+    try {
+      fs.writeFileSync(stateFile, JSON.stringify(state), 'utf8');
+    } catch (err) { /* ignore */ }
+
+    if (shouldWarn) {
+      // Plain stdout on exit 0 is only surfaced to Claude for UserPromptSubmit/
+      // SessionStart - for PreToolUse it's written to a debug log Claude never
+      // sees. To actually get an advisory (non-blocking) message in front of
+      // Claude here, it has to go through hookSpecificOutput.additionalContext.
+      const message = [
+        `Harness OS - Context Bloat Warning`,
+        `- Modified Files: ${modifiedCount}`,
+        `- Accumulated Diff: ${totalDiffLines} lines`,
+        ``,
+        `Caution: Large number of modified files or big diffs will bloat the Agent context window, leading to:`,
+        `  1. "Lost in the Middle" reasoning degradation`,
+        `  2. Rapidly inflating token costs`,
+        ``,
+        `Recommended Action:`,
+        `  - Run atomic commits or stage completed files.`,
+        `  - Use targeted sub-folders rather than broad searches.`,
+        `  - Ask user to run '/compact' or '/clear' if supported.`
+      ].join('\n');
+
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: message
+        }
+      }));
+    }
+  } catch (err) {
+    // Fail open - never block user execution on compaction checker
+  }
+
+  process.exit(0);
+}
+
+let inputData = '';
+const timeout = setTimeout(() => { main(null); }, 200);
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  let payload = null;
+  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
+  main(payload);
+});
+process.stdin.on('error', () => {
+  clearTimeout(timeout);
+  main(null);
+});

package/hooks/scripts/contract-test.js

@@ -1,79 +1,79 @@
-#!/usr/bin/env node
-/**
- * Contract Test (PostToolUse: Bash|PowerShell)
- * Resolves fable-mode stage contracts. fable-orchestrator's discipline says
- * every stage check must be "re-run or spot-checked... before building on
- * its output" - but a verbal claim of "I re-ran it" isn't auditable. So the
- * orchestrator now writes .claude/harness-state/contracts/<stageId>.json with
- * status:"pending" and the exact checkCommand BEFORE running it. This hook
- * watches every shell call; when the command matches a pending contract's
- * checkCommand verbatim, it records pass/fail into that manifest using the
- * same exitCode-or-stderr heuristic as rule-of-3-tracker.js.
- * Contracts are shared across sessions, not scoped to one - the orchestrator
- * writes them proactively (not in response to a hook message) and has no
- * clean way to learn its own session_id, so a collision only matters if two
- * fable-mode orchestrations run in the same repo at once.
- * Contracts are audit trail, not synchronous enforcement - EXCEPT when a
- * check this hook just resolved comes back FAILED, it surfaces that loudly
- * (exit 2) so silently building on a failed stage doesn't slip through.
- * Fails open on any parse/lookup error.
- */
-const fs = require('fs');
-const path = require('path');
-const { getWorkspaceRoot, getStateRoot } = require('./lib/harness-state');
-
-let inputData = '';
-process.stdin.on('data', chunk => { inputData += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const payload = JSON.parse(inputData);
-    if (payload.tool_name !== 'Bash' && payload.tool_name !== 'PowerShell') process.exit(0);
-
-    const command = ((payload.tool_input && payload.tool_input.command) || '').trim();
-    if (!command) process.exit(0);
-
-    const contractsDir = path.join(getStateRoot(getWorkspaceRoot()), 'contracts');
-    if (!fs.existsSync(contractsDir)) process.exit(0);
-
-    const toolResponse = payload.tool_response || {};
-    const stdout = toolResponse.stdout ?? payload.stdout ?? '';
-    const stderr = toolResponse.stderr ?? payload.stderr ?? '';
-    const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
-    const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
-    const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
-    const failed = (exitCode !== undefined && exitCode !== 0) || (exitCode === undefined && stderrSignal);
-
-    const files = fs.readdirSync(contractsDir).filter(f => f.endsWith('.json'));
-    let firstFailure = null;
-
-    for (const file of files) {
-      const manifestPath = path.join(contractsDir, file);
-      let manifest;
-      try {
-        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-      } catch (e) {
-        continue;
-      }
-      if (manifest.status !== 'pending') continue;
-      if (!manifest.checkCommand || manifest.checkCommand.trim() !== command) continue;
-
-      manifest.status = failed ? 'fail' : 'pass';
-      manifest.evidence = ((stderrSignal ? stderr : stdout) || '').slice(-500).trim();
-      manifest.verifiedAt = new Date().toISOString();
-      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
-
-      if (failed && !firstFailure) firstFailure = manifest;
-    }
-
-    if (firstFailure) {
-      console.error(`[Contract Test] Stage "${firstFailure.stageId}" FAILED its named check: ${firstFailure.checkCommand}`);
-      console.error(`Evidence: ${firstFailure.evidence || '(no output captured)'}`);
-      console.error(`Do not build on this stage's output until it passes. Artifact: ${firstFailure.outputPath || '(no path recorded)'}`);
-      process.exit(2);
-    }
-
-    process.exit(0);
-  } catch (err) {
-    process.exit(0);
-  }
-});
+#!/usr/bin/env node
+/**
+ * Contract Test (PostToolUse: Bash|PowerShell)
+ * Resolves fable-mode stage contracts. fable-orchestrator's discipline says
+ * every stage check must be "re-run or spot-checked... before building on
+ * its output" - but a verbal claim of "I re-ran it" isn't auditable. So the
+ * orchestrator now writes .claude/harness-everything/state/contracts/<stageId>.json with
+ * status:"pending" and the exact checkCommand BEFORE running it. This hook
+ * watches every shell call; when the command matches a pending contract's
+ * checkCommand verbatim, it records pass/fail into that manifest using the
+ * same exitCode-or-stderr heuristic as rule-of-3-tracker.js.
+ * Contracts are shared across sessions, not scoped to one - the orchestrator
+ * writes them proactively (not in response to a hook message) and has no
+ * clean way to learn its own session_id, so a collision only matters if two
+ * fable-mode orchestrations run in the same repo at once.
+ * Contracts are audit trail, not synchronous enforcement - EXCEPT when a
+ * check this hook just resolved comes back FAILED, it surfaces that loudly
+ * (exit 2) so silently building on a failed stage doesn't slip through.
+ * Fails open on any parse/lookup error.
+ */
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getStateRoot } = require('./lib/harness-state');
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    if (payload.tool_name !== 'Bash' && payload.tool_name !== 'PowerShell') process.exit(0);
+
+    const command = ((payload.tool_input && payload.tool_input.command) || '').trim();
+    if (!command) process.exit(0);
+
+    const contractsDir = path.join(getStateRoot(getWorkspaceRoot()), 'contracts');
+    if (!fs.existsSync(contractsDir)) process.exit(0);
+
+    const toolResponse = payload.tool_response || {};
+    const stdout = toolResponse.stdout ?? payload.stdout ?? '';
+    const stderr = toolResponse.stderr ?? payload.stderr ?? '';
+    const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
+    const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
+    const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
+    const failed = (exitCode !== undefined && exitCode !== 0) || (exitCode === undefined && stderrSignal);
+
+    const files = fs.readdirSync(contractsDir).filter(f => f.endsWith('.json'));
+    let firstFailure = null;
+
+    for (const file of files) {
+      const manifestPath = path.join(contractsDir, file);
+      let manifest;
+      try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      } catch (e) {
+        continue;
+      }
+      if (manifest.status !== 'pending') continue;
+      if (!manifest.checkCommand || manifest.checkCommand.trim() !== command) continue;
+
+      manifest.status = failed ? 'fail' : 'pass';
+      manifest.evidence = ((stderrSignal ? stderr : stdout) || '').slice(-500).trim();
+      manifest.verifiedAt = new Date().toISOString();
+      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+
+      if (failed && !firstFailure) firstFailure = manifest;
+    }
+
+    if (firstFailure) {
+      console.error(`[Contract Test] Stage "${firstFailure.stageId}" FAILED its named check: ${firstFailure.checkCommand}`);
+      console.error(`Evidence: ${firstFailure.evidence || '(no output captured)'}`);
+      console.error(`Do not build on this stage's output until it passes. Artifact: ${firstFailure.outputPath || '(no path recorded)'}`);
+      process.exit(2);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    process.exit(0);
+  }
+});

package/hooks/scripts/depth-guard.js

@@ -1,65 +1,65 @@
-#!/usr/bin/env node
-/**
- * Depth Guard (PreToolUse: Edit|Write)
- * Claude Code already refuses to Edit a file that wasn't Read first in the
- * same session - that's native behavior, not something this hook needs to
- * re-check. The gap is Write: it happily overwrites an existing file with
- * no prior Read at all. This hook closes that gap: blocks Write on a file
- * that already exists on disk unless a Read of that exact path shows up
- * earlier in this session's transcript.
- * Fails open on any parse/lookup error - never blocks due to a bug here.
- */
-const fs = require('fs');
-const path = require('path');
-
-let inputData = '';
-process.stdin.on('data', chunk => { inputData += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const payload = JSON.parse(inputData);
-    if (payload.tool_name !== 'Write') {
-      process.exit(0);
-    }
-
-    const filePath = payload.tool_input && payload.tool_input.file_path;
-    if (!filePath || !fs.existsSync(filePath)) {
-      // New file - nothing to have read first.
-      process.exit(0);
-    }
-
-    const transcriptPath = payload.transcript_path;
-    if (!transcriptPath || !fs.existsSync(transcriptPath)) {
-      // Can't verify either way - fail open.
-      process.exit(0);
-    }
-
-    const target = path.resolve(filePath).toLowerCase();
-    const lines = fs.readFileSync(transcriptPath, 'utf8').split('\n').filter(Boolean);
-
-    const wasRead = lines.some(line => {
-      try {
-        const entry = JSON.parse(line);
-        const content = entry && entry.message && entry.message.content;
-        if (!Array.isArray(content)) return false;
-        return content.some(block => {
-          if (!block || block.type !== 'tool_use' || block.name !== 'Read') return false;
-          const readPath = block.input && block.input.file_path;
-          return readPath && path.resolve(readPath).toLowerCase() === target;
-        });
-      } catch (e) {
-        return false;
-      }
-    });
-
-    if (!wasRead) {
-      console.error(`[Depth Guard] BLOCKED: "${filePath}" already exists but hasn't been Read in this session.`);
-      console.error(`Write() overwrites the whole file - doing that blind risks destroying content you never looked at.`);
-      console.error(`Read the file first (even a quick pass), then retry the Write, or use Edit for a targeted change.`);
-      process.exit(2);
-    }
-
-    process.exit(0);
-  } catch (err) {
-    process.exit(0);
-  }
-});
+#!/usr/bin/env node
+/**
+ * Depth Guard (PreToolUse: Edit|Write)
+ * Claude Code already refuses to Edit a file that wasn't Read first in the
+ * same session - that's native behavior, not something this hook needs to
+ * re-check. The gap is Write: it happily overwrites an existing file with
+ * no prior Read at all. This hook closes that gap: blocks Write on a file
+ * that already exists on disk unless a Read of that exact path shows up
+ * earlier in this session's transcript.
+ * Fails open on any parse/lookup error - never blocks due to a bug here.
+ */
+const fs = require('fs');
+const path = require('path');
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    if (payload.tool_name !== 'Write') {
+      process.exit(0);
+    }
+
+    const filePath = payload.tool_input && payload.tool_input.file_path;
+    if (!filePath || !fs.existsSync(filePath)) {
+      // New file - nothing to have read first.
+      process.exit(0);
+    }
+
+    const transcriptPath = payload.transcript_path;
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+      // Can't verify either way - fail open.
+      process.exit(0);
+    }
+
+    const target = path.resolve(filePath).toLowerCase();
+    const lines = fs.readFileSync(transcriptPath, 'utf8').split('\n').filter(Boolean);
+
+    const wasRead = lines.some(line => {
+      try {
+        const entry = JSON.parse(line);
+        const content = entry && entry.message && entry.message.content;
+        if (!Array.isArray(content)) return false;
+        return content.some(block => {
+          if (!block || block.type !== 'tool_use' || block.name !== 'Read') return false;
+          const readPath = block.input && block.input.file_path;
+          return readPath && path.resolve(readPath).toLowerCase() === target;
+        });
+      } catch (e) {
+        return false;
+      }
+    });
+
+    if (!wasRead) {
+      console.error(`[Depth Guard] BLOCKED: "${filePath}" already exists but hasn't been Read in this session.`);
+      console.error(`Write() overwrites the whole file - doing that blind risks destroying content you never looked at.`);
+      console.error(`Read the file first (even a quick pass), then retry the Write, or use Edit for a targeted change.`);
+      process.exit(2);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    process.exit(0);
+  }
+});