The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: surface warn-only PreToolUse hooks (#2084)
Affaan Mustafa64cd1ba248e7
diff --git a/scripts/hooks/bash-hook-dispatcher.js b/scripts/hooks/bash-hook-dispatcher.jsindex 9485738cc..f9f0e763e 100644--- a/scripts/hooks/bash-hook-dispatcher.js+++ b/scripts/hooks/bash-hook-dispatcher.js@@ -2,6 +2,10 @@'use strict';const { isHookEnabled } = require('../lib/hook-flags');+const {+ buildPreToolUseAdditionalContext,+ combineAdditionalContext,+} = require('./pretooluse-visible-output');const { run: runBlockNoVerify } = require('./block-no-verify');const { run: runAutoTmuxDev } = require('./auto-tmux-dev');@@ -93,7 +97,9 @@ function normalizeHookResult(previousRaw, output) {}if (output && typeof output === 'object') {- const nextRaw = Object.prototype.hasOwnProperty.call(output, 'stdout')+ const nextRaw = Object.prototype.hasOwnProperty.call(output, 'additionalContext')+ ? previousRaw+ : Object.prototype.hasOwnProperty.call(output, 'stdout')? String(output.stdout ?? ''): !Number.isInteger(output.exitCode) || output.exitCode === 0? previousRaw@@ -102,6 +108,7 @@ function normalizeHookResult(previousRaw, output) {return {raw: nextRaw,stderr: typeof output.stderr === 'string' ? output.stderr : '',+ additionalContext: output.additionalContext,exitCode: Number.isInteger(output.exitCode) ? output.exitCode : 0,};}@@ -116,6 +123,7 @@ function normalizeHookResult(previousRaw, output) {function runHooks(rawInput, hooks) {let currentRaw = rawInput;let stderr = '';+ let additionalContext = '';for (const hook of hooks) {if (!isHookEnabled(hook.id, { profiles: hook.profiles })) {@@ -128,15 +136,25 @@ function runHooks(rawInput, hooks) {if (result.stderr) {stderr += result.stderr.endsWith('\n') ? result.stderr : `${result.stderr}\n`;}+ if (result.additionalContext) {+ additionalContext = combineAdditionalContext(additionalContext, result.additionalContext);+ }if (result.exitCode !== 0) {- return { output: currentRaw, stderr, exitCode: result.exitCode };+ return { output: currentRaw, stderr, additionalContext, exitCode: result.exitCode };}} catch (error) {stderr += `[Hook] ${hook.id} failed: ${error.message}\n`;}}- return { output: currentRaw, stderr, exitCode: 0 };+ return {+ output: additionalContext+ ? buildPreToolUseAdditionalContext(additionalContext)+ : currentRaw,+ stderr,+ additionalContext,+ exitCode: 0,+ };}function runPreBash(rawInput) {diff --git a/scripts/hooks/doc-file-warning.js b/scripts/hooks/doc-file-warning.jsindex a8e71262c..d510b33f5 100644--- a/scripts/hooks/doc-file-warning.js+++ b/scripts/hooks/doc-file-warning.js@@ -14,6 +14,7 @@'use strict';const path = require('path');+const { buildPreToolUseAdditionalContext } = require('./pretooluse-visible-output');const MAX_STDIN = 1024 * 1024;let data = '';@@ -58,10 +59,11 @@ function run(inputOrRaw, _options = {}) {if (filePath && isSuspiciousDocPath(filePath)) {return {exitCode: 0,- stderr:- '[Hook] WARNING: Ad-hoc documentation filename detected\n' +- `[Hook] File: ${filePath}\n` ++ additionalContext: [+ '[Hook] WARNING: Ad-hoc documentation filename detected',+ `[Hook] File: ${filePath}`,'[Hook] Consider using a structured path (e.g. docs/, .claude/, skills/, .github/, benchmarks/, templates/)',+ ],};}@@ -86,5 +88,9 @@ process.stdin.on('end', () => {process.stderr.write(result.stderr + '\n');}- process.stdout.write(data);+ if (Object.prototype.hasOwnProperty.call(result, 'additionalContext')) {+ process.stdout.write(buildPreToolUseAdditionalContext(result.additionalContext));+ } else {+ process.stdout.write(data);+ }});diff --git a/scripts/hooks/pre-bash-git-push-reminder.js b/scripts/hooks/pre-bash-git-push-reminder.jsindex 62db1ff94..52ae376aa 100755--- a/scripts/hooks/pre-bash-git-push-reminder.js+++ b/scripts/hooks/pre-bash-git-push-reminder.js@@ -2,6 +2,7 @@'use strict';const MAX_STDIN = 1024 * 1024;+const { buildPreToolUseAdditionalContext } = require('./pretooluse-visible-output');let raw = '';function run(rawInput) {@@ -10,11 +11,10 @@ function run(rawInput) {const cmd = String(input.tool_input?.command || '');if (/\bgit\s+push\b/.test(cmd)) {return {- stdout: typeof rawInput === 'string' ? rawInput : JSON.stringify(rawInput),- stderr: [+ additionalContext: ['[Hook] Review changes before push...','[Hook] Continuing with push (remove this hook to add interactive review)',- ].join('\n'),+ ],exitCode: 0,};}@@ -40,7 +40,11 @@ if (require.main === module) {if (result.stderr) {process.stderr.write(`${result.stderr}\n`);}- process.stdout.write(String(result.stdout || ''));+ if (Object.prototype.hasOwnProperty.call(result, 'additionalContext')) {+ process.stdout.write(buildPreToolUseAdditionalContext(result.additionalContext));+ } else {+ process.stdout.write(String(result.stdout || ''));+ }process.exitCode = Number.isInteger(result.exitCode) ? result.exitCode : 0;return;}diff --git a/scripts/hooks/pre-bash-tmux-reminder.js b/scripts/hooks/pre-bash-tmux-reminder.jsindex fe3833eae..2ad56ea32 100755--- a/scripts/hooks/pre-bash-tmux-reminder.js+++ b/scripts/hooks/pre-bash-tmux-reminder.js@@ -2,6 +2,7 @@'use strict';const MAX_STDIN = 1024 * 1024;+const { buildPreToolUseAdditionalContext } = require('./pretooluse-visible-output');let raw = '';function run(rawInput) {@@ -15,11 +16,10 @@ function run(rawInput) {/(npm (install|test)|pnpm (install|test)|yarn (install|test)?|bun (install|test)|cargo build|make\b|docker\b|pytest|vitest|playwright)/.test(cmd)) {return {- stdout: typeof rawInput === 'string' ? rawInput : JSON.stringify(rawInput),- stderr: [+ additionalContext: ['[Hook] Consider running in tmux for session persistence','[Hook] tmux new -s dev | tmux attach -t dev',- ].join('\n'),+ ],exitCode: 0,};}@@ -45,7 +45,11 @@ if (require.main === module) {if (result.stderr) {process.stderr.write(`${result.stderr}\n`);}- process.stdout.write(String(result.stdout || ''));+ if (Object.prototype.hasOwnProperty.call(result, 'additionalContext')) {+ process.stdout.write(buildPreToolUseAdditionalContext(result.additionalContext));+ } else {+ process.stdout.write(String(result.stdout || ''));+ }process.exitCode = Number.isInteger(result.exitCode) ? result.exitCode : 0;return;}diff --git a/scripts/hooks/pretooluse-visible-output.js b/scripts/hooks/pretooluse-visible-output.jsnew file mode 100644index 000000000..dc4811909--- /dev/null+++ b/scripts/hooks/pretooluse-visible-output.js@@ -0,0 +1,41 @@+#!/usr/bin/env node+'use strict';++function normalizeAdditionalContext(value) {+ if (Array.isArray(value)) {+ return value+ .map(item => String(item || '').trim())+ .filter(Boolean)+ .join('\n');+ }++ return String(value || '').trim();+}++function combineAdditionalContext(current, next) {+ const currentText = normalizeAdditionalContext(current);+ const nextText = normalizeAdditionalContext(next);++ if (!currentText) return nextText;+ if (!nextText) return currentText;++ return `${currentText}\n${nextText}`;+}++function buildPreToolUseAdditionalContext(value) {+ const additionalContext = normalizeAdditionalContext(value);+ if (!additionalContext) return '';++ return JSON.stringify({+ hookSpecificOutput: {+ hookEventName: 'PreToolUse',+ additionalContext,+ },+ });+}++module.exports = {+ buildPreToolUseAdditionalContext,+ combineAdditionalContext,+ normalizeAdditionalContext,+};diff --git a/scripts/hooks/run-with-flags.js b/scripts/hooks/run-with-flags.jsindex 84aed34a6..a0b43fbaf 100755--- a/scripts/hooks/run-with-flags.js+++ b/scripts/hooks/run-with-flags.js@@ -12,6 +12,7 @@ const fs = require('fs');const path = require('path');const { spawnSync } = require('child_process');const { isHookEnabled } = require('../lib/hook-flags');+const { buildPreToolUseAdditionalContext } = require('./pretooluse-visible-output');const MAX_STDIN = 1024 * 1024;@@ -53,7 +54,9 @@ function emitHookResult(raw, output) {if (output && typeof output === 'object') {writeStderr(output.stderr);- if (Object.prototype.hasOwnProperty.call(output, 'stdout')) {+ if (Object.prototype.hasOwnProperty.call(output, 'additionalContext')) {+ process.stdout.write(buildPreToolUseAdditionalContext(output.additionalContext));+ } else if (Object.prototype.hasOwnProperty.call(output, 'stdout')) {process.stdout.write(String(output.stdout ?? ''));} else if (!Number.isInteger(output.exitCode) || output.exitCode === 0) {process.stdout.write(raw);diff --git a/tests/hooks/bash-hook-dispatcher.test.js b/tests/hooks/bash-hook-dispatcher.test.jsindex 2f89c90b1..2047462b4 100644--- a/tests/hooks/bash-hook-dispatcher.test.js+++ b/tests/hooks/bash-hook-dispatcher.test.js@@ -35,6 +35,10 @@ function runScript(scriptPath, input, env = {}) {});}+function parseHookOutput(stdout) {+ return JSON.parse(stdout);+}+function runTests() {console.log('\n=== Testing Bash hook dispatchers ===\n');@@ -54,13 +58,18 @@ function runTests() {const enabled = runScript(preDispatcher, input, { ECC_HOOK_PROFILE: 'strict' });assert.strictEqual(enabled.status, 0);- assert.ok(enabled.stderr.includes('Review changes before push'), 'Expected git push reminder when enabled');+ assert.strictEqual(enabled.stderr, '', `Expected visible reminder via stdout JSON, got stderr: ${enabled.stderr}`);+ assert.ok(+ parseHookOutput(enabled.stdout).hookSpecificOutput.additionalContext.includes('Review changes before push'),+ 'Expected git push reminder when enabled'+ );const disabled = runScript(preDispatcher, input, {ECC_HOOK_PROFILE: 'strict',ECC_DISABLED_HOOKS: 'pre:bash:git-push-reminder',});assert.strictEqual(disabled.status, 0);+ assert.strictEqual(disabled.stdout, JSON.stringify(input), 'Disabled hook should pass through original input');assert.ok(!disabled.stderr.includes('Review changes before push'), 'Disabled hook should not emit reminder');})) passed++; else failed++;diff --git a/tests/hooks/doc-file-warning.test.js b/tests/hooks/doc-file-warning.test.jsindex 9d9666347..2c0b3b6e9 100644--- a/tests/hooks/doc-file-warning.test.js+++ b/tests/hooks/doc-file-warning.test.js@@ -28,6 +28,10 @@ function runScript(input) {return { code: result.status || 0, stdout: result.stdout || '', stderr: result.stderr || '' };}+function parseHookOutput(stdout) {+ return JSON.parse(stdout);+}+function runTests() {console.log('\n=== Testing doc-file-warning.js (denylist policy) ===\n');let passed = 0;@@ -138,10 +142,13 @@ function runTests() {];for (const file of deniedFiles) {(test(`warns on ad-hoc denylist file: ${file}`, () => {- const { code, stderr } = runScript({ tool_input: { file_path: file } });+ const { code, stdout, stderr } = runScript({ tool_input: { file_path: file } });assert.strictEqual(code, 0, 'should still exit 0 (warn only)');- assert.ok(stderr.includes('WARNING'), `expected warning in stderr for ${file}, got: ${stderr}`);- assert.ok(stderr.includes(file), `expected file path in stderr for ${file}`);+ assert.strictEqual(stderr, '', `expected visible warning via stdout JSON, got stderr: ${stderr}`);+ const output = parseHookOutput(stdout);+ const additionalContext = output.hookSpecificOutput?.additionalContext || '';+ assert.ok(additionalContext.includes('WARNING'), `expected warning in additionalContext for ${file}, got: ${stdout}`);+ assert.ok(additionalContext.includes(file), `expected file path in additionalContext for ${file}`);}) ? passed++ : failed++);}@@ -153,9 +160,10 @@ function runTests() {}) ? passed++ : failed++);(test('warns on ad-hoc name with backslash in non-structured dir', () => {- const { code, stderr } = runScript({ tool_input: { file_path: 'src\\SCRATCH.md' } });+ const { code, stdout, stderr } = runScript({ tool_input: { file_path: 'src\\SCRATCH.md' } });assert.strictEqual(code, 0, 'should still exit 0');- assert.ok(stderr.includes('WARNING'), 'expected warning for non-structured backslash path');+ assert.strictEqual(stderr, '', `expected visible warning via stdout JSON, got stderr: ${stderr}`);+ assert.ok(parseHookOutput(stdout).hookSpecificOutput.additionalContext.includes('WARNING'), 'expected warning for non-structured backslash path');}) ? passed++ : failed++);// 8. Invalid/empty input - passes through without error@@ -196,10 +204,12 @@ function runTests() {assert.strictEqual(stdout, JSON.stringify(input));}) ? passed++ : failed++);- (test('passes through input to stdout for warned file', () => {+ (test('emits visible additionalContext JSON for warned file', () => {const input = { tool_input: { file_path: 'TODO.md' } };const { stdout } = runScript(input);- assert.strictEqual(stdout, JSON.stringify(input));+ const output = parseHookOutput(stdout);+ assert.strictEqual(output.hookSpecificOutput.hookEventName, 'PreToolUse');+ assert.ok(output.hookSpecificOutput.additionalContext.includes('TODO.md'));}) ? passed++ : failed++);(test('passes through input to stdout for empty input', () => {diff --git a/tests/hooks/pre-bash-reminders.test.js b/tests/hooks/pre-bash-reminders.test.jsindex 507059a24..def6be6c9 100644--- a/tests/hooks/pre-bash-reminders.test.js+++ b/tests/hooks/pre-bash-reminders.test.js@@ -35,6 +35,10 @@ function runScript(scriptPath, command, envOverrides = {}) {return { code: result.status || 0, stdout: result.stdout || '', stderr: result.stderr || '', inputStr };}+function parseHookOutput(stdout) {+ return JSON.parse(stdout);+}+function runTests() {console.log('\n=== Testing pre-bash-git-push-reminder.js & pre-bash-tmux-reminder.js ===\n');@@ -45,11 +49,13 @@ function runTests() {console.log(' git-push-reminder:');- (test('git push triggers stderr warning', () => {+ (test('git push triggers visible additionalContext warning', () => {const result = runScript(gitPushScript, 'git push origin main');assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);- assert.ok(result.stderr.includes('[Hook]'), `Expected stderr to contain [Hook], got: ${result.stderr}`);- assert.ok(result.stderr.includes('Review changes before push'), `Expected stderr to mention review`);+ assert.strictEqual(result.stderr, '', `Expected no stderr, got: ${result.stderr}`);+ const additionalContext = parseHookOutput(result.stdout).hookSpecificOutput.additionalContext;+ assert.ok(additionalContext.includes('[Hook]'), `Expected additionalContext to contain [Hook], got: ${result.stdout}`);+ assert.ok(additionalContext.includes('Review changes before push'), `Expected additionalContext to mention review`);}) ? passed++ : failed++);(test('git status has no warning', () => {@@ -58,9 +64,11 @@ function runTests() {assert.strictEqual(result.stderr, '', `Expected no stderr, got: ${result.stderr}`);}) ? passed++ : failed++);- (test('git push always passes through input on stdout', () => {+ (test('git push emits PreToolUse additionalContext JSON on stdout', () => {const result = runScript(gitPushScript, 'git push');- assert.strictEqual(result.stdout, result.inputStr, 'Expected stdout to match original input');+ const output = parseHookOutput(result.stdout);+ assert.strictEqual(output.hookSpecificOutput.hookEventName, 'PreToolUse');+ assert.ok(output.hookSpecificOutput.additionalContext.includes('Review changes before push'));}) ? passed++ : failed++);// --- tmux-reminder tests (non-Windows only) ---@@ -70,17 +78,20 @@ function runTests() {if (!isWindows) {console.log('\n tmux-reminder:');- (test('npm install triggers tmux suggestion', () => {+ (test('npm install triggers visible tmux suggestion', () => {const result = runScript(tmuxScript, 'npm install', { TMUX: '' });assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);- assert.ok(result.stderr.includes('[Hook]'), `Expected stderr to contain [Hook], got: ${result.stderr}`);- assert.ok(result.stderr.includes('tmux'), `Expected stderr to mention tmux`);+ assert.strictEqual(result.stderr, '', `Expected no stderr, got: ${result.stderr}`);+ const additionalContext = parseHookOutput(result.stdout).hookSpecificOutput.additionalContext;+ assert.ok(additionalContext.includes('[Hook]'), `Expected additionalContext to contain [Hook], got: ${result.stdout}`);+ assert.ok(additionalContext.includes('tmux'), `Expected additionalContext to mention tmux`);}) ? passed++ : failed++);(test('npm test triggers tmux suggestion', () => {const result = runScript(tmuxScript, 'npm test', { TMUX: '' });assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);- assert.ok(result.stderr.includes('tmux'), `Expected stderr to mention tmux`);+ assert.strictEqual(result.stderr, '', `Expected no stderr, got: ${result.stderr}`);+ assert.ok(parseHookOutput(result.stdout).hookSpecificOutput.additionalContext.includes('tmux'), `Expected additionalContext to mention tmux`);}) ? passed++ : failed++);(test('regular command like ls has no tmux suggestion', () => {@@ -89,9 +100,11 @@ function runTests() {assert.strictEqual(result.stderr, '', `Expected no stderr for ls, got: ${result.stderr}`);}) ? passed++ : failed++);- (test('tmux reminder always passes through input on stdout', () => {+ (test('tmux reminder emits PreToolUse additionalContext JSON on stdout', () => {const result = runScript(tmuxScript, 'npm install', { TMUX: '' });- assert.strictEqual(result.stdout, result.inputStr, 'Expected stdout to match original input');+ const output = parseHookOutput(result.stdout);+ assert.strictEqual(output.hookSpecificOutput.hookEventName, 'PreToolUse');+ assert.ok(output.hookSpecificOutput.additionalContext.includes('tmux'));}) ? passed++ : failed++);} else {console.log('\n (skipping tmux-reminder tests on Windows)\n');