evolcore 0.0.19 → 0.0.21

package/dist/core/permission/tool-policy.js

@@ -3,8 +3,8 @@ import path from 'path';
 import { randomUUID } from 'crypto';
 import { logger } from '../../utils/logger.js';
 import { resolveRoot } from '../../paths.js';
-import { containsHClassReference, containsLClassReference, checkProtectedPathAccess, getExistingHClassMaskTargets, hClassGrantIncludesProtectedPath, isHClassPath, isSameOrDescendant, isLClassPath, lClassGrantIncludesProtectedPath, resolveProtectedCandidate, resolveProtectedCandidateWithoutFinalSymlink, } from '../protected-paths.js';
-import { classifyEvolcoreShellCommand, parseCodexToolCommandArgv, parseBoundedOutputShellCommand, parseLiteralShellArgv, resolveCodexShellCarrierArgv, } from './ec-command-parser.js';
+import { containsHClassReference, containsLClassReference, checkProtectedPathAccess, getExistingHClassMaskTargets, hClassGrantIncludesProtectedPath, isHClassPath, isSameOrDescendant, isLClassPath, lClassGrantIncludesProtectedPath, resolveProtectedCandidate, resolveProtectedCandidateWithoutFinalSymlink, } from './protected-paths.js';
+import { classifyEvolcoreShellCommand, hasCodexCmdCarrierEcIntent, parseCodexToolCommandArgv, parseBoundedOutputShellCommand, parseLiteralShellArgv, resolveCodexShellCarrierArgv, resolveCodexShellCarrierString, } from './ec-command-parser.js';
 import { analyzeReadonlyShellQuery, } from './readonly-shell-query.js';
 /** Resolve the session-owned temporary root supplied by the execution host. */
 export function resolveManagedTempDir(env = process.env) {
@@ -412,6 +412,529 @@ function queryPathOperands(analysis) {
         accessKind: command.accessKind ?? (operand.access === 'recursive' ? 'enumerate' : 'content'),
     }))));
 }
