evolcore 0.0.2 → 0.0.4

package/dist/core/message/send-receipt.js

@@ -0,0 +1,24 @@
+export function sendOperationId(envelope) {
+    return envelope.operationId || envelope.taskId;
+}
+export function sentReceipt(envelope, messageIds, threadId) {
+    const messages = messageIds
+        .filter((messageId) => typeof messageId === 'string' && messageId.length > 0)
+        .map((messageId, partIndex) => ({ messageId, partIndex, threadId }));
+    if (messages.length === 0) {
+        throw new Error(`MISSING_MESSAGE_ID: operation=${sendOperationId(envelope)}`);
+    }
+    return {
+        status: 'sent',
+        operationId: sendOperationId(envelope),
+        messages: messages,
+    };
+}
+export function suppressedReceipt(envelope, reason) {
+    return {
+        status: 'suppressed',
+        operationId: sendOperationId(envelope),
+        messages: [],
+        reason,
+    };
+}

package/dist/core/message/stream-debouncer.js

@@ -27,9 +27,9 @@ export class StreamDebouncer {
      * 否则新建窗口。timer 到期后自动 flush。
      */
     submit(key, message, enqueue) {
-        const { content, images, mentions, messageId, replyContext, ...rest } = message;
+        const { content, images, mentions, messageId, sourceMessageIds, replyContext, ...rest } = message;
         return new Promise((resolve, reject) => {
-            const entry = { messageId, content, images, mentions, replyContext, rest, resolve, reject };
+            const entry = { messageId, sourceMessageIds, content, images, mentions, replyContext, rest, resolve, reject };
             const win = this.pending.get(key);
             if (win) {
                 clearTimeout(win.timer);
@@ -87,12 +87,20 @@ export class StreamDebouncer {
         const allImages = [];
         const allMentions = [];
         const contents = [];
+        const sourceMessageIds = [];
+        const seenSourceMessageIds = new Set();
         for (const e of entries) {
             contents.push(e.content);
             if (e.images)
                 allImages.push(...e.images);
             if (e.mentions)
                 allMentions.push(...e.mentions);
+            for (const id of [...(e.sourceMessageIds ?? []), ...(e.messageId ? [e.messageId] : [])]) {
+                if (!seenSourceMessageIds.has(id)) {
+                    seenSourceMessageIds.add(id);
+                    sourceMessageIds.push(id);
+                }
+            }
         }
         const last = entries[entries.length - 1];
         // 合并后保留最新一条的 messageId（用于 thought 锚定与中断追踪）
@@ -110,6 +118,7 @@ export class StreamDebouncer {
             mentions: allMentions.length > 0 ? allMentions : undefined,
             replyContext: last.replyContext,
             messageId: latestMessageId,
+            sourceMessageIds: sourceMessageIds.length > 0 ? sourceMessageIds : undefined,
         };
         const resolves = entries.map(e => e.resolve);
         const rejects = entries.map(e => e.reject);

package/dist/core/permission/approval-gateway.js

@@ -55,10 +55,10 @@ function structuredApprovalAuditSummary(input) {
         .slice(0, 16);
     return fields.length > 0 ? `input_fields=${fields.join(',')}` : 'input_withheld';
 }
-function requiredApproverRole(policy, routeKind) {
+function requiredApproverRole(policy) {
     if (policy === 'requester')
         return 'requester';
-    if (policy === 'agent_owner' || routeKind === 'handoff')
+    if (policy === 'agent_owner')
         return 'owner';
     return 'manager';
 }
@@ -148,13 +148,20 @@ export function planApprovalRoute(challenge, context) {
             approverPrincipalId: actor.principalId,
         };
     }
-    if (owners.length === 0) {
-        return { kind: 'unavailable', reason: 'no_agent_owner_configured' };
+    const handoffCandidates = challenge.approverPolicy === 'agent_manager'
+        ? Array.from(new Set([...admins, ...owners]))
+        : owners;
+    if (handoffCandidates.length === 0) {
+        return {
+            kind: 'unavailable',
+            reason: challenge.approverPolicy === 'agent_manager'
+                ? 'no_agent_manager_configured'
+                : 'no_agent_owner_configured',
+        };
     }
-    // Both management policies hand off to the first configured AUN owner.
-    // Admin handoff approval and implicit approver selection are intentionally
-    // out of scope; a future caller may explicitly select from the owner list.
-    const approverId = owners[0];
+    // Manager handoffs prefer the configured admin pool for routine approvals;
+    // owner-only policies remain restricted to owners. Only one card is sent.
+    const approverId = handoffCandidates[0];
     if (!approverId) {
         return { kind: 'unavailable', reason: 'no_aun_owner_available' };
     }
@@ -505,7 +512,7 @@ export class PermissionGateway {
                 grantScope,
                 approverPolicy: challenge.approverPolicy,
                 approvalRouteKind: route.kind,
-                requiredApproverRole: requiredApproverRole(challenge.approverPolicy, route.kind),
+                requiredApproverRole: requiredApproverRole(challenge.approverPolicy),
                 approverOperatorId: route.approverOperatorId,
                 approverChannelKey: route.approverChannelKey,
                 approverPrincipalId: route.approverPrincipalId,
@@ -763,7 +770,7 @@ export class PermissionGateway {
                 grantScope,
                 approverPolicy: challenge.approverPolicy,
                 approvalRouteKind: route.kind,
-                requiredApproverRole: requiredApproverRole(challenge.approverPolicy, route.kind),
+                requiredApproverRole: requiredApproverRole(challenge.approverPolicy),
                 approverOperatorId: route.approverOperatorId,
                 approverChannelKey: route.approverChannelKey,
                 approverPrincipalId: route.approverPrincipalId,

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

@@ -1,5 +1,4 @@
-const DEFAULT_HEAD_LINES = 10;
-const MAX_HEAD_LINES = 10_000;
+const HEAD_EXECUTABLES = new Set(['head', '/bin/head', '/usr/bin/head']);
 const SHELL_UNQUOTED_META = new Set([
     ';', '&', '|', '`', '<', '>', '$', '(', ')', '*', '?', '[', ']', '{', '}', '#',
 ]);
@@ -11,16 +10,36 @@ function trimShellSpacing(value) {
 function isShellSpacing(value) {
     return value === ' ' || value === '\t';
 }
+function isLiteralArgBoundary(value) {
+    return value === undefined || isShellSpacing(value);
+}
+function isShellParameterExpansionStart(value) {
+    return value === '(' || value === '{' || !!value && /[A-Za-z0-9_@*#?$!\-]/.test(value);
+}
+function doubleQuotedIssueAt(input, index) {
+    const char = input[index];
+    if (char === '`' || (char === '$' && isShellParameterExpansionStart(input[index + 1]))) {
+        return 'unsafe-expansion';
+    }
+    if (char !== '\\')
+        return null;
+    const next = input[index + 1];
+    if (next === undefined)
+        return 'invalid-quote';
+    return next === '\r' || next === '\n' ? 'structural-newline' : null;
+}
 /**
  * Parse the deliberately small shell subset accepted by the privileged EC
  * command path. The returned argv must describe one literal invocation: no
  * expansion, glob, pipeline, command substitution, redirection, or comment.
  * Anything outside this subset is never granted the privileged EC path.
  */
-export function parseLiteralShellArgv(command) {
+export function parseLiteralShellCommand(command) {
     const input = trimShellSpacing(command);
-    if (!input || input.includes('\0'))
-        return null;
+    if (!input)
+        return { ok: false, issue: 'empty-command' };
+    if (input.includes('\0'))
+        return { ok: false, issue: 'invalid-control-char' };
     const argv = [];
     let token = '';
     let tokenStarted = false;
@@ -35,26 +54,28 @@ export function parseLiteralShellArgv(command) {
     for (let index = 0; index < input.length; index++) {
         const char = input[index];
         if (quote === 'single') {
-            if (char === "'")
+            if (char === "'") {
+                if (!isLiteralArgBoundary(input[index + 1]))
+                    return { ok: false, issue: 'invalid-quote' };
                 quote = null;
+            }
             else
                 token += char;
             continue;
         }
         if (quote === 'double') {
             if (char === '"') {
+                if (!isLiteralArgBoundary(input[index + 1]))
+                    return { ok: false, issue: 'invalid-quote' };
                 quote = null;
                 continue;
             }
-            if (char === '$' || char === '`')
-                return null;
+            const issue = doubleQuotedIssueAt(input, index);
+            if (issue)
+                return { ok: false, issue };
             if (char === '\\') {
                 const next = input[++index];
-                if (next === undefined || next === '\r' || next === '\n')
-                    return null;
-                if (next === '$' || next === '`')
-                    return null;
-                token += ['"', '\\'].includes(next) ? next : `\\${next}`;
+                token += ['"', '\\', '$', '`'].includes(next) ? next : `\\${next}`;
                 continue;
             }
             token += char;
@@ -70,8 +91,11 @@ export function parseLiteralShellArgv(command) {
         // includes NBSP, line/paragraph separators, VT and FF, which the shell
         // keeps inside the executable name; accepting those would misclassify a
         // different executable as `ec`.
-        if (char === '\r' || char === '\n' || /\s/u.test(char) || char.charCodeAt(0) < 0x20 || char === '\x7f')
-            return null;
+        if (char === '\r' || char === '\n')
+            return { ok: false, issue: 'structural-newline' };
+        if (/\s/u.test(char) || char.charCodeAt(0) < 0x20 || char === '\x7f') {
+            return { ok: false, issue: 'invalid-control-char' };
+        }
         if (char === "'") {
             tokenStarted = true;
             quote = 'single';
@@ -84,8 +108,10 @@ export function parseLiteralShellArgv(command) {
         }
         if (char === '\\') {
             const next = input[++index];
-            if (next === undefined || next === '\r' || next === '\n')
-                return null;
+            if (next === undefined)
+                return { ok: false, issue: 'invalid-quote' };
+            if (next === '\r' || next === '\n')
+                return { ok: false, issue: 'structural-newline' };
             tokenStarted = true;
             token += next;
             continue;
@@ -94,14 +120,20 @@ export function parseLiteralShellArgv(command) {
         // peer keys such as `aun#alice` are ordinary literal arguments.
         if ((SHELL_UNQUOTED_META.has(char) && (char !== '#' || !tokenStarted))
             || (char === '~' && !tokenStarted))
-            return null;
+            return { ok: false, issue: 'shell-composition' };
         tokenStarted = true;
         token += char;
     }
     if (quote)
-        return null;
+        return { ok: false, issue: 'invalid-quote' };
     finishToken();
-    return argv.length > 0 ? argv : null;
+    return argv.length > 0
+        ? { ok: true, argv }
+        : { ok: false, issue: 'empty-command' };
+}
+export function parseLiteralShellArgv(command) {
+    const result = parseLiteralShellCommand(command);
+    return result.ok ? result.argv : null;
 }
 function scanBoundedOutputOperators(command) {
     const operators = [];
@@ -118,12 +150,10 @@ function scanBoundedOutputOperators(command) {
                 quote = null;
                 continue;
             }
-            if (char === '$' || char === '`')
+            if (doubleQuotedIssueAt(command, index))
                 return null;
             if (char === '\\') {
-                const next = command[++index];
-                if (next === undefined || next === '\r' || next === '\n' || next === '$' || next === '`')
-                    return null;
+                index++;
             }
             continue;
         }
@@ -171,21 +201,46 @@ function scanBoundedOutputOperators(command) {
     }
     return quote ? null : operators;
 }
-function parseHeadLines(segment) {
+/**
+ * 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.
+ *
+ * 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.
+ */
+function parseStdinOnlyHeadArgs(segment) {
     const argv = parseLiteralShellArgv(segment);
-    if (!argv || (argv[0] !== 'head' && argv[0] !== '/usr/bin/head'))
-        return null;
-    let value;
-    if (argv.length === 1)
-        value = String(DEFAULT_HEAD_LINES);
-    else if (argv.length === 2 && /^-\d+$/.test(argv[1]))
-        value = argv[1].slice(1);
-    else if (argv.length === 3 && argv[1] === '-n' && /^\d+$/.test(argv[2]))
-        value = argv[2];
-    else
+    if (!argv || !HEAD_EXECUTABLES.has(argv[0]))
         return null;
-    const lines = Number(value);
-    return Number.isSafeInteger(lines) && lines >= 1 && lines <= MAX_HEAD_LINES ? lines : null;
+    const args = argv.slice(1);
+    let optionsEnded = false;
+    let expectsOptionValue = false;
+    for (const arg of args) {
+        if (expectsOptionValue) {
+            expectsOptionValue = false;
+            continue;
+        }
+        if (optionsEnded) {
+            if (arg !== '-')
+                return null;
+            continue;
+        }
+        if (arg === '--') {
+            optionsEnded = true;
+            continue;
+        }
+        if (arg === '-')
+            continue;
+        if (!arg.startsWith('-'))
+            return null;
+        if (arg === '-n' || arg === '-c' || arg === '--lines' || arg === '--bytes') {
+            expectsOptionValue = true;
+            continue;
+        }
+    }
+    return args;
 }
 /**
  * Parse the only shell wrapper allowed around a privileged literal process:
@@ -234,13 +289,13 @@ export function parseBoundedOutputShellCommand(command) {
     else {
         redirect = first;
     }
-    let headLines;
+    let headArgs;
     if (pipe) {
         const headEnd = redirect?.start ?? input.length;
-        const parsedLines = parseHeadLines(trimShellSpacing(input.slice(pipe.end, headEnd)));
-        if (parsedLines === null)
+        const parsedArgs = parseStdinOnlyHeadArgs(trimShellSpacing(input.slice(pipe.end, headEnd)));
+        if (parsedArgs === null)
             return null;
-        headLines = parsedLines;
+        headArgs = parsedArgs;
     }
     let outputPath;
     if (redirect) {
@@ -249,7 +304,7 @@ export function parseBoundedOutputShellCommand(command) {
             return null;
         outputPath = outputArgv[0];
     }
-    return { argv, mergeStderr, ...(headLines ? { headLines } : {}), ...(outputPath ? { outputPath } : {}) };
+    return { argv, mergeStderr, ...(headArgs ? { headArgs } : {}), ...(outputPath ? { outputPath } : {}) };
 }
 /**
  * Classify only the shell boundary around an EC process invocation. Runner
@@ -257,9 +312,9 @@ export function parseBoundedOutputShellCommand(command) {
  * invocation may leave the sandbox, while shell composition may not.
  */
 export function classifyEvolcoreShellCommand(command) {
-    const literalArgv = parseLiteralShellArgv(command);
-    if (literalArgv) {
-        return literalArgv[0] === 'ec'
+    const literal = parseLiteralShellCommand(command);
+    if (literal.ok) {
+        return literal.argv[0] === 'ec'
             ? { kind: 'literal' }
             : { kind: 'none' };
     }
@@ -268,7 +323,7 @@ export function classifyEvolcoreShellCommand(command) {
         return { kind: 'bounded-output', command: boundedOutput };
     }
     return EVOLCORE_COMMAND_POSITION_RE.test(command)
-        ? { kind: 'composite' }
+        ? { kind: 'composite', issue: literal.issue }
         : { kind: 'none' };
 }
 function isDeterministicFilePath(value) {

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

@@ -3,7 +3,7 @@ import path from 'path';
 import { randomUUID } from 'crypto';
 import { logger } from '../../utils/logger.js';
 import { resolveRoot } from '../../paths.js';
-import { containsHClassReference, hClassGrantIncludesProtectedPath, isHClassPath, isSameOrDescendant, isLClassPath, lClassGrantIncludesProtectedPath, resolveProtectedCandidate, } from '../protected-paths.js';
+import { containsHClassReference, containsLClassReference, hClassGrantIncludesProtectedPath, isHClassPath, isSameOrDescendant, isLClassPath, lClassGrantIncludesProtectedPath, resolveProtectedCandidate, } from '../protected-paths.js';
 import { classifyEvolcoreShellCommand, parseBoundedOutputShellCommand, parseLiteralShellArgv, } from './ec-command-parser.js';
 // 绝对禁止命令（所有角色、所有权限模式下都禁止，不可授权）
 // 这些是系统级破坏操作，任何情况下都不应该允许
@@ -18,6 +18,15 @@ const READONLY_SHELL_EXECUTABLES = new Set([
     'ls', '/bin/ls', '/usr/bin/ls',
     'cat', '/bin/cat', '/usr/bin/cat',
 ]);
+const L_CLASS_READONLY_SHELL_EXECUTABLES = new Set([
+    ...READONLY_SHELL_EXECUTABLES,
+    'grep', '/bin/grep', '/usr/bin/grep',
+    'rg', '/bin/rg', '/usr/bin/rg',
+    'find', '/bin/find', '/usr/bin/find',
+    'sed', '/bin/sed', '/usr/bin/sed',
+]);
+const FIND_MUTATING_PRIMARY_RE = /^-(?:delete|exec|execdir|ok|okdir|fprint|fprint0|fprintf|fls)$/;
+const RG_PROCESS_SPAWNING_OPTION_RE = /^--pre(?:=|$)|^--pre-glob(?:=|$)/;
 // 危险操作（需要用户审批才能执行）
 // 这些操作有合理使用场景，但需要用户明确授权
 const DANGEROUS_PATTERNS = [
@@ -347,25 +356,45 @@ export function checkReadonly(toolName, input, projectPath, context) {
     logger.warn(`[ReadonlyCheck] 🔒 Unknown tool blocked: tool=${toolName} session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
     return { behavior: 'deny', message: `🔒 只读模式：未声明为只读的工具 ${toolName} 已拒绝执行` };
 }
-/**
- * H 类文件保护（用于 PreToolUse hook）
- * H 类文件只能由受控的人类/daemon 路径处理，agent 不可直接访问
- */
-function collectStringValues(value, output) {
+const NON_FILESYSTEM_METADATA_TOOLS = new Set([
+    'Agent',
+    'AskUserQuestion',
+    'CronCreate',
+    'CronDelete',
+    'CronList',
+    'EnterPlanMode',
+    'ExitPlanMode',
+    'SendMessage',
+    'Skill',
+    'Task',
+    'TaskCreate',
+    'TaskGet',
+    'TaskList',
+    'TaskOutput',
+    'TaskStop',
+    'TaskUpdate',
+    'TeamCreate',
+    'TeamDelete',
+    'TodoWrite',
+    'ToolSearch',
+    'WebFetch',
+    'WebSearch',
+]);
+function collectOpaqueToolStrings(value, output) {
     if (typeof value === 'string') {
-        output.push(value);
+        if (value.trim())
+            output.push(value);
         return;
     }
     if (Array.isArray(value)) {
         for (const entry of value)
-            collectStringValues(entry, output);
+            collectOpaqueToolStrings(entry, output);
         return;
     }
     if (!value || typeof value !== 'object')
         return;
-    for (const [key, entry] of Object.entries(value)) {
-        output.push(key);
-        collectStringValues(entry, output);
+    for (const entry of Object.values(value)) {
+        collectOpaqueToolStrings(entry, output);
     }
 }
 function collectPermissionPathSpec(value, output, projectRootSubpaths) {
@@ -532,28 +561,50 @@ function collectFileChangePaths(value, output) {
 }
 function shellCommandReferencesLClass(command, options) {
     const normalized = command.replace(/\\/g, '/');
-    const root = path.resolve(options.root ?? resolveRoot()).replace(/\\/g, '/');
-    const protectedRoot = `${root.replace(/\/+$/, '')}/data/triggers`;
-    if (normalized.includes(protectedRoot))
+    if (containsLClassReference(normalized))
         return true;
-    const references = normalized.match(/(?:^|[\s"'=<>;&|()])((?:\.\.\/|\.\/)*data\/triggers(?:\/[^\s"';&|<>)]*)?)/g) ?? [];
-    return references.some(reference => {
-        const candidate = reference.replace(/^[\s"'=<>;&|()]+/, '');
-        return isLClassPath(candidate, options);
-    });
+    const argv = parseLiteralShellArgv(command);
+    return argv?.slice(1).some(argument => {
+        if (argument === '-' || argument === '--' || argument.startsWith('-'))
+            return false;
+        return isLClassPath(argument, options);
+    }) ?? false;
 }
-function isLClassMutatingShellCommand(command, options) {
+function isVerifiedLClassReadOnlyShellCommand(command) {
+    const argv = parseLiteralShellArgv(command);
+    if (!argv || !L_CLASS_READONLY_SHELL_EXECUTABLES.has(argv[0]))
+        return false;
+    switch (argv[0].replace(/^.*\//, '')) {
+        case 'grep':
+            // grep never mutates its operands. Shell composition is rejected by the
+            // literal parser before this point.
+            return true;
+        case 'rg':
+            // ripgrep's --pre hooks may execute an arbitrary process.
+            return !argv.slice(1).some(argument => RG_PROCESS_SPAWNING_OPTION_RE.test(argument));
+        case 'find':
+            // Keep only the predicates/actions which cannot create, mutate, or
+            // execute files. Other find options remain fail-closed.
+            return !argv.slice(1).some(argument => FIND_MUTATING_PRIMARY_RE.test(argument));
+        case 'sed': {
+            // sed can write via -i or a `w` command. Permit only the bounded
+            // inspection form used for line-range reads: sed -n 'START[,END]p'.
+            const quiet = argv[1] === '-n' || argv[1] === '--quiet' || argv[1] === '--silent';
+            const program = quiet ? argv[2] : undefined;
+            return !!program
+                && /^(?:\d+(?:,\d+)?|\$)?p$/.test(program)
+                // GNU sed accepts options after the script as well. Reject every
+                // later option so -i/-e/-f cannot be smuggled into this read form.
+                && !argv.slice(3).some(argument => argument.startsWith('-'));
+        }
+        default:
+            return true;
+    }
+}
+function isUnverifiedLClassShellCommand(command, options) {
     if (!shellCommandReferencesLClass(command, options))
         return false;
-    const mutationPatterns = [
-        /(?:^|[;&|]\s*)\s*(?:rm|unlink|rmdir|mv|rename|truncate|touch|chmod|chown|chgrp|mkdir)\b/i,
-        /(?:^|[;&|]\s*)\s*(?:sed\s+[^;&|]*\s-i\b|perl\s+[^;&|]*\s-pi\b)/i,
-        /(?:^|[;&|]\s*)\s*tee\b/i,
-        /\bfind\b[^;&|]*(?:-delete|-exec\s+(?:rm|mv|chmod|chown)\b)/i,
-        /\bgit\s+(?:checkout|restore|clean|reset)\b/i,
-        /(?:^|[^<])>{1,2}\s*[^;&|\r\n]*data[\\/]triggers(?:[\\/]|$)/i,
-    ];
-    return mutationPatterns.some(pattern => pattern.test(command));
+    return !isVerifiedLClassReadOnlyShellCommand(command);
 }
 function requestsFilesystemRoot(value) {
     if (Array.isArray(value))
@@ -604,9 +655,18 @@ export function checkHClassWrite(toolName, input, context) {
         collectFilesystemGrantPaths(input.additionalPermissions, grantPaths, projectRootGrantSubpaths);
         collectFilesystemGrantPaths(input.permissions, grantPaths, projectRootGrantSubpaths);
     }
-    else {
-        collectStringValues(input, paths);
+    else if (!NON_FILESYSTEM_METADATA_TOOLS.has(toolName)) {
+        // Opaque external tools may run outside the Claude/Codex filesystem
+        // sandbox. Retain conservative string inspection for those tools, while
+        // excluding known orchestration tools whose payload is only metadata.
+        collectOpaqueToolStrings(input, paths);
     }
+    // Agent/Skill/Task and other orchestration tools carry natural-language
+    // metadata, not direct filesystem operands. Treating every string in their
+    // payload as a path makes a prompt that merely mentions daemon.json or a
+    // *.json_ backup indistinguishable from an actual file access. Any nested
+    // filesystem operation is checked again when it reaches Read/Write/Bash,
+    // FileChange, or PermissionGrant above.
     const pathOptions = { cwd: context?.projectPath, root: context?.root };
     if (requestsFilesystemRoot(input.permissions) || requestsFilesystemRoot(input.additionalPermissions)) {
         logger.warn(`[H-Class Protection] 🔒 Permission grant covers filesystem root: tool=${toolName} ` +
@@ -718,20 +778,23 @@ export function checkLClassWrite(toolName, input, context) {
     else if (toolName === 'Bash') {
         const command = typeof input.command === 'string' ? input.command.replace(/\\/g, '/') : '';
         const pathOptions = { cwd: context?.projectPath, root: context?.root };
-        if (isLClassMutatingShellCommand(command, pathOptions)) {
-            logger.warn(`[L-Class Protection] Protected path mutation requested by shell command: tool=${toolName} ` +
+        if (isUnverifiedLClassShellCommand(command, pathOptions)) {
+            logger.warn(`[L-Class Protection] Unverified L-class shell command denied: tool=${toolName} ` +
                 `session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
             return {
                 behavior: 'deny',
-                message: '🔒 Shell 命令试图修改 L-class 只读路径；读取允许，修改请使用 ec trigger',
+                message: '🔒 L-class 路径仅允许单个可验证的只读命令。请拆分为单条 ls/cat/grep/rg/find 或 sed -n，或使用 Read；禁止管道、重定向、变量展开和命令拼接。修改必须通过受控的 EvolCore 命令',
             };
         }
         collectFilesystemWriteGrantPaths(input.additionalPermissions, writeGrantPaths, projectRootWriteSubpaths);
         collectFilesystemWriteGrantPaths(input.permissions, writeGrantPaths, projectRootWriteSubpaths);
     }
-    else {
-        collectStringValues(input, paths);
+    else if (!NON_FILESYSTEM_METADATA_TOOLS.has(toolName)) {
+        collectOpaqueToolStrings(input, paths);
     }
+    // Do not infer mutation targets from arbitrary orchestration-tool strings.
+    // Skills commonly pass args: "" and delegation prompts may discuss
+    // protected paths; neither is itself a filesystem mutation.
     const pathOptions = { cwd: context?.projectPath, root: context?.root };
     for (const grantPath of writeGrantPaths) {
         if (grantPath && lClassGrantIncludesProtectedPath(grantPath, pathOptions)) {
@@ -759,7 +822,7 @@ export function checkLClassWrite(toolName, input, context) {
             `session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
         return {
             behavior: 'deny',
-            message: `🔒 L-class 路径允许读取但禁止 Agent 直接修改、删除或移动\n\n文件：${filePath}\n\n💡 请使用 ec trigger 命令修改`,
+            message: `🔒 L-class 路径允许读取但禁止 Agent 直接修改、删除或移动\n\n文件：${filePath}\n\n💡 请使用对应的 EvolCore 受控命令修改`,
         };
     }
     return { behavior: 'allow' };
@@ -862,7 +925,7 @@ function prepareBoundedOutputInput(input, command, kind, context) {
         cwd: path.resolve(context.projectPath),
         argv: command.argv,
         mergeStderr: command.mergeStderr,
-        ...(command.headLines ? { headLines: command.headLines } : {}),
+        ...(command.headArgs ? { headArgs: command.headArgs } : {}),
         ...(command.outputPath ? { outputPath: command.outputPath } : {}),
     }), 'utf8').toString('base64url');
     const rewrittenCommand = `${quotePosixShellArg(process.execPath)} ${quotePosixShellArg(helperPath)} ${quotePosixShellArg(payload)}`;
@@ -884,6 +947,20 @@ export function evaluateToolPreflight(toolName, input, context) {
             return prepareBoundedOutputInput(input, ecCommand.command, 'ec', context);
         }
         if (ecCommand.kind === 'composite') {
+            if (ecCommand.issue === 'unsafe-expansion') {
+                return {
+                    behavior: 'deny',
+                    input,
+                    message: '🔒 EC 双引号正文包含未转义的 Shell 展开；请将反引号写成 \\`，将 $()、${}、$变量中的 $ 写成 \\$。Shell 传给 ec 时会还原为原文字面量',
+                };
+            }
+            if (ecCommand.issue === 'invalid-quote') {
+                return {
+                    behavior: 'deny',
+                    input,
+                    message: '🔒 EC 命令引号未闭合或存在错误嵌套；正文中的双引号请写成 \\"',
+                };
+            }
             return {
                 behavior: 'deny',
                 input,