evolcore 0.0.27 → 0.0.29-test.0

package/dist/core/permission/ec-command-parser.js

@@ -1,5 +1,203 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { isTrustedWindowsShellExecutable } from '../../utils/windows-shell-trust.js';
-const HEAD_EXECUTABLES = new Set(['head', '/bin/head', '/usr/bin/head']);
+function parseApplyPatchCommand(command) {
+    const input = command.trim();
+    let commandText = input;
+    if (commandText.startsWith('&'))
+        commandText = commandText.slice(1).trimStart();
+    const executableMatch = commandText.match(/^(?:"([^"]+)"|'([^']+)'|([^\s]+))/u);
+    if (!executableMatch)
+        return { kind: 'not-apply-patch' };
+    const executable = executableMatch[1] ?? executableMatch[2] ?? executableMatch[3] ?? '';
+    if (!isApplyPatchExecutable(executable))
+        return { kind: 'not-apply-patch' };
+    const remainder = commandText.slice(executableMatch[0].length).trimStart();
+    if (!remainder)
+        return { kind: 'invalid', reason: 'missing patch document' };
+    const literal = parseLiteralShellCommand(input, { allowManagedTmpDir: true });
+    if (literal.ok && argvUsesShellApplyPatch(literal.argv)) {
+        if (literal.argv.length !== 2)
+            return { kind: 'invalid', reason: 'apply_patch must carry exactly one patch document' };
+        const fileChanges = parseApplyPatchDocument(literal.argv[1]);
+        return fileChanges
+            ? { kind: 'file-change', fileChanges }
+            : { kind: 'invalid', reason: 'patch document is not a complete apply_patch document' };
+    }
+    const heredoc = remainder.match(/^<<-?\s*(?:'([^']+)'|"([^"]+)"|([^\s]+))\s*\r?\n([\s\S]*)$/u);
+    if (!heredoc)
+        return { kind: 'invalid', reason: 'apply_patch must use one literal patch document' };
+    const delimiter = heredoc[1] ?? heredoc[2] ?? heredoc[3];
+    const bodyLines = heredoc[4].replace(/\r\n?/gu, '\n').split('\n');
+    const delimiterIndex = bodyLines.findIndex(line => line === delimiter);
+    if (delimiterIndex < 0 || bodyLines.slice(delimiterIndex + 1).some(line => line.trim() !== '')) {
+        return { kind: 'invalid', reason: 'heredoc delimiter is incomplete or has trailing commands' };
+    }
+    const fileChanges = parseApplyPatchDocument(bodyLines.slice(0, delimiterIndex).join('\n'));
+    return fileChanges
+        ? { kind: 'file-change', fileChanges }
+        : { kind: 'invalid', reason: 'patch document is not a complete apply_patch document' };
+}
+function composedApplyPatchOnCommandLine(command) {
+    const commandLine = command.split(/\r?\n/u, 1)[0] ?? command;
+    return commandLine.split(/[|;&]/u).slice(1).some(segment => {
+        const executable = leadingShellExecutable(segment);
+        return !!executable && isApplyPatchExecutable(executable);
+    });
+}
+export function parseShellApplyPatchInvocation(input, options = {}, parsedArgv) {
+    const rawCommand = typeof input.command === 'string' ? input.command : '';
+    const rawCommandArgv = Array.isArray(input.commandArgv)
+        && input.commandArgv.every(value => typeof value === 'string')
+        ? input.commandArgv
+        : undefined;
+    const candidates = [];
+    const addCandidate = (value) => {
+        if (value && !candidates.includes(value))
+            candidates.push(value);
+    };
+    addCandidate(rawCommand);
+    if (rawCommandArgv) {
+        if (argvUsesShellApplyPatch(rawCommandArgv)) {
+            if (rawCommandArgv.length === 2) {
+                const fileChanges = parseApplyPatchDocument(rawCommandArgv[1]);
+                return fileChanges
+                    ? { kind: 'file-change', fileChanges }
+                    : { kind: 'invalid', reason: 'patch document is not a complete apply_patch document' };
+            }
+            return { kind: 'invalid', reason: 'apply_patch must carry exactly one patch document' };
+        }
+        addCandidate(resolveCodexShellCarrierArgv(rawCommandArgv)?.command);
+    }
+    if (parsedArgv && argvUsesShellApplyPatch(parsedArgv)) {
+        return { kind: 'invalid', reason: 'apply_patch payload could not be reconstructed safely' };
+    }
+    addCandidate(resolveCodexShellCarrierString(rawCommand)?.command);
+    let sawApplyPatch = false;
+    let invalidReason = 'apply_patch payload could not be reconstructed safely';
+    for (const candidate of candidates) {
+        const parsed = parseApplyPatchCommand(candidate);
+        if (parsed.kind !== 'not-apply-patch') {
+            sawApplyPatch = true;
+            if (parsed.kind === 'file-change')
+                return parsed;
+            invalidReason = parsed.reason;
+        }
+        else if (composedApplyPatchOnCommandLine(candidate)) {
+            sawApplyPatch = true;
+            invalidReason = 'apply_patch must be the only shell command';
+        }
+    }
+    return sawApplyPatch ? { kind: 'invalid', reason: invalidReason } : { kind: 'not-apply-patch' };
+}
+/**
+ * stdout filters allowed after an EC invocation. Each entry reads stdin and
+ * writes stdout only, and its option grammar is an allowlist, so a filter can
+ * never acquire a file operand, a write target, or a process spawn. Changing
+ * this table means changing `bin/ec-safe-output.js`, which repeats the same
+ * validation before it spawns the process.
+ */
+const STDOUT_FILTER_SPECS = new Map([
+    // Every `tail` follow/retry option is absent below, so `tail -f` is rejected
+    // instead of being allowed to hold the pipe open.
+    ['head', {
+            flags: new Set(),
+            valueOptions: new Set(['-n', '-c', '--lines', '--bytes']),
+            maxOperands: 0,
+            numericShorthand: true,
+        }],
+    ['tail', {
+            flags: new Set(),
+            valueOptions: new Set(['-n', '-c', '--lines', '--bytes']),
+            maxOperands: 0,
+            numericShorthand: true,
+        }],
+    // `grep` needs a pattern: either `-e`/`--regexp` or the single leading
+    // operand. Once an explicit pattern option appears, a bare operand would be
+    // a file to read, so the operand budget drops to zero. `-r`/`-R`/`-f` are
+    // absent from both tables, which keeps recursion and pattern files out.
+    ['grep', {
+            flags: new Set([
+                '-i', '--ignore-case', '-v', '--invert-match', '-c', '--count',
+                '-l', '--files-with-matches', '-L', '--files-without-match', '-o', '--only-matching',
+                '-n', '--line-number', '-h', '--no-filename', '-H', '--with-filename',
+                '-q', '--quiet', '--silent', '-s', '--no-messages', '-w', '--word-regexp',
+                '-x', '--line-regexp', '-F', '--fixed-strings', '-E', '--extended-regexp',
+                '-G', '--basic-regexp', '-P', '--perl-regexp', '-a', '--text', '-I',
+                '-z', '--null-data', '-U', '--binary', '--line-buffered', '--no-group-separator',
+            ]),
+            valueOptions: new Set([
+                '-m', '--max-count', '-A', '--after-context', '-B', '--before-context',
+                '-C', '--context', '--color', '--colour', '--binary-files', '--label',
+                '--group-separator', '-d', '--directories', '--include', '--exclude', '--exclude-dir',
+            ]),
+            patternValueOptions: new Set(['-e', '--regexp']),
+            maxOperands: 1,
+        }],
+    // `wc`, `sort`, `cut` and `uniq` take no operands here: a path operand would
+    // make them read a file instead of the EC stdout. Options that name an input
+    // or output file (`--files0-from`, `sort -o`/`-T`/`--random-source`,
+    // `uniq --group`) are absent from both tables and therefore rejected.
+    ['wc', {
+            flags: new Set([
+                '-c', '-m', '-l', '-w', '-L',
+                '--bytes', '--chars', '--lines', '--words', '--max-line-length',
+            ]),
+            valueOptions: new Set(),
+            maxOperands: 0,
+        }],
+    ['sort', {
+            flags: new Set([
+                '-b', '-d', '-f', '-g', '-h', '-i', '-M', '-n', '-r', '-R', '-s', '-u', '-V', '-z',
+                '--ignore-leading-blanks', '--dictionary-order', '--ignore-case', '--general-numeric-sort',
+                '--human-numeric-sort', '--ignore-nonprinting', '--month-sort', '--numeric-sort',
+                '--random-sort', '--reverse', '--stable', '--unique', '--version-sort', '--zero-terminated',
+                '--check', '--merge',
+            ]),
+            valueOptions: new Set([
+                '-k', '-t', '-S', '--key', '--field-separator',
+                '--batch-size', '--buffer-size', '--parallel', '--sort',
+            ]),
+            maxOperands: 0,
+        }],
+    ['cut', {
+            flags: new Set(['-s', '--only-delimited', '-n', '--complement', '-z', '--zero-terminated']),
+            valueOptions: new Set([
+                '-b', '-c', '-f', '-d', '--bytes', '--characters', '--fields', '--delimiter', '--output-delimiter',
+            ]),
+            maxOperands: 0,
+        }],
+    ['uniq', {
+            flags: new Set([
+                '-c', '-d', '-D', '-u', '-i', '-z',
+                '--count', '--repeated', '--all-repeated', '--unique', '--ignore-case', '--zero-terminated',
+            ]),
+            valueOptions: new Set(['-f', '-s', '--skip-fields', '--skip-chars']),
+            maxOperands: 0,
+        }],
+    // `tr` takes its character sets as operands, which are never files.
+    ['tr', {
+            flags: new Set([
+                '-c', '-C', '-d', '-s', '-t',
+                '--complement', '--delete', '--squeeze-repeats', '--truncate-set1',
+            ]),
+            valueOptions: new Set(),
+            maxOperands: 2,
+        }],
+]);
+/** Accept `head`, `/bin/head` and `/usr/bin/head` for every allowed filter. */
+function normalizeStdoutFilterExecutable(value) {
+    if (STDOUT_FILTER_SPECS.has(value))
+        return value;
+    for (const prefix of ['/bin/', '/usr/bin/']) {
+        if (value.startsWith(prefix)) {
+            const bare = value.slice(prefix.length);
+            if (STDOUT_FILTER_SPECS.has(bare))
+                return bare;
+        }
+    }
+    return undefined;
+}
 // Codex app-server sends command executions through a fixed shell carrier.
 // Treat the carrier as syntax only after parsing it as literal argv; never
 // accept an arbitrary shell command string or unwrap composition here.