+const PROTECTED_BASENAME_LITERAL_RE = /^(?:daemon\.json|defaults\.json|config\.json|contact\.json|contact-operations\.jsonl|\.device_id|\.env|\.lock|daemon\.pid)$/i;
+const SHELL_PATH_LITERAL_META_RE = /[\0\r\n$`*?\[\]{}<>|;&(),]/;
+/**
+ * Extract literal operands immediately following an unquoted shell
+ * redirection operator. The full command remains unproven, but a redirect
+ * target is an explicit filesystem write/read operand and must retain H/L
+ * protection. Quoted prose and command text are deliberately ignored.
+ */
+function literalShellRedirectOperands(command) {
+    const operands = [];
+    let quote = null;
+    let escaped = false;
+    let redirectPending = false;
+    let token = '';
+    const finishRedirect = () => {
+        if (redirectPending && token)
+            operands.push(token);
+        token = '';
+        redirectPending = false;
+    };
+    for (let index = 0; index < command.length; index++) {
+        const char = command[index];
+        if (escaped) {
+            if (redirectPending)
+                token += char;
+            escaped = false;
+            continue;
+        }
+        if (char === '\\') {
+            if (redirectPending)
+                token += char;
+            escaped = true;
+            continue;
+        }
+        if (quote === 'single') {
+            if (char === "'")
+                quote = null;
+            else if (redirectPending)
+                token += char;
+            continue;
+        }
+        if (quote === 'double') {
+            if (char === '"')
+                quote = null;
+            else if (redirectPending)
+                token += char;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char === "'" ? 'single' : 'double';
+            continue;
+        }
+        if (char === '>' || char === '<') {
+            // A preceding numeric token is an optional file descriptor, not part
+            // of the target. Repeated operators (`>>`) share one target.
+            token = '';
+            redirectPending = true;
+            if (command[index + 1] === char)
+                index++;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (redirectPending && token)
+                finishRedirect();
+            continue;
+        }
+        if (/[;&|()]/.test(char)) {
+            finishRedirect();
+            continue;
+        }
+        if (redirectPending)
+            token += char;
+    }
+    finishRedirect();
+    return operands;
+}
+function looksLikeLiteralShellPath(value) {
+    return !!value
+        && !value.startsWith('-')
+        && !/\s/.test(value)
+        && !SHELL_PATH_LITERAL_META_RE.test(value)
+        && (value === '.' || value === '..' || value.includes('/') || value.includes('\\') || PROTECTED_BASENAME_LITERAL_RE.test(value));
+}
+function protectedClassPath(value, className, options) {
+    if (!looksLikeLiteralShellPath(value))
+        return undefined;
+    const matched = className === 'h'
+        ? (containsHClassReference(value) || isHClassPath(value, options))
+        : (containsLClassReference(value) || isLClassPath(value, options));
+    return matched ? resolveProtectedCandidate(value, options.cwd) : undefined;
+}
+function literalSedOperands(args) {
+    const values = [];
+    let hasExplicitProgram = false;
+    let skippedPositionalProgram = false;
+    let optionsEnded = false;
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (!optionsEnded && argument === '--') {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && argument.startsWith('--')) {
+            if (argument === '--expression') {
+                hasExplicitProgram = true;
+                index++;
+                continue;
+            }
+            if (argument.startsWith('--expression=')) {
+                hasExplicitProgram = true;
+                continue;
+            }
+            if (argument === '--file') {
+                hasExplicitProgram = true;
+                if (args[index + 1])
+                    values.push(args[++index]);
+                continue;
+            }
+            if (argument.startsWith('--file=')) {
+                hasExplicitProgram = true;
+                values.push(argument.slice(argument.indexOf('=') + 1));
+                continue;
+            }
+            continue;
+        }
+        if (!optionsEnded && argument.startsWith('-') && argument !== '-') {
+            const body = argument.slice(1);
+            for (let cursor = 0; cursor < body.length; cursor++) {
+                const option = body[cursor];
+                if (option !== 'e' && option !== 'f')
+                    continue;
+                hasExplicitProgram = true;
+                const attached = body.slice(cursor + 1);
+                const value = attached || args[index + 1];
+                if (option === 'f' && value)
+                    values.push(value);
+                if (!attached && value)
+                    index++;
+                break;
+            }
+            continue;
+        }
+        if (!hasExplicitProgram && !skippedPositionalProgram) {
+            skippedPositionalProgram = true;
+            continue;
+        }
+        values.push(argument);
+    }
+    return values;
+}
+/**
+ * Recover paths from a small set of commands whose ordinary argv is a write
+ * target list. This is intentionally separate from grep/rg/git parsing: their
+ * first operands are patterns or revisions and must never be treated as
+ * filesystem paths merely because they contain a protected-looking string.
+ */
+function literalMutationOperands(argv) {
+    const executable = commandName(argv[0]);
+    const args = argv.slice(1);
+    if (['mkdir', 'mktemp', 'touch', 'tee', 'cp', 'mv', 'install', 'chmod', 'chown', 'ln', 'rm'].includes(executable)) {
+        return args.filter(argument => argument !== '--' && !argument.startsWith('-'));
+    }
+    if (executable === 'sed')
+        return literalSedOperands(args);
+    if (executable === 'git') {
+        return literalGitOperands(argv);
+    }
+    return [];
+}
+/**
+ * Recover Git operands that are unambiguously filesystem paths. Git has many
+ * positional revision/search arguments, so scanning every argv value would
+ * turn a pickaxe string into a protected-path access. Keep global path options,
+ * explicit pathspecs after `--`, and the small set of subcommands/options that
+ * name an output or working directory.
+ */
+function literalGitOperands(argv) {
+    const args = argv.slice(1);
+    const values = [];
+    const globalPathOptions = new Set(['-C', '--git-dir', '--work-tree', '--exec-path']);
+    const globalValueOptions = new Set(['-C', '--git-dir', '--work-tree', '--namespace', '--super-prefix']);
+    let index = 0;
+    let subcommand;
+    // Git global options precede the subcommand. Capture only options whose
+    // values are directories/files; skip the rest so config values are not
+    // mistaken for paths.
+    const pathConfigKey = (key) => /^(?:include(?:if\..+)?\.path|core\.(?:gitdir|worktree|excludesfile|attributesfile|hookspath))$/i.test(key);
+    while (index < args.length) {
+        const argument = args[index];
+        if (!argument.startsWith('-')) {
+            subcommand = argument.toLowerCase();
+            index++;
+            break;
+        }
+        const option = argument.split('=', 1)[0];
+        const shortAttached = !argument.startsWith('--') && argument.length > 2 && argument.startsWith('-C');
+        if (option === '-c') {
+            const config = argument.includes('=') ? argument.slice(argument.indexOf('=') + 1) : args[index + 1];
+            if (config) {
+                const separator = config.indexOf('=');
+                if (separator < 0 || pathConfigKey(config.slice(0, separator))) {
+                    values.push(separator < 0 ? config : config.slice(separator + 1));
+                }
+            }
+            index += argument.includes('=') ? 1 : 2;
+            continue;
+        }
+        if (option === '--config-env') {
+            const config = argument.includes('=') ? argument.slice(argument.indexOf('=') + 1) : args[index + 1];
+            const separator = config?.indexOf('=') ?? -1;
+            const key = separator >= 0 ? config.slice(0, separator) : '';
+            const envName = separator >= 0 ? config.slice(separator + 1) : undefined;
+            if (envName && pathConfigKey(key) && process.env[envName])
+                values.push(process.env[envName]);
+            index += argument.includes('=') ? 1 : 2;
+            continue;
+        }
+        const execPathWithValue = option === '--exec-path' && argument.includes('=');
+        if ((globalPathOptions.has(option) && option !== '--exec-path') || execPathWithValue || shortAttached) {
+            const value = argument.includes('=')
+                ? argument.slice(argument.indexOf('=') + 1)
+                : shortAttached
+                    ? argument.slice(2)
+                    : args[index + 1];
+            if (value)
+                values.push(value);
+        }
+        if (!argument.includes('=') && globalValueOptions.has(option) && !shortAttached)
+            index++;
+        index++;
+    }
+    if (!subcommand)
+        return values;
+    const rest = args.slice(index);
+    const delimiter = rest.indexOf('--');
+    const beforeDelimiter = delimiter >= 0 ? rest.slice(0, delimiter) : rest;
+    if (delimiter >= 0) {
+        values.push(...rest.slice(delimiter + 1).filter(argument => !argument.startsWith('-')));
+    }
+    const positionalValues = (argsToScan, valueOptions, attachedShortOptions = new Set()) => {
+        const positionals = [];
+        for (let cursor = 0; cursor < argsToScan.length; cursor++) {
+            const argument = argsToScan[cursor];
+            if (!argument.startsWith('-')) {
+                positionals.push(argument);
+                continue;
+            }
+            const option = argument.split('=', 1)[0];
+            const attached = [...attachedShortOptions].some(entry => argument.startsWith(entry) && argument.length > entry.length);
+            if (valueOptions.has(option) && !argument.includes('=') && !attached)
+                cursor++;
+        }
+        return positionals;
+    };
+    const outputSubcommands = new Set(['archive', 'diff', 'log', 'show', 'format-patch', 'range-diff', 'shortlog']);
+    if (outputSubcommands.has(subcommand)) {
+        for (let cursor = 0; cursor < beforeDelimiter.length; cursor++) {
+            const argument = beforeDelimiter[cursor];
+            const option = argument.split('=', 1)[0];
+            const shortOutput = argument === '-o' || (!argument.startsWith('--') && argument.startsWith('-o') && argument.length > 2);
+            const longOutput = option === '--output' || option === '--output-directory';
+            if (!shortOutput && !longOutput)
+                continue;
+            const value = argument.includes('=')
+                ? argument.slice(argument.indexOf('=') + 1)
+                : shortOutput && argument.length > 2
+                    ? argument.slice(2)
+                    : beforeDelimiter[cursor + 1];
+            if (value)
+                values.push(value);
+            if (!argument.includes('=') && !(shortOutput && argument.length > 2))
+                cursor++;
+        }
+    }
+    // These subcommands have positional filesystem targets rather than
+    // revision/search operands. Conservative over-collection here preserves
+    // H/L protection for source and destination paths alike.
+    const positionalPathSubcommands = new Set(['clone', 'init', 'apply', 'am']);
+    if (positionalPathSubcommands.has(subcommand)) {
+        values.push(...beforeDelimiter.filter(argument => !argument.startsWith('-')));
+    }
+    else if (subcommand === 'worktree' || subcommand === 'bundle') {
+        const control = subcommand === 'worktree'
+            ? new Set(['add', 'move', 'remove', 'prune', 'lock', 'unlock', 'repair'])
+            : new Set(['create', 'verify-heads', 'list-heads', 'unbundle']);
+        values.push(...beforeDelimiter.filter(argument => !argument.startsWith('-') && !control.has(argument)));
+    }
+    // `git diff --no-index` compares two filesystem paths without the usual
+    // revision/pathspec ambiguity. Capture both operands even when the caller
+    // omitted the `--` delimiter.
+    if (subcommand === 'diff' && beforeDelimiter.includes('--no-index')) {
+        values.push(...beforeDelimiter.filter(argument => !argument.startsWith('-')));
+    }
+    else if (subcommand === 'diff' && delimiter < 0) {
+        // Without `--`, a path can be parsed by Git in the same position as a
+        // revision. Keep likely filesystem-shaped positionals in the protection
+        // pass, while skipping regex/text option values.
+        const textValueOptions = new Set([
+            '-I', '--ignore-matching-lines', '--anchored', '--word-diff-regex',
+            '--diff-algorithm', '--submodule', '--stat-width', '--stat-name-width',
+            '--stat-graph-width', '--stat-count', '--inter-hunk-context',
+            '--output', '--output-directory',
+        ]);
+        values.push(...positionalValues(beforeDelimiter, textValueOptions, new Set(['-I']))
+            .filter(looksLikeLiteralShellPath));
+    }
+    else if (subcommand === 'log' && delimiter < 0) {
+        const textValueOptions = new Set([
+            '-S', '-G', '-n', '--grep', '--author', '--committer', '--since', '--after',
+            '--until', '--before', '--format', '--pretty', '--max-count', '--skip',
+            '--decorate-refs',
+        ]);
+        values.push(...positionalValues(beforeDelimiter, textValueOptions, new Set(['-S', '-G', '-n']))
+            .filter(looksLikeLiteralShellPath));
+    }
+    // Several mutating Git subcommands accept directory/file options instead
+    // of positional targets. Keep these values in the H/L operand pass so a
+    // protected path cannot hide behind an option spelling.
+    const optionPathValues = new Set([
+        '--directory', '--include', '--build-fake-ancestor', '--separate-git-dir',
+        '--template', '--reference', '--reference-if-able', '--git-dir', '--work-tree',
+    ]);
+    if (['clone', 'init', 'apply', 'am', 'format-patch'].includes(subcommand)) {
+        for (let cursor = 0; cursor < beforeDelimiter.length; cursor++) {
+            const argument = beforeDelimiter[cursor];
+            const option = argument.split('=', 1)[0];
+            if (!optionPathValues.has(option))
+                continue;
+            const value = argument.includes('=') ? argument.slice(argument.indexOf('=') + 1) : beforeDelimiter[cursor + 1];
+            if (value)
+                values.push(value);
+            if (!argument.includes('='))
+                cursor++;
+        }
+    }
+    return values;
+}
+function literalReadonlyOperands(argv) {
+    const executable = commandName(argv[0]);
+    const args = argv.slice(1);
+    if (['cat', 'ls', 'head', 'sort', 'wc', 'stat', 'lstat'].includes(executable)) {
+        const valueOptions = new Set(['-c', '--format', '--printf', '-I', '-T', '-w', '--block-size', '--color', '--format', '--hide', '--ignore', '--key', '--parallel', '--sort']);
+        const values = [];
+        for (let index = 0; index < args.length; index++) {
+            const argument = args[index];
+            if (argument === '--') {
+                values.push(...args.slice(index + 1));
+                break;
+            }
+            if (argument.startsWith('-')) {
+                const option = argument.split('=', 1)[0];
+                if (valueOptions.has(option) && !argument.includes('=') && index + 1 < args.length)
+                    index++;
+                continue;
+            }
+            values.push(argument);
+        }
+        return values;
+    }
+    if (['grep', 'rg'].includes(executable)) {
+        const values = [];
+        let patternSeen = false;
+        const textValueOptions = new Set(['-A', '-B', '-C', '-m', '-d', '-g', '--after-context', '--before-context', '--context', '--directories', '--exclude', '--exclude-dir', '--include', '--glob', '--pre-glob']);
+        const patternOptions = new Set(['-e', '--regexp']);
+        const pathValueOptions = new Set(['-f', '--file', '--ignore-file', '--exclude-from', '--pre', '--hostname-bin']);
+        const shortTextValueOptions = executable === 'grep'
+            ? new Set(['A', 'B', 'C', 'd', 'D', 'm'])
+            : new Set(['A', 'B', 'C', 'E', 'g', 'j', 'm', 'M', 'r', 't', 'T']);
+        for (let index = 0; index < args.length; index++) {
+            const argument = args[index];
+            if (argument === '--') {
+                values.push(...args.slice(index + 1));
+                break;
+            }
+            if (argument.startsWith('-')) {
+                if (!argument.startsWith('--') && argument !== '-') {
+                    const body = argument.slice(1);
+                    let consumedValue = false;
+                    for (let cursor = 0; cursor < body.length; cursor++) {
+                        const option = body[cursor];
+                        if (option !== 'e' && option !== 'f' && !shortTextValueOptions.has(option))
+                            continue;
+                        const attached = body.slice(cursor + 1);
+                        const value = attached || args[index + 1];
+                        if (option === 'e')
+                            patternSeen = true;
+                        if (option === 'f') {
+                            patternSeen = true;
+                            if (value)
+                                values.push(value);
+                        }
+                        if (!attached && value)
+                            index++;
+                        consumedValue = true;
+                        break;
+                    }
+                    if (consumedValue)
+                        continue;
+                }
+                const option = argument.split('=', 1)[0];
+                if (patternOptions.has(option)) {
+                    patternSeen = true;
+                    if (!argument.includes('=') && index + 1 < args.length)
+                        index++;
+                    continue;
+                }
+                if (pathValueOptions.has(option)) {
+                    patternSeen ||= option === '-f' || option === '--file';
+                    const value = argument.includes('=') ? argument.slice(argument.indexOf('=') + 1) : args[++index];
+                    if (value)
+                        values.push(value);
+                    continue;
+                }
+                if (textValueOptions.has(option) && !argument.includes('=') && index + 1 < args.length)
+                    index++;
+                continue;
+            }
+            if (!patternSeen)
+                patternSeen = true;
+            else
+                values.push(argument);
+        }
+        return values;
+    }
+    if (executable === 'find') {
+        const values = [];
+        for (const argument of args) {
+            if (argument === '--' || argument.startsWith('-') || ['!', '(', ')'].includes(argument))
+                break;
+            values.push(argument);
+        }
+        return values;
+    }
+    if (executable === 'sed')
+        return literalSedOperands(args);
+    return [];
+}
+/** Extract literal path strings from an explicit node/python-style eval only
+ * when the script calls a filesystem API. The script itself is not a shell
+ * path operand; this narrow check preserves H/L protection for common
+ * `node -e fs.writeFileSync/readFileSync('...')` carriers without scanning
+ * prose or arbitrary string arguments. */
+function literalScriptFilesystemOperands(argv) {
+    const executable = commandName(argv[0]);
+    if (!['node', 'nodejs', 'python', 'python3', 'perl'].includes(executable))
+        return [];
+    const args = argv.slice(1);
+    const evalIndex = args.findIndex(argument => argument === '-e' || argument === '--eval' || argument === '-c');
+    const script = evalIndex >= 0 ? args[evalIndex + 1] : undefined;
+    if (!script || !/(?:writeFile|appendFile|truncate|unlink|rename|mkdir|rmdir|chmod|chown|symlink|link|copyFile|createWriteStream|readFile|readdir|realpath|lstat|stat|open\s*\()/.test(script)) {
+        return [];
+    }
+    const values = [];
+    const literalRe = /(['"])([^'"\\\r\n]+)\1/g;
+    for (const match of script.matchAll(literalRe)) {
+        if (match[2])
+            values.push(match[2]);
+    }
+    return values;
+}
+/**
+ * Recover only literal path-looking argv values when the structured readonly
+ * query parser cannot prove the complete command.  This is deliberately not a
+ * raw-text search: regexps, log prose, comments and shell syntax are ignored.
+ * The normal readonly path still fails closed for an unproven command; this
+ * helper exists only so a non-readonly H/L check can retain protection for an
+ * explicit literal path in an otherwise unsupported command.
+ */
+function literalProtectedShellOperand(command, className, options, depth = 0) {
+    for (const segment of splitShellCommandSegments(command)) {
+        for (const value of literalShellRedirectOperands(segment)) {
+            const matched = protectedClassPath(value, className, options);
+            if (matched)
+                return matched;
+        }
+        // A segment that is itself a proven readonly query already has precise
+        // path operands. Reusing that IR avoids treating patterns/revisions as
+        // paths and also lets a valid segment coexist with a protected one.
+        const segmentAnalysis = analyzeReadonlyShellQuery(segment);
+        if (segmentAnalysis.kind === 'proven-readonly') {
+            for (const operand of queryPathOperands(segmentAnalysis)) {
+                const matched = protectedClassPath(operand.operand.value, className, options);
+                if (matched)
+                    return matched;
+            }
+            continue;
+        }
+        const argv = parseLiteralShellArgv(segment);
+        if (!argv || argv.length < 2)
+            continue;
+        for (const value of literalMutationOperands(argv)) {
+            const matched = protectedClassPath(value, className, options);
+            if (matched)
+                return matched;
+        }
+        for (const value of literalReadonlyOperands(argv)) {
+            const matched = protectedClassPath(value, className, options);
+            if (matched)
+                return matched;
+        }
+        for (const value of literalScriptFilesystemOperands(argv)) {
+            const matched = protectedClassPath(value, className, options);
+            if (matched)
+                return matched;
+        }
+        // Explicit nested shell carriers are parsed recursively. A nested query
+        // still goes through the same segment-aware rules; arbitrary unsupported
+        // shell composition remains unproven and is never authorized here.
+        if (depth < 2) {
+            const executable = path.posix.basename(argv[0].replace(/\\/g, '/'));
+            if (['bash', 'sh', 'dash', 'zsh'].includes(executable)) {
+                const commandIndex = argv.findIndex(value => value === '-c' || value === '-lc');
+                const nested = commandIndex >= 0 ? argv[commandIndex + 1] : undefined;
+                if (nested) {
+                    const matched = literalProtectedShellOperand(nested, className, options, depth + 1);
+                    if (matched)
+                        return matched;
+                }
+            }
+        }
+    }
+    return undefined;
+}
 function shellOperandMatchesClass(operand, className, options, accessKind = operand.access === 'recursive' ? 'enumerate' : 'content') {
     // `$TMPDIR` is a private session namespace, so names such as `CA` or
     // `config.json` inside it are ordinary temporary data rather than paths in
@@ -425,7 +948,7 @@ function shellOperandMatchesClass(operand, className, options, accessKind = oper
         const workspace = options.cwd ? resolveProtectedCandidate(options.cwd) : undefined;
         if (isSameOrDescendant(candidate, managedTemp)
             && (!workspace || !isSameOrDescendant(candidate, workspace))) {
-            return false;
+            return undefined;
         }
     }
     if (className === 'h' && accessKind === 'metadata' && operand.access === 'exact') {
@@ -439,27 +962,31 @@ function shellOperandMatchesClass(operand, className, options, accessKind = oper
             followFinalSymlink: false,
         });
         if (options.allowProtectedMetadata === false) {
-            return metadata.pathClass === 'h-file' || metadata.pathClass === 'h-directory';
+            return metadata.pathClass === 'h-file' || metadata.pathClass === 'h-directory'
+                ? resolveProtectedCandidate(operand.value, options.cwd)
+                : undefined;
         }
         // The no-follow decision is authoritative for metadata. In particular,
         // an ordinary symlink whose target is H-class must remain inspectable as a
         // link; falling through to isHClassPath() would follow it and reject the
         // otherwise safe lstat/stat operation.
         if (metadata.pathClass !== 'unknown' && metadata.allowed) {
-            return false;
+            return undefined;
         }
     }
     const reference = className === 'h' ? containsHClassReference(operand.value) : containsLClassReference(operand.value);
     if (reference)
-        return true;
+        return resolveProtectedCandidate(operand.value, options.cwd);
     if (operand.access === 'recursive') {
-        return className === 'h'
+        const matched = className === 'h'
             ? hClassReadScopeIncludesProtectedPath(operand.value, options)
             : lClassGrantIncludesProtectedPath(operand.value, options);
+        return matched ? resolveProtectedCandidate(operand.value, options.cwd) : undefined;
     }
-    return className === 'h'
+    const matched = className === 'h'
         ? isHClassPath(operand.value, options)
         : isLClassPath(operand.value, options);
+    return matched ? resolveProtectedCandidate(operand.value, options.cwd) : undefined;
 }
 /**
  * A read-only recursive query only needs to cover H-class targets that exist
@@ -480,25 +1007,55 @@ function hClassReadScopeIncludesProtectedPath(value, options) {
 function analyzeShellProtectedOperands(command, options) {
     const analysis = analyzeReadonlyShellQuery(command, { managedTempDir: options.managedTempDir });
     if (analysis.kind === 'unproven') {
+        const pathOptions = { cwd: options.cwd, root: options.root };
+        const hClassPath = literalProtectedShellOperand(command, 'h', pathOptions);
+        const lClassPath = literalProtectedShellOperand(command, 'l', pathOptions);
         return {
             analysis,
-            hClass: containsHClassReference(command),
-            lClass: containsLClassReference(command),
-            pathHClass: false,
+            hClass: !!hClassPath,
+            lClass: !!lClassPath,
+            pathHClass: !!hClassPath,
             lockDiagnostic: false,
+            hClassPath,
+            lClassPath,
         };
     }
     const operands = queryPathOperands(analysis);
-    const lockDiagnostic = /(?:^|[\/\s'"`])(?:[^\s'"`/]*\.lock|EVOLCORE_RUNTIME_LOCK_DIR)(?=$|[\/\s'"`=])/i.test(command);
-    const pathHClass = operands.some(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'h', options, accessKind));
+    // Only parsed path operands can establish a lock-file diagnostic. Searching
+    // the raw command would mistake a grep/rg pattern or report text for an
+    // actual protected filesystem target.
+    const lockDiagnostic = operands.some(({ operand }) => containsLockPathReference(operand.value))
+        || hasFindLockPattern(analysis);
+    const hClassPath = operands.map(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'h', options, accessKind)).find(Boolean);
+    const lClassPath = operands.map(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'l', options, accessKind)).find(Boolean);
     return {
         analysis,
-        hClass: lockDiagnostic || pathHClass,
-        lClass: operands.some(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'l', options, accessKind)),
-        pathHClass,
+        hClass: lockDiagnostic || !!hClassPath,
+        lClass: !!lClassPath,
+        pathHClass: !!hClassPath,
         lockDiagnostic,
