evolcore 0.0.12 → 0.0.14

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

@@ -3,9 +3,94 @@ import path from 'path';
 import { randomUUID } from 'crypto';
 import { logger } from '../../utils/logger.js';
 import { resolveRoot } from '../../paths.js';
-import { containsHClassReference, containsLClassReference, getExistingHClassMaskTargets, hClassGrantIncludesProtectedPath, isHClassPath, isSameOrDescendant, isLClassPath, lClassGrantIncludesProtectedPath, resolveProtectedCandidate, } from '../protected-paths.js';
+import { containsHClassReference, containsLClassReference, checkProtectedPathAccess, getExistingHClassMaskTargets, hClassGrantIncludesProtectedPath, isHClassPath, isSameOrDescendant, isLClassPath, lClassGrantIncludesProtectedPath, resolveProtectedCandidate, resolveProtectedCandidateWithoutFinalSymlink, } from '../protected-paths.js';
 import { classifyEvolcoreShellCommand, parseCodexToolCommandArgv, parseBoundedOutputShellCommand, parseLiteralShellArgv, unwrapCodexShellCommandArgv, } from './ec-command-parser.js';
 import { analyzeReadonlyShellQuery, } from './readonly-shell-query.js';
+/** Resolve the session-owned temporary root supplied by the execution host. */
+export function resolveManagedTempDir(env = process.env) {
+    const raw = typeof env.TMPDIR === 'string' ? env.TMPDIR.trim() : '';
+    if (!raw || !path.isAbsolute(raw))
+        return undefined;
+    const resolved = resolveProtectedCandidate(raw);
+    // A process-wide shared temporary root is not a session capability. The
+    // runner must register a private subdirectory before `$TMPDIR` is trusted.
+    if (['/tmp', '/var/tmp', '/dev/shm'].includes(resolved))
+        return undefined;
+    return resolved;
+}
+function substituteTmpDir(value, root) {
+    if (!root)
+        return value;
+    return value
+        .replace(/\$\{TMPDIR\}/g, root)
+        .replace(/\$TMPDIR\b/g, root);
+}
+/**
+ * A temp path is valid only when its canonical existing ancestor remains below
+ * the current session's TMPDIR. This also closes symlink and `..` escapes.
+ */
+export function isManagedTempPath(value, options = {}) {
+    const root = resolveManagedTempDir(options.env);
+    if (!root || typeof value !== 'string' || !value.trim())
+        return false;
+    const candidate = resolveProtectedCandidate(substituteTmpDir(value, root), options.cwd);
+    return isSameOrDescendant(candidate, root);
+}
+export function expandManagedTempPath(value, options = {}) {
+    return substituteTmpDir(value, resolveManagedTempDir(options.env));
+}
+const WRITE_INTENT_RE = /(?:^|[\s;&|])(?:mkdir|mktemp|touch|tee|cp|mv|install|chmod|chown|ln|rm)(?:[\s;&|]|$)|(?:^|[\s])(?:\d>>?|>>?)\s*/i;
+const TEMP_TOKEN_RE = /(?:\$TMPDIR|\$\{TMPDIR\}|\/tmp(?:\/|$)|\/var\/tmp(?:\/|$)|\/dev\/shm(?:\/|$))[^\s'";&|<>)]*/g;
+/**
+ * Inspect shell write targets that look like temporary paths. Ordinary
+ * project writes are left to the existing workspace/H-class policy; any
+ * explicit /tmp-style target must be contained by TMPDIR.
+ */
+export function checkManagedTempShellCommand(command, options = {}) {
+    if (!WRITE_INTENT_RE.test(command))
+        return { kind: 'none' };
+    const root = resolveManagedTempDir(options.env);
+    const normalized = substituteTmpDir(command, root);
+    const candidates = [...normalized.matchAll(TEMP_TOKEN_RE)].map(match => match[0].replace(/[.,:]+$/, ''));
+    if (candidates.length === 0)
+        return { kind: 'none' };
+    if (!root) {
+        return { kind: 'deny', paths: candidates, reason: 'TMPDIR is unset or not an absolute managed path' };
+    }
+    const outside = candidates.filter(candidate => !isManagedTempPath(candidate, {
+        ...options,
+        env: { ...(options.env ?? process.env), TMPDIR: root },
+    }));
+    if (outside.length > 0) {
+        return { kind: 'deny', paths: outside, reason: 'temporary write target is outside the session-managed TMPDIR' };
+    }
+    return { kind: 'allow', paths: candidates };
+}
+/**
+ * Replace only already-validated temporary path operands before a second
+ * policy pass. This prevents a harmless `$TMPDIR/CA/root` name from looking
+ * like the real EvolCore CA directory while preserving any unrelated H-class
+ * operand in the same command.
+ */
+export function maskManagedTempShellPaths(command, options = {}) {
+    const check = checkManagedTempShellCommand(command, options);
+    if (check.kind !== 'allow')
+        return command;
+    const root = resolveManagedTempDir(options.env);
+    const normalized = substituteTmpDir(command, root);
+    let index = 0;
+    return normalized.replace(TEMP_TOKEN_RE, token => {
+        const candidate = token.replace(/[.,:]+$/, '');
+        if (!check.paths.includes(candidate) || !isManagedTempPath(candidate, {
+            ...options,
+            env: { ...(options.env ?? process.env), TMPDIR: root },
+        })) {
+            return token;
+        }
+        index += 1;
+        return `__managed_tmp_${index}__`;
+    });
+}
 // 绝对禁止命令（所有角色、所有权限模式下都禁止，不可授权）
 // 这些是系统级破坏操作，任何情况下都不应该允许
 const ABSOLUTE_FORBIDDEN = [
@@ -320,9 +405,50 @@ function containsNetStopCommand(command, depth = 0) {
     });
 }
 function queryPathOperands(analysis) {
-    return analysis.kind === 'proven-readonly' ? analysis.ir.pathOperands : [];
+    if (analysis.kind !== 'proven-readonly')
+        return [];
+    return analysis.ir.pipelines.flatMap(pipeline => pipeline.flatMap(command => command.pathOperands.map(operand => ({
+        operand,
+        accessKind: command.accessKind ?? (operand.access === 'recursive' ? 'enumerate' : 'content'),
+    }))));
 }
