The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
perf(gateguard): load modules and parse searches only when a call needs them
Jeffrey Montoyab7f80ff01293
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2f0783040..7c2726faf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,7 @@- Read-only shell commands (`ls`, `cat`, `rg`, `git status`/`log`/`diff`, `Get-ChildItem`, …) no longer use up the once-per-session routine shell gate; the first other command is still gated (#2573).- GateGuard session state keyed by a session id or transcript path now expires after 8 idle hours instead of 30 minutes; the project-directory fallback keeps 30 minutes.- Add opt-in `GATEGUARD_FACT_FORCE_MAX_DENIALS`, a per-session denial cap: once that many first-touch denials have been issued, further new paths pass through (counted in `cap_allows`). Unset keeps the current behaviour; a malformed value is reported once on stderr and leaves the gate uncapped (#2755, thanks @SulimanAbdulrazzaq; closes #2608).+- GateGuard loads its target-classification, transcript, search-matching and change-profile modules only on the calls that use them, and parses only the searches that name the target, so shell commands and edits of already checked files stay within a few milliseconds of the previous hook.- Add opt-in `GATEGUARD_METRICS` decision metrics (codes only, never paths, commands or content) and `scripts/gateguard-report.js` to summarise them.- Sensitive targets (`.env*`, keys and certificates, `credentials*`, `secrets.*`, `auth`/`security`/`payment(s)`/`billing`/`migrations` path segments, `.github/workflows/`) and files with more than one hard link get none of these allowances, judged on the path as written and its real location, and are gated in subagents too. `GATEGUARD_EXEMPT_GLOBS` still takes precedence.- Newly denied: a subagent's first touch of a sensitive or hard-linked file, and the first NotebookEdit of each notebook. Every other rule only removes denials and never returns an `allow` decision. See `skills/gateguard/SKILL.md`.diff --git a/docs/gateguard/design-notes.md b/docs/gateguard/design-notes.mdindex c9ad6a202..3e0e14124 100644--- a/docs/gateguard/design-notes.md+++ b/docs/gateguard/design-notes.md@@ -89,6 +89,18 @@ and trivial edits) is in [change-profile.md](change-profile.md).decision metrics lines (see [Metrics](#metrics)). `scripts/gateguard-report.js`reads them back.+## Lazy loading++Most hook calls are shell commands and edits of files already checked in the+session; neither needs the target classification beyond the path key, the+transcript scan, the search matcher or the change profile. The hook requires+those modules on first use, so a shell command loads only the shell parser and+the state helpers, as on `main`. Every Node process runs one hook call, so a+module that is loaded is also compiled on that call: the cost of a+first-touch edit follows how much code it runs, not how much the files hold.+`module.exports` lists `run` first because `run-with-flags.js` recognises a+`run()` hook by a lexical match on the export object.+## Fail to denyEvery allowance other than a retry of an already-gated target (prior-search@@ -273,6 +285,20 @@ evidence from shell operands must name a directory that exists now.PowerShell `-Path`/`-LiteralPath` values count as operands but never asdirectory evidence.+## Search prefilter++Before any search is parsed, the turn's searches are checked for the target's+stem as plain text, with quotes and backslashes removed so that quoting+cannot split the stem. A search whose input does not contain the stem cannot+credit the target (credit needs the stem as a word in the parsed search), so+it is skipped; when no search passes, the search-evidence modules are not+loaded at all. The hook-side check strips test prefixes and suffixes+(`test_`, `_test`, `.test`, `.spec`) so it never skips a search the full+match would accept. New-file creations, which can also be credited by a+search that names their directory, bypass the prefilter. Parsed evidence is+cached per search, so the credit check and the closest-miss note share one+parse.+## Stem matchingA target's stem (basename without extension) credits it only when it has atdiff --git a/scripts/hooks/gateguard-fact-force.js b/scripts/hooks/gateguard-fact-force.jsindex 0d6bcf065..dcb6cfd13 100644--- a/scripts/hooks/gateguard-fact-force.js+++ b/scripts/hooks/gateguard-fact-force.js@@ -28,24 +28,49 @@ const path = require('path');const { extractCommandSubstitutions, extractSubshellGroups, extractBraceGroups } = require('../lib/shell-substitution');const { classifyPowerShellDestructiveCommand } = require('../lib/powershell-destructive-command');const { stripHeredocBodies } = require('./gateguard-heredoc');-const {- WINDOWS_PATH_PATTERN,- questionIdsFor,- questionText,- condensedHintFor,- resolveTargetPath,- canonicalPathKey,- classifyTarget,- classifyTargetFor,- collapseGateDir,- isSensitiveTargetFor,- isHardLinkedTargetFor-} = require('../lib/gateguard-target-class');-const { scanCurrentTurn, createTurnScanner, currentTurnId, transcriptPathFor } = require('../lib/gateguard-turn-scan');-const { createSearchEvidence } = require('../lib/gateguard-search-evidence');-const { profileChange } = require('../lib/gateguard-change-profile');-const { createReadOnlyShell } = require('../lib/gateguard-readonly-shell');-const { appendMetrics, metricsEvent } = require('../lib/gateguard-metrics');++// --- Lazily loaded modules ---+// see docs/gateguard/design-notes.md#lazy-loading++function lazily(load) {+ let loaded = null;+ return () => loaded || (loaded = load());+}++const targetClass = lazily(() => require('../lib/gateguard-target-class'));+const turnScan = lazily(() => require('../lib/gateguard-turn-scan'));+const changeProfile = lazily(() => require('../lib/gateguard-change-profile'));+const metricsLib = lazily(() => require('../lib/gateguard-metrics'));+const readOnlyShell = lazily(() => require('../lib/gateguard-readonly-shell').createReadOnlyShell({ quoteAwareSegments }));+const searchEvidence = lazily(() =>+ require('../lib/gateguard-search-evidence').createSearchEvidence({ quoteAwareSegments, commandBasename, SHELL_SEGMENT_SEPARATORS })+);++const questionIdsFor = (...args) => targetClass().questionIdsFor(...args);+const questionText = (...args) => targetClass().questionText(...args);+const condensedHintFor = (...args) => targetClass().condensedHintFor(...args);+const resolveTargetPath = (...args) => targetClass().resolveTargetPath(...args);+const canonicalPathKey = (...args) => targetClass().canonicalPathKey(...args);+const classifyTargetFor = (...args) => targetClass().classifyTargetFor(...args);+const collapseGateDir = (...args) => targetClass().collapseGateDir(...args);+const isSensitiveTargetFor = (...args) => targetClass().isSensitiveTargetFor(...args);+const isHardLinkedTargetFor = (...args) => targetClass().isHardLinkedTargetFor(...args);+const createTurnScanner = (...args) => turnScan().createTurnScanner(...args);+const currentTurnId = (...args) => turnScan().currentTurnId(...args);+const transcriptPathFor = (...args) => turnScan().transcriptPathFor(...args);+const profileChange = (...args) => changeProfile().profileChange(...args);+const appendMetrics = (...args) => metricsLib().appendMetrics(...args);+const metricsEvent = (...args) => metricsLib().metricsEvent(...args);+const isReadOnlyShellCommand = (...args) => readOnlyShell().isReadOnlyShellCommand(...args);+const hasEntries = list => Array.isArray(list) && list.length > 0;+const findCreditingSearch = (scan, filePath, allowDirMatch, data) =>+ scan && hasEntries(scan.searches) && (allowDirMatch || turnScan().searchesMayNameTarget(scan, filePath))+ ? searchEvidence().findCreditingSearch(scan, filePath, allowDirMatch, data)+ : null;+const findClosestMiss = (scan, filePath, allowDirMatch, data) =>+ scan && (hasEntries(scan.reads) || (hasEntries(scan.searches) && (allowDirMatch || turnScan().searchesMayNameTarget(scan, filePath))))+ ? searchEvidence().findClosestMiss(scan, filePath, allowDirMatch, data)+ : null;const {getDenialCount,getCreditedCount,@@ -191,7 +216,7 @@ function getExemptMatchers() {function isExemptPath(filePath, data) {const projectRoot = process.env.CLAUDE_PROJECT_DIR || data.cwd || process.cwd();if (typeof projectRoot !== 'string' || typeof filePath !== 'string') return false;- const paths = WINDOWS_PATH_PATTERN.test(projectRoot) ? path.win32 : path.posix;+ const paths = targetClass().WINDOWS_PATH_PATTERN.test(projectRoot) ? path.win32 : path.posix;if (!paths.isAbsolute(projectRoot)) return false;const target = paths.resolve(projectRoot, filePath);const relative = paths.relative(projectRoot, target);@@ -1655,8 +1680,6 @@ function isTrivialChange(cls, restricted, profile) {// --- Read-only first shell command ----const { isReadOnlyShellCommand } = createReadOnlyShell({ quoteAwareSegments });-function countRoutineReadonlyPass() {const state = loadState();return saveState({ ...state, routine_readonly_passes: getRoutineReadonlyPassCount(state) + 1 });@@ -2030,7 +2053,6 @@ function allowWithStateWarning() {// --- Prior-search credit ---const CREDIT_DETAIL_MAX_CHARS = 80;-const { findCreditingSearch, findClosestMiss } = createSearchEvidence({ quoteAwareSegments, commandBasename, SHELL_SEGMENT_SEPARATORS });function creditNote(match, filePath) {const chars = Array.from(sanitizePath(match.detail).replace(/\s+/g, ' '));@@ -2279,7 +2301,8 @@ function gate(rawInput) {pendingMetrics = { tool: toolName, data, entries: [], keys: new Set() };}const inSubagent = isSubagentInvocation(data);- const getTurnScan = createTurnScanner(data);+ let turnScanner = null;+ const getTurnScan = () => (turnScanner || (turnScanner = createTurnScanner(data)))();if (toolName === 'Edit' || toolName === 'Write' || toolName === 'NotebookEdit') {const filePath = (toolName === 'NotebookEdit' ? toolInput.notebook_path : toolInput.file_path) || '';@@ -2473,4 +2496,21 @@ function gate(rawInput) {return rawInput; // allow}-module.exports = { classifyDestructiveCommand, classifyTarget, classifyTargetFor, findCreditingSearch, findClosestMiss, isReadOnlyShellCommand, run, scanCurrentTurn };+module.exports = {+ run,+ classifyDestructiveCommand,+ findCreditingSearch,+ findClosestMiss,+ get classifyTarget() {+ return targetClass().classifyTarget;+ },+ get classifyTargetFor() {+ return targetClass().classifyTargetFor;+ },+ get isReadOnlyShellCommand() {+ return readOnlyShell().isReadOnlyShellCommand;+ },+ get scanCurrentTurn() {+ return turnScan().scanCurrentTurn;+ }+};diff --git a/scripts/lib/gateguard-search-evidence.js b/scripts/lib/gateguard-search-evidence.jsindex 27ae44111..92d8806e2 100644--- a/scripts/lib/gateguard-search-evidence.js+++ b/scripts/lib/gateguard-search-evidence.js@@ -84,6 +84,16 @@ function eligibleStem(filePath, data) {return stem.length >= MIN_STEM_LENGTH && !GENERIC_STEMS.has(stem) ? stem : null;}+// see docs/gateguard/design-notes.md#search-prefilter+function inputMayMention(input, word) {+ if (!input || typeof input !== 'object') return false;+ let text = '';+ for (const value of Object.values(input)) {+ if (typeof value === 'string') text += `\n${value}`;+ }+ return text.toLowerCase().replace(/["'\\]/g, '').includes(word);+}+// see docs/gateguard/design-notes.md#stem-matchingfunction stemMatcher(stem) {if (!stem) return null;@@ -393,6 +403,30 @@ function createSearchEvidence({ quoteAwareSegments, commandBasename, SHELL_SEGMEreturn evidence;}+ const evidenceCache = new WeakMap();+ const trustCache = new WeakMap();++ function cachedEvidence(search, shellDirsTrusted) {+ if (!search || typeof search !== 'object') return { items: [], misses: [] };+ let byTrust = evidenceCache.get(search);+ if (!byTrust) {+ byTrust = new Map();+ evidenceCache.set(search, byTrust);+ }+ let entry = byTrust.get(shellDirsTrusted);+ if (!entry) {+ const misses = [];+ entry = { items: searchEvidence(search, shellDirsTrusted, misses), misses };+ byTrust.set(shellDirsTrusted, entry);+ }+ return entry;+ }++ function shellDirsTrustedFor(scan) {+ if (!trustCache.has(scan)) trustCache.set(scan, !turnChangesDirectory(scan.shellCommands));+ return trustCache.get(scan);+ }+function turnChangesDirectory(shellCommands) {if (!Array.isArray(shellCommands)) return false;return shellCommands.some(command => {@@ -409,13 +443,17 @@ function createSearchEvidence({ quoteAwareSegments, commandBasename, SHELL_SEGMEif (typeof targetPath !== 'string' || !targetPath) return null;const ctx = dirContext(targetPath, data);if (!ctx) return null;- const stem = stemMatcher(eligibleStem(targetPath, data));+ const eligible = eligibleStem(targetPath, data);+ if (eligible === null && !allowDirMatch) return null;+ const stem = stemMatcher(eligible);// see docs/gateguard/design-notes.md#same-batch-searchesconst excluded = excludedBatchId(scan, data);- const shellDirsTrusted = !turnChangesDirectory(scan.shellCommands);+ let shellDirsTrusted = null;for (const search of scan.searches) {if (typeof search.messageId !== 'string' || !search.messageId || search.messageId === excluded) continue;- for (const item of searchEvidence(search, shellDirsTrusted)) {+ if (!allowDirMatch && !inputMayMention(search.input, eligible)) continue;+ if (shellDirsTrusted === null) shellDirsTrusted = shellDirsTrustedFor(scan);+ for (const item of cachedEvidence(search, shellDirsTrusted).items) {if (!evidenceInScope(item, ctx) || !filtersAdmitTarget(item, ctx, stem)) continue;const byStem = stem !== null && includesAdmitTarget(item, ctx) && item.texts.some(text => stem.test(text.toLowerCase()));const byDir = Boolean(allowDirMatch) && evidenceNamesDir(item, ctx);@@ -462,15 +500,17 @@ function createSearchEvidence({ quoteAwareSegments, commandBasename, SHELL_SEGMEconst bare = bareStem(targetPath, data);const rawStem = eligible === null && bare.length >= MIN_GENERIC_MISS_STEM ? stemMatcher(bare) : null;const excluded = excludedBatchId(scan, data);- const shellDirsTrusted = !turnChangesDirectory(scan.shellCommands);+ let shellDirsTrusted = null;let best = null;const consider = (name, detail, reason) => {if (reason && (best === null || MISS_RANK[reason] < MISS_RANK[best.reason])) best = { name, detail, reason };};for (const search of scan.searches) {if (!search || typeof search.messageId !== 'string' || !search.messageId) continue;- const misses = [];- for (const item of searchEvidence(search, shellDirsTrusted, misses)) {+ if (!allowDirMatch && (!bare || !inputMayMention(search.input, bare))) continue;+ if (shellDirsTrusted === null) shellDirsTrusted = shellDirsTrustedFor(scan);+ const { items, misses } = cachedEvidence(search, shellDirsTrusted);+ for (const item of items) {consider(search.name, item.detail, itemMiss(item, ctx, stem, rawStem, allowDirMatch, search.messageId === excluded));}for (const miss of misses) {diff --git a/scripts/lib/gateguard-state.js b/scripts/lib/gateguard-state.jsindex aafaff09a..aa6dc5678 100644--- a/scripts/lib/gateguard-state.js+++ b/scripts/lib/gateguard-state.js@@ -1,7 +1,5 @@'use strict';-const { COLLAPSIBLE_CLASSES } = require('./gateguard-target-class');-// --- Counters ---// see docs/gateguard/design-notes.md#state-file-is-untrusted@@ -87,7 +85,7 @@ function dirGateKey(cls, dir) {function isDirGateKey(key) {if (!isSafeKey(key)) return false;const at = key.indexOf(DIR_GATE_KEY_SEPARATOR);- return at > 0 && at < key.length - 1 && COLLAPSIBLE_CLASSES.has(key.slice(0, at));+ return at > 0 && at < key.length - 1 && require('./gateguard-target-class').COLLAPSIBLE_CLASSES.has(key.slice(0, at));}function isDirGateEntry(entry) {diff --git a/scripts/lib/gateguard-turn-scan.js b/scripts/lib/gateguard-turn-scan.jsindex 302bd8bb7..687623763 100644--- a/scripts/lib/gateguard-turn-scan.js+++ b/scripts/lib/gateguard-turn-scan.js@@ -2,6 +2,7 @@const crypto = require('crypto');const fs = require('fs');+const path = require('path');const { readFileTail, DEFAULT_TRANSCRIPT_TAIL_BYTES } = require('./transcript-context');const TRANSCRIPT_SCAN_MAX_LINES = 2000;@@ -231,6 +232,33 @@ function createTurnScanner(data) {};}+// see docs/gateguard/design-notes.md#search-prefilter+function targetNeedle(filePath) {+ const base = (String(filePath).split(/[\\/]/).pop() || '').toLowerCase();+ const ext = path.posix.extname(base);+ let stem = ext ? base.slice(0, -ext.length) : base;+ if (stem.endsWith('.test') || stem.endsWith('.spec')) stem = stem.slice(0, -5);+ if (stem.startsWith('test_')) stem = stem.slice(5);+ if (stem.endsWith('_test')) stem = stem.slice(0, -5);+ return stem;+}++/** False only when no search of the turn can name the target's stem, so matching can be skipped. */+function searchesMayNameTarget(scan, filePath) {+ if (!scan || !Array.isArray(scan.searches) || scan.searches.length === 0) return false;+ const needle = targetNeedle(filePath);+ if (!needle) return true;+ return scan.searches.some(search => {+ const input = search && search.input;+ if (!isObject(input)) return false;+ let text = '';+ for (const value of Object.values(input)) {+ if (typeof value === 'string') text += `\n${value}`;+ }+ return text.toLowerCase().replace(/["'\\]/g, '').includes(needle);+ });+}+function currentTurnId(scan) {return scan && typeof scan.turnId === 'string' && scan.turnId ? scan.turnId : null;}@@ -247,5 +275,6 @@ module.exports = {scanCurrentTurn: neverThrows(scanCurrentTurn, null),excludedBatchId: neverThrows(excludedBatchId, null),createTurnScanner: neverThrows(createTurnScanner, () => null),- currentTurnId: neverThrows(currentTurnId, null)+ currentTurnId: neverThrows(currentTurnId, null),+ searchesMayNameTarget: neverThrows(searchesMayNameTarget, true)};diff --git a/tests/hooks/gateguard-fact-force.test.js b/tests/hooks/gateguard-fact-force.test.jsindex 04aaa881b..b77ca8dcf 100644--- a/tests/hooks/gateguard-fact-force.test.js+++ b/tests/hooks/gateguard-fact-force.test.js@@ -5663,6 +5663,21 @@ function runTests() {});}+ // --- The search prefilter never hides a search that names the target ---+ const prefilterCases = [+ ["rg wid''get .", true],+ ['rg "wid"get .', true],+ ['rg WIDGET .', true],+ ['rg gadget .', false]+ ];+ for (const [command, credited] of prefilterCases) {+ gateCase(`search prefilter: ${command}`, () => {+ const out = creditEdit(exclusionTarget, exclusionTurn('Bash', { command }));+ if (credited) assertCredited(out, command);+ else assertNotCredited(out, command);+ });+ }+// --- Every PowerShell spelling of -Exclude is an exclusion ---const psExcludeDenied = ['Get-ChildItem -Recurse -ex widget.py',@@ -7371,6 +7386,38 @@ function runTests() {failed++;}+ // --- Modules load only on the paths that need them ---+ const loadedLibs = (payload, setup = []) => {+ const dir = fs.mkdtempSync(path.join(tmpRoot, 'gateguard-lazy-'));+ const env = { PATH: process.env.PATH, HOME: dir, GATEGUARD_STATE_DIR: path.join(dir, 'state'), CLAUDE_PROJECT_DIR: dir };+ const probe = [+ 'const hook = require(process.argv[1]);',+ 'hook.run(process.argv[2]);',+ "const names = Object.keys(require.cache).map(f => require('path').basename(f, '.js'));",+ "const libs = names.filter(n => /^(gateguard-|transcript-context$)/.test(n) && !/^gateguard-(fact-force|heredoc)$/.test(n));",+ 'process.stdout.write(JSON.stringify(libs.sort()));'+ ].join('\n');+ try {+ for (const step of setup) spawnSync(process.execPath, ['-e', probe, hookScript, JSON.stringify(step)], { env });+ const out = spawnSync(process.execPath, ['-e', probe, hookScript, JSON.stringify(payload)], { encoding: 'utf8', env });+ return JSON.parse(out.stdout);+ } finally {+ fs.rmSync(dir, { recursive: true, force: true });+ }+ };+ const lazyEdit = { session_id: 'lazy', tool_name: 'Edit', tool_input: { file_path: '/tmp/gateguard-lazy/src/widget.js', old_string: 'a', new_string: 'b' } };+ const lazyBash = command => ({ session_id: 'lazy', tool_name: 'Bash', tool_input: { command } });+ const lazyCases = [+ ['a first shell command loads only the read-only check', lazyBash('npm test'), [], ['gateguard-readonly-shell', 'gateguard-state']],+ ['a shell command after the routine gate loads only the state helpers', lazyBash('npm run build'), [lazyBash('npm test')], ['gateguard-state']],+ ['an edit of a checked file loads only the target classification', lazyEdit, [lazyEdit], ['gateguard-state', 'gateguard-target-class']],+ ['a first touch without a transcript loads no search matching', lazyEdit, [], ['gateguard-change-profile', 'gateguard-code-lexer', 'gateguard-file-context', 'gateguard-state', 'gateguard-target-class', 'gateguard-turn-scan', 'transcript-context']]+ ];+ for (const [label, payload, setup, expected] of lazyCases) {+ if (test(`lazy loading: ${label}`, () => assert.deepStrictEqual(loadedLibs(payload, setup), expected))) passed++;+ else failed++;+ }+const ddResults = runDdRegressionTests();passed += ddResults.passed;failed += ddResults.failed;diff --git a/tests/lib/gateguard-turn-scan.test.js b/tests/lib/gateguard-turn-scan.test.jsindex 3b3f56a74..3ffd69ffe 100644--- a/tests/lib/gateguard-turn-scan.test.js+++ b/tests/lib/gateguard-turn-scan.test.js@@ -370,6 +370,22 @@ test('the hook re-exports scanCurrentTurn', () => {}});+test('searchesMayNameTarget finds the stem in any search input', () => {+ const { searchesMayNameTarget } = require(libPath);+ const scanOf = (...inputs) => ({ searches: inputs.map(input => ({ name: 'Bash', input })) });+ assert.strictEqual(searchesMayNameTarget(scanOf({ command: 'rg widget .' }), 'src/widget.py'), true);+ assert.strictEqual(searchesMayNameTarget(scanOf({ command: 'rg other .' }, { pattern: 'x', glob: '*.md' }), 'src/widget.py'), false);+ assert.strictEqual(searchesMayNameTarget(scanOf({ command: "rg wid''get ." }), 'src/widget.py'), true, 'quotes cannot split the stem');+ assert.strictEqual(searchesMayNameTarget(scanOf({ command: 'rg "wid\\get" .' }), 'src/widget.py'), true, 'backslashes cannot split the stem');+ assert.strictEqual(searchesMayNameTarget(scanOf({ command: 'rg WIDGET .' }), 'src/widget.py'), true, 'case-insensitive');+ assert.strictEqual(searchesMayNameTarget(scanOf({ pattern: 'widget' }), 'tests/test_widget.py'), true, 'test prefix stripped');+ assert.strictEqual(searchesMayNameTarget(scanOf({ pattern: 'widget' }), 'src/widget.test.js'), true, 'test suffix stripped');+ assert.strictEqual(searchesMayNameTarget(scanOf({ pattern: 'widget' }), 'pkg/widget_test.go'), true, 'go test suffix stripped');+ assert.strictEqual(searchesMayNameTarget({ searches: [] }, 'src/widget.py'), false);+ assert.strictEqual(searchesMayNameTarget(null, 'src/widget.py'), false);+ assert.strictEqual(searchesMayNameTarget(scanOf({ command: 'ls' }), 'dir/'), true, 'no stem: never skipped');+});+fs.rmSync(transcriptDir, { recursive: true, force: true });console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);