The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
refactor(gateguard): move search evidence and state helpers to lib
Jeffrey Montoyaea86d156fe3a
diff --git a/scripts/hooks/gateguard-fact-force.js b/scripts/hooks/gateguard-fact-force.jsindex 1dbbc4312..3bf5361a8 100644--- a/scripts/hooks/gateguard-fact-force.js+++ b/scripts/hooks/gateguard-fact-force.js@@ -37,7 +37,6 @@ const { classifyPowerShellDestructiveCommand } = require('../lib/powershell-destconst { stripHeredocBodies } = require('./gateguard-heredoc');const {WINDOWS_PATH_PATTERN,- COLLAPSIBLE_CLASSES,CLASS_QUESTIONS,CLASS_CONDENSED_HINTS,QUOTE_INSTRUCTION,@@ -48,7 +47,22 @@ const {collapseGateDir,isSensitiveTargetFor} = require('../lib/gateguard-target-class');-const { scanCurrentTurn, excludedBatchId, createTurnScanner, currentTurnId, transcriptPathFor } = require('../lib/gateguard-turn-scan');+const { scanCurrentTurn, createTurnScanner, currentTurnId, transcriptPathFor } = require('../lib/gateguard-turn-scan');+const { createSearchEvidence } = require('../lib/gateguard-search-evidence');+const {+ getDenialCount,+ getCreditedCount,+ getCapAllowCount,+ getSiblingAllowCount,+ getClassCounts,+ mergeClassCounts,+ incrementClassCount,+ withEntry,+ dirGateKey,+ getDirGates,+ mergeDirGates,+ capDirGates+} = require('../lib/gateguard-state');// Session state — scoped per session to avoid cross-session races.const STATE_DIR = process.env.GATEGUARD_STATE_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.gateguard');@@ -1575,24 +1589,6 @@ function getMaxDenialBudget() {return Number.POSITIVE_INFINITY;}-/** A non-negative integer count from untrusted state; anything else is 0. */-function toCount(value) {- const n = Number(value);- return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;-}--function getDenialCount(state) {- return toCount(state && state.fact_force_denials);-}--function getCreditedCount(state) {- return toCount(state && state.fact_force_credited);-}--function getCapAllowCount(state) {- return toCount(state && state.cap_allows);-}-/** Mark a target checked and apply `update` in one state write, so an event is never half-recorded. */function markCheckedWith(key, update) {const loaded = loadState();@@ -1637,104 +1633,8 @@ function markCheckedAndCountCredit(key, cls) {}// --- Sibling gates and per-class counters ----// dir_gates maps `<class>\u0000<canonicalDir>` to { turn, at, first, ordinal }.-// The state file is untrusted, so every map is null-prototype and rejects prototype keys.-const MAX_DIR_GATES = 50;const SIBLING_NO_TURN_WINDOW_MS = 120 * 1000;-const DIR_GATE_KEY_SEPARATOR = '\u0000';-const UNSAFE_MAP_KEYS = new Set(['__proto__', 'constructor', 'prototype']);--function isPlainObject(value) {- return Boolean(value) && typeof value === 'object' && !Array.isArray(value);-}--function isSafeKey(key) {- return typeof key === 'string' && key !== '' && !UNSAFE_MAP_KEYS.has(key);-}--function nullMap(entries) {- const map = Object.create(null);- for (const [key, value] of entries) map[key] = value;- return map;-}--function withEntry(map, key, value) {- return nullMap([...Object.entries(map), [key, value]]);-}--function getClassCounts(state, field) {- const raw = state && state[field];- if (!isPlainObject(raw)) return nullMap([]);- const entries = Object.keys(raw)- .filter(cls => isSafeKey(cls) && typeof raw[cls] === 'number' && toCount(raw[cls]) > 0)- .map(cls => [cls, toCount(raw[cls])]);- return nullMap(entries);-}--function mergeClassCounts(a, b) {- const merged = nullMap(Object.entries(a));- for (const [cls, n] of Object.entries(b)) {- merged[cls] = Math.max(Object.hasOwn(merged, cls) ? merged[cls] : 0, n);- }- return merged;-}--function incrementClassCount(counts, cls) {- if (!isSafeKey(cls)) return counts;- return withEntry(counts, cls, (Object.hasOwn(counts, cls) ? counts[cls] : 0) + 1);-}--function getSiblingAllowCount(state) {- return toCount(state && state.sibling_allows);-}--function dirGateKey(cls, dir) {- return `${cls}${DIR_GATE_KEY_SEPARATOR}${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));-}--function isDirGateEntry(entry) {- return (- isPlainObject(entry) &&- typeof entry.at === 'number' &&- Number.isFinite(entry.at) &&- typeof entry.first === 'string' &&- (entry.turn === null || entry.turn === undefined || typeof entry.turn === 'string')- );-}--function getDirGates(state) {- const raw = state && state.dir_gates;- if (!isPlainObject(raw)) return nullMap([]);- const entries = Object.keys(raw)- .filter(key => isDirGateKey(key) && isDirGateEntry(raw[key]))- .map(key => {- const entry = raw[key];- return [key, { turn: entry.turn || null, at: entry.at, first: entry.first, ordinal: toCount(entry.ordinal) }];- });- return nullMap(entries);-}--/** Union by key; the newer `at` wins, so concurrent writers keep the latest gate. */-function mergeDirGates(older, newer) {- const merged = nullMap(Object.entries(older));- for (const [key, entry] of Object.entries(newer)) {- if (!Object.hasOwn(merged, key) || entry.at >= merged[key].at) merged[key] = entry;- }- return merged;-}--function capDirGates(gates) {- const entries = Object.entries(gates);- if (entries.length <= MAX_DIR_GATES) return gates;- return nullMap(entries.sort((a, b) => b[1].at - a[1].at).slice(0, MAX_DIR_GATES));-}function markCheckedAndCountSibling(key) {return markCheckedWith(key, state => ({@@ -2124,847 +2024,9 @@ function allowWithStateWarning() {}// --- Prior-search credit ----// `Read` never counts: Claude Code already requires a Read before an Edit, so-// crediting it would disable the Edit gate. Any ambiguity or failure means no credit.--const SHELL_SEARCH_COMMANDS = new Set([- 'rg',- 'grep',- 'egrep',- 'fgrep',- 'git',- 'find',- 'fd',- 'ls',- 'tree',- 'get-childitem',- 'gci',- 'select-string',- 'sls'-]);-const GIT_SEARCH_SUBCOMMANDS = new Set(['grep', 'ls-files']);-const DIRECTORY_CHANGE_COMMANDS = new Set(['cd', 'pushd', 'popd', 'chdir', 'set-location', 'sl', 'push-location', 'pop-location']);-// Search kinds whose first positional argument is the pattern, not a path.-const PATTERN_FIRST_SEARCHES = new Set(['grep', 'egrep', 'fgrep', 'rg', 'git grep', 'select-string', 'sls', 'fd']);-const RECURSIVE_BY_DEFAULT = new Set(['rg', 'git grep', 'git ls-files', 'find', 'fd', 'tree']);-const GREP_FAMILY = new Set(['grep', 'egrep', 'fgrep']);-const POWERSHELL_SEARCHES = new Set(['get-childitem', 'gci', 'select-string', 'sls']);-// Flags whose value is the search pattern (so the first positional is a path).-const PATTERN_VALUE_FLAGS = new Set(['-e', '-f', '--regexp', '--file']);-// Flags that consume the next argument; that argument is never a path operand.-const VALUE_FLAGS = new Set([- '-e', '-f', '-g', '-t', '-T', '-m', '-A', '-B', '-C',- '--regexp', '--file', '--type', '--glob', '--iglob', '--include', '--exclude', '--exclude-dir', '--exclude-from',- '--ignore-file', '--max-count', '--replace',- '-name', '-iname', '-path', '-ipath', '-type', '-maxdepth', '-mindepth', '-newer', '-regex', '-size', '-user', '-group', '-perm'-]);-// PowerShell parameters are case-insensitive. -Path/-LiteralPath values are paths-// (they count as operands for the stdin/target-only checks) but never directory evidence.-const LS_VALUE_FLAGS = new Set(['-I', '--ignore', '--hide']);-const TREE_VALUE_FLAGS = new Set(['-L', '-P', '-I', '-o']);-// fd: `-E/--exclude <glob>` take a value (fd's `-e` is an extension, also a value).-const FD_VALUE_FLAGS = new Set([...VALUE_FLAGS, '-E']);-// Only these tools take the search pattern from -e/-f (fd's -e is an extension).-const PATTERN_FLAG_SEARCHES = new Set(['grep', 'egrep', 'fgrep', 'rg', 'git grep']);-const POWERSHELL_VALUE_FLAGS = new Set(['-path', '-literalpath', '-depth', '-pattern']);-const POWERSHELL_PATH_FLAGS = new Set(['-path', '-literalpath']);-// PowerShell binds a parameter by any unambiguous prefix, `-Name:value`, and comma lists across arguments.-const POWERSHELL_FILTER_PARAMS = new Set(['filter', 'include', 'exclude']);-const POWERSHELL_COMMON_PARAMS = [- 'verbose', 'debug', 'erroraction', 'warningaction', 'informationaction', 'progressaction',- 'errorvariable', 'warningvariable', 'informationvariable', 'outvariable', 'outbuffer', 'pipelinevariable'-];-const POWERSHELL_CHILDITEM_PARAMS = [- 'path', 'literalpath', 'filter', 'include', 'exclude', 'recurse', 'depth', 'force', 'name',- 'attributes', 'directory', 'file', 'hidden', 'readonly', 'system', 'followsymlink'-];-const POWERSHELL_SELECTSTRING_PARAMS = [- 'pattern', 'path', 'literalpath', 'inputobject', 'simplematch', 'casesensitive', 'quiet', 'list', 'noemphasis',- 'include', 'exclude', 'notmatch', 'allmatches', 'encoding', 'context', 'raw', 'culture'-];-const POWERSHELL_PARAM_ALIASES = new Set([- 's', 'ad', 'd', 'af', 'ah', 'h', 'ar', 'as', 'lp', 'pspath',- 'vb', 'db', 'ea', 'wa', 'infa', 'proga', 'ev', 'wv', 'iv', 'ov', 'ob', 'pv'-]);-const GENERIC_STEMS = new Set([- 'index',- 'main',- 'init',- '__init__',- 'utils',- 'util',- 'types',- 'readme',- 'test',- 'tests',- 'config',- 'mod',- 'lib',- 'setup',- 'app',- 'spec',- 'helpers',- 'common'-]);-const MIN_STEM_LENGTH = 4;-const MAX_SEARCH_COMMAND_CHARS = 8192;-const CREDIT_DETAIL_MAX_CHARS = 80;-// Command substitution, process substitution, heredocs and PowerShell-// backtick escapes make the searched text ambiguous: never credit them.-const AMBIGUOUS_SHELL_PATTERN = /`|\$\(|[<>]\(|<</;-const GLOB_CHARS_PATTERN = /[*?[{]/;--function eligibleStem(filePath) {- const base = String(filePath).split(/[\\/]/).pop() || '';- const ext = path.posix.extname(base);- const stem = (ext ? base.slice(0, -ext.length) : base).toLowerCase();- return stem.length >= MIN_STEM_LENGTH && !GENERIC_STEMS.has(stem) ? stem : null;-}--/** Word-boundary stem matcher; an indexOf scan, never a RegExp built from untrusted text. */-function stemMatcher(stem) {- if (!stem) return null;- return { test: text => containsWord(String(text), stem) };-}--function isStemWordChar(ch) {- return ch !== undefined && ((ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9'));-}--function containsWord(text, word) {- for (let at = text.indexOf(word); at !== -1; at = text.indexOf(word, at + 1)) {- if (!isStemWordChar(text[at - 1]) && !isStemWordChar(text[at + word.length])) return true;- }- return false;-}--/** Path-resolution context for a target; relative paths resolve against the tool `cwd`. */-function dirContext(targetPath, data) {- const base = (data && typeof data.cwd === 'string' && data.cwd) || process.env.CLAUDE_PROJECT_DIR || process.cwd();- const isWin = WINDOWS_PATH_PATTERN.test(base) || WINDOWS_PATH_PATTERN.test(targetPath);- const paths = isWin ? path.win32 : path.posix;- if (!paths.isAbsolute(base)) return null;- const resolveNative = (...parts) => paths.resolve(base, ...parts);- const resolveDir = (...parts) => {- const dir = resolveNative(...parts).replace(/\\/g, '/');- return isWin ? dir.toLowerCase() : dir;- };- const targetKey = resolveDir(targetPath);- return { resolveDir, resolveNative, targetKey, targetDir: path.posix.dirname(targetKey) };-}--function isInsideDir(targetKey, dirKey) {- return targetKey.startsWith(dirKey.endsWith('/') ? dirKey : `${dirKey}/`);-}--function isDirectoryNow(nativePath) {- try {- return fs.statSync(nativePath).isDirectory();- } catch (_) {- return false;- }-}--function globLiteralPrefix(pattern) {- const segments = pattern.split(/[\\/]/);- const firstGlob = segments.findIndex(segment => GLOB_CHARS_PATTERN.test(segment));- const literal = firstGlob === -1 ? segments.slice(0, -1) : segments.slice(0, firstGlob);- const joined = literal.join('/');- return joined || (literal.length > 0 && pattern.startsWith('/') ? '/' : '');-}--function stringsOf(...values) {- return values.filter(value => typeof value === 'string' && value);-}--/**- * Evidence a search offers: stem `texts`, candidate `dirs`, the `scope`/`scopes`- * the target must lie in, and `operands` that must not all be the target itself.- */-function searchEvidence(search, shellDirsTrusted) {- const input = search.input;- if (search.name === 'Glob') {- if (typeof input.pattern !== 'string' || !input.pattern) return [];- const explicit = typeof input.path === 'string' && input.path ? input.path : '';- const prefix = globLiteralPrefix(input.pattern);- const scope = [explicit || '.', prefix || '.'];- if (!GLOB_CHARS_PATTERN.test(input.pattern)) {- // A single-file lookup names no directory, and looking up the target itself is not a search.- const lookup = [explicit || '.', input.pattern];- return [{ texts: [input.pattern], dirs: [], scope, scopeExact: true, operands: [lookup], detail: input.pattern }];- }- // An empty literal prefix with no explicit path names only the implicit cwd.- const dirs = prefix || explicit ? [scope] : [];- return [{ texts: [input.pattern], dirs, scope, detail: input.pattern }];- }- if (search.name === 'Grep') {- if (typeof input.pattern !== 'string' || !input.pattern) return [];- const explicit = typeof input.path === 'string' && input.path ? input.path : '';- const detail = typeof input.glob === 'string' && input.glob ? `${input.pattern} --glob ${input.glob}` : input.pattern;- const filters = grepToolFilters(input.glob);- return [{- texts: stringsOf(input.pattern, ...filters.positives),- dirs: explicit ? [[explicit]] : [],- scope: [explicit || '.'],- detail,- ...filters- }];- }- if (search.name === 'LS') {- return stringsOf(input.path).map(dir => ({ texts: [], dirs: [[dir]], scope: [dir], detail: dir }));- }- return shellSearchEvidence(input.command, shellDirsTrusted);-}-/**- * Per segment, whether it reads piped input. Mirrors `quoteAwareSegments`- * splitting; `||` also marks the next segment, which only ever removes evidence.- */-function segmentPipeFlags(input) {- const flags = [];- let quote = null;- let escaped = false;- let hasContent = false;- let piped = false;- for (const ch of String(input || '')) {- if (escaped) {- escaped = false;- } else if (ch === '\\') {- escaped = true;- hasContent = true;- } else if (quote) {- if (ch === quote) quote = null;- } else if (ch === '"' || ch === "'") {- quote = ch;- hasContent = true;- } else if (SHELL_SEGMENT_SEPARATORS.has(ch)) {- if (hasContent) {- flags.push(piped);- piped = false;- hasContent = false;- }- piped = piped || ch === '|';- } else if (!/\s/.test(ch)) {- hasContent = true;- }- }- if (hasContent) flags.push(piped);- return flags;-}--/** Base for relative operands after a directory change; null unless it is a plain literal `cd <dir>`. */-function baseAfterDirectoryChange(base, lead, tokens) {- if (!['cd', 'chdir', 'set-location', 'sl'].includes(lead) || tokens.length !== 2) return null;- const dir = tokens[1];- if (!dir || /^[-$~]/.test(dir) || GLOB_CHARS_PATTERN.test(dir)) return null;- if (isAbsoluteShellPath(dir)) return [dir];- return base === null ? null : base.concat(dir);-}--function isAbsoluteShellPath(arg) {- return path.posix.isAbsolute(arg) || WINDOWS_PATH_PATTERN.test(arg);-}--function operandScopePath(arg) {- if (!GLOB_CHARS_PATTERN.test(arg)) return arg;- const segments = arg.split(/[\\/]/);- const literal = segments.slice(0, segments.findIndex(segment => GLOB_CHARS_PATTERN.test(segment)));- if (literal.length === 0) return '.';- return literal.join('/') || '/';-}--/** Scopes a shell segment searched; unresolvable operands (variables, `~`, unknown cwd) scope nothing. */-function shellSearchScopes(parsed, base) {- if (parsed.operands.length === 0) return base === null ? [] : [base];- const scopes = [];- for (const operand of parsed.operands) {- if (!operand || operand === '-' || /^[$~]/.test(operand)) continue;- const scoped = operandScopePath(operand);- if (isAbsoluteShellPath(scoped)) scopes.push([scoped]);- else if (base !== null) scopes.push(base.concat(scoped));- }- return scopes;-}--/** Evidence for each search segment of a shell command; ambiguous or oversized commands yield none. */-function shellSearchEvidence(command, dirsTrusted) {- if (typeof command !== 'string' || !command || command.length > MAX_SEARCH_COMMAND_CHARS) return [];- if (AMBIGUOUS_SHELL_PATTERN.test(command)) return [];- const pipeFlags = segmentPipeFlags(command);- const evidence = [];- let trusted = dirsTrusted;- // A cd in any other call of the turn leaves the cwd of this one unknown.- let base = dirsTrusted ? [] : null;- quoteAwareSegments(command).forEach((tokens, index) => {- const lead = commandBasename(tokens[0]);- if (DIRECTORY_CHANGE_COMMANDS.has(lead)) {- trusted = false;- base = baseAfterDirectoryChange(base, lead, tokens);- return;- }- if (!SHELL_SEARCH_COMMANDS.has(lead)) return;- let kind = lead;- let args = tokens.slice(1);- if (lead === 'git') {- if (!GIT_SEARCH_SUBCOMMANDS.has(tokens[1])) return;- kind = `git ${tokens[1]}`;- args = tokens.slice(2);- }- const parsed = parseSearchArgs(kind, args);- // A segment that reads stdin (redirection, pipe, or no operand without recursion) is not a tree search.- if (parsed.stdin) return;- if (parsed.operands.length === 0 && (!parsed.recursive || pipeFlags[index] !== false)) return;- const scopes = shellSearchScopes(parsed, base);- if (scopes.length === 0) return;- const filters = shellSearchFilters(kind, args);- // Exclusion values (and the flags that introduce them) are never a stem source.- const stemText = tokens.slice(0, tokens.length - args.length).concat(args.filter((_, i) => !filters.dropped.has(i))).join(' ');- const dirs = trusted ? parsed.dirOperands.map(shellDirCandidate).filter(Boolean).map(dir => [dir]) : [];- evidence.push({- texts: [stemText],- dirs,- dirsMustExist: true,- scopes,- operands: parsed.operands.map(op => [op]),- detail: tokens.join(' '),- exclusions: filters.exclusions,- includes: filters.includes,- opaque: filters.opaque- });- });- return evidence;-}--function isRecursiveFlag(kind, arg) {- const lower = arg.toLowerCase();- if (POWERSHELL_SEARCHES.has(kind)) return (kind === 'get-childitem' || kind === 'gci') && lower.startsWith('-rec');- if (arg === '--recursive' || arg === '--dereference-recursive') return GREP_FAMILY.has(kind) || kind === 'ls';- if (!/^-[a-zA-Z]+$/.test(arg)) return false;- if (GREP_FAMILY.has(kind)) return /[rR]/.test(arg);- return kind === 'ls' && arg.includes('R');-}--function valueFlagsFor(kind) {- if (kind === 'ls' || kind === 'git ls-files') return LS_VALUE_FLAGS;- if (kind === 'tree') return TREE_VALUE_FLAGS;- if (kind === 'fd') return FD_VALUE_FLAGS;- return VALUE_FLAGS;-}--/** Arguments a flag consumes; single-dash clusters (`-rne PAT`) are read letter by letter. */-function flagEffect(kind, args, i) {- const arg = args[i];- if (POWERSHELL_SEARCHES.has(kind)) {- const lower = arg.toLowerCase();- const filter = powershellFilterArg(kind, args, i);- const consumes = filter ? filter.end - i : POWERSHELL_VALUE_FLAGS.has(lower) ? 1 : 0;- return { consumes, patternFlag: lower === '-pattern', pathFlag: POWERSHELL_PATH_FLAGS.has(lower) };- }- const values = valueFlagsFor(kind);- const takesValue = flag => values.has(flag) || (kind === 'rg' && (flag === '-r' || flag === '--replace'));- const isPatternFlag = flag => PATTERN_FLAG_SEARCHES.has(kind) && PATTERN_VALUE_FLAGS.has(flag);- const name = arg.split('=')[0];- if (arg.startsWith('--') || kind === 'find' || takesValue(arg)) {- return { consumes: !arg.includes('=') && takesValue(name) ? 1 : 0, patternFlag: isPatternFlag(name), pathFlag: false };- }- for (let i = 1; i < arg.length; i++) {- const flag = `-${arg[i]}`;- if (takesValue(flag)) return { consumes: i === arg.length - 1 ? 1 : 0, patternFlag: isPatternFlag(flag), pathFlag: false };- }- return { consumes: 0, patternFlag: false, pathFlag: false };-}--/** Path operands of a search command, skipping flag values and the pattern positional. */-function parseSearchArgs(kind, args) {- const positionals = [];- const pathValues = [];- let recursive = RECURSIVE_BY_DEFAULT.has(kind);- let patternGiven = false;- let expressionStarted = false;- let inputRedirect = false;- for (let i = 0; i < args.length; i++) {- const arg = args[i];- if (/^\d*[<>]/.test(arg)) {- inputRedirect = /^\d*</.test(arg);- break;- }- if (arg.includes('<')) {- inputRedirect = true; // a quoted `<` cannot be told from a redirection- break;- }- if (arg.length > 1 && arg.startsWith('-')) {- expressionStarted = true;- if (isRecursiveFlag(kind, arg)) recursive = true;- const effect = flagEffect(kind, args, i);- if (effect.patternFlag) patternGiven = true;- if (effect.pathFlag && i + 1 < args.length) pathValues.push(args[i + 1]);- i += effect.consumes;- continue;- }- if (kind === 'find' && (expressionStarted || arg === '(' || arg === '!')) {- expressionStarted = true;- continue;- }- positionals.push(arg);- }- const dirOperands = PATTERN_FIRST_SEARCHES.has(kind) && !patternGiven ? positionals.slice(1) : positionals;- const operands = dirOperands.concat(pathValues);- return { operands, dirOperands, recursive, stdin: inputRedirect && operands.length === 0 };-}--function shellDirCandidate(arg) {- if (!arg || /^[$~]/.test(arg)) return '';- const dir = arg.replace(/(?:[\\/]\*\*|[\\/]\*|[\\/])+$/, '');- if (!dir || dir === '.' || GLOB_CHARS_PATTERN.test(dir)) return '';- return dir;-}--/** A directory change anywhere in the turn makes relative shell paths unreliable. */-function turnChangesDirectory(shellCommands) {- if (!Array.isArray(shellCommands)) return false;- return shellCommands.some(command => {- if (typeof command !== 'string') return false;- if (command.length > MAX_SEARCH_COMMAND_CHARS) return true;- return quoteAwareSegments(command).some(tokens => DIRECTORY_CHANGE_COMMANDS.has(commandBasename(tokens[0])));- });-}--function evidenceInScope(item, ctx) {- if (item.scopes) {- const covers = parts => {- const scope = ctx.resolveDir(...parts);- return scope === ctx.targetKey || isInsideDir(ctx.targetKey, scope);- };- if (!item.scopes.some(covers)) return false;- }- if (item.scope) {- const scope = ctx.resolveDir(...item.scope);- if (scope === ctx.targetKey || !isInsideDir(ctx.targetKey, scope)) return false;- if (item.scopeExact && ctx.targetDir !== scope) return false;- }- if (item.operands && item.operands.length > 0 && item.operands.every(parts => ctx.resolveDir(...parts) === ctx.targetKey)) {- return false; // reading the target itself is not a search- }- return true;-}--function evidenceNamesDir(item, ctx) {- return item.dirs.some(- parts => ctx.resolveDir(...parts) === ctx.targetDir && (!item.dirsMustExist || isDirectoryNow(ctx.resolveNative(...parts)))- );-}--// --- Search filters ----// A search that excluded the target never saw it, so exclusions are never a stem-// source and one covering the target blocks credit; unreadable exclusion lists-// block it too. Globs are matched without RegExp and bounded; past the bounds they cover the target.--const MAX_FILTER_GLOB_CHARS = 256;-const MAX_BRACE_ALTERNATIVES = 32;-const MAX_FILTERS_PER_SEARCH = 32;-const FIND_NAME_FLAGS = new Set(['-name', '-iname', '-path', '-ipath', '-wholename', '-iwholename', '-regex', '-iregex']);-const FIND_BASENAME_FLAGS = new Set(['-name', '-iname']);-const OPAQUE_FILTER_FLAGS = new Set(['--exclude-from', '--ignore-file', '--exclude-per-directory']);-const EXCLUDE_LONG_FLAGS = new Set(['--exclude', '--exclude-dir', '--ignore', '--hide']);-const LS_ONLY_EXCLUDE_FLAGS = new Set(['--ignore', '--hide']);-const GIT_EXCLUDE_PATHSPEC = /^:(?:[!^]|\([^)]*\bexclude\b[^)]*\))/;--function splitTopLevelCommas(value) {- const parts = [];- let depth = 0;- let current = '';- for (const ch of String(value)) {- if (ch === '{') depth += 1;- else if (ch === '}' && depth > 0) depth -= 1;- if (ch === ',' && depth === 0) {- parts.push(current);- current = '';- } else {- current += ch;- }- }- parts.push(current);- return parts.map(part => part.trim()).filter(Boolean);-}--function expandBraces(glob) {- const open = glob.indexOf('{');- if (open === -1) return [glob];- let depth = 0;- for (let i = open; i < glob.length; i++) {- if (glob[i] === '{') depth += 1;- else if (glob[i] === '}' && --depth === 0) {- const head = glob.slice(0, open);- const tail = glob.slice(i + 1);- const results = [];- for (const option of splitTopLevelCommas(glob.slice(open + 1, i)).concat(glob[open + 1] === ',' ? [''] : [])) {- const expanded = expandBraces(`${head}${option}${tail}`);- if (!expanded) return null;- results.push(...expanded);- if (results.length > MAX_BRACE_ALTERNATIVES) return null;- }- return results;- }- }- return [glob]; // unbalanced: `{` is literal-}--function globTokens(glob) {- const tokens = [];- for (let i = 0; i < glob.length; i++) {- const ch = glob[i];- if (ch === '*' && glob[i + 1] === '*') {- const dirs = glob[i + 2] === '/';- tokens.push({ type: dirs ? 'dirs' : 'deep' });- i += dirs ? 2 : 1;- } else if (ch === '*') {- tokens.push({ type: 'star' });- } else if (ch === '?') {- tokens.push({ type: 'one' });- } else if (ch === '[') {- const parsed = bracketClass(glob, i);- if (!parsed) return null;- tokens.push(parsed.token);- i = parsed.end;- } else {- tokens.push({ type: 'lit', ch });- }- }- return tokens;-}--/** `[...]` with members, ranges, `!`/`^` negation and a leading literal `]`; null when unclosed. */-function bracketClass(glob, open) {- let i = open + 1;- const negated = glob[i] === '!' || glob[i] === '^';- if (negated) i += 1;- const ranges = [];- for (let first = true; i < glob.length && (first || glob[i] !== ']'); first = false) {- if (glob[i + 1] === '-' && i + 2 < glob.length && glob[i + 2] !== ']') {- ranges.push([glob[i], glob[i + 2]]);- i += 3;- } else {- ranges.push([glob[i], glob[i]]);- i += 1;- }- }- if (i >= glob.length) return null;- return { token: { type: 'class', negated, ranges }, end: i };-}--function classMatches(token, ch) {- if (ch === '/') return false;- const forms = [ch, ch.toLowerCase(), ch.toUpperCase()];- const member = token.ranges.some(([lo, hi]) => forms.some(form => form >= lo && form <= hi));- return member !== token.negated;-}--/** Glob match by dynamic programming, so a hostile glob cannot cause regex backtracking; null when malformed. */-function wildcardMatch(glob, text) {- const tokens = globTokens(glob);- if (!tokens) return null;- const n = text.length;- let next = new Array(n + 1).fill(false);- next[n] = true;- for (let t = tokens.length - 1; t >= 0; t--) {- const token = tokens[t];- const row = new Array(n + 1).fill(false);- let afterSlash = false; // for 'dirs': some k > j with text[k-1] === '/' and next[k]- for (let j = n; j >= 0; j--) {- if (token.type === 'lit') row[j] = j < n && text[j] === token.ch && next[j + 1];- else if (token.type === 'one') row[j] = j < n && text[j] !== '/' && next[j + 1];- else if (token.type === 'class') row[j] = j < n && classMatches(token, text[j]) && next[j + 1];- else if (token.type === 'star') row[j] = next[j] || (j < n && text[j] !== '/' && row[j + 1]);- else if (token.type === 'deep') row[j] = next[j] || (j < n && row[j + 1]);- else {- if (j < n && text[j] === '/' && next[j + 1]) afterSlash = true;- row[j] = next[j] || afterSlash;- }- }- next = row;- }- return next[0];-}--function normalizeFilterGlob(glob) {- return String(glob).toLowerCase().replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/^\/+/, '').replace(/\/+$/, '');-}--/** Null when the glob is past the length or brace bounds; a malformed alternative counts as `malformed`. */-function globMatches(glob, text, malformed) {- if (glob.length > MAX_FILTER_GLOB_CHARS) return null;- const alternatives = expandBraces(glob);- if (!alternatives) return null;- return alternatives.some(alternative => {- const matched = wildcardMatch(alternative, text);- return matched === null ? malformed : matched;- });-}--function targetSegments(ctx) {- return ctx.targetKey.toLowerCase().split('/').filter(Boolean);-}--/** An exclusion covers the target when it names the stem or matches the file or any directory above it. */-function exclusionCoversTarget(exclusion, segments, stem) {- const glob = normalizeFilterGlob(exclusion);- if (!glob) return true;- if (stem !== null && stem.test(glob)) return true;- for (let start = 0; start < segments.length; start++) {- for (let end = start + 1; end <= segments.length; end++) {- const matched = globMatches(glob, segments.slice(start, end).join('/'), true);- if (matched !== false) return true;- }- }- return false;-}--function filtersAdmitTarget(item, ctx, stem) {- if (item.opaque) return false;- const exclusions = Array.isArray(item.exclusions) ? item.exclusions : [];- if (exclusions.length === 0) return true;- if (exclusions.length > MAX_FILTERS_PER_SEARCH) return false;- const segments = targetSegments(ctx);- return !exclusions.some(exclusion => exclusionCoversTarget(exclusion, segments, stem));-}--/** Basename include globs that all miss the target stop its stem from crediting; oversized globs admit, malformed ones do not. */-function includesAdmitTarget(item, ctx) {- const includes = Array.isArray(item.includes) ? item.includes : [];- if (includes.length === 0) return true;- const segments = targetSegments(ctx);- const base = segments[segments.length - 1] || '';- return includes.some(include => globMatches(normalizeFilterGlob(include).replace(/^(?:\*\*\/)+/, ''), base, false) !== false);-}--function isBasenameGlob(glob) {- return !/[\\/]/.test(String(glob).replace(/^(?:\*\*[\\/])+/, ''));-}--function grepToolFilters(glob) {- const filters = { positives: [], includes: [], exclusions: [], opaque: false };- if (typeof glob !== 'string' || !glob) return filters;- for (const part of splitTopLevelCommas(glob)) {- if (part.startsWith('!')) filters.exclusions.push(part.slice(1));- else {- filters.positives.push(part);- if (isBasenameGlob(part)) filters.includes.push(part);- }- }- return filters;-}--function shellSearchFilters(kind, args) {- const filters = { exclusions: [], includes: [], opaque: false, dropped: new Set() };- if (kind === 'find') return findSearchFilters(args, filters);- if (POWERSHELL_SEARCHES.has(kind)) return powershellSearchFilters(kind, args, filters);- for (let i = 0; i < args.length; i++) {- const arg = args[i];- if (/^\d*[<>]/.test(arg)) break;- const consumed = applyShellFilterArg(kind, args, i, filters);- i += consumed;- }- return filters;-}--function applyShellFilterArg(kind, args, i, filters) {- const arg = args[i];- const exclude = (value, indexes, separator) => {- for (const glob of separator ? String(value).split(separator) : [value]) {- if (glob) filters.exclusions.push(glob);- }- indexes.forEach(index => filters.dropped.add(index));- };- const include = value => {- if (isBasenameGlob(value)) filters.includes.push(value);- };- if (kind.startsWith('git ') && GIT_EXCLUDE_PATHSPEC.test(arg)) {- exclude(arg.replace(GIT_EXCLUDE_PATHSPEC, ''), [i]);- return 0;- }- if (arg.startsWith('--')) {- const eq = arg.indexOf('=');- const name = eq > 0 ? arg.slice(0, eq) : arg;- const hasNext = eq <= 0 && i + 1 < args.length;- const value = eq > 0 ? arg.slice(eq + 1) : hasNext ? args[i + 1] : '';- const indexes = eq > 0 || !hasNext ? [i] : [i, i + 1];- const consumed = indexes.length - 1;- if (OPAQUE_FILTER_FLAGS.has(name)) {- filters.opaque = true;- return consumed;- }- if (name === '--glob' || name === '--iglob') {- if (value.startsWith('!')) exclude(value.slice(1), indexes);- else include(value);- return consumed;- }- if (name === '--include') {- include(value);- return consumed;- }- // `--ignore`/`--hide` hide names only for ls (rg's `--ignore` is a switch).- if (EXCLUDE_LONG_FLAGS.has(name) && (kind === 'ls' || !LS_ONLY_EXCLUDE_FLAGS.has(name))) {- exclude(value, indexes);- return consumed;- }- return 0;- }- if (!/^-[A-Za-z]/.test(arg)) return 0;- const letters = shortFilterLetters(kind);- const valueFlags = valueFlagsFor(kind);- for (let k = 1; k < arg.length; k++) {- const letter = arg[k];- if (!letters.has(letter)) {- // Another value flag ends the cluster: the rest (or the next argument) is its value.- if (valueFlags.has(`-${letter}`)) return k === arg.length - 1 ? 1 : 0;- continue;- }- const attached = arg.slice(k + 1);- const value = attached || args[i + 1] || '';- const indexes = attached || i + 1 >= args.length ? [i] : [i, i + 1];- const consumed = indexes.length - 1;- applyShortFilter(kind, letter, value, indexes, { filters, exclude, include });- return consumed;- }- return 0;-}--function shortFilterLetters(kind) {- if (kind === 'rg') return new Set(['g']);- if (kind === 'fd') return new Set(['E']);- if (kind === 'ls') return new Set(['I']);- if (kind === 'tree') return new Set(['I', 'P']);- if (kind === 'git ls-files') return new Set(['x', 'X']);- return new Set();-}--function applyShortFilter(kind, letter, value, indexes, { filters, exclude, include }) {- if (kind === 'rg') {- if (value.startsWith('!')) exclude(value.slice(1), indexes);- else include(value);- } else if (kind === 'tree' && letter === 'P') {- value.split('|').forEach(include);- } else if (kind === 'git ls-files' && letter === 'X') {- filters.opaque = true;- } else {- exclude(value, indexes, kind === 'tree' ? '|' : '');- }-}--/** find: a negated or pruned name test is an exclusion; a plain `-name`/`-iname` is an include. */-function findSearchFilters(args, filters) {- let negateNext = false;- let negatedDepth = 0;- let depth = 0;- for (let i = 0; i < args.length; i++) {- const arg = args[i];- if (/^\d*[<>]/.test(arg)) break;- if (arg === '-not' || arg === '!') {- negateNext = true;- filters.dropped.add(i);- continue;- }- if (arg === '(') {- depth += 1;- if (negateNext && negatedDepth === 0) negatedDepth = depth;- negateNext = false;- continue;- }- if (arg === ')') {- if (negatedDepth === depth) negatedDepth = 0;- depth = Math.max(depth - 1, 0);- continue;- }- if (FIND_NAME_FLAGS.has(arg) && i + 1 < args.length) {- const value = args[i + 1];- if (negateNext || negatedDepth > 0 || args[i + 2] === '-prune') {- filters.exclusions.push(value);- filters.dropped.add(i);- filters.dropped.add(i + 1);- } else if (FIND_BASENAME_FLAGS.has(arg)) {- filters.includes.push(value);- }- i += 1;- }- negateNext = false;- }- return filters;-}--function powershellParam(kind, arg) {- const colon = arg.indexOf(':');- const spelled = (colon === -1 ? arg.slice(1) : arg.slice(1, colon)).toLowerCase();- const inline = colon === -1 ? null : arg.slice(colon + 1);- const own = kind === 'get-childitem' || kind === 'gci' ? POWERSHELL_CHILDITEM_PARAMS : POWERSHELL_SELECTSTRING_PARAMS;- const params = own.concat(POWERSHELL_COMMON_PARAMS);- if (!spelled) return { name: null, inline };- if (params.includes(spelled) || POWERSHELL_PARAM_ALIASES.has(spelled)) return { name: spelled, inline };- const matches = params.filter(param => param.startsWith(spelled));- return { name: matches.length === 1 ? matches[0] : null, inline };-}--function powershellFilterArg(kind, args, i) {- if (!/^-[A-Za-z]/.test(args[i])) return null;- const { name, inline } = powershellParam(kind, args[i]);- if (!POWERSHELL_FILTER_PARAMS.has(name)) return null;- const first = inline ? i : i + 1;- if (first >= args.length) return { name, globs: [], end: i };- let end = first;- while (end + 1 < args.length && (args[end].endsWith(',') || args[end + 1].startsWith(','))) end += 1;- const parts = [inline || args[first]].concat(args.slice(first + 1, end + 1));- return { name, globs: splitTopLevelCommas(parts.join(',')), end };-}--function powershellSearchFilters(kind, args, filters) {- for (let i = 0; i < args.length; i++) {- const filter = powershellFilterArg(kind, args, i);- if (filter) {- if (filter.name === 'exclude') {- filters.exclusions.push(...filter.globs);- for (let k = i; k <= filter.end; k++) filters.dropped.add(k);- } else {- filter.globs.filter(isBasenameGlob).forEach(glob => filters.includes.push(glob));- }- i = filter.end;- } else if (/^-[A-Za-z]/.test(args[i]) && powershellParam(kind, args[i]).name === null) {- // An unresolvable parameter may be an exclusion in disguise: neither it nor a value it may carry is a stem source.- filters.dropped.add(i);- if (!args[i].includes(':') && i + 1 < args.length && !args[i + 1].startsWith('-')) filters.dropped.add(i + 1);- }- }- return filters;-}--/**- * A completed search in the current turn that names the target by stem (or by- * directory, for a new-file Write). Searches in the pending call's own batch- * never count: their results were not seen when the edit was decided.- */-function findCreditingSearch(scan, targetPath, allowDirMatch, data) {- try {- if (!scan || !Array.isArray(scan.searches) || scan.searches.length === 0) return null;- if (typeof targetPath !== 'string' || !targetPath) return null;- const ctx = dirContext(targetPath, data);- if (!ctx) return null;- const stem = stemMatcher(eligibleStem(targetPath));- const excluded = excludedBatchId(scan, data);- const shellDirsTrusted = !turnChangesDirectory(scan.shellCommands);- 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 (!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);- if (byStem || byDir) {- return { name: search.name, detail: item.detail, callsAgo: search.callsAgo };- }- }- }- return null;- } catch (_) {- return null;- }-}+const CREDIT_DETAIL_MAX_CHARS = 80;+const { findCreditingSearch } = createSearchEvidence({ quoteAwareSegments, commandBasename, SHELL_SEGMENT_SEPARATORS });function creditNote(match, filePath) {const chars = Array.from(sanitizePath(match.detail).replace(/\s+/g, ' '));diff --git a/scripts/lib/gateguard-search-evidence.js b/scripts/lib/gateguard-search-evidence.jsnew file mode 100644index 000000000..38ddec1d0--- /dev/null+++ b/scripts/lib/gateguard-search-evidence.js@@ -0,0 +1,855 @@+'use strict';++const fs = require('fs');+const path = require('path');+const { WINDOWS_PATH_PATTERN } = require('./gateguard-target-class');+const { excludedBatchId } = require('./gateguard-turn-scan');++// --- Prior-search credit ---+// `Read` never counts: Claude Code already requires a Read before an Edit, so+// crediting it would disable the Edit gate. Any ambiguity or failure means no credit.++const SHELL_SEARCH_COMMANDS = new Set([+ 'rg',+ 'grep',+ 'egrep',+ 'fgrep',+ 'git',+ 'find',+ 'fd',+ 'ls',+ 'tree',+ 'get-childitem',+ 'gci',+ 'select-string',+ 'sls'+]);+const GIT_SEARCH_SUBCOMMANDS = new Set(['grep', 'ls-files']);+const DIRECTORY_CHANGE_COMMANDS = new Set(['cd', 'pushd', 'popd', 'chdir', 'set-location', 'sl', 'push-location', 'pop-location']);+// Search kinds whose first positional argument is the pattern, not a path.+const PATTERN_FIRST_SEARCHES = new Set(['grep', 'egrep', 'fgrep', 'rg', 'git grep', 'select-string', 'sls', 'fd']);+const RECURSIVE_BY_DEFAULT = new Set(['rg', 'git grep', 'git ls-files', 'find', 'fd', 'tree']);+const GREP_FAMILY = new Set(['grep', 'egrep', 'fgrep']);+const POWERSHELL_SEARCHES = new Set(['get-childitem', 'gci', 'select-string', 'sls']);+// Flags whose value is the search pattern (so the first positional is a path).+const PATTERN_VALUE_FLAGS = new Set(['-e', '-f', '--regexp', '--file']);+// Flags that consume the next argument; that argument is never a path operand.+const VALUE_FLAGS = new Set([+ '-e', '-f', '-g', '-t', '-T', '-m', '-A', '-B', '-C',+ '--regexp', '--file', '--type', '--glob', '--iglob', '--include', '--exclude', '--exclude-dir', '--exclude-from',+ '--ignore-file', '--max-count', '--replace',+ '-name', '-iname', '-path', '-ipath', '-type', '-maxdepth', '-mindepth', '-newer', '-regex', '-size', '-user', '-group', '-perm'+]);+// PowerShell parameters are case-insensitive. -Path/-LiteralPath values are paths+// (they count as operands for the stdin/target-only checks) but never directory evidence.+const LS_VALUE_FLAGS = new Set(['-I', '--ignore', '--hide']);+const TREE_VALUE_FLAGS = new Set(['-L', '-P', '-I', '-o']);+// fd: `-E/--exclude <glob>` take a value (fd's `-e` is an extension, also a value).+const FD_VALUE_FLAGS = new Set([...VALUE_FLAGS, '-E']);+// Only these tools take the search pattern from -e/-f (fd's -e is an extension).+const PATTERN_FLAG_SEARCHES = new Set(['grep', 'egrep', 'fgrep', 'rg', 'git grep']);+const POWERSHELL_VALUE_FLAGS = new Set(['-path', '-literalpath', '-depth', '-pattern']);+const POWERSHELL_PATH_FLAGS = new Set(['-path', '-literalpath']);+// PowerShell binds a parameter by any unambiguous prefix, `-Name:value`, and comma lists across arguments.+const POWERSHELL_FILTER_PARAMS = new Set(['filter', 'include', 'exclude']);+const POWERSHELL_COMMON_PARAMS = [+ 'verbose', 'debug', 'erroraction', 'warningaction', 'informationaction', 'progressaction',+ 'errorvariable', 'warningvariable', 'informationvariable', 'outvariable', 'outbuffer', 'pipelinevariable'+];+const POWERSHELL_CHILDITEM_PARAMS = [+ 'path', 'literalpath', 'filter', 'include', 'exclude', 'recurse', 'depth', 'force', 'name',+ 'attributes', 'directory', 'file', 'hidden', 'readonly', 'system', 'followsymlink'+];+const POWERSHELL_SELECTSTRING_PARAMS = [+ 'pattern', 'path', 'literalpath', 'inputobject', 'simplematch', 'casesensitive', 'quiet', 'list', 'noemphasis',+ 'include', 'exclude', 'notmatch', 'allmatches', 'encoding', 'context', 'raw', 'culture'+];+const POWERSHELL_PARAM_ALIASES = new Set([+ 's', 'ad', 'd', 'af', 'ah', 'h', 'ar', 'as', 'lp', 'pspath',+ 'vb', 'db', 'ea', 'wa', 'infa', 'proga', 'ev', 'wv', 'iv', 'ov', 'ob', 'pv'+]);+const GENERIC_STEMS = new Set([+ 'index',+ 'main',+ 'init',+ '__init__',+ 'utils',+ 'util',+ 'types',+ 'readme',+ 'test',+ 'tests',+ 'config',+ 'mod',+ 'lib',+ 'setup',+ 'app',+ 'spec',+ 'helpers',+ 'common'+]);+const MIN_STEM_LENGTH = 4;+const MAX_SEARCH_COMMAND_CHARS = 8192;+// Command substitution, process substitution, heredocs and PowerShell+// backtick escapes make the searched text ambiguous: never credit them.+const AMBIGUOUS_SHELL_PATTERN = /`|\$\(|[<>]\(|<</;+const GLOB_CHARS_PATTERN = /[*?[{]/;++function eligibleStem(filePath) {+ const base = String(filePath).split(/[\\/]/).pop() || '';+ const ext = path.posix.extname(base);+ const stem = (ext ? base.slice(0, -ext.length) : base).toLowerCase();+ return stem.length >= MIN_STEM_LENGTH && !GENERIC_STEMS.has(stem) ? stem : null;+}++/** Word-boundary stem matcher; an indexOf scan, never a RegExp built from untrusted text. */+function stemMatcher(stem) {+ if (!stem) return null;+ return { test: text => containsWord(String(text), stem) };+}++function isStemWordChar(ch) {+ return ch !== undefined && ((ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9'));+}++function containsWord(text, word) {+ for (let at = text.indexOf(word); at !== -1; at = text.indexOf(word, at + 1)) {+ if (!isStemWordChar(text[at - 1]) && !isStemWordChar(text[at + word.length])) return true;+ }+ return false;+}++/** Path-resolution context for a target; relative paths resolve against the tool `cwd`. */+function dirContext(targetPath, data) {+ const base = (data && typeof data.cwd === 'string' && data.cwd) || process.env.CLAUDE_PROJECT_DIR || process.cwd();+ const isWin = WINDOWS_PATH_PATTERN.test(base) || WINDOWS_PATH_PATTERN.test(targetPath);+ const paths = isWin ? path.win32 : path.posix;+ if (!paths.isAbsolute(base)) return null;+ const resolveNative = (...parts) => paths.resolve(base, ...parts);+ const resolveDir = (...parts) => {+ const dir = resolveNative(...parts).replace(/\\/g, '/');+ return isWin ? dir.toLowerCase() : dir;+ };+ const targetKey = resolveDir(targetPath);+ return { resolveDir, resolveNative, targetKey, targetDir: path.posix.dirname(targetKey) };+}++function isInsideDir(targetKey, dirKey) {+ return targetKey.startsWith(dirKey.endsWith('/') ? dirKey : `${dirKey}/`);+}++function isDirectoryNow(nativePath) {+ try {+ return fs.statSync(nativePath).isDirectory();+ } catch (_) {+ return false;+ }+}++function globLiteralPrefix(pattern) {+ const segments = pattern.split(/[\\/]/);+ const firstGlob = segments.findIndex(segment => GLOB_CHARS_PATTERN.test(segment));+ const literal = firstGlob === -1 ? segments.slice(0, -1) : segments.slice(0, firstGlob);+ const joined = literal.join('/');+ return joined || (literal.length > 0 && pattern.startsWith('/') ? '/' : '');+}++function stringsOf(...values) {+ return values.filter(value => typeof value === 'string' && value);+}++/** Base for relative operands after a directory change; null unless it is a plain literal `cd <dir>`. */+function baseAfterDirectoryChange(base, lead, tokens) {+ if (!['cd', 'chdir', 'set-location', 'sl'].includes(lead) || tokens.length !== 2) return null;+ const dir = tokens[1];+ if (!dir || /^[-$~]/.test(dir) || GLOB_CHARS_PATTERN.test(dir)) return null;+ if (isAbsoluteShellPath(dir)) return [dir];+ return base === null ? null : base.concat(dir);+}++function isAbsoluteShellPath(arg) {+ return path.posix.isAbsolute(arg) || WINDOWS_PATH_PATTERN.test(arg);+}++function operandScopePath(arg) {+ if (!GLOB_CHARS_PATTERN.test(arg)) return arg;+ const segments = arg.split(/[\\/]/);+ const literal = segments.slice(0, segments.findIndex(segment => GLOB_CHARS_PATTERN.test(segment)));+ if (literal.length === 0) return '.';+ return literal.join('/') || '/';+}++/** Scopes a shell segment searched; unresolvable operands (variables, `~`, unknown cwd) scope nothing. */+function shellSearchScopes(parsed, base) {+ if (parsed.operands.length === 0) return base === null ? [] : [base];+ const scopes = [];+ for (const operand of parsed.operands) {+ if (!operand || operand === '-' || /^[$~]/.test(operand)) continue;+ const scoped = operandScopePath(operand);+ if (isAbsoluteShellPath(scoped)) scopes.push([scoped]);+ else if (base !== null) scopes.push(base.concat(scoped));+ }+ return scopes;+}++function isRecursiveFlag(kind, arg) {+ const lower = arg.toLowerCase();+ if (POWERSHELL_SEARCHES.has(kind)) return (kind === 'get-childitem' || kind === 'gci') && lower.startsWith('-rec');+ if (arg === '--recursive' || arg === '--dereference-recursive') return GREP_FAMILY.has(kind) || kind === 'ls';+ if (!/^-[a-zA-Z]+$/.test(arg)) return false;+ if (GREP_FAMILY.has(kind)) return /[rR]/.test(arg);+ return kind === 'ls' && arg.includes('R');+}++function valueFlagsFor(kind) {+ if (kind === 'ls' || kind === 'git ls-files') return LS_VALUE_FLAGS;+ if (kind === 'tree') return TREE_VALUE_FLAGS;+ if (kind === 'fd') return FD_VALUE_FLAGS;+ return VALUE_FLAGS;+}++/** Arguments a flag consumes; single-dash clusters (`-rne PAT`) are read letter by letter. */+function flagEffect(kind, args, i) {+ const arg = args[i];+ if (POWERSHELL_SEARCHES.has(kind)) {+ const lower = arg.toLowerCase();+ const filter = powershellFilterArg(kind, args, i);+ const consumes = filter ? filter.end - i : POWERSHELL_VALUE_FLAGS.has(lower) ? 1 : 0;+ return { consumes, patternFlag: lower === '-pattern', pathFlag: POWERSHELL_PATH_FLAGS.has(lower) };+ }+ const values = valueFlagsFor(kind);+ const takesValue = flag => values.has(flag) || (kind === 'rg' && (flag === '-r' || flag === '--replace'));+ const isPatternFlag = flag => PATTERN_FLAG_SEARCHES.has(kind) && PATTERN_VALUE_FLAGS.has(flag);+ const name = arg.split('=')[0];+ if (arg.startsWith('--') || kind === 'find' || takesValue(arg)) {+ return { consumes: !arg.includes('=') && takesValue(name) ? 1 : 0, patternFlag: isPatternFlag(name), pathFlag: false };+ }+ for (let i = 1; i < arg.length; i++) {+ const flag = `-${arg[i]}`;+ if (takesValue(flag)) return { consumes: i === arg.length - 1 ? 1 : 0, patternFlag: isPatternFlag(flag), pathFlag: false };+ }+ return { consumes: 0, patternFlag: false, pathFlag: false };+}++/** Path operands of a search command, skipping flag values and the pattern positional. */+function parseSearchArgs(kind, args) {+ const positionals = [];+ const pathValues = [];+ let recursive = RECURSIVE_BY_DEFAULT.has(kind);+ let patternGiven = false;+ let expressionStarted = false;+ let inputRedirect = false;+ for (let i = 0; i < args.length; i++) {+ const arg = args[i];+ if (/^\d*[<>]/.test(arg)) {+ inputRedirect = /^\d*</.test(arg);+ break;+ }+ if (arg.includes('<')) {+ inputRedirect = true; // a quoted `<` cannot be told from a redirection+ break;+ }+ if (arg.length > 1 && arg.startsWith('-')) {+ expressionStarted = true;+ if (isRecursiveFlag(kind, arg)) recursive = true;+ const effect = flagEffect(kind, args, i);+ if (effect.patternFlag) patternGiven = true;+ if (effect.pathFlag && i + 1 < args.length) pathValues.push(args[i + 1]);+ i += effect.consumes;+ continue;+ }+ if (kind === 'find' && (expressionStarted || arg === '(' || arg === '!')) {+ expressionStarted = true;+ continue;+ }+ positionals.push(arg);+ }+ const dirOperands = PATTERN_FIRST_SEARCHES.has(kind) && !patternGiven ? positionals.slice(1) : positionals;+ const operands = dirOperands.concat(pathValues);+ return { operands, dirOperands, recursive, stdin: inputRedirect && operands.length === 0 };+}++function shellDirCandidate(arg) {+ if (!arg || /^[$~]/.test(arg)) return '';+ const dir = arg.replace(/(?:[\\/]\*\*|[\\/]\*|[\\/])+$/, '');+ if (!dir || dir === '.' || GLOB_CHARS_PATTERN.test(dir)) return '';+ return dir;+}++function evidenceInScope(item, ctx) {+ if (item.scopes) {+ const covers = parts => {+ const scope = ctx.resolveDir(...parts);+ return scope === ctx.targetKey || isInsideDir(ctx.targetKey, scope);+ };+ if (!item.scopes.some(covers)) return false;+ }+ if (item.scope) {+ const scope = ctx.resolveDir(...item.scope);+ if (scope === ctx.targetKey || !isInsideDir(ctx.targetKey, scope)) return false;+ if (item.scopeExact && ctx.targetDir !== scope) return false;+ }+ if (item.operands && item.operands.length > 0 && item.operands.every(parts => ctx.resolveDir(...parts) === ctx.targetKey)) {+ return false; // reading the target itself is not a search+ }+ return true;+}++function evidenceNamesDir(item, ctx) {+ return item.dirs.some(+ parts => ctx.resolveDir(...parts) === ctx.targetDir && (!item.dirsMustExist || isDirectoryNow(ctx.resolveNative(...parts)))+ );+}++// --- Search filters ---+// A search that excluded the target never saw it, so exclusions are never a stem+// source and one covering the target blocks credit; unreadable exclusion lists+// block it too. Globs are matched without RegExp and bounded; past the bounds they cover the target.++const MAX_FILTER_GLOB_CHARS = 256;+const MAX_BRACE_ALTERNATIVES = 32;+const MAX_FILTERS_PER_SEARCH = 32;+const FIND_NAME_FLAGS = new Set(['-name', '-iname', '-path', '-ipath', '-wholename', '-iwholename', '-regex', '-iregex']);+const FIND_BASENAME_FLAGS = new Set(['-name', '-iname']);+const OPAQUE_FILTER_FLAGS = new Set(['--exclude-from', '--ignore-file', '--exclude-per-directory']);+const EXCLUDE_LONG_FLAGS = new Set(['--exclude', '--exclude-dir', '--ignore', '--hide']);+const LS_ONLY_EXCLUDE_FLAGS = new Set(['--ignore', '--hide']);+const GIT_EXCLUDE_PATHSPEC = /^:(?:[!^]|\([^)]*\bexclude\b[^)]*\))/;++function splitTopLevelCommas(value) {+ const parts = [];+ let depth = 0;+ let current = '';+ for (const ch of String(value)) {+ if (ch === '{') depth += 1;+ else if (ch === '}' && depth > 0) depth -= 1;+ if (ch === ',' && depth === 0) {+ parts.push(current);+ current = '';+ } else {+ current += ch;+ }+ }+ parts.push(current);+ return parts.map(part => part.trim()).filter(Boolean);+}++function expandBraces(glob) {+ const open = glob.indexOf('{');+ if (open === -1) return [glob];+ let depth = 0;+ for (let i = open; i < glob.length; i++) {+ if (glob[i] === '{') depth += 1;+ else if (glob[i] === '}' && --depth === 0) {+ const head = glob.slice(0, open);+ const tail = glob.slice(i + 1);+ const results = [];+ for (const option of splitTopLevelCommas(glob.slice(open + 1, i)).concat(glob[open + 1] === ',' ? [''] : [])) {+ const expanded = expandBraces(`${head}${option}${tail}`);+ if (!expanded) return null;+ results.push(...expanded);+ if (results.length > MAX_BRACE_ALTERNATIVES) return null;+ }+ return results;+ }+ }+ return [glob]; // unbalanced: `{` is literal+}++function globTokens(glob) {+ const tokens = [];+ for (let i = 0; i < glob.length; i++) {+ const ch = glob[i];+ if (ch === '*' && glob[i + 1] === '*') {+ const dirs = glob[i + 2] === '/';+ tokens.push({ type: dirs ? 'dirs' : 'deep' });+ i += dirs ? 2 : 1;+ } else if (ch === '*') {+ tokens.push({ type: 'star' });+ } else if (ch === '?') {+ tokens.push({ type: 'one' });+ } else if (ch === '[') {+ const parsed = bracketClass(glob, i);+ if (!parsed) return null;+ tokens.push(parsed.token);+ i = parsed.end;+ } else {+ tokens.push({ type: 'lit', ch });+ }+ }+ return tokens;+}++/** `[...]` with members, ranges, `!`/`^` negation and a leading literal `]`; null when unclosed. */+function bracketClass(glob, open) {+ let i = open + 1;+ const negated = glob[i] === '!' || glob[i] === '^';+ if (negated) i += 1;+ const ranges = [];+ for (let first = true; i < glob.length && (first || glob[i] !== ']'); first = false) {+ if (glob[i + 1] === '-' && i + 2 < glob.length && glob[i + 2] !== ']') {+ ranges.push([glob[i], glob[i + 2]]);+ i += 3;+ } else {+ ranges.push([glob[i], glob[i]]);+ i += 1;+ }+ }+ if (i >= glob.length) return null;+ return { token: { type: 'class', negated, ranges }, end: i };+}++function classMatches(token, ch) {+ if (ch === '/') return false;+ const forms = [ch, ch.toLowerCase(), ch.toUpperCase()];+ const member = token.ranges.some(([lo, hi]) => forms.some(form => form >= lo && form <= hi));+ return member !== token.negated;+}++/** Glob match by dynamic programming, so a hostile glob cannot cause regex backtracking; null when malformed. */+function wildcardMatch(glob, text) {+ const tokens = globTokens(glob);+ if (!tokens) return null;+ const n = text.length;+ let next = new Array(n + 1).fill(false);+ next[n] = true;+ for (let t = tokens.length - 1; t >= 0; t--) {+ const token = tokens[t];+ const row = new Array(n + 1).fill(false);+ let afterSlash = false; // for 'dirs': some k > j with text[k-1] === '/' and next[k]+ for (let j = n; j >= 0; j--) {+ if (token.type === 'lit') row[j] = j < n && text[j] === token.ch && next[j + 1];+ else if (token.type === 'one') row[j] = j < n && text[j] !== '/' && next[j + 1];+ else if (token.type === 'class') row[j] = j < n && classMatches(token, text[j]) && next[j + 1];+ else if (token.type === 'star') row[j] = next[j] || (j < n && text[j] !== '/' && row[j + 1]);+ else if (token.type === 'deep') row[j] = next[j] || (j < n && row[j + 1]);+ else {+ if (j < n && text[j] === '/' && next[j + 1]) afterSlash = true;+ row[j] = next[j] || afterSlash;+ }+ }+ next = row;+ }+ return next[0];+}++function normalizeFilterGlob(glob) {+ return String(glob).toLowerCase().replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/^\/+/, '').replace(/\/+$/, '');+}++/** Null when the glob is past the length or brace bounds; a malformed alternative counts as `malformed`. */+function globMatches(glob, text, malformed) {+ if (glob.length > MAX_FILTER_GLOB_CHARS) return null;+ const alternatives = expandBraces(glob);+ if (!alternatives) return null;+ return alternatives.some(alternative => {+ const matched = wildcardMatch(alternative, text);+ return matched === null ? malformed : matched;+ });+}++function targetSegments(ctx) {+ return ctx.targetKey.toLowerCase().split('/').filter(Boolean);+}++/** An exclusion covers the target when it names the stem or matches the file or any directory above it. */+function exclusionCoversTarget(exclusion, segments, stem) {+ const glob = normalizeFilterGlob(exclusion);+ if (!glob) return true;+ if (stem !== null && stem.test(glob)) return true;+ for (let start = 0; start < segments.length; start++) {+ for (let end = start + 1; end <= segments.length; end++) {+ const matched = globMatches(glob, segments.slice(start, end).join('/'), true);+ if (matched !== false) return true;+ }+ }+ return false;+}++function filtersAdmitTarget(item, ctx, stem) {+ if (item.opaque) return false;+ const exclusions = Array.isArray(item.exclusions) ? item.exclusions : [];+ if (exclusions.length === 0) return true;+ if (exclusions.length > MAX_FILTERS_PER_SEARCH) return false;+ const segments = targetSegments(ctx);+ return !exclusions.some(exclusion => exclusionCoversTarget(exclusion, segments, stem));+}++/** Basename include globs that all miss the target stop its stem from crediting; oversized globs admit, malformed ones do not. */+function includesAdmitTarget(item, ctx) {+ const includes = Array.isArray(item.includes) ? item.includes : [];+ if (includes.length === 0) return true;+ const segments = targetSegments(ctx);+ const base = segments[segments.length - 1] || '';+ return includes.some(include => globMatches(normalizeFilterGlob(include).replace(/^(?:\*\*\/)+/, ''), base, false) !== false);+}++function isBasenameGlob(glob) {+ return !/[\\/]/.test(String(glob).replace(/^(?:\*\*[\\/])+/, ''));+}++function grepToolFilters(glob) {+ const filters = { positives: [], includes: [], exclusions: [], opaque: false };+ if (typeof glob !== 'string' || !glob) return filters;+ for (const part of splitTopLevelCommas(glob)) {+ if (part.startsWith('!')) filters.exclusions.push(part.slice(1));+ else {+ filters.positives.push(part);+ if (isBasenameGlob(part)) filters.includes.push(part);+ }+ }+ return filters;+}++function shellSearchFilters(kind, args) {+ const filters = { exclusions: [], includes: [], opaque: false, dropped: new Set() };+ if (kind === 'find') return findSearchFilters(args, filters);+ if (POWERSHELL_SEARCHES.has(kind)) return powershellSearchFilters(kind, args, filters);+ for (let i = 0; i < args.length; i++) {+ const arg = args[i];+ if (/^\d*[<>]/.test(arg)) break;+ const consumed = applyShellFilterArg(kind, args, i, filters);+ i += consumed;+ }+ return filters;+}++function applyShellFilterArg(kind, args, i, filters) {+ const arg = args[i];+ const exclude = (value, indexes, separator) => {+ for (const glob of separator ? String(value).split(separator) : [value]) {+ if (glob) filters.exclusions.push(glob);+ }+ indexes.forEach(index => filters.dropped.add(index));+ };+ const include = value => {+ if (isBasenameGlob(value)) filters.includes.push(value);+ };+ if (kind.startsWith('git ') && GIT_EXCLUDE_PATHSPEC.test(arg)) {+ exclude(arg.replace(GIT_EXCLUDE_PATHSPEC, ''), [i]);+ return 0;+ }+ if (arg.startsWith('--')) {+ const eq = arg.indexOf('=');+ const name = eq > 0 ? arg.slice(0, eq) : arg;+ const hasNext = eq <= 0 && i + 1 < args.length;+ const value = eq > 0 ? arg.slice(eq + 1) : hasNext ? args[i + 1] : '';+ const indexes = eq > 0 || !hasNext ? [i] : [i, i + 1];+ const consumed = indexes.length - 1;+ if (OPAQUE_FILTER_FLAGS.has(name)) {+ filters.opaque = true;+ return consumed;+ }+ if (name === '--glob' || name === '--iglob') {+ if (value.startsWith('!')) exclude(value.slice(1), indexes);+ else include(value);+ return consumed;+ }+ if (name === '--include') {+ include(value);+ return consumed;+ }+ // `--ignore`/`--hide` hide names only for ls (rg's `--ignore` is a switch).+ if (EXCLUDE_LONG_FLAGS.has(name) && (kind === 'ls' || !LS_ONLY_EXCLUDE_FLAGS.has(name))) {+ exclude(value, indexes);+ return consumed;+ }+ return 0;+ }+ if (!/^-[A-Za-z]/.test(arg)) return 0;+ const letters = shortFilterLetters(kind);+ const valueFlags = valueFlagsFor(kind);+ for (let k = 1; k < arg.length; k++) {+ const letter = arg[k];+ if (!letters.has(letter)) {+ // Another value flag ends the cluster: the rest (or the next argument) is its value.+ if (valueFlags.has(`-${letter}`)) return k === arg.length - 1 ? 1 : 0;+ continue;+ }+ const attached = arg.slice(k + 1);+ const value = attached || args[i + 1] || '';+ const indexes = attached || i + 1 >= args.length ? [i] : [i, i + 1];+ const consumed = indexes.length - 1;+ applyShortFilter(kind, letter, value, indexes, { filters, exclude, include });+ return consumed;+ }+ return 0;+}++function shortFilterLetters(kind) {+ if (kind === 'rg') return new Set(['g']);+ if (kind === 'fd') return new Set(['E']);+ if (kind === 'ls') return new Set(['I']);+ if (kind === 'tree') return new Set(['I', 'P']);+ if (kind === 'git ls-files') return new Set(['x', 'X']);+ return new Set();+}++function applyShortFilter(kind, letter, value, indexes, { filters, exclude, include }) {+ if (kind === 'rg') {+ if (value.startsWith('!')) exclude(value.slice(1), indexes);+ else include(value);+ } else if (kind === 'tree' && letter === 'P') {+ value.split('|').forEach(include);+ } else if (kind === 'git ls-files' && letter === 'X') {+ filters.opaque = true;+ } else {+ exclude(value, indexes, kind === 'tree' ? '|' : '');+ }+}++/** find: a negated or pruned name test is an exclusion; a plain `-name`/`-iname` is an include. */+function findSearchFilters(args, filters) {+ let negateNext = false;+ let negatedDepth = 0;+ let depth = 0;+ for (let i = 0; i < args.length; i++) {+ const arg = args[i];+ if (/^\d*[<>]/.test(arg)) break;+ if (arg === '-not' || arg === '!') {+ negateNext = true;+ filters.dropped.add(i);+ continue;+ }+ if (arg === '(') {+ depth += 1;+ if (negateNext && negatedDepth === 0) negatedDepth = depth;+ negateNext = false;+ continue;+ }+ if (arg === ')') {+ if (negatedDepth === depth) negatedDepth = 0;+ depth = Math.max(depth - 1, 0);+ continue;+ }+ if (FIND_NAME_FLAGS.has(arg) && i + 1 < args.length) {+ const value = args[i + 1];+ if (negateNext || negatedDepth > 0 || args[i + 2] === '-prune') {+ filters.exclusions.push(value);+ filters.dropped.add(i);+ filters.dropped.add(i + 1);+ } else if (FIND_BASENAME_FLAGS.has(arg)) {+ filters.includes.push(value);+ }+ i += 1;+ }+ negateNext = false;+ }+ return filters;+}++function powershellParam(kind, arg) {+ const colon = arg.indexOf(':');+ const spelled = (colon === -1 ? arg.slice(1) : arg.slice(1, colon)).toLowerCase();+ const inline = colon === -1 ? null : arg.slice(colon + 1);+ const own = kind === 'get-childitem' || kind === 'gci' ? POWERSHELL_CHILDITEM_PARAMS : POWERSHELL_SELECTSTRING_PARAMS;+ const params = own.concat(POWERSHELL_COMMON_PARAMS);+ if (!spelled) return { name: null, inline };+ if (params.includes(spelled) || POWERSHELL_PARAM_ALIASES.has(spelled)) return { name: spelled, inline };+ const matches = params.filter(param => param.startsWith(spelled));+ return { name: matches.length === 1 ? matches[0] : null, inline };+}++function powershellFilterArg(kind, args, i) {+ if (!/^-[A-Za-z]/.test(args[i])) return null;+ const { name, inline } = powershellParam(kind, args[i]);+ if (!POWERSHELL_FILTER_PARAMS.has(name)) return null;+ const first = inline ? i : i + 1;+ if (first >= args.length) return { name, globs: [], end: i };+ let end = first;+ while (end + 1 < args.length && (args[end].endsWith(',') || args[end + 1].startsWith(','))) end += 1;+ const parts = [inline || args[first]].concat(args.slice(first + 1, end + 1));+ return { name, globs: splitTopLevelCommas(parts.join(',')), end };+}++function powershellSearchFilters(kind, args, filters) {+ for (let i = 0; i < args.length; i++) {+ const filter = powershellFilterArg(kind, args, i);+ if (filter) {+ if (filter.name === 'exclude') {+ filters.exclusions.push(...filter.globs);+ for (let k = i; k <= filter.end; k++) filters.dropped.add(k);+ } else {+ filter.globs.filter(isBasenameGlob).forEach(glob => filters.includes.push(glob));+ }+ i = filter.end;+ } else if (/^-[A-Za-z]/.test(args[i]) && powershellParam(kind, args[i]).name === null) {+ // An unresolvable parameter may be an exclusion in disguise: neither it nor a value it may carry is a stem source.+ filters.dropped.add(i);+ if (!args[i].includes(':') && i + 1 < args.length && !args[i + 1].startsWith('-')) filters.dropped.add(i + 1);+ }+ }+ return filters;+}++/** Build the prior-search matcher around the hook's shell segmenter. */+function createSearchEvidence({ quoteAwareSegments, commandBasename, SHELL_SEGMENT_SEPARATORS }) {+ /**+ * Evidence a search offers: stem `texts`, candidate `dirs`, the `scope`/`scopes`+ * the target must lie in, and `operands` that must not all be the target itself.+ */+ function searchEvidence(search, shellDirsTrusted) {+ const input = search.input;+ if (search.name === 'Glob') {+ if (typeof input.pattern !== 'string' || !input.pattern) return [];+ const explicit = typeof input.path === 'string' && input.path ? input.path : '';+ const prefix = globLiteralPrefix(input.pattern);+ const scope = [explicit || '.', prefix || '.'];+ if (!GLOB_CHARS_PATTERN.test(input.pattern)) {+ // A single-file lookup names no directory, and looking up the target itself is not a search.+ const lookup = [explicit || '.', input.pattern];+ return [{ texts: [input.pattern], dirs: [], scope, scopeExact: true, operands: [lookup], detail: input.pattern }];+ }+ // An empty literal prefix with no explicit path names only the implicit cwd.+ const dirs = prefix || explicit ? [scope] : [];+ return [{ texts: [input.pattern], dirs, scope, detail: input.pattern }];+ }+ if (search.name === 'Grep') {+ if (typeof input.pattern !== 'string' || !input.pattern) return [];+ const explicit = typeof input.path === 'string' && input.path ? input.path : '';+ const detail = typeof input.glob === 'string' && input.glob ? `${input.pattern} --glob ${input.glob}` : input.pattern;+ const filters = grepToolFilters(input.glob);+ return [{+ texts: stringsOf(input.pattern, ...filters.positives),+ dirs: explicit ? [[explicit]] : [],+ scope: [explicit || '.'],+ detail,+ ...filters+ }];+ }+ if (search.name === 'LS') {+ return stringsOf(input.path).map(dir => ({ texts: [], dirs: [[dir]], scope: [dir], detail: dir }));+ }+ return shellSearchEvidence(input.command, shellDirsTrusted);+ }++ /**+ * Per segment, whether it reads piped input. Mirrors `quoteAwareSegments`+ * splitting; `||` also marks the next segment, which only ever removes evidence.+ */+ function segmentPipeFlags(input) {+ const flags = [];+ let quote = null;+ let escaped = false;+ let hasContent = false;+ let piped = false;+ for (const ch of String(input || '')) {+ if (escaped) {+ escaped = false;+ } else if (ch === '\\') {+ escaped = true;+ hasContent = true;+ } else if (quote) {+ if (ch === quote) quote = null;+ } else if (ch === '"' || ch === "'") {+ quote = ch;+ hasContent = true;+ } else if (SHELL_SEGMENT_SEPARATORS.has(ch)) {+ if (hasContent) {+ flags.push(piped);+ piped = false;+ hasContent = false;+ }+ piped = piped || ch === '|';+ } else if (!/\s/.test(ch)) {+ hasContent = true;+ }+ }+ if (hasContent) flags.push(piped);+ return flags;+ }++ /** Evidence for each search segment of a shell command; ambiguous or oversized commands yield none. */+ function shellSearchEvidence(command, dirsTrusted) {+ if (typeof command !== 'string' || !command || command.length > MAX_SEARCH_COMMAND_CHARS) return [];+ if (AMBIGUOUS_SHELL_PATTERN.test(command)) return [];+ const pipeFlags = segmentPipeFlags(command);+ const evidence = [];+ let trusted = dirsTrusted;+ // A cd in any other call of the turn leaves the cwd of this one unknown.+ let base = dirsTrusted ? [] : null;+ quoteAwareSegments(command).forEach((tokens, index) => {+ const lead = commandBasename(tokens[0]);+ if (DIRECTORY_CHANGE_COMMANDS.has(lead)) {+ trusted = false;+ base = baseAfterDirectoryChange(base, lead, tokens);+ return;+ }+ if (!SHELL_SEARCH_COMMANDS.has(lead)) return;+ let kind = lead;+ let args = tokens.slice(1);+ if (lead === 'git') {+ if (!GIT_SEARCH_SUBCOMMANDS.has(tokens[1])) return;+ kind = `git ${tokens[1]}`;+ args = tokens.slice(2);+ }+ const parsed = parseSearchArgs(kind, args);+ // A segment that reads stdin (redirection, pipe, or no operand without recursion) is not a tree search.+ if (parsed.stdin) return;+ if (parsed.operands.length === 0 && (!parsed.recursive || pipeFlags[index] !== false)) return;+ const scopes = shellSearchScopes(parsed, base);+ if (scopes.length === 0) return;+ const filters = shellSearchFilters(kind, args);+ // Exclusion values (and the flags that introduce them) are never a stem source.+ const stemText = tokens.slice(0, tokens.length - args.length).concat(args.filter((_, i) => !filters.dropped.has(i))).join(' ');+ const dirs = trusted ? parsed.dirOperands.map(shellDirCandidate).filter(Boolean).map(dir => [dir]) : [];+ evidence.push({+ texts: [stemText],+ dirs,+ dirsMustExist: true,+ scopes,+ operands: parsed.operands.map(op => [op]),+ detail: tokens.join(' '),+ exclusions: filters.exclusions,+ includes: filters.includes,+ opaque: filters.opaque+ });+ });+ return evidence;+ }++ /** A directory change anywhere in the turn makes relative shell paths unreliable. */+ function turnChangesDirectory(shellCommands) {+ if (!Array.isArray(shellCommands)) return false;+ return shellCommands.some(command => {+ if (typeof command !== 'string') return false;+ if (command.length > MAX_SEARCH_COMMAND_CHARS) return true;+ return quoteAwareSegments(command).some(tokens => DIRECTORY_CHANGE_COMMANDS.has(commandBasename(tokens[0])));+ });+ }++ /**+ * A completed search in the current turn that names the target by stem (or by+ * directory, for a new-file Write). Searches in the pending call's own batch+ * never count: their results were not seen when the edit was decided.+ */+ function findCreditingSearch(scan, targetPath, allowDirMatch, data) {+ try {+ if (!scan || !Array.isArray(scan.searches) || scan.searches.length === 0) return null;+ if (typeof targetPath !== 'string' || !targetPath) return null;+ const ctx = dirContext(targetPath, data);+ if (!ctx) return null;+ const stem = stemMatcher(eligibleStem(targetPath));+ const excluded = excludedBatchId(scan, data);+ const shellDirsTrusted = !turnChangesDirectory(scan.shellCommands);+ 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 (!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);+ if (byStem || byDir) {+ return { name: search.name, detail: item.detail, callsAgo: search.callsAgo };+ }+ }+ }+ return null;+ } catch (_) {+ return null;+ }+ }++ return { findCreditingSearch };+}++module.exports = { createSearchEvidence };diff --git a/scripts/lib/gateguard-state.js b/scripts/lib/gateguard-state.jsnew file mode 100644index 000000000..65609f597--- /dev/null+++ b/scripts/lib/gateguard-state.js@@ -0,0 +1,134 @@+'use strict';++const { COLLAPSIBLE_CLASSES } = require('./gateguard-target-class');++/** A non-negative integer count from untrusted state; anything else is 0. */+function toCount(value) {+ const n = Number(value);+ return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;+}++function getDenialCount(state) {+ return toCount(state && state.fact_force_denials);+}++function getCreditedCount(state) {+ return toCount(state && state.fact_force_credited);+}++function getCapAllowCount(state) {+ return toCount(state && state.cap_allows);+}++// dir_gates maps `<class>\u0000<canonicalDir>` to { turn, at, first, ordinal }.+// The state file is untrusted, so every map is null-prototype and rejects prototype keys.++const MAX_DIR_GATES = 50;+const DIR_GATE_KEY_SEPARATOR = '\u0000';+const UNSAFE_MAP_KEYS = new Set(['__proto__', 'constructor', 'prototype']);++function isPlainObject(value) {+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);+}++function isSafeKey(key) {+ return typeof key === 'string' && key !== '' && !UNSAFE_MAP_KEYS.has(key);+}++function nullMap(entries) {+ const map = Object.create(null);+ for (const [key, value] of entries) map[key] = value;+ return map;+}++function withEntry(map, key, value) {+ return nullMap([...Object.entries(map), [key, value]]);+}++function getClassCounts(state, field) {+ const raw = state && state[field];+ if (!isPlainObject(raw)) return nullMap([]);+ const entries = Object.keys(raw)+ .filter(cls => isSafeKey(cls) && typeof raw[cls] === 'number' && toCount(raw[cls]) > 0)+ .map(cls => [cls, toCount(raw[cls])]);+ return nullMap(entries);+}++function mergeClassCounts(a, b) {+ const merged = nullMap(Object.entries(a));+ for (const [cls, n] of Object.entries(b)) {+ merged[cls] = Math.max(Object.hasOwn(merged, cls) ? merged[cls] : 0, n);+ }+ return merged;+}++function incrementClassCount(counts, cls) {+ if (!isSafeKey(cls)) return counts;+ return withEntry(counts, cls, (Object.hasOwn(counts, cls) ? counts[cls] : 0) + 1);+}++function getSiblingAllowCount(state) {+ return toCount(state && state.sibling_allows);+}++function dirGateKey(cls, dir) {+ return `${cls}${DIR_GATE_KEY_SEPARATOR}${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));+}++function isDirGateEntry(entry) {+ return (+ isPlainObject(entry) &&+ typeof entry.at === 'number' &&+ Number.isFinite(entry.at) &&+ typeof entry.first === 'string' &&+ (entry.turn === null || entry.turn === undefined || typeof entry.turn === 'string')+ );+}++function getDirGates(state) {+ const raw = state && state.dir_gates;+ if (!isPlainObject(raw)) return nullMap([]);+ const entries = Object.keys(raw)+ .filter(key => isDirGateKey(key) && isDirGateEntry(raw[key]))+ .map(key => {+ const entry = raw[key];+ return [key, { turn: entry.turn || null, at: entry.at, first: entry.first, ordinal: toCount(entry.ordinal) }];+ });+ return nullMap(entries);+}++/** Union by key; the newer `at` wins, so concurrent writers keep the latest gate. */+function mergeDirGates(older, newer) {+ const merged = nullMap(Object.entries(older));+ for (const [key, entry] of Object.entries(newer)) {+ if (!Object.hasOwn(merged, key) || entry.at >= merged[key].at) merged[key] = entry;+ }+ return merged;+}++function capDirGates(gates) {+ const entries = Object.entries(gates);+ if (entries.length <= MAX_DIR_GATES) return gates;+ return nullMap(entries.sort((a, b) => b[1].at - a[1].at).slice(0, MAX_DIR_GATES));+}++module.exports = {+ getDenialCount,+ getCreditedCount,+ getCapAllowCount,+ getSiblingAllowCount,+ getClassCounts,+ mergeClassCounts,+ incrementClassCount,+ withEntry,+ dirGateKey,+ getDirGates,+ mergeDirGates,+ capDirGates+};diff --git a/tests/hooks/gateguard-fact-force.test.js b/tests/hooks/gateguard-fact-force.test.jsindex dfd7daf82..9cd2945e5 100644--- a/tests/hooks/gateguard-fact-force.test.js+++ b/tests/hooks/gateguard-fact-force.test.js@@ -4862,35 +4862,6 @@ function runTests() {assert.strictEqual(c3State().fact_force_denials, 1);});- c3Case('scanCurrentTurn / findCreditingSearch units', () => {- const { scanCurrentTurn, findCreditingSearch } = loadDirectHook();- const human = c3Human('go');- const t = c3WriteTranscript(- [c3Human('old'), human, ...c3Search('toolu_u1', 'Glob', { pattern: '**/*.md' }), c3ToolUse('toolu_u2', 'Grep', { pattern: 'pending' })],- { pending: false }- );- const scan = scanCurrentTurn(t);- assert.strictEqual(scan.turnId, human.uuid, 'turnId is the boundary uuid');- assert.deepStrictEqual(scan.searches.map(s => [s.name, s.callsAgo]), [['Glob', 2]]);- assert.strictEqual(scanCurrentTurn(path.join(c3TranscriptDir, 'missing.jsonl')), null);- const data = { cwd: c3Root };- // A Glob with no literal prefix and no explicit path names no directory.- assert.strictEqual(findCreditingSearch(scan, `${c3Root}/new-notes.md`, true, data), null, 'Glob **/*.md gives no dir credit');- const docsScan = scanCurrentTurn(- c3WriteTranscript([c3Human('go'), ...c3Search('toolu_u3', 'Glob', { pattern: 'docs/*.md' }), c3ToolUse('toolu_u4', 'Grep', { pattern: 'x' })], {- pending: false- })- );- assert.ok(findCreditingSearch(docsScan, `${c3Root}/docs/new-notes.md`, true, data), 'Glob literal prefix names the dir');- assert.strictEqual(findCreditingSearch(docsScan, `${c3Root}/docs/sub/new-notes.md`, true, data), null, 'not a subdirectory');- assert.strictEqual(findCreditingSearch(scan, `${c3Root}/new-notes.md`, false, data), null, 'Edit needs a stem match');- assert.strictEqual(findCreditingSearch(null, `${c3Root}/x.md`, true, data), null);- const winScan = { turnId: null, searches: [{ name: 'LS', input: { path: 'C:\\Proj\\Src' }, callsAgo: 1, messageId: 'msg_w' }] };- assert.ok(findCreditingSearch(winScan, 'c:/proj/src/new_file.js', true, { cwd: 'C:\\proj' }), 'win32 dir match folds case');- const posixScan = { turnId: null, searches: [{ name: 'LS', input: { path: '/Proj/Src' }, callsAgo: 1, messageId: 'msg_p' }] };- assert.strictEqual(findCreditingSearch(posixScan, '/proj/src/new_file.js', true, { cwd: '/proj' }), null, 'posix is case-sensitive');- });-c3Case('50 MB transcript is scanned from the tail only (<= 256 KiB read)', () => {const big = path.join(c3TranscriptDir, 'big.jsonl');const bigSize = 50 * 1024 * 1024;diff --git a/tests/lib/gateguard-search-evidence.test.js b/tests/lib/gateguard-search-evidence.test.jsnew file mode 100644index 000000000..0d8c10832--- /dev/null+++ b/tests/lib/gateguard-search-evidence.test.js@@ -0,0 +1,95 @@+'use strict';+/**+ * Tests for scripts/lib/gateguard-search-evidence.js.+ *+ * Run with: node tests/lib/gateguard-search-evidence.test.js+ */++const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');++const hookPath = path.join(__dirname, '..', '..', 'scripts', 'hooks', 'gateguard-fact-force.js');+const { scanCurrentTurn } = require(path.join(__dirname, '..', '..', 'scripts', 'lib', 'gateguard-turn-scan.js'));++console.log('=== Testing gateguard-search-evidence.js ===\n');++let passed = 0;+let failed = 0;++function test(desc, fn) {+ try {+ fn();+ console.log(` ✓ ${desc}`);+ passed++;+ } catch (e) {+ console.log(` ✗ ${desc}: ${e.message}`);+ failed++;+ }+}++function loadHook() {+ const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gateguard-search-evidence-state-'));+ const savedStateDir = process.env.GATEGUARD_STATE_DIR;+ process.env.GATEGUARD_STATE_DIR = stateDir;+ try {+ return require(hookPath);+ } finally {+ if (savedStateDir === undefined) delete process.env.GATEGUARD_STATE_DIR;+ else process.env.GATEGUARD_STATE_DIR = savedStateDir;+ fs.rmSync(stateDir, { recursive: true, force: true });+ }+}++const root = '/proj-search';+const transcriptDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gateguard-search-evidence-'));+let seq = 0;+let uuidSeq = 0;+const nextUuid = () => `uuid-${++uuidSeq}`;+const human = text => ({ type: 'user', uuid: nextUuid(), message: { role: 'user', content: text } });+const toolUse = (id, name, input) => ({+ type: 'assistant',+ uuid: nextUuid(),+ message: { id: `msg_${id}`, role: 'assistant', content: [{ type: 'tool_use', id, name, input }] }+});+const toolResult = id => ({+ type: 'user',+ uuid: nextUuid(),+ message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, is_error: false, content: 'ok' }] }+});+const search = (id, name, input) => [toolUse(id, name, input), toolResult(id)];+const writeTranscript = records => {+ seq += 1;+ const file = path.join(transcriptDir, `t-${seq}.jsonl`);+ fs.writeFileSync(file, records.map(r => JSON.stringify(r)).join('\n') + '\n', 'utf8');+ return file;+};++test('credits by Glob literal-prefix directory and stem, folding case only for Windows paths', () => {+ const { findCreditingSearch } = loadHook();+ const boundary = human('go');+ const t = writeTranscript([human('old'), boundary, ...search('toolu_u1', 'Glob', { pattern: '**/*.md' }), toolUse('toolu_u2', 'Grep', { pattern: 'pending' })]);+ const scan = scanCurrentTurn(t);+ assert.strictEqual(scan.turnId, boundary.uuid, 'turnId is the boundary uuid');+ assert.deepStrictEqual(scan.searches.map(s => [s.name, s.callsAgo]), [['Glob', 2]]);+ assert.strictEqual(scanCurrentTurn(path.join(transcriptDir, 'missing.jsonl')), null);+ const data = { cwd: root };+ assert.strictEqual(findCreditingSearch(scan, `${root}/new-notes.md`, true, data), null, 'Glob **/*.md gives no dir credit');+ const docsScan = scanCurrentTurn(+ writeTranscript([human('go'), ...search('toolu_u3', 'Glob', { pattern: 'docs/*.md' }), toolUse('toolu_u4', 'Grep', { pattern: 'x' })])+ );+ assert.ok(findCreditingSearch(docsScan, `${root}/docs/new-notes.md`, true, data), 'Glob literal prefix names the dir');+ assert.strictEqual(findCreditingSearch(docsScan, `${root}/docs/sub/new-notes.md`, true, data), null, 'not a subdirectory');+ assert.strictEqual(findCreditingSearch(scan, `${root}/new-notes.md`, false, data), null, 'Edit needs a stem match');+ assert.strictEqual(findCreditingSearch(null, `${root}/x.md`, true, data), null);+ const winScan = { turnId: null, searches: [{ name: 'LS', input: { path: 'C:\\Proj\\Src' }, callsAgo: 1, messageId: 'msg_w' }] };+ assert.ok(findCreditingSearch(winScan, 'c:/proj/src/new_file.js', true, { cwd: 'C:\\proj' }), 'win32 dir match folds case');+ const posixScan = { turnId: null, searches: [{ name: 'LS', input: { path: '/Proj/Src' }, callsAgo: 1, messageId: 'msg_p' }] };+ assert.strictEqual(findCreditingSearch(posixScan, '/proj/src/new_file.js', true, { cwd: '/proj' }), null, 'posix is case-sensitive');+});++fs.rmSync(transcriptDir, { recursive: true, force: true });++console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+process.exit(failed > 0 ? 1 : 0);diff --git a/tests/lib/gateguard-state.test.js b/tests/lib/gateguard-state.test.jsnew file mode 100644index 000000000..bd8466cd5--- /dev/null+++ b/tests/lib/gateguard-state.test.js@@ -0,0 +1,77 @@+'use strict';+/**+ * Tests for scripts/lib/gateguard-state.js.+ *+ * Run with: node tests/lib/gateguard-state.test.js+ */++const assert = require('assert');+const path = require('path');++const {+ getDenialCount,+ getCapAllowCount,+ getClassCounts,+ mergeClassCounts,+ incrementClassCount,+ dirGateKey,+ getDirGates,+ mergeDirGates,+ capDirGates+} = require(path.join(__dirname, '..', '..', 'scripts', 'lib', 'gateguard-state.js'));++console.log('=== Testing gateguard-state.js ===\n');++let passed = 0;+let failed = 0;++function test(desc, fn) {+ try {+ fn();+ console.log(` ✓ ${desc}`);+ passed++;+ } catch (e) {+ console.log(` ✗ ${desc}: ${e.message}`);+ failed++;+ }+}++test('malformed or missing counters read as zero', () => {+ assert.strictEqual(getDenialCount(null), 0);+ assert.strictEqual(getDenialCount({ fact_force_denials: 'x' }), 0);+ assert.strictEqual(getDenialCount({ fact_force_denials: -3 }), 0);+ assert.strictEqual(getDenialCount({ fact_force_denials: 2.9 }), 2);+ assert.strictEqual(getCapAllowCount({ cap_allows: Infinity }), 0);+});++test('class counts reject prototype keys and non-numeric values', () => {+ const counts = getClassCounts(JSON.parse('{"denials_by_class":{"__proto__":5,"code":2,"test":"3","prose":0}}'), 'denials_by_class');+ assert.deepStrictEqual(Object.entries(counts), [['code', 2]]);+ assert.strictEqual(Object.getPrototypeOf(counts), null);+ assert.strictEqual(incrementClassCount(counts, 'constructor'), counts);+ assert.strictEqual(incrementClassCount(counts, 'code').code, 3);+ assert.strictEqual(mergeClassCounts(counts, { code: 1, test: 4 }).test, 4);+});++test('dir gates keep valid class-prefixed entries, newest wins on merge, capped at 50', () => {+ const key = dirGateKey('code', '/p/src');+ const gates = getDirGates({+ dir_gates: {+ [key]: { turn: 't1', at: 10, first: '/p/src/a.js', ordinal: 1 },+ '/p/old-shape': { turn: null, at: 10, first: '/p/old-shape/a.js', ordinal: 1 },+ [dirGateKey('config', '/p/cfg')]: { turn: null, at: 10, first: '/p/cfg/a.json', ordinal: 1 },+ [dirGateKey('test', '/p/bad')]: { at: 'soon', first: '/p/bad/a.js' }+ }+ });+ assert.deepStrictEqual(Object.keys(gates), [key]);+ const merged = mergeDirGates(gates, { [key]: { turn: 't2', at: 20, first: '/p/src/b.js', ordinal: 2 } });+ assert.strictEqual(merged[key].turn, 't2');+ const many = {};+ for (let i = 0; i < 60; i++) many[dirGateKey('code', `/p/d${i}`)] = { turn: null, at: i, first: `/p/d${i}/a.js`, ordinal: 1 };+ const capped = capDirGates(many);+ assert.strictEqual(Object.keys(capped).length, 50);+ assert.ok(!(dirGateKey('code', '/p/d0') in capped), 'oldest evicted');+});++console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+process.exit(failed > 0 ? 1 : 0);