+        hClassPath,
+        lClassPath,
     };
 }
+/** Detect a find pattern such as `-name '*.lock'` from parsed argv only. */
+function hasFindLockPattern(analysis) {
+    if (analysis.kind !== 'proven-readonly')
+        return false;
+    return analysis.ir.pipelines.some(pipeline => pipeline.some(command => {
+        if (command.executable !== 'find')
+            return false;
+        for (let index = 0; index < command.argv.length - 1; index++) {
+            if (!['-name', '-iname', '-path', '-ipath', '-wholename'].includes(command.argv[index]))
+                continue;
+            if (/(?:^|[\\/])[^\\/]*\.lock(?:$|[\\/])/i.test(command.argv[index + 1]))
+                return true;
+            if (/^EVOLCORE_RUNTIME_LOCK_DIR$/i.test(command.argv[index + 1]))
+                return true;
+        }
+        return false;
+    }));
+}
 function protectedReadToolPaths(toolName, input) {
     if (toolName === 'Read') {
         return typeof input.file_path === 'string' ? [input.file_path] : [];
@@ -513,33 +1070,43 @@ function protectedReadToolPaths(toolName, input) {
 }
 function protectedReadToolMatchesLClass(toolName, input, options) {
     const paths = protectedReadToolPaths(toolName, input);
-    if (paths.some(filePath => containsLClassReference(filePath) || isLClassPath(filePath, options))) {
-        return true;
+    const direct = paths.find(filePath => containsLClassReference(filePath) || isLClassPath(filePath, options));
+    if (direct) {
+        return resolveProtectedCandidate(direct, options.cwd);
     }
     if (toolName === 'Grep') {
         const scope = typeof input.path === 'string' && input.path ? input.path : '.';
-        return lClassGrantIncludesProtectedPath(scope, options);
+        return lClassGrantIncludesProtectedPath(scope, options)
+            ? resolveProtectedCandidate(scope, options.cwd)
+            : undefined;
     }
     if (toolName === 'Glob') {
         const scope = globReadScope(input, options);
-        return lClassGrantIncludesProtectedPath(scope, { root: options.root });
+        return lClassGrantIncludesProtectedPath(scope, { root: options.root })
+            ? resolveProtectedCandidate(scope, options.cwd)
+            : undefined;
     }
-    return false;
+    return undefined;
 }
 function protectedReadToolMatchesHClass(toolName, input, options) {
     const paths = protectedReadToolPaths(toolName, input);
-    if (paths.some(filePath => containsHClassReference(filePath) || isHClassPath(filePath, options))) {
-        return true;
+    const direct = paths.find(filePath => containsHClassReference(filePath) || isHClassPath(filePath, options));
+    if (direct) {
+        return resolveProtectedCandidate(direct, options.cwd);
     }
     if (toolName === 'Grep') {
         const scope = typeof input.path === 'string' && input.path ? input.path : '.';
-        return hClassReadScopeIncludesProtectedPath(scope, options);
+        return hClassReadScopeIncludesProtectedPath(scope, options)
+            ? resolveProtectedCandidate(scope, options.cwd)
+            : undefined;
     }
     if (toolName === 'Glob') {
         const scope = globReadScope(input, options);
-        return hClassReadScopeIncludesProtectedPath(scope, options);
+        return hClassReadScopeIncludesProtectedPath(scope, options)
+            ? resolveProtectedCandidate(scope, options.cwd)
+            : undefined;
     }
-    return false;
+    return undefined;
 }
 function globLiteralPrefix(pattern) {
     const normalized = pattern.replace(/\\/g, '/');
@@ -646,14 +1213,17 @@ export function checkReadonly(toolName, input, projectPath, context) {
         if (!protectedReadToolStaysInWorkspace(toolName, input, projectPath)) {
             return { behavior: 'deny', message: '🔒 只读模式：文件读取范围不能越出当前项目目录', policyCode: 'readonly_workspace_escape' };
         }
-        if (paths.some(filePath => containsHClassReference(filePath) || isHClassPath(filePath, pathOptions))) {
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
+        const directHPath = paths.find(filePath => containsHClassReference(filePath) || isHClassPath(filePath, pathOptions));
+        if (directHPath) {
+            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read', matchedPath: resolveProtectedCandidate(directHPath, projectPath) };
         }
-        if (protectedReadToolMatchesHClass(toolName, input, pathOptions)) {
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
+        const hPath = protectedReadToolMatchesHClass(toolName, input, pathOptions);
+        if (hPath) {
+            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read', matchedPath: hPath };
         }
-        if (protectedReadToolMatchesLClass(toolName, input, pathOptions)) {
-            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read' };
+        const lPath = protectedReadToolMatchesLClass(toolName, input, pathOptions);
+        if (lPath) {
+            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read', matchedPath: lPath };
         }
         return { behavior: 'allow' };
     }
@@ -691,11 +1261,15 @@ export function checkReadonly(toolName, input, projectPath, context) {
         }
         if (protectedOperands.hClass) {
             logger.warn(`[ReadonlyCheck] 🔒 H-class path blocked in readonly shell: cmd="${cmd}" session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
+            if (protectedOperands.analysis.kind === 'proven-readonly') {
+                return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read', matchedPath: protectedOperands.hClassPath };
+            }
         }
         if (protectedOperands.lClass) {
             logger.warn(`[ReadonlyCheck] 🔒 L-class path blocked in readonly shell: cmd="${cmd}" session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read' };
+            if (protectedOperands.analysis.kind === 'proven-readonly') {
+                return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read', matchedPath: protectedOperands.lClassPath };
+            }
         }
         if (protectedOperands.analysis.kind === 'proven-readonly') {
             return { behavior: 'deny', message: '🔒 只读模式：Shell 查询范围不能越出当前项目目录', policyCode: 'readonly_workspace_escape' };
@@ -967,6 +1541,7 @@ export function checkHClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 临时文件必须位于当前会话的 $TMPDIR 内',
+                matchedPath: tempCheck.paths[0],
             };
         }
         // A managed temp write is intentionally allowed to contain names such as
@@ -992,6 +1567,7 @@ export function checkHClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 Shell 命令涉及受保护的 H 类配置/证书/快照路径，agent 不可直接操作',
+                matchedPath: protectedOperands.hClassPath,
             };
         }
         collectFilesystemGrantPaths(input.additionalPermissions, grantPaths, projectRootGrantSubpaths);
@@ -1010,14 +1586,17 @@ export function checkHClassWrite(toolName, input, context) {
     // filesystem operation is checked again when it reaches Read/Write/Bash,
     // FileChange, or PermissionGrant above.
     const pathOptions = { cwd: context?.projectPath, root: context?.root };
-    if (['Read', 'Glob', 'Grep'].includes(toolName)
-        && protectedReadToolMatchesHClass(toolName, input, pathOptions)) {
-        logger.warn(`[H-Class Protection] 🔒 Protected filesystem read scope blocked: tool=${toolName} ` +
-            `session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-        return {
-            behavior: 'deny',
-            message: '🔒 文件读取范围包含受保护的 H 类配置/证书/快照路径，agent 不可直接操作',
-        };
+    if (['Read', 'Glob', 'Grep'].includes(toolName)) {
+        const matchedReadPath = protectedReadToolMatchesHClass(toolName, input, pathOptions);
+        if (matchedReadPath) {
+            logger.warn(`[H-Class Protection] 🔒 Protected filesystem read scope blocked: tool=${toolName} ` +
+                `session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
+            return {
+                behavior: 'deny',
+                message: '🔒 文件读取范围包含受保护的 H 类配置/证书/快照路径，agent 不可直接操作',
+                matchedPath: matchedReadPath,
+            };
+        }
     }
     if (requestsFilesystemRoot(input.permissions) || requestsFilesystemRoot(input.additionalPermissions)) {
         logger.warn(`[H-Class Protection] 🔒 Permission grant covers filesystem root: tool=${toolName} ` +
@@ -1036,6 +1615,7 @@ export function checkHClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 请求的文件系统权限范围包含受保护的 H 类路径，已拒绝授权',
+                matchedPath: resolveProtectedCandidate(grantPath, pathOptions.cwd),
             };
         }
     }
@@ -1059,6 +1639,7 @@ export function checkHClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 请求的 project_roots 权限范围包含受保护的 H 类路径，已拒绝授权',
+                matchedPath: resolveProtectedCandidate(candidate, permissionWorkspace),
             };
         }
     }
@@ -1093,7 +1674,8 @@ export function checkHClassWrite(toolName, input, context) {
                 behavior: 'deny',
                 message: `🔒 此文件受保护，agent 不可直接写入\n\n` +
                     `文件：${filePath}\n` +
-                    `类型：配置/快照/证书等系统关键文件${suggestion}`
+                    `类型：配置/快照/证书等系统关键文件${suggestion}`,
+                matchedPath: resolveProtectedCandidate(filePath, pathOptions.cwd),
             };
         }
     }
@@ -1108,7 +1690,7 @@ export function checkLClassWrite(toolName, input, context) {
         const pathOptions = { cwd: context?.projectPath, root: context?.root };
         const lClassRead = protectedReadToolMatchesLClass(toolName, input, pathOptions);
         if (lClassRead && context?.permissionMode === 'readonly') {
-            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径' };
+            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', matchedPath: lClassRead };
         }
         return { behavior: 'allow' };
     }
@@ -1149,6 +1731,7 @@ export function checkLClassWrite(toolName, input, context) {
                 message: context?.permissionMode === 'readonly'
                     ? '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径'
                     : '🔒 L-class 路径允许读取，但当前 Bash 复合命令无法证明为只读，已拒绝执行。请改用受控的 EvolCore 读取命令或白名单只读命令',
+                matchedPath: protectedOperands.lClassPath,
             };
         }
         collectFilesystemWriteGrantPaths(input.additionalPermissions, writeGrantPaths, projectRootWriteSubpaths);
