From 54989037b4ee445af37cec0546700e54183de4dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=94=B5=E5=A4=A7=E8=80=81baby?= <3231811510@qq.com> Date: Wed, 4 Nov 2026 10:32:42 +0800 Subject: [PATCH 1/4] fix(hooks): keep recovery bypass controls out of default denial text (#3844) Denial reasons are tool output the guarded agent reads. Naming ECC_GATEGUARD=off, ECC_DISABLED_HOOKS and the exemption globs there handed the agent its own bypass. Hint text is now opt-in via ECC_SHOW_RECOVERY_HINTS, and the default denials keep only the factual requirement. Co-Authored-By: TRAE --- scripts/hooks/config-protection.js | 14 ++++++++--- scripts/hooks/gateguard-fact-force.js | 12 ++++++++- scripts/hooks/run-with-flags.js | 7 +++++- tests/hooks/gateguard-fact-force.test.js | 31 ++++++++++++++++++++++++ 4 files changed, 59 insertions(+), 5 deletions(-) mode change 100755 => 100644 scripts/hooks/run-with-flags.js diff --git a/scripts/hooks/config-protection.js b/scripts/hooks/config-protection.js index 6adbdfbae..0eaca95ae 100644 --- a/scripts/hooks/config-protection.js +++ b/scripts/hooks/config-protection.js @@ -145,6 +145,10 @@ function parseInput(inputOrRaw) { * Exportable run() for in-process execution via run-with-flags.js. * Avoids the ~50-100ms spawnSync overhead when available. */ +function showRecoveryHints() { + return /^(1|true|yes|on|enabled)$/i.test(String(process.env.ECC_SHOW_RECOVERY_HINTS || '')); +} + function run(inputOrRaw, options = {}) { if (options.truncated) { return { @@ -152,7 +156,9 @@ function run(inputOrRaw, options = {}) { stderr: `BLOCKED: Hook input exceeded ${options.maxStdin || MAX_STDIN} bytes. ` + 'Refusing to bypass config-protection on a truncated payload. ' + - 'Retry with a smaller edit or disable the config-protection hook temporarily.' + (showRecoveryHints() + ? 'Retry with a smaller edit or disable the config-protection hook temporarily.' + : 'Retry with a smaller edit.') }; } @@ -221,8 +227,10 @@ function checkTarget(filePath) { stderr: `BLOCKED: Modifying ${basename} is not allowed. ` + 'Fix the source code to satisfy linter/formatter rules instead of ' + - 'weakening the config. If this is a legitimate config change, ' + - 'disable the config-protection hook temporarily.' + 'weakening the config.' + + (showRecoveryHints() + ? ' If this is a legitimate config change, disable the config-protection hook temporarily.' + : '') }; } diff --git a/scripts/hooks/gateguard-fact-force.js b/scripts/hooks/gateguard-fact-force.js index 583f36052..ee0b988a4 100644 --- a/scripts/hooks/gateguard-fact-force.js +++ b/scripts/hooks/gateguard-fact-force.js @@ -115,6 +115,13 @@ const ROUTINE_POWERSHELL_NARROW_RECOVERY_HINT = const ECC_DISABLE_VALUES = new Set(['0', 'false', 'off', 'disabled', 'disable']); const ECC_ENABLE_VALUES = new Set(['1', 'true', 'on', 'enabled', 'enable', 'yes']); +// A denial is fed back to the agent as untrusted tool text. Naming the env vars +// that disable the guard in that same message hands a bypass to the guarded +// agent (#3844), so the recovery controls are opt-in for human operators. +function showRecoveryHints() { + return ECC_ENABLE_VALUES.has(normalizeEnvValue(process.env.ECC_SHOW_RECOVERY_HINTS)); +} + // SQL keywords remain a phrase check. Quoted strings are stripped before // this regex runs so a commit message mentioning "drop table" stays passive. // `dd if=` used to be a fourth arm here. Matching it as text could not work: @@ -2108,7 +2115,9 @@ function condensedGateMsg(action, filePath, ordinal, { cls = 'code', targetNote `${batchSiblingWarning(safe)} ` + (missNote ? `${missNote} ` : '') + (targetNote ? `${targetNote} ` : '') + - '(Use GATEGUARD_EXEMPT_GLOBS for path-scoped exemptions; GATEGUARD_FACT_FORCE_MAX_DENIALS caps denials per session; ECC_GATEGUARD=off disables this gate.)' + (showRecoveryHints() + ? '(Use GATEGUARD_EXEMPT_GLOBS for path-scoped exemptions; GATEGUARD_FACT_FORCE_MAX_DENIALS caps denials per session; ECC_GATEGUARD=off disables this gate.)' + : '') ); } @@ -2183,6 +2192,7 @@ function routineShellMsg(toolName) { } function withRecoveryHint(message, hookIds = [EDIT_WRITE_HOOK_ID], narrowRecoveryHint = '') { + if (!showRecoveryHints()) return message; const disableTargets = hookIds.map(hookId => `\`${hookId}\``).join(' or '); const recoveryLines = narrowRecoveryHint ? [narrowRecoveryHint, ''] : []; return [ diff --git a/scripts/hooks/run-with-flags.js b/scripts/hooks/run-with-flags.js old mode 100755 new mode 100644 index d96bdff78..8544d3e59 --- a/scripts/hooks/run-with-flags.js +++ b/scripts/hooks/run-with-flags.js @@ -138,9 +138,14 @@ function truncatedInputResult(hookId, maxStdin) { if (failOpen) return null; } + const showRecoveryHints = /^(1|true|yes|on|enabled)$/i.test( + String(process.env.ECC_SHOW_RECOVERY_HINTS || '') + ); return { stdout: '', - stderr: `BLOCKED: Hook input exceeded ${maxStdin} bytes, so ${hookId} could not safely inspect the complete request. Retry with a smaller tool input or explicitly disable this hook.`, + stderr: showRecoveryHints + ? `BLOCKED: Hook input exceeded ${maxStdin} bytes, so ${hookId} could not safely inspect the complete request. Retry with a smaller tool input or explicitly disable this hook.` + : `BLOCKED: Hook input exceeded ${maxStdin} bytes, so ${hookId} could not safely inspect the complete request. Retry with a smaller tool input.`, exitCode: 2 }; } diff --git a/tests/hooks/gateguard-fact-force.test.js b/tests/hooks/gateguard-fact-force.test.js index a0d16f056..ce269a534 100644 --- a/tests/hooks/gateguard-fact-force.test.js +++ b/tests/hooks/gateguard-fact-force.test.js @@ -7,6 +7,10 @@ const fs = require('fs'); const path = require('path'); const { spawnSync } = require('child_process'); +// These assertions cover the opt-in human-operator hint text (#3844): the +// default denial no longer names the env vars that disable the guard. +process.env.ECC_SHOW_RECOVERY_HINTS = '1'; + const runner = path.join(__dirname, '..', '..', 'scripts', 'hooks', 'run-with-flags.js'); const hookScript = path.join(__dirname, '..', '..', 'scripts', 'hooks', 'gateguard-fact-force.js'); const externalStateDir = process.env.GATEGUARD_STATE_DIR; @@ -7690,6 +7694,33 @@ function runTests() { else failed++; } + // --- Test N: the default denial never names the controls that disable the hook (#3844) --- + clearState(); + if ( + test('default denial does not name recovery bypass controls', () => { + const input = { + session_id: TEST_SESSION_ID, + tool_name: 'Edit', + tool_input: { file_path: '/workspace/app/src/recovery-hint.js', old_string: 'a', new_string: 'b' } + }; + const result = runHook(input, { ECC_SHOW_RECOVERY_HINTS: '' }); + const output = parseOutput(result.stdout); + assert.ok(output && output.hookSpecificOutput, 'expected a denial'); + assert.strictEqual(output.hookSpecificOutput.permissionDecision, 'deny'); + const reason = output.hookSpecificOutput.permissionDecisionReason; + for (const leaked of [ + 'ECC_GATEGUARD=off', + 'ECC_DISABLED_HOOKS', + 'GATEGUARD_EXEMPT_GLOBS', + 'GATEGUARD_BASH_ROUTINE_DISABLED' + ]) { + assert.ok(!reason.includes(leaked), `default denial must not name ${leaked}`); + } + }) + ) + passed++; + else failed++; + const ddResults = runDdRegressionTests(); passed += ddResults.passed; failed += ddResults.failed; From cdb8a9381989871102612377094e4690c030a66f Mon Sep 17 00:00:00 2001 From: huangpz6 Date: Wed, 4 Nov 2026 21:35:45 +0800 Subject: [PATCH 2/4] fix(hooks): share one recovery-hint parser and cover default denials (#3864) Move ECC_SHOW_RECOVERY_HINTS parsing into scripts/lib/hooks/recovery-hints.js so every hook trims and accepts the same truthy values. Add default-off and opt-in assertions for the condensed GateGuard denial, config-protection (protected and truncated payloads) and the fail-closed truncation wrapper. Co-Authored-By: TRAE --- scripts/hooks/config-protection.js | 5 +- scripts/hooks/gateguard-fact-force.js | 8 +-- scripts/hooks/run-with-flags.js | 6 +-- scripts/lib/hooks/recovery-hints.js | 12 +++++ tests/hooks/config-protection.test.js | 49 +++++++++++++++++++ tests/hooks/gateguard-fact-force.test.js | 30 ++++++++++++ tests/hooks/run-with-flags-truncation.test.js | 30 ++++++++++++ 7 files changed, 125 insertions(+), 15 deletions(-) create mode 100644 scripts/lib/hooks/recovery-hints.js diff --git a/scripts/hooks/config-protection.js b/scripts/hooks/config-protection.js index 0eaca95ae..654a102c8 100644 --- a/scripts/hooks/config-protection.js +++ b/scripts/hooks/config-protection.js @@ -15,6 +15,7 @@ const fs = require('fs'); const path = require('path'); +const { showRecoveryHints } = require('../lib/hooks/recovery-hints'); const MAX_STDIN = 1024 * 1024; let raw = ''; @@ -145,10 +146,6 @@ function parseInput(inputOrRaw) { * Exportable run() for in-process execution via run-with-flags.js. * Avoids the ~50-100ms spawnSync overhead when available. */ -function showRecoveryHints() { - return /^(1|true|yes|on|enabled)$/i.test(String(process.env.ECC_SHOW_RECOVERY_HINTS || '')); -} - function run(inputOrRaw, options = {}) { if (options.truncated) { return { diff --git a/scripts/hooks/gateguard-fact-force.js b/scripts/hooks/gateguard-fact-force.js index ee0b988a4..228b6a247 100644 --- a/scripts/hooks/gateguard-fact-force.js +++ b/scripts/hooks/gateguard-fact-force.js @@ -25,6 +25,7 @@ const crypto = require('crypto'); const fs = require('fs'); const path = require('path'); +const { showRecoveryHints } = require('../lib/hooks/recovery-hints'); const { extractCommandSubstitutions, extractSubshellGroups, extractBraceGroups } = require('../lib/shell-substitution'); const { classifyPowerShellDestructiveCommand } = require('../lib/powershell-destructive-command'); const { stripHeredocBodies } = require('./gateguard-heredoc'); @@ -115,13 +116,6 @@ const ROUTINE_POWERSHELL_NARROW_RECOVERY_HINT = const ECC_DISABLE_VALUES = new Set(['0', 'false', 'off', 'disabled', 'disable']); const ECC_ENABLE_VALUES = new Set(['1', 'true', 'on', 'enabled', 'enable', 'yes']); -// A denial is fed back to the agent as untrusted tool text. Naming the env vars -// that disable the guard in that same message hands a bypass to the guarded -// agent (#3844), so the recovery controls are opt-in for human operators. -function showRecoveryHints() { - return ECC_ENABLE_VALUES.has(normalizeEnvValue(process.env.ECC_SHOW_RECOVERY_HINTS)); -} - // SQL keywords remain a phrase check. Quoted strings are stripped before // this regex runs so a commit message mentioning "drop table" stays passive. // `dd if=` used to be a fourth arm here. Matching it as text could not work: diff --git a/scripts/hooks/run-with-flags.js b/scripts/hooks/run-with-flags.js index 8544d3e59..a5cdbb584 100644 --- a/scripts/hooks/run-with-flags.js +++ b/scripts/hooks/run-with-flags.js @@ -13,6 +13,7 @@ const path = require('path'); const { spawnSync } = require('child_process'); const { StringDecoder } = require('string_decoder'); const { isHookEnabled, isDryRun } = require('../lib/hook-flags'); +const { showRecoveryHints } = require('../lib/hooks/recovery-hints'); const { readStdinRaw: readBoundedStdin, resolveMaxStdin } = require('./hook-input'); const { buildPreToolUseAdditionalContext } = require('./pretooluse-visible-output'); const { createHookContextScanner } = require('./hook-input-limits'); @@ -138,12 +139,9 @@ function truncatedInputResult(hookId, maxStdin) { if (failOpen) return null; } - const showRecoveryHints = /^(1|true|yes|on|enabled)$/i.test( - String(process.env.ECC_SHOW_RECOVERY_HINTS || '') - ); return { stdout: '', - stderr: showRecoveryHints + stderr: showRecoveryHints() ? `BLOCKED: Hook input exceeded ${maxStdin} bytes, so ${hookId} could not safely inspect the complete request. Retry with a smaller tool input or explicitly disable this hook.` : `BLOCKED: Hook input exceeded ${maxStdin} bytes, so ${hookId} could not safely inspect the complete request. Retry with a smaller tool input.`, exitCode: 2 diff --git a/scripts/lib/hooks/recovery-hints.js b/scripts/lib/hooks/recovery-hints.js new file mode 100644 index 000000000..7b1e45528 --- /dev/null +++ b/scripts/lib/hooks/recovery-hints.js @@ -0,0 +1,12 @@ +'use strict'; + +// Denial text is tool output the guarded agent reads. Naming the env vars that +// disable a hook hands it a bypass, so recovery instructions are opt-in for +// human operators (#3844). Every hook must parse the switch the same way. +const ENABLE_VALUES = new Set(['1', 'true', 'on', 'enabled', 'enable', 'yes']); + +function showRecoveryHints(value = process.env.ECC_SHOW_RECOVERY_HINTS) { + return ENABLE_VALUES.has(String(value || '').trim().toLowerCase()); +} + +module.exports = { showRecoveryHints }; diff --git a/tests/hooks/config-protection.test.js b/tests/hooks/config-protection.test.js index 6d78bedac..0a682e9d6 100644 --- a/tests/hooks/config-protection.test.js +++ b/tests/hooks/config-protection.test.js @@ -164,6 +164,55 @@ function runTests() { }) ); + results.push( + test('hides the config-protection recovery hint by default', () => { + return withOwnedDirectory(fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-')), tmpDir => { + const absPath = path.join(tmpDir, '.eslintrc.js'); + fs.writeFileSync(absPath, 'module.exports = {};'); + const result = runHook( + { tool_name: 'Write', tool_input: { file_path: absPath, content: '{}' } }, + { ECC_SHOW_RECOVERY_HINTS: '' } + ); + assert.strictEqual(result.code, 2); + assert.ok(!result.stderr.includes('disable the config-protection hook temporarily'), result.stderr); + }); + }) + ); + + results.push( + test('restores the config-protection recovery hint for normalized truthy values', () => { + return withOwnedDirectory(fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-')), tmpDir => { + const absPath = path.join(tmpDir, '.eslintrc.js'); + fs.writeFileSync(absPath, 'module.exports = {};'); + for (const value of [' true ', 'enable']) { + const result = runHook( + { tool_name: 'Write', tool_input: { file_path: absPath, content: '{}' } }, + { ECC_SHOW_RECOVERY_HINTS: value } + ); + assert.strictEqual(result.code, 2); + assert.ok(result.stderr.includes('disable the config-protection hook temporarily'), `${value}: ${result.stderr}`); + } + }); + }) + ); + + results.push( + test('hides the truncated-payload recovery hint by default and restores it on demand', () => { + const rawInput = JSON.stringify({ + tool_name: 'Write', + tool_input: { file_path: '.eslintrc.js', content: 'x'.repeat(1024 * 1024 + 2048) } + }); + + const hidden = runHook(rawInput, { ECC_SHOW_RECOVERY_HINTS: '' }); + assert.strictEqual(hidden.code, 2); + assert.ok(!hidden.stderr.includes('disable the config-protection hook temporarily'), hidden.stderr); + + const shown = runHook(rawInput, { ECC_SHOW_RECOVERY_HINTS: ' true ' }); + assert.strictEqual(shown.code, 2); + assert.ok(shown.stderr.includes('disable the config-protection hook temporarily'), shown.stderr); + }) + ); + results.push( test('allows first-time creation of a protected config file', () => { return withOwnedDirectory(fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-')), tmpDir => { diff --git a/tests/hooks/gateguard-fact-force.test.js b/tests/hooks/gateguard-fact-force.test.js index ce269a534..7bf4c18e6 100644 --- a/tests/hooks/gateguard-fact-force.test.js +++ b/tests/hooks/gateguard-fact-force.test.js @@ -7721,6 +7721,36 @@ function runTests() { passed++; else failed++; + clearState(); + writeState({ checked: [], last_active: Date.now(), fact_force_denials: 3 }); + if ( + test('condensed default denial omits recovery markers and bypass controls', () => { + const input = { + session_id: TEST_SESSION_ID, + tool_name: 'Edit', + tool_input: { file_path: '/workspace/app/src/recovery-condensed.js', old_string: 'a', new_string: 'b' } + }; + const result = runHook(input, { ECC_SHOW_RECOVERY_HINTS: '' }); + const output = parseOutput(result.stdout); + assert.ok(output && output.hookSpecificOutput, 'expected the condensed denial'); + assert.strictEqual(output.hookSpecificOutput.permissionDecision, 'deny'); + const reason = output.hookSpecificOutput.permissionDecisionReason; + assert.ok(reason.includes('denial #4'), 'expected the condensed denial ordinal'); + for (const leaked of [ + 'Narrow recovery:', + 'Recovery:', + 'ECC_GATEGUARD=off', + 'ECC_DISABLED_HOOKS', + 'GATEGUARD_EXEMPT_GLOBS', + 'GATEGUARD_BASH_ROUTINE_DISABLED' + ]) { + assert.ok(!reason.includes(leaked), `condensed default denial must not contain ${leaked}`); + } + }) + ) + passed++; + else failed++; + const ddResults = runDdRegressionTests(); passed += ddResults.passed; failed += ddResults.failed; diff --git a/tests/hooks/run-with-flags-truncation.test.js b/tests/hooks/run-with-flags-truncation.test.js index 267f9556b..66fb48b1d 100644 --- a/tests/hooks/run-with-flags-truncation.test.js +++ b/tests/hooks/run-with-flags-truncation.test.js @@ -198,6 +198,36 @@ for (const [hookId, toolName, toolInput] of GATEGUARD_TRUNCATION_CASES) { } } +if ( + test('fail-closed truncation hides the disable-hook hint by default', () => { + const result = runRunner( + ['pre:edit-write:gateguard-fact-force', 'scripts/hooks/gateguard-fact-force.js', 'standard,strict'], + oversizedPayload(), + { ...GATEGUARD_ENV_BASELINE, ECC_GATEGUARD: 'on', ECC_SHOW_RECOVERY_HINTS: '' } + ); + assert.strictEqual(result.status, 2); + assert.doesNotMatch(result.stderr, /explicitly disable this hook/); + }) +) + passed++; +else failed++; + +if ( + test('fail-closed truncation restores the disable-hook hint for normalized truthy values', () => { + for (const value of [' true ', 'enable']) { + const result = runRunner( + ['pre:edit-write:gateguard-fact-force', 'scripts/hooks/gateguard-fact-force.js', 'standard,strict'], + oversizedPayload(), + { ...GATEGUARD_ENV_BASELINE, ECC_GATEGUARD: 'on', ECC_SHOW_RECOVERY_HINTS: value } + ); + assert.strictEqual(result.status, 2); + assert.match(result.stderr, /explicitly disable this hook/, `${value}: ${result.stderr}`); + } + }) +) + passed++; +else failed++; + console.log(`\nPassed: ${passed}`); console.log(`Failed: ${failed}\n`); process.exit(failed > 0 ? 1 : 0); From 5dcd3d66f7b29010e122c60a569b0f739a74b31f Mon Sep 17 00:00:00 2001 From: huangpz6 Date: Wed, 4 Nov 2026 21:53:11 +0800 Subject: [PATCH 3/4] test(hooks): cover the shared recovery-hint parser directly (#3864) scripts/lib additions require a matching tests/lib test. Exercise normalization, default argument handling and the hidden-by-default set. Co-Authored-By: TRAE --- tests/lib/hooks/recovery-hints.test.js | 61 ++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 tests/lib/hooks/recovery-hints.test.js diff --git a/tests/lib/hooks/recovery-hints.test.js b/tests/lib/hooks/recovery-hints.test.js new file mode 100644 index 000000000..3db651687 --- /dev/null +++ b/tests/lib/hooks/recovery-hints.test.js @@ -0,0 +1,61 @@ +'use strict'; + +const assert = require('assert'); +const { showRecoveryHints } = require('../../../scripts/lib/hooks/recovery-hints'); + +function test(name, fn) { + try { + fn(); + console.log(` ✓ ${name}`); + return true; + } catch (error) { + console.log(` ✗ ${name}`); + console.log(` Error: ${error.message}`); + return false; + } +} + +let passed = 0; +let failed = 0; + +if ( + test('truthy values enable hints, trimming case-insensitive whitespace', () => { + for (const value of ['1', 'true', 'on', 'enabled', 'enable', 'yes', ' TRUE ', ' enable ']) { + assert.strictEqual(showRecoveryHints(value), true, `expected truthy: ${JSON.stringify(value)}`); + } + }) +) + passed++; +else failed++; + +if ( + test('unset, empty and non-listed values keep hints hidden', () => { + for (const value of ['', '0', 'false', 'off', 'disabled', 'disable', 'no', 'random']) { + assert.strictEqual(showRecoveryHints(value), false, `expected falsy: ${JSON.stringify(value)}`); + } + }) +) + passed++; +else failed++; + +if ( + test('the default argument reads ECC_SHOW_RECOVERY_HINTS', () => { + const saved = process.env.ECC_SHOW_RECOVERY_HINTS; + try { + process.env.ECC_SHOW_RECOVERY_HINTS = ' enable '; + assert.strictEqual(showRecoveryHints(), true); + process.env.ECC_SHOW_RECOVERY_HINTS = ''; + assert.strictEqual(showRecoveryHints(), false); + delete process.env.ECC_SHOW_RECOVERY_HINTS; + assert.strictEqual(showRecoveryHints(), false); + } finally { + if (saved === undefined) delete process.env.ECC_SHOW_RECOVERY_HINTS; + else process.env.ECC_SHOW_RECOVERY_HINTS = saved; + } + }) +) + passed++; +else failed++; + +console.log(`\n ${passed} passed, ${failed} failed\n`); +process.exit(failed > 0 ? 1 : 0); From 464440aa5134311f327c4254d35e286b6af43037 Mon Sep 17 00:00:00 2001 From: huangpz6 Date: Wed, 4 Nov 2026 22:07:01 +0800 Subject: [PATCH 4/4] test(hooks): emit the aggregated summary the runner parses (#3864) The suite printed 'N passed, M failed', which parseCounts ignores, so its three cases vanished from combined totals. Use the runner's Passed:/Failed: format. Co-Authored-By: TRAE --- tests/lib/hooks/recovery-hints.test.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/lib/hooks/recovery-hints.test.js b/tests/lib/hooks/recovery-hints.test.js index 3db651687..bd4d13a96 100644 --- a/tests/lib/hooks/recovery-hints.test.js +++ b/tests/lib/hooks/recovery-hints.test.js @@ -57,5 +57,6 @@ if ( passed++; else failed++; -console.log(`\n ${passed} passed, ${failed} failed\n`); +console.log(`\nPassed: ${passed}`); +console.log(`Failed: ${failed}\n`); process.exit(failed > 0 ? 1 : 0);