-function shellOperandMatchesClass(operand, className, options) {
+function shellOperandMatchesClass(operand, className, options, accessKind = operand.access === 'recursive' ? 'enumerate' : 'content') {
+    // `$TMPDIR` is a private session namespace, so names such as `CA` or
+    // `config.json` inside it are ordinary temporary data rather than paths in
+    // the EvolCore root. Resolve the candidate first so a symlink escape does
+    // not inherit this exception.
+    if (options.managedTempDir) {
+        const managedTemp = resolveProtectedCandidate(options.managedTempDir);
+        const candidate = accessKind === 'metadata' && operand.access === 'exact'
+            ? resolveProtectedCandidateWithoutFinalSymlink(operand.value, options.cwd)
+            : resolveProtectedCandidate(operand.value, options.cwd);
+        const workspace = options.cwd ? resolveProtectedCandidate(options.cwd) : undefined;
+        if (isSameOrDescendant(candidate, managedTemp)
+            && (!workspace || !isSameOrDescendant(candidate, workspace))) {
+            return false;
+        }
+    }
+    if (className === 'h' && accessKind === 'metadata' && operand.access === 'exact') {
+        // Filesystem sandboxes currently expose only path-wide H-class deny
+        // rules. A runner that cannot provide an action-aware metadata channel
+        // must keep the policy decision aligned with that lower-level boundary,
+        // but ordinary workspace metadata remains safe and should stay usable.
+        const metadata = checkProtectedPathAccess(operand.value, 'metadata', {
+            ...options,
+            // stat/lstat must inspect the final symlink itself, never its target.
+            followFinalSymlink: false,
+        });
+        if (options.allowProtectedMetadata === false) {
+            return metadata.pathClass === 'h-file' || metadata.pathClass === 'h-directory';
+        }
+        // The no-follow decision is authoritative for metadata. In particular,
+        // an ordinary symlink whose target is H-class must remain inspectable as a
+        // link; falling through to isHClassPath() would follow it and reject the
+        // otherwise safe lstat/stat operation.
+        if (metadata.pathClass !== 'unknown' && metadata.allowed) {
+            return false;
+        }
+    }
     const reference = className === 'h' ? containsHClassReference(operand.value) : containsLClassReference(operand.value);
     if (reference)
         return true;
@@ -352,7 +478,7 @@ function hClassReadScopeIncludesProtectedPath(value, options) {
     return getExistingHClassMaskTargets(root).some(target => isSameOrDescendant(target.path, scope));
 }
 function analyzeShellProtectedOperands(command, options) {
-    const analysis = analyzeReadonlyShellQuery(command);
+    const analysis = analyzeReadonlyShellQuery(command, { managedTempDir: options.managedTempDir });
     if (analysis.kind === 'unproven') {
         return {
             analysis,
@@ -363,8 +489,8 @@ function analyzeShellProtectedOperands(command, options) {
     const operands = queryPathOperands(analysis);
     return {
         analysis,
-        hClass: operands.some(operand => shellOperandMatchesClass(operand, 'h', options)),
-        lClass: operands.some(operand => shellOperandMatchesClass(operand, 'l', options)),
+        hClass: operands.some(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'h', options, accessKind)),
+        lClass: operands.some(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'l', options, accessKind)),
     };
 }
 function protectedReadToolPaths(toolName, input) {
@@ -444,11 +570,21 @@ function protectedReadToolStaysInWorkspace(toolName, input, projectPath) {
     }
     return true;
 }
-function readonlyShellStaysInWorkspace(analysis, projectPath) {
+function readonlyShellStaysInWorkspace(analysis, projectPath, managedTempDir) {
     if (analysis.kind !== 'proven-readonly')
         return false;
     const workspace = resolveProtectedCandidate(projectPath);
-    return analysis.ir.pathOperands.every(operand => isSameOrDescendant(resolveProtectedCandidate(operand.value, projectPath), workspace));
+    const managedTemp = managedTempDir ? resolveProtectedCandidate(managedTempDir) : undefined;
+    return analysis.ir.pipelines.flatMap(pipeline => pipeline.flatMap(command => command.pathOperands.map(operand => ({
+        operand,
+        accessKind: command.accessKind ?? (operand.access === 'recursive' ? 'enumerate' : 'content'),
+    })))).every(({ operand, accessKind }) => (() => {
+        const candidate = accessKind === 'metadata' && operand.access === 'exact'
+            ? resolveProtectedCandidateWithoutFinalSymlink(operand.value, projectPath)
+            : resolveProtectedCandidate(operand.value, projectPath);
+        return isSameOrDescendant(candidate, workspace)
+            || (!!managedTemp && isSameOrDescendant(candidate, managedTemp));
+    })());
 }
 /**
  * 只读模式检查（用于 PreToolUse hook 和 canUseTool callback）。普通
@@ -463,50 +599,61 @@ export function checkReadonly(toolName, input, projectPath, context) {
         const paths = protectedReadToolPaths(toolName, input);
         const pathOptions = { cwd: projectPath, root: context?.root };
         if (!protectedReadToolStaysInWorkspace(toolName, input, projectPath)) {
-            return { behavior: 'deny', message: '🔒 只读模式：文件读取范围不能越出当前项目目录' };
+            return { behavior: 'deny', message: '🔒 只读模式：文件读取范围不能越出当前项目目录', policyCode: 'readonly_workspace_escape' };
         }
         if (paths.some(filePath => containsHClassReference(filePath) || isHClassPath(filePath, pathOptions))) {
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径' };
+            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
         }
         if (protectedReadToolMatchesHClass(toolName, input, pathOptions)) {
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径' };
+            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
         }
         if (protectedReadToolMatchesLClass(toolName, input, pathOptions)) {
-            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径' };
+            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read' };
         }
         return { behavior: 'allow' };
     }
     if (toolName === 'Write' || toolName === 'Edit' || toolName === 'NotebookEdit') {
         const filePath = (input.file_path || input.notebook_path);
         logger.warn(`[ReadonlyCheck] 🔒 File write blocked: tool=${toolName} path=${filePath} project=${projectPath} session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-        return { behavior: 'deny', message: '🔒 只读模式：禁止写入或修改文件' };
+        return { behavior: 'deny', message: '🔒 只读模式：禁止写入或修改文件', policyCode: 'readonly_file_write' };
     }
     if (toolName === 'Bash') {
         const cmd = input.command || '';
-        const protectedOperands = analyzeShellProtectedOperands(cmd, { cwd: projectPath, root: context?.root });
+        // A managed session must provide its runner-registered temp root. For
+        // direct policy callers without a session, the process TMPDIR remains a
+        // useful compatibility fallback after the shared-root check above.
+        const managedTempDir = context?.sessionId
+            ? context.managedTempDir
+            : context?.managedTempDir ?? resolveManagedTempDir();
+        const protectedOperands = analyzeShellProtectedOperands(cmd, {
+            cwd: projectPath,
+            root: context?.root,
+            managedTempDir,
+            allowProtectedMetadata: context?.allowProtectedMetadata,
+        });
         if (protectedOperands.analysis.kind === 'proven-readonly'
             && !protectedOperands.hClass
             && !protectedOperands.lClass
-            && readonlyShellStaysInWorkspace(protectedOperands.analysis, projectPath)) {
+            && readonlyShellStaysInWorkspace(protectedOperands.analysis, projectPath, managedTempDir)) {
             return { behavior: 'allow' };
         }
         if (protectedOperands.hClass) {
             logger.warn(`[ReadonlyCheck] 🔒 H-class path blocked in readonly shell: cmd="${cmd}" session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径' };
+            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
         }
         if (protectedOperands.lClass) {
             logger.warn(`[ReadonlyCheck] 🔒 L-class path blocked in readonly shell: cmd="${cmd}" session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径' };
+            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read' };
         }
         if (protectedOperands.analysis.kind === 'proven-readonly') {
-            return { behavior: 'deny', message: '🔒 只读模式：Shell 查询范围不能越出当前项目目录' };
+            return { behavior: 'deny', message: '🔒 只读模式：Shell 查询范围不能越出当前项目目录', policyCode: 'readonly_workspace_escape' };
         }
         const cmdPreview = cmd.length > 80 ? cmd.substring(0, 80) + '...' : cmd;
         logger.warn(`[ReadonlyCheck] 🔒 Bash blocked by default: cmd="${cmdPreview}" session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-        return { behavior: 'deny', message: '🔒 只读模式：Shell 仅允许受限、可证明只读的普通路径查询' };
+        return { behavior: 'deny', message: '🔒 只读模式：Shell 仅允许受限、可证明只读的普通路径查询', policyCode: 'readonly_shell_unproven' };
     }
     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} 已拒绝执行` };
+    return { behavior: 'deny', message: `🔒 只读模式：未声明为只读的工具 ${toolName} 已拒绝执行`, policyCode: 'readonly_tool_unavailable' };
 }
 const NON_FILESYSTEM_METADATA_TOOLS = new Set([
     'Agent',
@@ -752,9 +899,35 @@ export function checkHClassWrite(toolName, input, context) {
     }
     else if (toolName === 'Bash') {
         const command = typeof input.command === 'string' ? input.command : '';
-        const protectedOperands = analyzeShellProtectedOperands(command, {
+        // Keep this H-class pass aligned with the shared preflight pass. A
+        // managed session must not fall back to the daemon's process-wide TMPDIR;
+        // without a registered root, explicit temporary paths fail closed.
+        const tempOptions = {
+            cwd: context?.projectPath,
+            env: context?.sessionId
+                ? { ...process.env, TMPDIR: context.managedTempDir ?? '' }
+                : context?.managedTempDir !== undefined
+                    ? { ...process.env, TMPDIR: context.managedTempDir }
+                    : process.env,
+        };
+        const tempCheck = checkManagedTempShellCommand(command, tempOptions);
+        if (tempCheck.kind === 'deny') {
+            return {
+                behavior: 'deny',
+                message: '🔒 临时文件必须位于当前会话的 $TMPDIR 内',
+            };
+        }
+        // A managed temp write is intentionally allowed to contain names such as
+        // CA/root, but only that validated operand is masked. Any other protected
+        // operand in a mixed command must still be rejected.
+        const policyCommand = tempCheck.kind === 'allow'
+            ? maskManagedTempShellPaths(command, tempOptions)
+            : command;
+        const protectedOperands = analyzeShellProtectedOperands(policyCommand, {
             cwd: context?.projectPath,
             root: context?.root,
+            managedTempDir: context?.managedTempDir,
+            allowProtectedMetadata: context?.allowProtectedMetadata,
         });
         if (protectedOperands.hClass) {
             logger.warn(`[H-Class Protection] 🔒 Protected filesystem operand in shell command: tool=${toolName} ` +
@@ -905,7 +1078,10 @@ export function checkLClassWrite(toolName, input, context) {
     else if (toolName === 'Bash') {
         const command = typeof input.command === 'string' ? input.command : '';
         const pathOptions = { cwd: context?.projectPath, root: context?.root };
-        const protectedOperands = analyzeShellProtectedOperands(command, pathOptions);
+        const protectedOperands = analyzeShellProtectedOperands(command, {
+            ...pathOptions,
+            managedTempDir: context?.managedTempDir,
+        });
         const lClassDenied = protectedOperands.lClass
             && (context?.permissionMode === 'readonly' || protectedOperands.analysis.kind === 'unproven');
         if (lClassDenied) {
@@ -992,14 +1168,46 @@ export function checkBlacklist(toolName, input) {
     // 默认允许
     return { behavior: 'allow', updatedInput: input };
 }
+function managedTempOptions(context) {
+    return {
+        cwd: context.projectPath,
+        // A managed session must never inherit the daemon's unrelated TMPDIR.
+        env: context.sessionId
+            ? { ...process.env, TMPDIR: context.managedTempDir ?? '' }
+            : context.managedTempDir !== undefined
+                ? { ...process.env, TMPDIR: context.managedTempDir }
+                : process.env,
+    };
+}
 function validateBoundedOutputPath(command, context) {
     const outputPath = command.outputPath;
     if (!outputPath)
         return undefined;
     if (context.permissionMode === 'readonly')
         return '🔒 只读模式：禁止将命令输出写入文件';
-    if (path.isAbsolute(outputPath))
-        return '🔒 输出文件必须使用项目目录内的相对路径';
+    const tempOptions = managedTempOptions(context);
+    const expandedOutputPath = expandManagedTempPath(outputPath, tempOptions);
+    if (path.isAbsolute(expandedOutputPath)) {
+        // A literal `/tmp/...` path is not proof that the caller is using this
+        // session's managed workspace. Only an explicit `$TMPDIR` reference may
+        // opt into the absolute temporary-path branch; the runner owns the value
+        // of TMPDIR and validates its containment below.
+        const explicitManagedTemp = /^\$(?:\{TMPDIR\}|TMPDIR)(?:[\\/]|$)/.test(outputPath);
+        if (!explicitManagedTemp || !isManagedTempPath(outputPath, tempOptions)) {
+            return '🔒 输出文件必须使用项目目录内的相对路径，或当前会话的 $TMPDIR';
+        }
+        const tempTarget = resolveProtectedCandidate(expandedOutputPath);
+        if (fs.existsSync(tempTarget))
+            return '🔒 临时安全输出只允许创建新文件，不能覆盖或追加现有文件';
+        try {
+            if (!fs.statSync(path.dirname(tempTarget)).isDirectory())
+                return '🔒 临时输出文件的父目录无效';
+        }
+        catch {
+            return '🔒 临时输出文件的父目录必须已经存在';
+        }
+        return undefined;
+    }
     const workspace = resolveProtectedCandidate(context.workspacePath ?? context.projectPath);
     const cwd = resolveProtectedCandidate(context.projectPath);
     if (!isSameOrDescendant(cwd, workspace))
@@ -1033,7 +1241,7 @@ function quotePosixShellArg(value) {
 function prepareBoundedOutputInput(input, command, kind, context) {
     const validationError = validateBoundedOutputPath(command, context);
     if (validationError)
-        return { behavior: 'deny', input, message: validationError };
+        return { behavior: 'deny', input, message: validationError, policyCode: 'bounded_output_invalid' };
     const helperPath = context.safeOutputHelperPath;
     if (!helperPath) {
         return {
@@ -1047,7 +1255,7 @@ function prepareBoundedOutputInput(input, command, kind, context) {
             throw new Error('not a file');
     }
     catch {
-        return { behavior: 'deny', input, message: '🔒 安全输出 helper 不可用，命令已拒绝' };
+        return { behavior: 'deny', input, message: '🔒 安全输出 helper 不可用，命令已拒绝', policyCode: 'bounded_output_helper_unavailable' };
     }
     const payload = Buffer.from(JSON.stringify({
         v: 1,
@@ -1058,7 +1266,9 @@ function prepareBoundedOutputInput(input, command, kind, context) {
         argv: command.argv,
         mergeStderr: command.mergeStderr,
         ...(command.headArgs ? { headArgs: command.headArgs } : {}),
-        ...(command.outputPath ? { outputPath: command.outputPath } : {}),
+        ...(command.outputPath
+            ? { outputPath: expandManagedTempPath(command.outputPath, managedTempOptions(context)) }
+            : {}),
     }), 'utf8').toString('base64url');
     const rewrittenCommand = `${quotePosixShellArg(process.execPath)} ${quotePosixShellArg(helperPath)} ${quotePosixShellArg(payload)}`;
     return {
@@ -1071,6 +1281,15 @@ function prepareBoundedOutputInput(input, command, kind, context) {
 export function evaluateToolPreflight(toolName, input, context) {
     if (toolName === 'Bash') {
         const command = typeof input.command === 'string' ? input.command : '';
+        const tempCheck = checkManagedTempShellCommand(command, managedTempOptions(context));
+        if (tempCheck.kind === 'deny') {
+            return {
+                behavior: 'deny',
+                input,
+                message: `🔒 临时文件必须位于当前会话的 $TMPDIR 内：${tempCheck.reason}`,
+                policyCode: 'temporary_path_outside_tmpdir',
+            };
+        }
         const explicitCommandArgv = Array.isArray(input.commandArgv)
             && input.commandArgv.every(value => typeof value === 'string')
             ? input.commandArgv
@@ -1129,40 +1348,28 @@ export function evaluateToolPreflight(toolName, input, context) {
             return prepareBoundedOutputInput(input, ecCommand.command, 'ec', context);
         }
         if (ecCommand.kind === 'composite') {
-            // Older app-server approval callbacks may provide only the rendered
-            // `/bin/bash -lc ...` command string.  A composite inside that carrier
-            // is not eligible for a delegation ticket, but owner bypass still
-            // handles it as an ordinary shell request.  Structured `commandArgv`
-            // callbacks remain fail-closed below because their command boundary is
-            // authoritative.
-            const legacyRenderedCarrier = !explicitCommandArgv && wrappedCommand !== undefined;
-            const allowLegacyBypassComposition = legacyRenderedCarrier
-                && context.permissionMode === 'bypass'
-                && ecCommand.issue === 'shell-composition';
-            if (!allowLegacyBypassComposition) {
-                if (ecCommand.issue === 'unsafe-expansion') {
-                    return {
-                        behavior: 'deny',
-                        input,
-                        message: '🔒 EC 双引号正文包含未转义的 Shell 展开；请将反引号写成 \\`，将 $()、${}、$变量中的 $ 写成 \\$。Shell 传给 ec 时会还原为原文字面量',
-                        policyCode: 'ec_shell_unsafe_expansion',
-                    };
-                }
-                if (ecCommand.issue === 'invalid-quote') {
-                    return {
-                        behavior: 'deny',
-                        input,
-                        message: '🔒 EC 命令引号未闭合或存在错误嵌套；正文中的双引号请写成 \\"',
-                        policyCode: 'ec_shell_invalid_quote',
-                    };
-                }
+            if (ecCommand.issue === 'unsafe-expansion') {
+                return {
+                    behavior: 'deny',
+                    input,
+                    message: '🔒 EC 双引号正文包含未转义的 Shell 展开；请将反引号写成 \\`，将 $()、${}、$变量中的 $ 写成 \\$。Shell 传给 ec 时会还原为原文字面量',
+                    policyCode: 'ec_shell_unsafe_expansion',
+                };
+            }
+            if (ecCommand.issue === 'invalid-quote') {
                 return {
                     behavior: 'deny',
                     input,
-                    message: '🔒 EC 命令调用被拒绝：一次 Bash/exec_command 只能执行一条完整的 `ec` 命令。请直接调用 `ec ...`，不要先用 `command -v`/`ec aid` 探测，也不要使用 `&&`、`||`、`;`、`|`、重定向、变量展开、子 shell、`sh -c` 或 `bash -lc` 拼接其它命令。',
-                    policyCode: 'ec_shell_composite_command',
+                    message: '🔒 EC 命令引号未闭合或存在错误嵌套；正文中的双引号请写成 \\"',
+                    policyCode: 'ec_shell_invalid_quote',
                 };
             }
+            return {
+                behavior: 'deny',
+                input,
+                message: '🔒 EC 命令调用被拒绝：一次 Bash/exec_command 只能执行一条完整的 `ec` 命令。请直接调用 `ec ...`，不要先用 `command -v`/`ec aid` 探测，也不要使用 `&&`、`||`、`;`、`|`、重定向、变量展开、子 shell、`sh -c` 或 `bash -lc` 拼接其它命令。',
+                policyCode: 'ec_shell_composite_command',
+            };
         }
         const boundedOutput = parseBoundedOutputShellCommand(command);
         const hostProcessCommand = boundedOutput
@@ -1190,6 +1397,8 @@ export function evaluateToolPreflight(toolName, input, context) {
         projectPath: context.projectPath,
         workspacePath: context.workspacePath,
         root: context.root,
+        managedTempDir: context.managedTempDir,
+        allowProtectedMetadata: context.allowProtectedMetadata,
     });
     if (hClass.behavior === 'deny') {
         return { behavior: 'deny', input: checkedInput, message: hClass.message, policyCode: 'h_class_protection' };
@@ -1203,6 +1412,7 @@ export function evaluateToolPreflight(toolName, input, context) {
         projectPath: context.projectPath,
         workspacePath: context.workspacePath,
         root: context.root,
+        managedTempDir: context.managedTempDir,
     });
     if (lClass.behavior === 'deny') {
         return { behavior: 'deny', input: checkedInput, message: lClass.message, policyCode: 'l_class_protection' };

package/dist/core/protected-paths.js

@@ -38,6 +38,20 @@ const H_CLASS_REFERENCE_PATTERNS = [
     /(?:^|[/\\\s"'=<>])data[\\/]triggers(?:[\\/]|$|[\s"';&|<>)},])/,
     /(?:^|[/\\\s"'=<>])(?:[^/\\\s"']+\.json_|[^/\\\s"']+\.json\.migrated|defaults_\d+\.json)(?=$|[\s"';&|<>)},])/,
 ];
+// H-class directory roots are kept separately from the full path matcher so
+// an exact metadata query can distinguish a protected directory from a
+// protected file. Descendants inherit the directory classification unless an
+// existing regular file gives us a more precise answer.
+const H_CLASS_DIRECTORY_RELATIVE_PATTERNS = [
+    /^backups\/config(?:\/|$)/,
+    /^\.snapshots(?:\/|$)/,
+    /^CA(?:\/|$)/,
+    /^(?:AIDs|aids)\/[^/]+\/(?:cert|keys|private)(?:\/|$)/,
+    /^data\/(?:triggers|sessions|outbox|handoff|channel-state)(?:\/|$)/,
+    /^data\/daemon\/(?:control|migrations)(?:\/|$)/,
+    /^agents\/[^/]+\/sessions(?:\/|$)/,
+    /^agents\/[^/]+\/data\/(?:channels|handoff)(?:\/|$)/,
+];
 const L_CLASS_RELATIVE_PATTERNS = [
     /^agents\/[^/]+\/triggers(?:\/|$)/,
     /^agents\/[^/]+\/roles(?:\/|$)/,
@@ -68,6 +82,22 @@ function resolveThroughExistingAncestor(value) {
         return absolute;
     }
 }
+/**
+ * H-class file names are normally leaves, but treating their descendants as
+ * protected as well is important when a malformed or externally-created
+ * directory uses a reserved file name (for example `config.json/child`).
+ * Such a path cannot expose content from the expected file, and fail-closed
+ * classification avoids turning that unusual filesystem state into a bypass.
+ */
+function matchesHClassRelative(relative) {
+    const segments = relative.split('/').filter(Boolean);
+    for (let end = segments.length; end > 0; end--) {
+        if (H_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(segments.slice(0, end).join('/')))) {
+            return true;
+        }
+    }
+    return false;
+}
 export function isSameOrDescendant(candidate, parent) {
     const normalizedCandidate = normalizeForComparison(candidate);
     const normalizedParent = normalizeForComparison(parent);
@@ -85,14 +115,89 @@ export function isHClassPath(value, options = {}) {
         : path.resolve(options.cwd ?? process.cwd(), value);
     if (isSameOrDescendant(lexicalCandidate, root)) {
         const lexicalRelative = path.relative(root, lexicalCandidate).split(path.sep).join('/');
-        if (H_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(lexicalRelative)))
+        if (matchesHClassRelative(lexicalRelative))
             return true;
     }
     const candidate = resolveProtectedCandidate(value, options.cwd);
     if (!isSameOrDescendant(candidate, root))
         return false;
     const relative = path.relative(root, candidate).split(path.sep).join('/');
-    return H_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(relative));
+    return matchesHClassRelative(relative);
+}
+function hasPathSyntax(value) {
+    return /[\0\r\n$`*?\[\]{}<>|;&]/.test(value);
+}
+function lexicalCandidate(value, cwd = process.cwd()) {
+    return path.isAbsolute(value) ? path.resolve(value) : path.resolve(cwd, value);
+}
+function resolveWithoutFinalSymlink(value, cwd = process.cwd()) {
+    const absolute = lexicalCandidate(value, cwd);
+    const basename = path.basename(absolute);
+    const parent = resolveThroughExistingAncestor(path.dirname(absolute));
+    return basename ? path.join(parent, basename) : parent;
+}
+/** Resolve path ancestors while preserving the final symlink as a literal node. */
+export function resolveProtectedCandidateWithoutFinalSymlink(value, cwd = process.cwd()) {
+    return resolveWithoutFinalSymlink(value, cwd);
+}
+function relativeWithinRoot(value, root) {
+    if (!isSameOrDescendant(value, root))
+        return undefined;
+    return path.relative(root, value).split(path.sep).join('/');
+}
+/**
+ * Classify one literal filesystem path without interpreting shell syntax.
+ * `followFinalSymlink=false` is used by stat/lstat policy so metadata queries
+ * describe the link itself rather than exposing the protected target.
+ */
+export function classifyProtectedPath(value, options = {}) {
+    if (typeof value !== 'string' || !value.trim() || hasPathSyntax(value))
+        return 'unknown';
+    const root = resolveThroughExistingAncestor(options.root ?? resolveRoot());
+    const lexical = resolveWithoutFinalSymlink(value, options.cwd);
+    const followFinalSymlink = options.followFinalSymlink !== false;
+    const candidate = followFinalSymlink ? resolveProtectedCandidate(value, options.cwd) : lexical;
+    const relative = relativeWithinRoot(candidate, root);
+    if (relative === undefined)
+        return 'ordinary';
+    const hMatch = matchesHClassRelative(relative);
+    if (hMatch) {
+        let directory = H_CLASS_DIRECTORY_RELATIVE_PATTERNS.some(pattern => pattern.test(relative));
+        try {
+            const statTarget = followFinalSymlink ? candidate : lexical;
+            directory = fs.lstatSync(statTarget).isDirectory();
+        }
+        catch {
+            // Missing paths below a protected directory inherit that directory's
+            // class; missing exact H-class filenames remain H-class files.
+        }
+        return directory ? 'h-directory' : 'h-file';
+    }
+    const lMatch = L_CLASS_RELATIVE_PATTERNS.some(pattern => pattern.test(relative));
+    if (lMatch)
+        return 'l-path';
+    return 'ordinary';
+}
+/** Apply the H/L path-class × access-action matrix to one literal path. */
+export function checkProtectedPathAccess(value, accessKind, options = {}) {
+    const pathClass = classifyProtectedPath(value, options);
+    if (pathClass === 'unknown')
+        return { pathClass, accessKind, allowed: false };
+    if (pathClass === 'h-file' || pathClass === 'h-directory') {
+        return { pathClass, accessKind, allowed: accessKind === 'metadata' };
+    }
+    if (pathClass === 'l-path') {
+        return {
+            pathClass,
+            accessKind,
+            allowed: accessKind !== 'write' && accessKind !== 'grant',
+        };
+    }
+    return {
+        pathClass,
+        accessKind,
+        allowed: accessKind !== 'write' && accessKind !== 'grant',
+    };
 }
 export function containsHClassReference(value) {
     const normalized = value.replace(/\\/g, '/');