@@ -1167,6 +1750,7 @@ export function checkLClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 请求的文件系统写权限包含 L-class 只读路径，已拒绝授权',
+                matchedPath: resolveProtectedCandidate(grantPath, pathOptions.cwd),
             };
         }
     }
@@ -1188,6 +1772,7 @@ export function checkLClassWrite(toolName, input, context) {
         return {
             behavior: 'deny',
             message: `🔒 L-class 路径允许读取但禁止 Agent 直接修改、删除或移动\n\n文件：${filePath}\n\n💡 请使用对应的 EvolCore 受控命令修改`,
+            matchedPath: resolveProtectedCandidate(filePath, pathOptions.cwd),
         };
     }
     return { behavior: 'allow' };
@@ -1338,7 +1923,25 @@ function prepareBoundedOutputInput(input, command, kind, context) {
 export function evaluateToolPreflight(toolName, input, context) {
     if (toolName === 'Bash') {
         const command = typeof input.command === 'string' ? input.command : '';
-        const tempCheck = checkManagedTempShellCommand(command, managedTempOptions(context));
+        const explicitCommandArgv = Array.isArray(input.commandArgv)
+            && input.commandArgv.every(value => typeof value === 'string')
+            ? input.commandArgv
+            : undefined;
+        if (Array.isArray(input.commandArgv) && !explicitCommandArgv) {
+            return {
+                behavior: 'deny',
+                input,
+                message: '🔒 Codex commandArgv 必须是完整的字符串 argv，无法安全解析时拒绝执行。',
+                policyCode: 'ec_command_not_canonical',
+            };
+        }
+        // When both forms are present, commandArgv is the app-server's structured
+        // source of truth. Do not let a conflicting display string hide a path or
+        // shell operator that is present in the argv payload.
+        const commandForPolicy = explicitCommandArgv
+            ? explicitCommandArgv.join(' ')
+            : command;
+        const tempCheck = checkManagedTempShellCommand(commandForPolicy, managedTempOptions(context));
         if (tempCheck.kind === 'deny') {
             return {
                 behavior: 'deny',
@@ -1347,14 +1950,14 @@ export function evaluateToolPreflight(toolName, input, context) {
                 policyCode: 'temporary_path_outside_tmpdir',
             };
         }
-        const explicitCommandArgv = Array.isArray(input.commandArgv)
-            && input.commandArgv.every(value => typeof value === 'string')
-            ? input.commandArgv
-            : undefined;
         const outerArgv = explicitCommandArgv ?? parseLiteralShellArgv(command) ?? undefined;
-        const shellCarrier = outerArgv ? resolveCodexShellCarrierArgv(outerArgv) : undefined;
-        const wrappedCommand = shellCarrier?.command;
-        const policyCommand = wrappedCommand ?? command;
+        const shellCarrier = outerArgv
+            ? resolveCodexShellCarrierArgv(outerArgv)
+            : undefined;
+        const stringShellCarrier = shellCarrier
+            ?? (explicitCommandArgv ? undefined : resolveCodexShellCarrierString(command));
+        const wrappedCommand = stringShellCarrier?.command;
+        const policyCommand = wrappedCommand ?? commandForPolicy;
         if (context.sessionId && /^\s*(?:command\s+-v|which|type)\s+ec\s*$/i.test(policyCommand)) {
             return {
                 behavior: 'deny',
@@ -1398,8 +2001,10 @@ export function evaluateToolPreflight(toolName, input, context) {
                 policyCode: 'managed_ec_aid_scope_forbidden',
             };
         }
-        const ecCommand = classifyEvolcoreShellCommand(policyCommand, shellCarrier
-            ? { dialect: shellCarrier.dialect }
+        const shellDialect = stringShellCarrier?.dialect
+            ?? (hasCodexCmdCarrierEcIntent(input) ? 'cmd' : undefined);
+        const ecCommand = classifyEvolcoreShellCommand(policyCommand, shellDialect
+            ? { dialect: shellDialect }
             : {});
         if (ecCommand.kind === 'literal') {
             return { behavior: 'allow', input, reason: 'ec-command' };
@@ -1409,9 +2014,11 @@ export function evaluateToolPreflight(toolName, input, context) {
         }
         if (ecCommand.kind === 'composite') {
             if (ecCommand.issue === 'unsafe-expansion') {
-                const message = shellCarrier?.dialect === 'powershell'
+                const message = shellDialect === 'powershell'
                     ? '🔒 EC 双引号正文包含未转义的 PowerShell 展开；纯文字请优先使用单引号，或用 PowerShell 反引号转义 $ 和正文内的双引号。PowerShell 传给 ec 时会还原为原文字面量'
-                    : '🔒 EC 双引号正文包含未转义的 Shell 展开；请将反引号写成 \\`，将 $()、${}、$变量中的 $ 写成 \\$。Shell 传给 ec 时会还原为原文字面量';
+                    : shellDialect === 'cmd'
+                        ? '🔒 EC 命令包含未转义的 cmd.exe 展开；请不要使用 %VAR%、!VAR! 或 ^ 转义。cmd.exe 传给 ec 时必须保持原文字面量'
+                        : '🔒 EC 双引号正文包含未转义的 Shell 展开；请将反引号写成 \\`，将 $()、${}、$变量中的 $ 写成 \\$。Shell 传给 ec 时会还原为原文字面量';
                 return {
                     behavior: 'deny',
                     input,
@@ -1420,9 +2027,11 @@ export function evaluateToolPreflight(toolName, input, context) {
                 };
             }
             if (ecCommand.issue === 'invalid-quote') {
-                const message = shellCarrier?.dialect === 'powershell'
+                const message = shellDialect === 'powershell'
                     ? '🔒 EC 命令引号未闭合或存在错误嵌套；PowerShell 正文内的双引号请用反引号转义，或改用单引号包裹纯文字'
-                    : '🔒 EC 命令引号未闭合或存在错误嵌套；正文中的双引号请写成 \\"';
+                    : shellDialect === 'cmd'
+                        ? '🔒 EC 命令引号未闭合或存在错误嵌套；cmd.exe carrier 的命令正文请保持一个完整参数，不要用未配对的双引号'
+                        : '🔒 EC 命令引号未闭合或存在错误嵌套；正文中的双引号请写成 \\"';
                 return {
                     behavior: 'deny',
                     input,
@@ -1430,9 +2039,11 @@ export function evaluateToolPreflight(toolName, input, context) {
                     policyCode: 'ec_shell_invalid_quote',
                 };
             }
-            const message = shellCarrier?.dialect === 'powershell'
+            const message = shellDialect === 'powershell'
                 ? '🔒 EC 命令调用被拒绝：一次 PowerShell/exec_command 只能执行一条完整的 `ec` 命令。请直接调用 `ec ...`，不要拼接探测命令，也不要使用 `&&`、`||`、`;`、`|`、重定向、变量展开或子表达式追加其它命令。'
-                : '🔒 EC 命令调用被拒绝：一次 Bash/exec_command 只能执行一条完整的 `ec` 命令。请直接调用 `ec ...`，不要先用 `command -v`/`ec aid` 探测，也不要使用 `&&`、`||`、`;`、`|`、重定向、变量展开、子 shell、`sh -c` 或 `bash -lc` 拼接其它命令。';
+                : shellDialect === 'cmd'
+                    ? '🔒 EC 命令调用被拒绝：一次 cmd.exe/exec_command 只能执行一条完整的 `ec` 命令。请直接调用 `ec ...`，不要拼接其它命令，不要使用 &、|、重定向、变量展开或 ^ 转义。'
+                    : '🔒 EC 命令调用被拒绝：一次 Bash/exec_command 只能执行一条完整的 `ec` 命令。请直接调用 `ec ...`，不要先用 `command -v`/`ec aid` 探测，也不要使用 `&&`、`||`、`;`、`|`、重定向、变量展开、子 shell、`sh -c` 或 `bash -lc` 拼接其它命令。';
             return {
                 behavior: 'deny',
                 input,
@@ -1472,7 +2083,7 @@ export function evaluateToolPreflight(toolName, input, context) {
         allowProtectedMetadata: context.allowProtectedMetadata,
     });
     if (hClass.behavior === 'deny') {
-        return { behavior: 'deny', input: checkedInput, message: hClass.message, policyCode: 'h_class_protection' };
+        return { behavior: 'deny', input: checkedInput, message: hClass.message, policyCode: 'h_class_protection', matchedPath: hClass.matchedPath };
     }
     const lClass = checkLClassWrite(toolName, checkedInput, {
         sessionId: context.sessionId,
@@ -1486,7 +2097,7 @@ export function evaluateToolPreflight(toolName, input, context) {
         managedTempDir: context.managedTempDir,
     });
     if (lClass.behavior === 'deny') {
-        return { behavior: 'deny', input: checkedInput, message: lClass.message, policyCode: 'l_class_protection' };
+        return { behavior: 'deny', input: checkedInput, message: lClass.message, policyCode: 'l_class_protection', matchedPath: lClass.matchedPath };
     }
     const dangerous = checkDangerousCommand(toolName, checkedInput);
     if (dangerous.isDangerous