@@ -28,8 +226,22 @@ const CODEX_POWERSHELL_INERT_SWITCHES = new Set([
 // `/e:*`, and `/f:*` can change process lifetime or command semantics and are
 // intentionally not treated as a trusted Codex carrier.
 const CODEX_CMD_INERT_SWITCHES = new Set(['/d', '/s', '/q', '/a', '/u']);
-const EVOLCORE_EXECUTABLE_ALIASES = new Set(['ec', 'ec.cmd', 'ec.exe']);
+const EVOLCORE_EXECUTABLE_ALIASES = new Set(['ec', 'ec.cmd', 'ec.exe', 'ec.ps1']);
 const EVOLCORE_NODE_EXECUTABLES = new Set(['node', 'node.exe']);
+const APPLY_PATCH_EXECUTABLE_BASENAMES = new Set([
+    'apply_patch',
+    'apply_patch.bat',
+    'apply_patch.cmd',
+    'apply_patch.exe',
+    'apply_patch.ps1',
+]);
+const EVOLCORE_SUBCOMMANDS = new Set([
+    'agent', 'aid', 'bench', 'config', 'contact', 'ctl', 'data', 'diag', 'diagnose',
+    'fs', 'gateway', 'group', 'handoff', 'init', 'link-rules', 'logs', 'menu-client',
+    'mode', 'model', 'msg', 'mv', 'net', 'queue', 'response', 'restart',
+    'restart-monitor', 'rpc', 'start', 'stats', 'status', 'stop', 'storage', 'task',
+    'trigger', 'version', 'watch',
+]);
 // Development/install entrypoints that are part of this repository's CLI.
 // Only these exact relative paths are canonicalized; arbitrary Node scripts
 // must never become an EC command merely because their filename is similar.
@@ -41,6 +253,45 @@ const POWERSHELL_UNQUOTED_META = new Set([
     ';', '&', '|', '<', '>', '$', '(', ')', '*', '?', '[', ']', '{', '}', '#', '@',
 ]);
 const AMBIGUOUS_FILE_PATH_RE = /[\0\r\n$`*?\[\]{}<>|;&]/;
+/**
+ * 用空格替换 heredoc 正文，保留命令行本身。
+ *
+ * heredoc 正文是**数据**（提交信息、脚本片段、文档示例），不是 shell 语法。
+ * 若不剥离，正文里出现的 `; ec ...`、`&& ec ...` 会被命令边界扫描当成真的
+ * 拼接调用——`git commit -F - <<'MSG'` 的提交信息里写了 `` `cd "x"; ec ...` ``
+ * 就会整条被拒，且报的还是"拼接命令"，病因完全指错方向。
+ *
+ * 只处理 heredoc，不动其它多行结构：不支持 heredoc 的场景（比如真正的多行
+ * 拼接攻击）仍然走原有的 fail-closed 路径。
+ */
+function stripHeredocBodies(command) {
+    if (!command.includes('<<'))
+        return command;
+    const lines = command.split('\n');
+    const out = [];
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        // 收集本行声明的所有 heredoc 终止符（`<<WORD` / `<<'WORD'` / `<<"WORD"` / `<<-WORD`）。
+        const delimiters = [];
+        const pattern = /<<-?[ \t]*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
+        let match;
+        while ((match = pattern.exec(line)) !== null)
+            delimiters.push(match[2]);
+        out.push(line);
+        if (delimiters.length === 0)
+            continue;
+        // 逐行丢弃，直到每个终止符都出现过；未闭合时丢弃剩余全部（保守：正文永远不是命令）。
+        let remaining = delimiters.slice();
+        while (remaining.length > 0 && index + 1 < lines.length) {
+            index++;
+            const candidate = lines[index].trim();
+            const hit = remaining.indexOf(candidate);
+            if (hit >= 0)
+                remaining.splice(hit, 1);
+        }
+    }
+    return out.join('\n');
+}
 // This is intentionally limited to the command boundary. It is not a search
 // for `ec` anywhere in the input: quoted arguments, regexps and log text must
 // never establish an EC invocation.
@@ -85,7 +336,7 @@ function hasEcCommandPrefix(command) {
         }
         if (boundary && /\s/.test(char))
             continue;
-        if (boundary && /^ec(?:\.cmd|\.exe)?(?=$|\s|[;&|`()<>])/i.test(command.slice(index)))
+        if (boundary && /^ec(?:\.cmd|\.exe|\.ps1)?(?=$|\s|[;&|`()<>])/i.test(command.slice(index)))
             return true;
         boundary = false;
     }
@@ -100,7 +351,7 @@ function trimShellSpacing(value) {
  * Relative names remain restricted to the fixed executable allowlists above.
  */
 function isAbsoluteCustomShellPath(value, executableNames) {
-    if (!value || /[\0\r\n"'<>|?*]/.test(value))
+    if (!value || /[\0\r\n"'<>|?*`$;&|(){}\[\]]/.test(value))
         return false;
     const normalized = value.replaceAll('\\', '/');
     if (!/^[A-Za-z]:\//.test(normalized) && !normalized.startsWith('//'))
@@ -108,6 +359,114 @@ function isAbsoluteCustomShellPath(value, executableNames) {
     const basename = normalized.slice(normalized.lastIndexOf('/') + 1).toLowerCase();
     return executableNames.has(basename);
 }
+function isStandardNpmEvolcoreShim(content, basename) {
+    const lines = content.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n').split('\n')
+        .map(line => line.trim())
+        .filter(Boolean);
+    if (basename === 'ec.cmd') {
+        const patterns = [
+            /^@echo off$/i,
+            /^goto start$/i,
+            /^:find_dp0$/i,
+            /^set dp0=%~dp0$/i,
+            /^exit \/b$/i,
+            /^:start$/i,
+            /^setlocal$/i,
+            /^call :find_dp0$/i,
+            /^if exist "%dp0%[\\/]node\.exe" \($/i,
+            /^set "_prog=%dp0%[\\/]node\.exe"$/i,
+            /^\) else \($/i,
+            /^set "_prog=node"$/i,
+            /^set pathext=%pathext:;\.js;=;%$/i,
+            /^\)$/i,
+            /^endlocal\s*&\s*goto #_undefined_#\s+2>nul\s+\|\|\s+title %comspec%\s*&\s+"%_prog%"\s+"%dp0%[\\/]node_modules[\\/]evolcore[\\/]bin[\\/]ec\.js"\s+%\*$/i,
+        ];
+        return lines.length === patterns.length && lines.every((line, index) => patterns[index].test(line));
+    }
+    const patterns = [
+        /^#!\/usr\/bin\/env\s+pwsh$/i,
+        /^\$basedir\s*=\s*split-path\s+\$myinvocation\.mycommand\.definition\s+-parent$/i,
+        /^\$exe\s*=\s*""$/i,
+        /^if\s*\(\$PSVersionTable\.PSVersion\s+-lt\s+"6\.0"\s+-or\s+\$IsWindows\)\s*\{$/i,
+        /^#\s*Fix case when both the Windows and Linux builds of Node$/i,
+        /^#\s*are installed in the same directory$/i,
+        /^\$exe\s*=\s*"\.exe"$/i,
+        /^\}$/,
+        /^\$ret\s*=\s*0$/i,
+        /^if\s*\(Test-Path\s+"\$basedir\/node\$exe"\)\s*\{$/i,
+        /^#\s*Support pipeline input$/i,
+        /^if\s*\(\$MyInvocation\.ExpectingInput\)\s*\{$/i,
+        /^\$input\s+\|\s+&\s+"\$basedir\/node\$exe"\s+"\$basedir\/node_modules\/evolcore\/bin\/ec\.js"\s+\$args$/i,
+        /^\}\s*else\s*\{$/i,
+        /^&\s+"\$basedir\/node\$exe"\s+"\$basedir\/node_modules\/evolcore\/bin\/ec\.js"\s+\$args$/i,
+        /^\}$/,
+        /^\$ret\s*=\s*\$LASTEXITCODE$/i,
+        /^\}\s*else\s*\{$/i,
+        /^#\s*Support pipeline input$/i,
+        /^if\s*\(\$MyInvocation\.ExpectingInput\)\s*\{$/i,
+        /^\$input\s+\|\s+&\s+"node\$exe"\s+"\$basedir\/node_modules\/evolcore\/bin\/ec\.js"\s+\$args$/i,
+        /^\}\s*else\s*\{$/i,
+        /^&\s+"node\$exe"\s+"\$basedir\/node_modules\/evolcore\/bin\/ec\.js"\s+\$args$/i,
+        /^\}$/,
+        /^\$ret\s*=\s*\$LASTEXITCODE$/i,
+        /^\}$/,
+        /^exit\s+\$ret$/i,
+    ];
+    return lines.length === patterns.length && lines.every((line, index) => patterns[index].test(line));
+}
+/**
+ * PowerShell's call operator executes the path exactly as supplied. The
+ * canonical argv is only safe to arm when that path is the npm shim for this
+ * package; accepting an arbitrary same-named `ec.cmd` would let a wrapper run
+ * unrelated code while receiving an EC delegation approval.
+ */
+function isTrustedEvolcoreCallPath(value) {
+    if (!isAbsoluteCustomShellPath(value, EVOLCORE_EXECUTABLE_ALIASES))
+        return false;
+    if (process.platform !== 'win32')
+        return false;
+    const normalized = value.replaceAll('\\', '/');
+    const basename = normalized.slice(normalized.lastIndexOf('/') + 1).toLowerCase();
+    if (basename !== 'ec.cmd' && basename !== 'ec.ps1')
+        return false;
+    let shimPath;
+    try {
+        shimPath = fs.realpathSync.native(value);
+        const stat = fs.statSync(shimPath);
+        if (!stat.isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    let content;
+    try {
+        content = fs.readFileSync(shimPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    // npm's Windows shims use either `%dp0%\\node_modules\\evolcore\\...`
+    // or `$basedir/node_modules/evolcore/...`. The PowerShell shim references
+    // the same target once per input branch, so validate one distinct target
+    // rather than counting textual occurrences.
+    const nodeModuleRefs = content.match(/node_modules[^"'`\r\n\s]*/gi) ?? [];
+    const targetMatches = content.match(/node_modules[\\/]evolcore[\\/]bin[\\/]ec\.js/gi) ?? [];
+    const normalizedTargets = new Set(targetMatches.map(value => value.replaceAll('\\', '/').toLowerCase()));
+    if (targetMatches.length === 0
+        || normalizedTargets.size !== 1
+        || nodeModuleRefs.some(value => !/^node_modules[\\/]evolcore[\\/]bin[\\/]ec\.js$/i.test(value))
+        || !isStandardNpmEvolcoreShim(content, basename)) {
+        return false;
+    }
+    const targetPath = path.win32.join(path.win32.dirname(shimPath), 'node_modules', 'evolcore', 'bin', 'ec.js');
+    try {
+        return fs.statSync(targetPath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 function isNodeExecutable(value) {
     if (!value)
         return false;
@@ -203,6 +562,20 @@ function isShellSpacing(value) {
 function isLiteralArgBoundary(value) {
     return value === undefined || isShellSpacing(value);
 }
+/**
+ * POSIX 引号闭合后允许直接出现的字符。
+ *
+ * 与 `isLiteralArgBoundary` 的区别：`cd "x"; ec ...` 在 bash 里完全合法，
+ * 引号后紧跟 `;`/`&`/`|` 等操作符是标准写法。若只认空白，这类输入会被
+ * 误判成 `invalid-quote`（"引号未闭合"）——词法上引号其实配对完好，
+ * 报错方向完全错误，把人引去排查转义。
+ *
+ * 这里放宽的只是**引号是否闭合**的判定；操作符本身仍由后续非引号分支
+ * 判为 `shell-composition`，拦截力度不变，只让错误归因准确。
+ */
+function isPosixQuotedTokenBoundary(value) {
+    return value === undefined || isShellSpacing(value) || SHELL_UNQUOTED_META.has(value);
+}
 function isShellParameterExpansionStart(value) {
     return value === '(' || value === '{' || !!value && /[A-Za-z0-9_@*#?$!\-]/.test(value);
 }
@@ -213,7 +586,7 @@ function hasCarrierEcCommandPrefix(command, dialect) {
     const inner = input.length >= 2 && input.startsWith('"') && input.endsWith('"')
         ? input.slice(1, -1)
         : input;
-    return /^\s*ec(?:\.cmd|\.exe)?(?:\s|$)/i.test(inner);
+    return /^\s*ec(?:\.cmd|\.exe|\.ps1)?(?:\s|$)/i.test(inner);
 }
 /** Normalize the Windows npm shims to the canonical EvolCore CLI name. */
 export function normalizeEvolcoreCommandArgv(argv) {
@@ -229,11 +602,151 @@ export function normalizeEvolcoreCommandArgv(argv) {
     }
     return [...argv];
 }
+const INLINE_TEXT_FLAGS = {
+    agentNew: new Set(['--description', '--persona-text', '--handoff']),
+    agentPersona: new Set(['--text']),
+    agentWelcome: new Set(['--text']),
+    msgSend: new Set(['--description', '--text', '--transcript', '--handoff-context']),
+    groupSend: new Set(['--text', '--transcript']),
+    groupCreate: new Set(['--description']),
+    groupUpdate: new Set(['--description']),
+    groupRules: new Set(['--question']),
+    groupJoin: new Set(['--message', '--answer']),
+    groupBlock: new Set(['--reason']),
+    triggerCreate: new Set(['--prompt']),
+    triggerUpdate: new Set(['--prompt', '--description']),
+};
+const MESSAGE_POSITIONAL_FLAGS = new Set([
+    '--file', '--payload', '--as', '--content-type', '--text', '--transcript',
+    '--thread', '--return', '--title', '--description', '--text-from-file',
+    '--handoff-context', '--aun-path', '--app', '--format', '--encrypt', '--no-encrypt',
+]);
+/** Decode the EC inline text contract exactly once, after shell parsing. */
+export function decodeEvolcoreInlineText(value) {
+    return value.replace(/\\([\\nrt])/g, (_match, escaped) => {
+        if (escaped === 'n')
+            return '\n';
+        if (escaped === 'r')
+            return '\r';
+        if (escaped === 't')
+            return '\t';
+        return '\\';
+    });
+}
+function decodeInlineFlags(argv, flags) {
+    for (let index = 0; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === '--')
+            break;
+        if (flags.has(value) && argv[index + 1] !== undefined) {
+            argv[index + 1] = decodeEvolcoreInlineText(argv[index + 1]);
+            index++;
+            continue;
+        }
+        const separator = value.indexOf('=');
+        if (separator > 0 && flags.has(value.slice(0, separator))) {
+            argv[index] = value.slice(0, separator + 1) + decodeEvolcoreInlineText(value.slice(separator + 1));
+        }
+    }
+}
+function decodePositionalText(argv, start, optionFlags) {
+    for (let index = start; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === '--') {
+            for (let bodyIndex = index + 1; bodyIndex < argv.length; bodyIndex++) {
+                argv[bodyIndex] = decodeEvolcoreInlineText(argv[bodyIndex]);
+            }
+            return;
+        }
+        if (value.startsWith('--')) {
+            const separator = value.indexOf('=');
+            if (separator > 0)
+                continue;
+            if (optionFlags.has(value) && argv[index + 1] !== undefined)
+                index++;
+            continue;
+        }
+        argv[index] = decodeEvolcoreInlineText(value);
+    }
+}
+function canonicalizeHandoffText(argv) {
+    const action = argv[2];
+    if (action !== 'return' && action !== 'recover-return')
+        return;
+    const delimiter = argv.indexOf('--', 2);
+    if (delimiter >= 0) {
+        for (let index = delimiter + 1; index < argv.length; index++) {
+            argv[index] = decodeEvolcoreInlineText(argv[index]);
+        }
+        return;
+    }
+    const fileIndex = argv.indexOf('--text-from-file', 2);
+    for (let index = 2; index < argv.length; index++) {
+        if (index === fileIndex) {
+            index++;
+            continue;
+        }
+        if (!argv[index].startsWith('--'))
+            argv[index] = decodeEvolcoreInlineText(argv[index]);
+    }
+}
+/**
+ * Convert an EC invocation to the one argv representation shared by approval,
+ * delegation hashing, IPC, and command execution. Shell syntax is already
+ * resolved before this function is called; this function only normalizes the
+ * EC entrypoint and applies the command-specific inline text contract.
+ */
+export function canonicalizeEvolcoreCommandArgv(argv) {
+    const canonical = normalizeEvolcoreCommandArgv(argv);
+    if (canonical[0] !== 'ec')
+        return canonical;
+    const result = [...canonical];
+    const command = result[1];
+    const subcommand = result[2];
+    if (command === 'agent') {
+        if (subcommand === 'new')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.agentNew);
+        else if (subcommand === 'persona')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.agentPersona);
+        else if (subcommand === 'welcome')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.agentWelcome);
+    }
+    else if (command === 'msg' && subcommand === 'send') {
+        decodeInlineFlags(result, INLINE_TEXT_FLAGS.msgSend);
+        decodePositionalText(result, 5, MESSAGE_POSITIONAL_FLAGS);
+    }
+    else if (command === 'group') {
+        if (subcommand === 'send') {
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.groupSend);
+            decodePositionalText(result, 5, MESSAGE_POSITIONAL_FLAGS);
+        }
+        else if (subcommand === 'create')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.groupCreate);
+        else if (subcommand === 'update')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.groupUpdate);
+        else if (subcommand === 'rules')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.groupRules);
+        else if (subcommand === 'join')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.groupJoin);
+        else if (subcommand === 'block')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.groupBlock);
+    }
+    else if (command === 'trigger') {
+        if (subcommand === 'create' || subcommand === 'set')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.triggerCreate);
+        else if (subcommand === 'update')
+            decodeInlineFlags(result, INLINE_TEXT_FLAGS.triggerUpdate);
+    }
+    else if (command === 'handoff') {
+        canonicalizeHandoffText(result);
+    }
+    return result;
+}
 const POWERSHELL_CREDENTIAL_ENV_RE = /^(EVOLCORE_CODEX_SESSION_TOKEN|EVOLCORE_DELEGATION_TOKEN)$/i;
 /** Detect a PowerShell prefix that materializes an EvolCore session credential. */
 export function hasPowerShellCredentialAssignment(command) {
     return /^\s*\$env\s*:\s*(?:EVOLCORE_CODEX_SESSION_TOKEN|EVOLCORE_DELEGATION_TOKEN)\b/i.test(command)
-        && /\bec(?:\.cmd|\.exe)?(?:\s|$)/i.test(command);
+        && /\bec(?:\.cmd|\.exe|\.ps1)?(?:\s|$)/i.test(command);
 }
 /**
  * Windows Codex may materialize one environment variable assignment directly
@@ -354,10 +867,41 @@ export function parseCodexCarrierCommand(carrier, options = {}) {
             && options.expectedCredentialToken !== unwrapped.token)) {
         return parseFailure('shell-composition', carrier.command, 0, 0, carrier.dialect);
     }
-    const parsed = parseLiteralShellCommand(unwrapped.command, {
+    const materialized = parseLiteralShellCommand(unwrapped.command, {
         ...options,
         dialect: carrier.dialect,
     });
+    if (materialized.ok && carrier.dialect === 'powershell') {
+        const nestedCarrier = resolveCodexCmdCarrierString(unwrapped.command);
+        if (nestedCarrier) {
+            const nested = parseCodexCarrierCommand(nestedCarrier, options);
+            if (!nested.ok)
+                return nested;
+            const executeIndex = materialized.argv.findIndex((value, index) => index > 0 && value.toLowerCase() === '/c');
+            if (executeIndex < 1 || executeIndex >= materialized.argv.length - 1) {
+                return parseFailure('shell-composition', unwrapped.command, 0, 0, carrier.dialect);
+            }
+            const bodyArgv = materialized.argv.slice(executeIndex + 1);
+            const materializedBody = bodyArgv.length === 1
+                ? parseLiteralShellCommand(bodyArgv[0], { ...options, dialect: 'cmd' })
+                : { ok: true, argv: normalizeEvolcoreCommandArgv(bodyArgv) };
+            if (!materializedBody.ok
+                || materializedBody.argv.length !== nested.argv.length
+                || materializedBody.argv.some((value, index) => value !== nested.argv[index])) {
+                return parseFailure('shell-composition', unwrapped.command, 0, 0, carrier.dialect);
+            }
+            return {
+                ...nested,
+                ...(unwrapped.kind === 'valid' ? { credentialToken: unwrapped.token } : {}),
+            };
+        }
+    }
+    const parsed = materialized;
+    if (parsed.ok && carrier.dialect === 'powershell'
+        && /^\s*ec\.cmd(?:\s|$)/i.test(unwrapped.command)
+        && parsed.argv.some(value => /[\r\n]/.test(value))) {
+        return parseFailure('lossy-cmd-shim', unwrapped.command, 0, 0, 'powershell');
+    }
     return parsed.ok
         ? {
             ...parsed,
@@ -376,12 +920,115 @@ function parseFailure(issue, input, offset, tokenIndex, dialect) {
         inputLength: input.length,
     };
 }
+// PowerShell uses smart quotes as delimiters, including when the opening
+// quote was ASCII. Treating them as text changes argv and delegation hashes.
+function isPowerShellSingleQuote(char) {
+    return char !== undefined && /['\u2018\u2019\u201a\u201b]/u.test(char);
+}
+function isPowerShellDoubleQuote(char) {
+    return char !== undefined && /["\u201c\u201d\u201e]/u.test(char);
+}
+function powerShellCallQuoteKind(char) {
+    if (isPowerShellSingleQuote(char))
+        return 'single';
+    if (isPowerShellDoubleQuote(char))
+        return 'double';
+    return undefined;
+}
+function isPowerShellCallQuote(kind, char) {
+    return kind === 'single' ? isPowerShellSingleQuote(char) : isPowerShellDoubleQuote(char);
+}
+function parsePowerShellCallOperator(command) {
+    const input = trimShellSpacing(command);
+    if (!input.startsWith('&'))
+        return undefined;
+    let index = 1;
+    while (isShellSpacing(input[index]))
+        index++;
+    const quote = powerShellCallQuoteKind(input[index]);
+    if (!quote)
+        return undefined;
+    const pathStart = ++index;
+    while (index < input.length && !isPowerShellCallQuote(quote, input[index]))
+        index++;
+    if (index >= input.length)
+        return undefined;
+    const executable = input.slice(pathStart, index);
+    if (!isTrustedEvolcoreCallPath(executable))
+        return undefined;
+    index++;
+    if (!isShellSpacing(input[index]))
+        return undefined;
+    while (isShellSpacing(input[index]))
+        index++;
+    if (index >= input.length)
+        return undefined;
+    return `ec ${input.slice(index)}`;
+}
+function looksLikePowerShellEvolcoreCallOperator(command, dialect) {
+    const input = trimShellSpacing(command);
+    if (!input.startsWith('&'))
+        return false;
+    let index = 1;
+    while (isShellSpacing(input[index]))
+        index++;
+    const quote = powerShellCallQuoteKind(input[index]);
+    let executable;
+    if (quote) {
+        const start = ++index;
+        while (index < input.length && !isPowerShellCallQuote(quote, input[index]))
+            index++;
+        if (index >= input.length) {
+            const lower = input.slice(start).toLowerCase();
+            return [...EVOLCORE_EXECUTABLE_ALIASES].some(alias => lower.includes(alias));
+        }
+        executable = input.slice(start, index);
+        index++;
+    }
+    else {
+        const start = index;
+        while (index < input.length && !isShellSpacing(input[index]))
+            index++;
+        executable = input.slice(start, index);
+    }
+    while (isShellSpacing(input[index]))
+        index++;
+    if (!executable)
+        return false;
+    const normalizedExecutable = executable.replaceAll('\\', '/');
+    const basename = normalizedExecutable.slice(normalizedExecutable.lastIndexOf('/') + 1).toLowerCase();
+    if (dialect && dialect !== 'powershell')
+        return false;
+    if (EVOLCORE_EXECUTABLE_ALIASES.has(basename))
+        return true;
+    if (index >= input.length)
+        return false;
+    const commandName = input.slice(index).match(/^([^\s;&|<>]+)/)?.[1]?.toLowerCase();
+    if (!commandName || !EVOLCORE_SUBCOMMANDS.has(commandName))
+        return false;
+    if (dialect !== 'powershell') {
+        // A quoted or dynamic call target followed by a known CLI subcommand is
+        // treated as a possible PowerShell EC call until proven otherwise.
+        return !!quote || /^[\$([{]/.test(executable);
+    }
+    // A dynamic or non-EC path is still an EC intent when its first literal
+    // argument is an EC command. This keeps `& $path ctl ...` fail-closed.
+    return true;
+}
 function parseLiteralPowerShellCommand(command, options = {}) {
     const input = trimShellSpacing(command);
     if (!input)
         return parseFailure('empty-command', input, 0, 0, 'powershell');
     if (input.includes('\0'))
         return parseFailure('invalid-control-char', input, input.indexOf('\0'), 0, 'powershell');
+    const callOperatorCommand = parsePowerShellCallOperator(input);
+    if (callOperatorCommand) {
+        const parsed = parseLiteralPowerShellCommand(callOperatorCommand, options);
+        return parsed.ok
+            ? { ...parsed, argv: normalizeEvolcoreCommandArgv(parsed.argv) }
+            : { ...parsed, inputLength: input.length };
+    }
+    const isEcCommand = hasEcCommandPrefix(input);
     const argv = [];
     let token = '';
     let tokenStarted = false;
@@ -399,11 +1046,11 @@ function parseLiteralPowerShellCommand(command, options = {}) {
     for (let index = 0; index < input.length; index++) {
         const char = input[index];
         if (quote === 'single') {
-            if (char === "'" && input[index + 1] === "'") {
-                token += "'";
+            if (isPowerShellSingleQuote(char) && isPowerShellSingleQuote(input[index + 1])) {
+                token += input[index + 1];
                 index++;
             }
-            else if (char === "'") {
+            else if (isPowerShellSingleQuote(char)) {
                 if (!isLiteralArgBoundary(input[index + 1]))
                     return parseFailure('invalid-quote', input, index, argv.length, 'powershell');
                 quote = null;
@@ -420,7 +1067,7 @@ function parseLiteralPowerShellCommand(command, options = {}) {
                 return parseFailure('unsafe-expansion', input, index, argv.length, 'powershell');
             }
             if (!options.allowManagedTmpDir || !options.managedTempDir
-                || (next !== undefined && !/[\\/\s"']/u.test(next))) {
+                || (next !== undefined && !/[\\/\s"']/u.test(next) && !isPowerShellSingleQuote(next) && !isPowerShellDoubleQuote(next))) {
                 return parseFailure('unsafe-expansion', input, index, argv.length, 'powershell');
             }
             // Append the registered value directly: spaces remain in this argument,
@@ -431,7 +1078,7 @@ function parseLiteralPowerShellCommand(command, options = {}) {
             continue;
         }
         if (quote === 'double') {
-            if (char === '"') {
+            if (isPowerShellDoubleQuote(char)) {
                 if (!isLiteralArgBoundary(input[index + 1]))
                     return parseFailure('invalid-quote', input, index, argv.length, 'powershell');
                 quote = null;
@@ -443,6 +1090,8 @@ function parseLiteralPowerShellCommand(command, options = {}) {
                     return parseFailure('invalid-quote', input, index, argv.length, 'powershell');
                 if (next === '\r' || next === '\n')
                     return parseFailure('structural-newline', input, index, argv.length, 'powershell');
+                if (isEcCommand && next === 'n')
+                    return parseFailure('unsupported-escape', input, index - 1, argv.length, 'powershell');
                 token += next;
                 continue;
             }
@@ -458,12 +1107,12 @@ function parseLiteralPowerShellCommand(command, options = {}) {
         if (/\s/u.test(char) || char.charCodeAt(0) < 0x20 || char === '\x7f') {
             return parseFailure('invalid-control-char', input, index, argv.length, 'powershell');
         }
-        if (char === "'") {
+        if (isPowerShellSingleQuote(char)) {
             tokenStarted = true;
             quote = 'single';
             continue;
         }
-        if (char === '"') {
+        if (isPowerShellDoubleQuote(char)) {
             tokenStarted = true;
             quote = 'double';
             continue;
@@ -474,6 +1123,8 @@ function parseLiteralPowerShellCommand(command, options = {}) {
                 return parseFailure('invalid-quote', input, index, argv.length, 'powershell');
             if (next === '\r' || next === '\n')
                 return parseFailure('structural-newline', input, index, argv.length, 'powershell');
+            if (isEcCommand && next === 'n')
+                return parseFailure('unsupported-escape', input, index - 1, argv.length, 'powershell');
             tokenStarted = true;
             token += next;
             continue;
@@ -671,7 +1322,7 @@ function resolveCodexPowerShellCarrierString(command) {
 /** Resolve a POSIX shell carrier when app-server provides only a string. */
 function resolveCodexPosixShellCarrierString(command) {
     const input = trimShellSpacing(command);
-    const match = input.match(/^(?:"([^"]+)"|(\S+))\s+(-lc|-c)\s+(.+)$/);
+    const match = input.match(/^(?:"([^"]+)"|(\S+))\s+(-lc|-c)\s+(.+)$/s);
     if (!match)
         return undefined;
     const executable = match[1] ?? match[2];
@@ -732,7 +1383,7 @@ function looksLikeEcCommandBody(command) {
         return false;
     const input = command.trim();
     const body = (input.startsWith('"') ? input.slice(1) : input).trimStart();
-    return /^ec(?:\.cmd|\.exe)?(?:\s|$)/i.test(body);
+    return /^ec(?:\.cmd|\.exe|\.ps1)?(?:\s|$)/i.test(body);
 }
 /** True only when a trusted cmd executable is carrying an EC command body. */
 export function hasCodexCmdCarrierEcIntent(input) {
@@ -811,7 +1462,7 @@ export function parseLiteralShellCommand(command, options = {}) {
         const char = input[index];
         if (quote === 'single') {
             if (char === "'") {
-                if (!isLiteralArgBoundary(input[index + 1]))
+                if (!isPosixQuotedTokenBoundary(input[index + 1]))
                     return parseFailure('invalid-quote', input, index, argv.length, 'posix');
                 quote = null;
             }
@@ -821,7 +1472,7 @@ export function parseLiteralShellCommand(command, options = {}) {
         }
         if (quote === 'double') {
             if (char === '"') {
-                if (!isLiteralArgBoundary(input[index + 1]))
+                if (!isPosixQuotedTokenBoundary(input[index + 1]))
                     return parseFailure('invalid-quote', input, index, argv.length, 'posix');
                 quote = null;
                 continue;
@@ -919,6 +1570,14 @@ export function unwrapCodexShellCommandArgv(argv) {
  * command still has to pass `parseLiteralShellCommand`.
  */
 export function parseCodexShellCommandArgv(command, options = {}) {
+    const powerShellCallOperatorCommand = parsePowerShellCallOperator(command);
+    if (powerShellCallOperatorCommand) {
+        const parsed = parseLiteralShellCommand(powerShellCallOperatorCommand, {
+            ...options,
+            dialect: 'powershell',
+        });
+        return parsed.ok ? canonicalizeEvolcoreCommandArgv(parsed.argv) : null;
+    }
     const outer = parseLiteralShellArgv(command, options);
     if (outer) {
         const carrier = resolveCodexShellCarrierArgv(outer);
@@ -951,6 +1610,19 @@ export function parseCodexToolCommand(input, options = {}) {
         const nulIndex = outer.findIndex(value => value.includes('\0'));
         if (nulIndex >= 0)
             return parseFailure('invalid-control-char', '', 0, nulIndex, 'posix');
+        if (outer.length === 1) {
+            const callOperatorCommand = parsePowerShellCallOperator(outer[0]);
+            if (callOperatorCommand) {
+                const parsed = parseLiteralShellCommand(callOperatorCommand, {
+                    allowManagedTmpDir: true,
+                    ...options,
+                    dialect: 'powershell',
+                });
+                return parsed.ok
+                    ? { ...parsed, argv: normalizeEvolcoreCommandArgv(parsed.argv) }
+                    : parsed;
+            }
+        }
         const carrier = resolveCodexShellCarrierArgv(outer);
         if (carrier === undefined) {
             return parseCodexCmdCarrierArgvFailure(outer)
@@ -959,6 +1631,17 @@ export function parseCodexToolCommand(input, options = {}) {
         return parseCodexCarrierCommand(carrier, { allowManagedTmpDir: true, ...options });
     }
     const command = typeof input.command === 'string' ? input.command : '';
+    const callOperatorCommand = parsePowerShellCallOperator(command);
+    if (callOperatorCommand) {
+        const parsed = parseLiteralShellCommand(callOperatorCommand, {
+            allowManagedTmpDir: true,
+            ...options,
+            dialect: 'powershell',
+        });
+        return parsed.ok
+            ? { ...parsed, argv: normalizeEvolcoreCommandArgv(parsed.argv) }
+            : parsed;
+    }
     const outer = parseLiteralShellCommand(command, { allowManagedTmpDir: true });
     if (outer.ok) {
         const carrier = resolveCodexShellCarrierArgv(outer.argv);
@@ -976,6 +1659,98 @@ export function parseCodexToolCommand(input, options = {}) {
         ? parseCodexCarrierCommand(stringCarrier, { allowManagedTmpDir: true, ...options })
         : parseCodexCmdCarrierStringFailure(command, { allowManagedTmpDir: true }) ?? outer;
 }
+function isApplyPatchExecutable(value) {
+    const normalized = value.replaceAll('\\', '/').replace(/\/+$/u, '');
+    const basename = normalized.slice(normalized.lastIndexOf('/') + 1).toLowerCase();
+    return APPLY_PATCH_EXECUTABLE_BASENAMES.has(basename);
+}
+function normalizeApplyPatchPath(value) {
+    const normalized = value.trim();
+    if (!normalized || /[\0\r\n]/u.test(normalized))
+        return undefined;
+    return normalized;
+}
+function parseApplyPatchDocument(source) {
+    const lines = source.replace(/\r\n?/gu, '\n').split('\n');
+    while (lines.at(-1) === '')
+        lines.pop();
+    if (lines[0] !== '*** Begin Patch' || lines.at(-1) !== '*** End Patch')
+        return undefined;
+    const changes = [];
+    const seen = new Set();
+    let index = 1;
+    while (index < lines.length - 1) {
+        const header = lines[index].match(/^\*\*\* (Add|Delete|Update) File: (.+)$/u);
+        if (!header)
+            return undefined;
+        const kind = header[1].toLowerCase();
+        const filePath = normalizeApplyPatchPath(header[2]);
+        if (!filePath)
+            return undefined;
+        const key = filePath.replaceAll('\\', '/').toLowerCase();
+        if (seen.has(key))
+            return undefined;
+        seen.add(key);
+        index++;
+        let movePath;
+        if (kind === 'update' && lines[index]?.startsWith('*** Move to: ')) {
+            movePath = normalizeApplyPatchPath(lines[index].slice('*** Move to: '.length));
+            if (!movePath)
+                return undefined;
+            index++;
+        }
+        while (index < lines.length - 1 && !/^\*\*\* (?:Add|Delete|Update) File: /u.test(lines[index])) {
+            const line = lines[index];
+            if (kind === 'delete')
+                return undefined;
+            if (line !== '*** End of File') {
+                const validLine = kind === 'add'
+                    ? line.startsWith('+')
+                    : line.startsWith('@@')
+                        || line.startsWith('+')
+                        || line.startsWith('-')
+                        || line.startsWith(' ')
+                        || line === '\';
+                if (!validLine)
+                    return undefined;
+            }
+            index++;
+        }
+        changes.push({ path: filePath, kind, ...(movePath ? { movePath } : {}) });
+    }
+    return changes.length > 0 ? changes : undefined;
+}
+function argvUsesShellApplyPatch(argv) {
+    if (argv.length === 0)
+        return false;
+    return isApplyPatchExecutable(argv[0]);
+}
+function leadingShellExecutable(command) {
+    let input = command.trim();
+    if (input.startsWith('&'))
+        input = input.slice(1).trimStart();
+    if (!input)
+        return undefined;
+    const quote = input[0];
+    if (quote === '"' || quote === "'") {
+        const end = input.indexOf(quote, 1);
+        return end > 1 ? input.slice(1, end) : undefined;
+    }
+    return input.split(/[\s]/u, 1)[0] || undefined;
+}
+/**
+ * Detect the shell fallback that tries to perform a file edit outside Codex's
+ * structured FileChange/Edit protocol. The executable check intentionally
+ * looks only at argv[0], so ordinary searches such as `rg apply_patch` remain
+ * valid.
+ */
+export function isShellApplyPatchInvocation(input, parsedArgv, options = {}) {
+    const parsed = parseShellApplyPatchInvocation(input, {
+        ...options,
+        verifyShellExecutable: false,
+    }, parsedArgv);
+    return parsed.kind !== 'not-apply-patch';
+}
 /**
  * Resolve a Codex command input while preserving the raw `commandArgv` form
  * supplied by app-server. Joining that argv with spaces loses the quoting of
@@ -1547,29 +2322,38 @@ function scanBoundedOutputOperators(command) {
     return quote ? null : operators;
 }
 /**
- * Accept `head` as a generic, trusted stdout filter without mirroring its
- * option grammar here. Non-option operands are the security boundary: they
- * could make `head` read a file instead of the EC process' stdout.
+ * Accept one trusted stdout filter after an EC invocation. The security
+ * boundary is that the filter may only consume the EC process' stdout: every
+ * non-option operand must be accounted for by the filter's operand budget, and
+ * every option must appear in its allowlist. Unknown or malformed options make
+ * the filter itself fail rather than widening what it can reach.
  *
- * GNU/POSIX head only uses a separate value for -n/-c (and their long forms).
- * All other dash-prefixed arguments are safe to leave to head itself; unknown
- * or malformed options simply make head fail.
+ * Returns the full filter argv (executable included) so the spawn helper can
+ * execute exactly what policy validated.
  */
-function parseStdinOnlyHeadArgs(segment) {
+export function parseStdinOnlyFilterArgv(segment) {
     const argv = parseLiteralShellArgv(segment);
-    if (!argv || !HEAD_EXECUTABLES.has(argv[0]))
+    if (!argv)
+        return null;
+    const executable = normalizeStdoutFilterExecutable(argv[0]);
+    if (!executable)
         return null;
-    const args = argv.slice(1);
+    const spec = STDOUT_FILTER_SPECS.get(executable);
+    if (!spec)
+        return null;
+    let operands = 0;
+    let sawPatternValue = false;
     let optionsEnded = false;
     let expectsOptionValue = false;
-    for (const arg of args) {
+    for (let index = 1; index < argv.length; index++) {
+        const arg = argv[index];
         if (expectsOptionValue) {
             expectsOptionValue = false;
             continue;
         }
         if (optionsEnded) {
             if (arg !== '-')
-                return null;
+                operands++;
             continue;
         }
         if (arg === '--') {
@@ -1578,18 +2362,43 @@ function parseStdinOnlyHeadArgs(segment) {
         }
         if (arg === '-')
             continue;
-        if (!arg.startsWith('-'))
-            return null;
-        if (arg === '-n' || arg === '-c' || arg === '--lines' || arg === '--bytes') {
-            expectsOptionValue = true;
+        if (!arg.startsWith('-')) {
+            operands++;
+            continue;
+        }
+        if (spec.numericShorthand && /^-\d+$/.test(arg))
+            continue;
+        const option = arg.split('=', 1)[0];
+        if (spec.patternValueOptions?.has(option)) {
+            sawPatternValue = true;
+            // `-ePATTERN` and `--regexp=PATTERN` carry their own value; only the
+            // bare forms consume the next token.
+            if (!arg.includes('=') && arg.length === option.length)
+                expectsOptionValue = true;
+            continue;
+        }
+        if (spec.valueOptions.has(option)) {
+            if (!arg.includes('=') && arg.length === option.length)
+                expectsOptionValue = true;
             continue;
         }
+        if (spec.flags.has(arg))
+            continue;
+        return null;
     }
-    return args;
+    // An explicit pattern option means every remaining operand would be a file
+    // to read, so the operand budget drops to zero.
+    const operandBudget = sawPatternValue ? 0 : spec.maxOperands;
+    if (operands > operandBudget)
+        return null;
+    if (spec.patternValueOptions && !sawPatternValue && operands === 0)
+        return null;
+    return [executable, ...argv.slice(1)];
 }
 /**
  * Parse the only shell wrapper allowed around a privileged literal process:
- * optional stderr merge, one bounded `head`, and one create-only output path.
+ * optional stderr merge, one trusted stdin-only stdout filter, and one
+ * create-only output path.
  */
 export function parseBoundedOutputShellCommand(command) {
     const input = trimShellSpacing(substituteManagedTmpDirToken(command));
@@ -1598,16 +2407,17 @@ export function parseBoundedOutputShellCommand(command) {
     const operators = scanBoundedOutputOperators(input);
     if (!operators || operators.length === 0)
         return null;
-    const pattern = operators.map(operator => operator.kind).join(',');
-    if (![
-        'merge-stderr',
-        'pipe',
-        'pipe,redirect',
-        'merge-stderr,pipe',
-        'merge-stderr,pipe,redirect',
-        'redirect',
-    ].includes(pattern))
-        return null;
+    // 允许的形态：可选的 2>&1 合并 + **任意长度**的受控过滤器管道链 + 可选重定向。
+    // 不再枚举具体管道段数（旧实现只列了单段+重定向，模型写 `| grep | head` 就掉出去）。
+    // 放宽的依据：每一级过滤器都要过同一个 stdin-only 白名单，能力面不随段数增长。
+    let cursor = 0;
+    let mergeStderr = false;
+    if (operators[cursor]?.kind === 'merge-stderr') {
+        mergeStderr = true;
+        cursor++;
+    }
+    // 源命令是第一个操作符**之前**的全部文本。合并 stderr 的 `2>&1` 本身也是操作符，
+    // 所以两种情况都切在 operators[0].start，绝不能按 end 切——那会把 `2>&1` 混进 argv。
     const first = operators[0];
     const sourceText = trimShellSpacing(input.slice(0, first.start));
     const argv = parseLiteralShellArgv(sourceText);
@@ -1617,48 +2427,161 @@ export function parseBoundedOutputShellCommand(command) {
     // expansion for the privileged command itself.
     if (argv.some(value => value.includes(MANAGED_TMPDIR_TOKEN)))
         return null;
-    let mergeStderr = false;
-    let pipe;
-    let redirect;
-    if (first.kind === 'merge-stderr') {
-        mergeStderr = true;
-        if (operators.length === 1)
-            return { argv, mergeStderr };
-        pipe = operators[1];
-        if (!pipe || pipe.kind !== 'pipe')
+    const filterChain = [];
+    let outputPath;
+    let prevEnd = mergeStderr ? operators[0].end : first.start;
+    while (cursor < operators.length) {
+        const operator = operators[cursor];
+        // 段与段之间只允许空白（合并 stderr 与首个管道之间同理）。
+        if (trimShellSpacing(input.slice(prevEnd, operator.start)))
             return null;
-        if (trimShellSpacing(input.slice(first.end, pipe.start)))
+        if (operator.kind === 'redirect') {
+            // 重定向必须是最后一段；其后再出现操作符即拒绝。
+            if (cursor !== operators.length - 1)
+                return null;
+            const outputArgv = parseLiteralShellArgv(trimShellSpacing(input.slice(operator.end)));
+            if (!outputArgv || outputArgv.length !== 1)
+                return null;
+            if (outputArgv[0].includes('$') && !outputArgv[0].includes(MANAGED_TMPDIR_TOKEN))
+                return null;
+            outputPath = restoreManagedTmpDirToken(outputArgv[0]);
+            cursor++;
+            break;
+        }
+        if (operator.kind !== 'pipe')
             return null;
-        redirect = operators[2];
-    }
-    else if (first.kind === 'pipe') {
-        pipe = first;
-        redirect = operators[1];
-    }
-    else {
-        redirect = first;
-    }
-    let headArgs;
-    if (pipe) {
-        const headEnd = redirect?.start ?? input.length;
-        const parsedArgs = parseStdinOnlyHeadArgs(trimShellSpacing(input.slice(pipe.end, headEnd)));
+        // 该管道的下游终点：下一个操作符起点，或输入末尾。
+        const next = operators[cursor + 1];
+        const segmentEnd = next ? next.start : input.length;
+        const parsedArgs = parseStdinOnlyFilterArgv(trimShellSpacing(input.slice(operator.end, segmentEnd)));
         if (parsedArgs === null)
             return null;
-        headArgs = parsedArgs;
+        filterChain.push(parsedArgs);
+        prevEnd = segmentEnd;
+        cursor++;
     }
-    let outputPath;
-    if (redirect) {
-        const outputArgv = parseLiteralShellArgv(trimShellSpacing(input.slice(redirect.end)));
-        if (!outputArgv || outputArgv.length !== 1)
-            return null;
-        // A single-quoted or escaped `$TMPDIR` is literal shell text, not the
-        // managed directory reference. Do not reinterpret it as a route to the
-        // session temp root.
-        if (outputArgv[0].includes('$') && !outputArgv[0].includes(MANAGED_TMPDIR_TOKEN))
+    return {
+        argv,
+        mergeStderr,
+        ...(filterChain.length > 0 ? { filterChain } : {}),
+        ...(outputPath ? { outputPath } : {}),
+    };
+}
+/**
+ * 每段必须自己就能通过零副作用校验，否则整条拒绝。
+ *
+ * 判据是「这段的字面量 argv 不含任何会被 shell 二次解释的字符」：`$`、反引号、
+ * 通配、括号、重定向、管道、以及 `&&`/`;` 本身。引号包裹的普通文本（如
+ * `echo "extra"`）合法；`echo $?`、`echo \`id\``、`echo *` 一律不合法。
+ */
+function parseInertSegment(segment) {
+    const text = trimShellSpacing(segment);
+    if (!text)
+        return null;
+    const argv = parseLiteralShellArgv(text);
+    if (!argv || argv.length === 0)
+        return null;
+    // 字面量解析已处理引号；拒绝任何仍可能造成展开或结构变化的字符。
+    // 注意**不含反斜杠**：Windows 路径必然带 `\`，而解析后的 argv 直接交给
+    // spawn、不经 shell，反斜杠不会被再解释一次；`cd` 的目标另有范围校验。
+    if (argv.some(value => /[$`*?\[\]{}()<>|;&]/.test(value)))
+        return null;
+    return argv;
+}
+function isInertSegment(argv) {
+    if (argv.length === 0)
+        return false;
+    // cd 的额外约束（唯一参数、必须在前缀位、目录范围）在调用处单独校验。
+    return argv[0] === 'pwd' || argv[0] === 'echo' || argv[0] === 'cd';
+}
+/**
+ * 识别「零副作用前后缀 + 恰好一条 ec」的可证拼接。
+ *
+ * 模型最常见的写法是"先切目录再跑命令"或"跑完打印一行提示"，而这些会被通用
+ * 拼接规则一律拒绝。这里只放行**结构可证**的窄形态：
+ *   - 按顶层 `&&` / `;` 切段（`||`、`&`、`|` 语义不同，直接拒绝不参与切分）
+ *   - 恰好一段能解析成 ec 命令（`ec ...`，或 `ec ... | 受控过滤器`）
+ *   - 其余每一段都必须是零副作用段：`cd <字面量目录>` / `pwd` / `echo <字面量>`
+ *   - `cd` 至多一段且必须是前缀；目录无变量/通配，由 policy 层校验范围
+ *
+ * 返回 ec 段的 argv（调用方按 bounded-output 同样的方式直接 spawn，不经 shell）。
+ * 前后的零副作用段只用来判定结构，不参与执行。
+ */
+export function parseCdPrefixedEcCommand(input) {
+    const text = trimShellSpacing(input);
+    if (!text)
+        return null;
+    // 只看 `&&` 与 `;` 两种分隔符；以下形态语义不同，一律拒绝：
+    //   `||` 短路、`&&&`、以及真正的后台执行 `&`。
+    // 两点必须注意：
+    //   1. 不能写成 `[^|]&[^&]`——它会命中 ` && ` 里的「空格 + & + 空格」，
+    //      把正常拼接一并拒掉，所以用前后断言。
+    //   2. `2>&1` 里的 `&` 是重定向，不是后台符号，必须先剔除再找裸 `&`。
+    const withoutFdRedirect = text.replace(/[0-9]?>>?&[0-9]+/g, ' ');
+    if (/\|\||&&&/.test(text) || /(?<!&)&(?!&)/.test(withoutFdRedirect))
+        return null;
+    const segments = text.split(/(?:\s*&&\s*|\s*;\s*)/).map(trimShellSpacing).filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    let cwd;
+    let ecCommand;
+    let suffix;
+    let ecIndex = -1;
+    for (let index = 0; index < segments.length; index++) {
+        const segment = segments[index];
+        const parsed = parseEcTail(segment);
+        if (parsed) {
+            if (ecCommand)
+                return null; // 两条 ec，拒绝
+            ecCommand = parsed;
+            ecIndex = index;
+            continue;
+        }
+        // 非 ec 段：只允许零副作用形态。
+        const argv = parseInertSegment(segment);
+        if (!argv || !isInertSegment(argv))
             return null;
-        outputPath = restoreManagedTmpDirToken(outputArgv[0]);
+        if (argv[0] === 'cd') {
+            // cd 必须以字面量目录为唯一参数，且只能出现在 ec 之前。
+            // ecIndex 为 -1 表示尚未遇到 ec，此时按定义 cd 就在前面。
+            if (argv.length !== 2 || cwd !== undefined || (ecIndex >= 0 && index > ecIndex))
+                return null;
+            const dir = argv[1];
+            if (!dir || dir.startsWith('-'))
+                return null;
+            cwd = dir;
+            continue;
+        }
+        // pwd / echo：ec 之前只是分隔提示，不执行；ec 之后作为尾部命令执行一次。
+        // 实参已在 parseInertSegment 里过滤成纯字面量，不含变量/通配/重定向。
+        if (ecIndex >= 0) {
+            if (suffix)
+                return null; // 至多一段尾部命令
+            suffix = argv;
+        }
     }
-    return { argv, mergeStderr, ...(headArgs ? { headArgs } : {}), ...(outputPath ? { outputPath } : {}) };
+    if (!ecCommand)
+        return null;
+    return {
+        ...(cwd ? { cwd } : {}),
+        command: { ...ecCommand, ...(suffix ? { suffixArgv: suffix } : {}) },
+    };
+}
+/**
+ * 解析白名单里 ec 那一段，接受两种形态：
+ *   1. 单条字面量 `ec ...`
+ *   2. `ec ... 2>&1 | head` 这类已有受控过滤器（bounded-output）
+ * 两者都直接产出 argv 交给运行器，不再经 shell。其它一律返回 null。
+ */
+function parseEcTail(segment) {
+    const literal = parseLiteralShellArgv(segment);
+    if (literal && literal.length > 0 && normalizeEvolcoreCommandArgv(literal)[0] === 'ec') {
+        return { argv: literal, mergeStderr: false };
+    }
+    const bounded = parseBoundedOutputShellCommand(segment);
+    if (bounded && bounded.argv[0] === 'ec')
+        return bounded;
+    return null;
 }
 /**
  * Classify only the shell boundary around an EC process invocation. Runner
@@ -1667,7 +2590,30 @@ export function parseBoundedOutputShellCommand(command) {
  */
 export function classifyEvolcoreShellCommand(command, options = {}) {
     const parseOptions = { allowManagedTmpDir: true, ...options };
-    const literal = parseLiteralShellCommand(command, parseOptions);
+    // heredoc 正文是数据不是语法，先剥掉再判——否则提交信息里的 `; ec ...`
+    // 会被当成本轮真的拼接调用（详见 stripHeredocBodies）。
+    const stripped = stripHeredocBodies(command);
+    const powerShellCallOperatorIntent = looksLikePowerShellEvolcoreCallOperator(stripped, options.dialect);
+    const powerShellCallOperatorCommand = powerShellCallOperatorIntent
+        ? parsePowerShellCallOperator(stripped)
+        : undefined;
+    if (powerShellCallOperatorCommand) {
+        const parsed = parseLiteralShellCommand(powerShellCallOperatorCommand, {
+            ...parseOptions,
+            dialect: 'powershell',
+        });
+        if (parsed.ok && normalizeEvolcoreCommandArgv(parsed.argv)[0] === 'ec')
+            return { kind: 'literal' };
+        return { kind: 'composite', issue: parsed.ok ? 'shell-composition' : parsed.issue };
+    }
+    if (powerShellCallOperatorIntent) {
+        const parsed = parseLiteralShellCommand(stripped, {
+            ...parseOptions,
+            dialect: 'powershell',
+        });
+        return { kind: 'composite', issue: parsed.ok ? 'shell-composition' : parsed.issue };
+    }
+    const literal = parseLiteralShellCommand(stripped, parseOptions);
     if (literal.ok) {
         if (normalizeEvolcoreCommandArgv(literal.argv)[0] === 'ec')
             return { kind: 'literal' };
@@ -1681,7 +2627,7 @@ export function classifyEvolcoreShellCommand(command, options = {}) {
                 return { kind: 'composite', issue: nested.issue };
             }
         }
-        const stringCarrier = resolveCodexShellCarrierString(command);
+        const stringCarrier = resolveCodexShellCarrierString(stripped);
         if (stringCarrier) {
             const nested = parseCodexCarrierCommand(stringCarrier, parseOptions);
             if (nested.ok && nested.argv[0] === 'ec')
@@ -1691,7 +2637,7 @@ export function classifyEvolcoreShellCommand(command, options = {}) {
                 return { kind: 'composite', issue: nested.issue };
             }
         }
-        const malformedCmdBody = extractCodexCmdCarrierBody(command);
+        const malformedCmdBody = extractCodexCmdCarrierBody(stripped);
         if (malformedCmdBody && looksLikeEcCommandBody(malformedCmdBody)) {
             const nested = parseLiteralShellCommand(malformedCmdBody, {
                 ...parseOptions,
@@ -1703,7 +2649,7 @@ export function classifyEvolcoreShellCommand(command, options = {}) {
         }
         return { kind: 'none' };
     }
-    const stringCarrier = resolveCodexShellCarrierString(command);
+    const stringCarrier = resolveCodexShellCarrierString(stripped);
     if (stringCarrier) {
         const nested = parseCodexCarrierCommand(stringCarrier, parseOptions);
         if (nested.ok && nested.argv[0] === 'ec')
@@ -1714,7 +2660,7 @@ export function classifyEvolcoreShellCommand(command, options = {}) {
         }
         return { kind: 'none' };
     }
-    const malformedCmdBody = extractCodexCmdCarrierBody(command);
+    const malformedCmdBody = extractCodexCmdCarrierBody(stripped);
     if (malformedCmdBody && looksLikeEcCommandBody(malformedCmdBody)) {
         const nested = parseLiteralShellCommand(malformedCmdBody, {
             ...parseOptions,
@@ -1726,14 +2672,21 @@ export function classifyEvolcoreShellCommand(command, options = {}) {
     }
     const boundedOutput = options.dialect === 'powershell' || options.dialect === 'cmd'
         ? null
-        : parseBoundedOutputShellCommand(command);
+        : parseBoundedOutputShellCommand(stripped);
     if (boundedOutput && boundedOutput.argv[0] === 'ec') {
         return { kind: 'bounded-output', command: boundedOutput };
     }
+    // `cd <字面量目录> && ec ...`：切目录是模型最常见的写法，结构可证时放行。
+    // 只放宽前缀，ec 段仍走完整的字面量解析。
+    const cdPrefixed = options.dialect === 'powershell' || options.dialect === 'cmd'
+        ? null
+        : parseCdPrefixedEcCommand(stripped);
+    if (cdPrefixed)
+        return { kind: 'cd-prefixed', command: cdPrefixed.command, cwd: cdPrefixed.cwd };
     // Only a command-boundary prefix is enough to preserve a useful syntax
     // error for a malformed direct EC invocation. Never scan for EC tokens in
     // arbitrary raw text after parsing fails.
-    return hasEcCommandPrefix(command)
+    return hasEcCommandPrefix(stripped)
         ? { kind: 'composite', issue: literal.issue }
         : { kind: 'none' };
 }
@@ -1829,6 +2782,10 @@ export function containsLiteralManagedTmpDirOutsideSendContent(argv) {
         return true;
     return literalIndexes.some(index => !textIndexes.has(index));
 }
+/** Shell-escaped TMPDIR references are literal text and must not authorize file paths. */
+export function containsUnresolvedManagedTmpDirReference(argv) {
+    return argv.some(value => /(?:\\\$TMPDIR|\\\$\{TMPDIR\})/i.test(value));
+}
 function hasExecutableProactiveSendPayload(argv, scope) {
     if (!argv || argv[0] !== 'ec' || argv[1] !== scope || argv[2] !== 'send')
         return false;