evolcore 0.0.19 → 0.0.20

package/dist/core/bootstrap-service.js

@@ -5,7 +5,7 @@ import { kitsTemplatesDir, agentMdPath } from '../paths.js';
 import { resolveAgentDisplayName } from '../aun/aid/agentmd.js';
 import { logger } from '../utils/logger.js';
 import { loadAgent, saveAgent } from '../config-store.js';
-import { normalizeAgentLifecycle, withLifecycleForWrite } from '../config/lifecycle.js';
+import { resolveAgentLifecycle, withLifecycleForWrite } from '../config/lifecycle.js';
 import { renderTemplate } from '../eck/manifest-engine.js';
 import { activeBaseagent } from './model/config-scope.js';
 import { buildEnvelope } from './message/message-utils.js';
@@ -123,12 +123,18 @@ export class BootstrapService {
             this.inFlight.delete(key);
             return false;
         }
-        const config = normalizeAgentLifecycle(loadedConfig);
-        if (config.lifecycle === 'active') {
+        const lifecycle = resolveAgentLifecycle(loadedConfig);
+        if (lifecycle === 'active') {
             this.inFlight.delete(key);
             return false;
         }
-        const starting = config.lifecycle === 'created';
+        if (lifecycle !== 'created' && lifecycle !== 'bootstrapping') {
+            this.inFlight.delete(key);
+            logger.warn(`[Bootstrap] Refusing invalid lifecycle for ${aid}: ${String(loadedConfig.lifecycle)}`);
+            return false;
+        }
+        const config = { ...loadedConfig, lifecycle };
+        const starting = lifecycle === 'created';
         const channelType = ctx.channelType || this.channelTypeFromKey(ctx.channelKey);
         const configuredRecipient = this.resolveConfiguredRecipient(config, ctx.channelKey, channelType);
         const recipientId = ctx.recipientId || configuredRecipient;
@@ -140,35 +146,14 @@ export class BootstrapService {
             this.inFlight.delete(key);
             return false;
         }
-        // The bootstrap prompt is deliberately a private message to the configured
-        // owner. An inbound owner message may have arrived from a group, in which
-        // case ctx.channelId is the group AID and must not be paired with the
-        // private delivery route below (that would call message.send(to=group)).
-        // A configured AUN recipient may itself be a group AID. Ask the channel's
-        // authoritative group endpoint before choosing the transport; never infer
-        // group/private semantics from the AID string or from the inbound venue.
-        let isGroupRecipient = false;
-        try {
-            isGroupRecipient = channelType === 'aun'
-                ? (await ctx.adapter.isGroup?.(recipientId)) === true
-                : false;
-        }
-        catch (error) {
-            // Group/private routing is security-sensitive. If the authoritative
-            // probe fails, do not guess a route, and release the single-flight key
-            // so a later connection or retry can recover.
-            this.inFlight.delete(key);
-            logger.warn(`[Bootstrap] Failed to resolve recipient type for ${aid}: ${error instanceof Error ? error.message : String(error)}`);
-            return false;
-        }
-        const delivery = isGroupRecipient === true
-            ? { chatType: 'group', groupId: recipientId }
-            : { chatType: 'private' };
-        const channelId = delivery.chatType === 'group'
-            ? delivery.groupId
-            : channelType === 'aun'
-                ? recipientId
-                : ctx.channelId || this.defaultChannelIdForConnection(channelType, recipientId);
+        // Bootstrap is initiated by connection/owner binding, not by a reply to
+        // an existing group message. `owners[]` contains personal Owner AIDs, so
+        // the first prompt must always use the private message route. Inbound
+        // group context must never change this initial delivery target.
+        const delivery = { chatType: 'private' };
+        const channelId = channelType === 'aun'
+            ? recipientId
+            : ctx.channelId || this.defaultChannelIdForConnection(channelType, recipientId);
         if (!channelId) {
             this.inFlight.delete(key);
             return false;
@@ -234,14 +219,14 @@ export class BootstrapService {
         const loadedConfig = loadAgent(aid) || agent?.config;
         if (!loadedConfig)
             return { ok: false, error: `Agent "${aid}" not found` };
-        const lifecycle = normalizeAgentLifecycle(loadedConfig).lifecycle;
+        const lifecycle = resolveAgentLifecycle(loadedConfig);
         if (lifecycle === 'active')
             return { ok: true, aid, transitioned: false };
         if (lifecycle !== 'bootstrapping') {
             return {
                 ok: false,
                 code: 'INVALID_LIFECYCLE',
-                error: `Agent "${aid}" is ${lifecycle}; only a bootstrapping agent can become ready`,
+                error: `Agent "${aid}" is ${lifecycle ?? `invalid (${String(loadedConfig.lifecycle)})`}; only a bootstrapping agent can become ready`,
             };
         }
         this.setLifecycle(agent, aid, 'active');
@@ -253,7 +238,7 @@ export class BootstrapService {
         const agent = this.agentRegistry.get(aid);
         const loadedConfig = loadAgent(aid) || agent?.config;
         return loadedConfig
-            ? normalizeAgentLifecycle(loadedConfig).lifecycle
+            ? resolveAgentLifecycle(loadedConfig)
             : null;
     }
     setLifecycle(agent, aid, lifecycle) {

package/dist/core/channel-loader.js

@@ -65,7 +65,6 @@ export class ChannelLoader {
             owner: agent.getOwner(aunEffName),
             enabled: true,
             keystorePath: agent.config.aun?.keystorePath,
-            gatewayUrl: agent.config.aun?.gatewayUrl,
         };
         const configInsts = [aunInst];
         for (const inst of agent.config.channels) {
@@ -255,7 +254,6 @@ export function buildReloadHooks(deps) {
                     aid,
                     enabled: true,
                     keystorePath: agent.config?.aun?.keystorePath,
-                    gatewayUrl: agent.config?.aun?.gatewayUrl,
                 }
                 : (() => {
                     const agentChannels = agent.config?.channels ?? [];

package/dist/core/evolagent.js

@@ -243,16 +243,17 @@ export class EvolAgent {
                 b.mentionMode = value;
         });
     }
-    /** 读取观察者模式开关（默认 false）。 */
+    /** 读取观察者模式开关（默认 true；显式 false 可关闭）。 */
     getObservable() {
-        return this.merged.observable === true;
+        return this.merged.observable ?? true;
     }
     /** 设置观察者模式开关：开启后入站/出站消息各转发一份给 owners[]。 */
     setObservable(value) {
+        // The default is enabled, so false must remain an explicit persisted override.
         if (value)
-            this.rawAgent.observable = true;
-        else
             delete this.rawAgent.observable;
+        else
+            this.rawAgent.observable = false;
         this.merged.observable = value;
         this.persist();
     }

package/dist/core/message/response-engine.js

@@ -33,6 +33,7 @@ import { eligibleFallbackModels } from '../model/model-fallback.js';
 import { RetryScheduler } from './retry-scheduler.js';
 import { constrainRuntimePermissionMode, resolveRuntimeStringField } from '../role/runtime-policy.js';
 import { resolveEffective, resolveEffectiveFieldWithSource } from '../../config/config-manager.js';
+import { resolveAgentLifecycle } from '../../config/lifecycle.js';
 import { authorizationConfigRevision, checkRoleAccess, getFirstStaticAgentOwner, listStaticAgentAdmins, listStaticAgentOwners, resolvePeerRoleDetail, roleToSessionIdentity, } from '../../config/peer-role-resolver.js';
 import { insertUsageEvent, insertContextBreakdown, insertModelCalls } from '../../stats/writer.js';
 import { normalizeUsage } from '../../stats/normalizer.js';
@@ -1606,7 +1607,9 @@ export class ResponseEngine {
         const owningAgentForTask = this.agentRegistry?.resolveByChannel(channelKey)
             ?? (taskAgentAid ? this.agentRegistry?.get(taskAgentAid) : null);
         const runnerSelfAid = owningAgentForTask?.aid || session.selfAID || message.selfAID;
-        const lifecycle = owningAgentForTask?.config?.lifecycle;
+        const lifecycle = owningAgentForTask
+            ? resolveAgentLifecycle(owningAgentForTask.config)
+            : undefined;
         const isActive = lifecycle === 'active';
         const isBootstrapping = lifecycle === 'bootstrapping';
         // Per-method agent name for stats bucketing (agent.name or '<unknown>')
@@ -1617,10 +1620,12 @@ export class ResponseEngine {
             return;
         }
         // Agent-owned turns are runnable only in the two explicit execution
-        // states. An untransitioned `created` agent or a malformed/missing
-        // lifecycle must not fall through to a base runner's default prompt.
+        // states. An untransitioned `created` agent or malformed lifecycle must
+        // not fall through to a base runner's default prompt. Missing lifecycle
+        // is normalized to active for legacy configurations.
         if (owningAgentForTask && !isActive && !isBootstrapping) {
-            const blockedLifecycle = lifecycle ?? 'missing';
+            const blockedLifecycle = lifecycle
+                ?? `invalid (${String(owningAgentForTask.config.lifecycle)})`;
             logger.error(`[ResponseEngine] Agent lifecycle is not runnable: agent=${owningAgentForTask.aid} lifecycle=${blockedLifecycle}`);
             this.publishTriggerExecutionFailure(message, `agent_lifecycle_not_runnable:${blockedLifecycle}`);
             return;

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

@@ -17,7 +17,57 @@ const POWERSHELL_UNQUOTED_META = new Set([
     ';', '&', '|', '<', '>', '$', '(', ')', '*', '?', '[', ']', '{', '}', '#', '@',
 ]);
 const AMBIGUOUS_FILE_PATH_RE = /[\0\r\n$`*?\[\]{}<>|;&]/;
-const EVOLCORE_COMMAND_POSITION_RE = /(?:^|[;&|()`])\s*ec(?=\s|[;&|()<>`]|$)/i;
+// 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.
+function hasEcCommandPrefix(command) {
+    let quote = null;
+    let escaped = false;
+    let boundary = true;
+    for (let index = 0; index < command.length; index++) {
+        const char = command[index];
+        if (escaped) {
+            escaped = false;
+            boundary = false;
+            continue;
+        }
+        if (quote === 'single') {
+            if (char === "'")
+                quote = null;
+            continue;
+        }
+        if (quote === 'double') {
+            if (char === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (char === '"')
+                quote = null;
+            continue;
+        }
+        if (char === "'") {
+            quote = 'single';
+            boundary = false;
+            continue;
+        }
+        if (char === '"') {
+            quote = 'double';
+            boundary = false;
+            continue;
+        }
+        if (/[;&|`()<>]/.test(char)) {
+            boundary = true;
+            continue;
+        }
+        if (boundary && /\s/.test(char))
+            continue;
+        if (boundary && command.slice(index, index + 2).toLowerCase() === 'ec'
+            && (index + 2 === command.length || /\s|[;&|`()<>]/.test(command[index + 2])))
+            return true;
+        boundary = false;
+    }
+    return false;
+}
 function trimShellSpacing(value) {
     return value.replace(/^[ \t]+|[ \t]+$/g, '');
 }
@@ -1059,7 +1109,7 @@ export function classifyEvolcoreShellCommand(command, options = {}) {
             });
             if (nested.ok && nested.argv[0] === 'ec')
                 return { kind: 'literal' };
-            if (!nested.ok && EVOLCORE_COMMAND_POSITION_RE.test(carrier.command)) {
+            if (!nested.ok && hasEcCommandPrefix(carrier.command)) {
                 return { kind: 'composite', issue: nested.issue };
             }
         }
@@ -1071,7 +1121,10 @@ export function classifyEvolcoreShellCommand(command, options = {}) {
     if (boundedOutput && boundedOutput.argv[0] === 'ec') {
         return { kind: 'bounded-output', command: boundedOutput };
     }
-    return EVOLCORE_COMMAND_POSITION_RE.test(command)
+    // 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)
         ? { kind: 'composite', issue: literal.issue }
         : { kind: 'none' };
 }

package/dist/core/permission/sandbox-runtime.js

@@ -285,6 +285,48 @@ function appendLClassReadOnlyBinds(args, root) {
         args.push('--ro-bind', target.path, target.path);
     }
 }
+export function ensureCodexManagedMountpoint(systemConfigDirectory = '/etc/codex', effectiveUid = typeof process.getuid === 'function' ? process.getuid() : undefined) {
+    let systemConfigStat;
+    try {
+        systemConfigStat = fs.lstatSync(systemConfigDirectory);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error(`Codex managed requirements mountpoint is unavailable: ${systemConfigDirectory} `
+                + `could not be inspected (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    if (!systemConfigStat && process.platform === 'linux' && effectiveUid === 0) {
+        let created = false;
+        try {
+            fs.mkdirSync(systemConfigDirectory, { mode: 0o755 });
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw new Error(`Codex managed requirements mountpoint is unavailable: ${systemConfigDirectory} `
+                    + `could not be created by the root daemon (${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
+        if (created)
+            fs.chmodSync(systemConfigDirectory, 0o755);
+        try {
+            systemConfigStat = fs.lstatSync(systemConfigDirectory);
+        }
+        catch (error) {
+            throw new Error(`Codex managed requirements mountpoint is unavailable: ${systemConfigDirectory} `
+                + `could not be verified after creation (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    if (!systemConfigStat) {
+        throw new Error(`Codex managed requirements mountpoint is unavailable: ${systemConfigDirectory} `
+            + 'must be created as a real directory during installation; run: sudo install -d -m 0755 /etc/codex');
+    }
+    if (!systemConfigStat.isDirectory() || systemConfigStat.isSymbolicLink()) {
+        throw new Error(`Codex managed requirements mountpoint is unsafe: ${systemConfigDirectory} `
+            + 'must be a real directory');
+    }
+}
 export function buildHClassGuardCommand(executable, executableArgs, root = resolveRoot(), options = {}) {
     const bubblewrapPath = resolveBubblewrapPath();
     if (!bubblewrapPath)
@@ -306,18 +348,10 @@ export function buildHClassGuardCommand(executable, executableArgs, root = resol
         }
         const managedDirectory = path.dirname(requirements);
         const systemConfigDirectory = '/etc/codex';
-        let systemConfigStat;
-        try {
-            systemConfigStat = fs.lstatSync(systemConfigDirectory);
-        }
-        catch {
-            throw new Error(`Codex managed requirements mountpoint is unavailable: ${systemConfigDirectory} `
-                + 'must be created as a real directory during installation');
-        }
-        if (!systemConfigStat.isDirectory() || systemConfigStat.isSymbolicLink()) {
-            throw new Error(`Codex managed requirements mountpoint is unsafe: ${systemConfigDirectory} `
-                + 'must be a real directory');
-        }
+        // The npm lifecycle and public installer provision this path. Root-owned
+        // legacy daemons may repair only the missing-directory case; unsafe path
+        // types and unprivileged processes remain fail-closed.
+        ensureCodexManagedMountpoint(systemConfigDirectory);
         // Keep the copied hook immutable even when a session uses bypass mode.
         args.push('--ro-bind', managedDirectory, managedDirectory);
         // The guard starts from a writable root so owner-bypass workspaces keep

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

@@ -425,7 +425,7 @@ function shellOperandMatchesClass(operand, className, options, accessKind = oper
         const workspace = options.cwd ? resolveProtectedCandidate(options.cwd) : undefined;
         if (isSameOrDescendant(candidate, managedTemp)
             && (!workspace || !isSameOrDescendant(candidate, workspace))) {
-            return false;
+            return undefined;
         }
     }
     if (className === 'h' && accessKind === 'metadata' && operand.access === 'exact') {
@@ -439,27 +439,31 @@ function shellOperandMatchesClass(operand, className, options, accessKind = oper
             followFinalSymlink: false,
         });
         if (options.allowProtectedMetadata === false) {
-            return metadata.pathClass === 'h-file' || metadata.pathClass === 'h-directory';
+            return metadata.pathClass === 'h-file' || metadata.pathClass === 'h-directory'
+                ? resolveProtectedCandidate(operand.value, options.cwd)
+                : undefined;
         }
         // The no-follow decision is authoritative for metadata. In particular,
         // an ordinary symlink whose target is H-class must remain inspectable as a
         // link; falling through to isHClassPath() would follow it and reject the
         // otherwise safe lstat/stat operation.
         if (metadata.pathClass !== 'unknown' && metadata.allowed) {
-            return false;
+            return undefined;
         }
     }
     const reference = className === 'h' ? containsHClassReference(operand.value) : containsLClassReference(operand.value);
     if (reference)
-        return true;
+        return resolveProtectedCandidate(operand.value, options.cwd);
     if (operand.access === 'recursive') {
-        return className === 'h'
+        const matched = className === 'h'
             ? hClassReadScopeIncludesProtectedPath(operand.value, options)
             : lClassGrantIncludesProtectedPath(operand.value, options);
+        return matched ? resolveProtectedCandidate(operand.value, options.cwd) : undefined;
     }
-    return className === 'h'
+    const matched = className === 'h'
         ? isHClassPath(operand.value, options)
         : isLClassPath(operand.value, options);
+    return matched ? resolveProtectedCandidate(operand.value, options.cwd) : undefined;
 }
 /**
  * A read-only recursive query only needs to cover H-class targets that exist
@@ -489,16 +493,41 @@ function analyzeShellProtectedOperands(command, options) {
         };
     }
     const operands = queryPathOperands(analysis);
-    const lockDiagnostic = /(?:^|[\/\s'"`])(?:[^\s'"`/]*\.lock|EVOLCORE_RUNTIME_LOCK_DIR)(?=$|[\/\s'"`=])/i.test(command);
-    const pathHClass = operands.some(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'h', options, accessKind));
+    // Only parsed path operands can establish a lock-file diagnostic. Searching
+    // the raw command would mistake a grep/rg pattern or report text for an
+    // actual protected filesystem target.
+    const lockDiagnostic = operands.some(({ operand }) => containsLockPathReference(operand.value))
+        || hasFindLockPattern(analysis);
+    const hClassPath = operands.map(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'h', options, accessKind)).find(Boolean);
+    const lClassPath = operands.map(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'l', options, accessKind)).find(Boolean);
     return {
         analysis,
-        hClass: lockDiagnostic || pathHClass,
-        lClass: operands.some(({ operand, accessKind }) => shellOperandMatchesClass(operand, 'l', options, accessKind)),
-        pathHClass,
+        hClass: lockDiagnostic || !!hClassPath,
+        lClass: !!lClassPath,
+        pathHClass: !!hClassPath,
         lockDiagnostic,
+        hClassPath,
+        lClassPath,
     };
 }
+/** Detect a find pattern such as `-name '*.lock'` from parsed argv only. */
+function hasFindLockPattern(analysis) {
+    if (analysis.kind !== 'proven-readonly')
+        return false;
+    return analysis.ir.pipelines.some(pipeline => pipeline.some(command => {
+        if (command.executable !== 'find')
+            return false;
+        for (let index = 0; index < command.argv.length - 1; index++) {
+            if (!['-name', '-iname', '-path', '-ipath', '-wholename'].includes(command.argv[index]))
+                continue;
+            if (/(?:^|[\\/])[^\\/]*\.lock(?:$|[\\/])/i.test(command.argv[index + 1]))
+                return true;
+            if (/^EVOLCORE_RUNTIME_LOCK_DIR$/i.test(command.argv[index + 1]))
+                return true;
+        }
+        return false;
+    }));
+}
 function protectedReadToolPaths(toolName, input) {
     if (toolName === 'Read') {
         return typeof input.file_path === 'string' ? [input.file_path] : [];
@@ -513,33 +542,43 @@ function protectedReadToolPaths(toolName, input) {
 }
 function protectedReadToolMatchesLClass(toolName, input, options) {
     const paths = protectedReadToolPaths(toolName, input);
-    if (paths.some(filePath => containsLClassReference(filePath) || isLClassPath(filePath, options))) {
-        return true;
+    const direct = paths.find(filePath => containsLClassReference(filePath) || isLClassPath(filePath, options));
+    if (direct) {
+        return resolveProtectedCandidate(direct, options.cwd);
     }
     if (toolName === 'Grep') {
         const scope = typeof input.path === 'string' && input.path ? input.path : '.';
-        return lClassGrantIncludesProtectedPath(scope, options);
+        return lClassGrantIncludesProtectedPath(scope, options)
+            ? resolveProtectedCandidate(scope, options.cwd)
+            : undefined;
     }
     if (toolName === 'Glob') {
         const scope = globReadScope(input, options);
-        return lClassGrantIncludesProtectedPath(scope, { root: options.root });
+        return lClassGrantIncludesProtectedPath(scope, { root: options.root })
+            ? resolveProtectedCandidate(scope, options.cwd)
+            : undefined;
     }
-    return false;
+    return undefined;
 }
 function protectedReadToolMatchesHClass(toolName, input, options) {
     const paths = protectedReadToolPaths(toolName, input);
-    if (paths.some(filePath => containsHClassReference(filePath) || isHClassPath(filePath, options))) {
-        return true;
+    const direct = paths.find(filePath => containsHClassReference(filePath) || isHClassPath(filePath, options));
+    if (direct) {
+        return resolveProtectedCandidate(direct, options.cwd);
     }
     if (toolName === 'Grep') {
         const scope = typeof input.path === 'string' && input.path ? input.path : '.';
-        return hClassReadScopeIncludesProtectedPath(scope, options);
+        return hClassReadScopeIncludesProtectedPath(scope, options)
+            ? resolveProtectedCandidate(scope, options.cwd)
+            : undefined;
     }
     if (toolName === 'Glob') {
         const scope = globReadScope(input, options);
-        return hClassReadScopeIncludesProtectedPath(scope, options);
+        return hClassReadScopeIncludesProtectedPath(scope, options)
+            ? resolveProtectedCandidate(scope, options.cwd)
+            : undefined;
     }
-    return false;
+    return undefined;
 }
 function globLiteralPrefix(pattern) {
     const normalized = pattern.replace(/\\/g, '/');
@@ -646,14 +685,17 @@ export function checkReadonly(toolName, input, projectPath, context) {
         if (!protectedReadToolStaysInWorkspace(toolName, input, projectPath)) {
             return { behavior: 'deny', message: '🔒 只读模式：文件读取范围不能越出当前项目目录', policyCode: 'readonly_workspace_escape' };
         }
-        if (paths.some(filePath => containsHClassReference(filePath) || isHClassPath(filePath, pathOptions))) {
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
+        const directHPath = paths.find(filePath => containsHClassReference(filePath) || isHClassPath(filePath, pathOptions));
+        if (directHPath) {
+            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read', matchedPath: resolveProtectedCandidate(directHPath, projectPath) };
         }
-        if (protectedReadToolMatchesHClass(toolName, input, pathOptions)) {
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
+        const hPath = protectedReadToolMatchesHClass(toolName, input, pathOptions);
+        if (hPath) {
+            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read', matchedPath: hPath };
         }
-        if (protectedReadToolMatchesLClass(toolName, input, pathOptions)) {
-            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read' };
+        const lPath = protectedReadToolMatchesLClass(toolName, input, pathOptions);
+        if (lPath) {
+            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read', matchedPath: lPath };
         }
         return { behavior: 'allow' };
     }
@@ -691,11 +733,15 @@ export function checkReadonly(toolName, input, projectPath, context) {
         }
         if (protectedOperands.hClass) {
             logger.warn(`[ReadonlyCheck] 🔒 H-class path blocked in readonly shell: cmd="${cmd}" session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-            return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read' };
+            if (protectedOperands.analysis.kind === 'proven-readonly') {
+                return { behavior: 'deny', message: '🔒 只读模式：不允许读取 H 类受保护路径', policyCode: 'readonly_h_class_read', matchedPath: protectedOperands.hClassPath };
+            }
         }
         if (protectedOperands.lClass) {
             logger.warn(`[ReadonlyCheck] 🔒 L-class path blocked in readonly shell: cmd="${cmd}" session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read' };
+            if (protectedOperands.analysis.kind === 'proven-readonly') {
+                return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', policyCode: 'readonly_l_class_read', matchedPath: protectedOperands.lClassPath };
+            }
         }
         if (protectedOperands.analysis.kind === 'proven-readonly') {
             return { behavior: 'deny', message: '🔒 只读模式：Shell 查询范围不能越出当前项目目录', policyCode: 'readonly_workspace_escape' };
@@ -967,6 +1013,7 @@ export function checkHClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 临时文件必须位于当前会话的 $TMPDIR 内',
+                matchedPath: tempCheck.paths[0],
             };
         }
         // A managed temp write is intentionally allowed to contain names such as
@@ -992,6 +1039,7 @@ export function checkHClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 Shell 命令涉及受保护的 H 类配置/证书/快照路径，agent 不可直接操作',
+                matchedPath: protectedOperands.hClassPath,
             };
         }
         collectFilesystemGrantPaths(input.additionalPermissions, grantPaths, projectRootGrantSubpaths);
@@ -1010,14 +1058,17 @@ export function checkHClassWrite(toolName, input, context) {
     // filesystem operation is checked again when it reaches Read/Write/Bash,
     // FileChange, or PermissionGrant above.
     const pathOptions = { cwd: context?.projectPath, root: context?.root };
-    if (['Read', 'Glob', 'Grep'].includes(toolName)
-        && protectedReadToolMatchesHClass(toolName, input, pathOptions)) {
-        logger.warn(`[H-Class Protection] 🔒 Protected filesystem read scope blocked: tool=${toolName} ` +
-            `session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
-        return {
-            behavior: 'deny',
-            message: '🔒 文件读取范围包含受保护的 H 类配置/证书/快照路径，agent 不可直接操作',
-        };
+    if (['Read', 'Glob', 'Grep'].includes(toolName)) {
+        const matchedReadPath = protectedReadToolMatchesHClass(toolName, input, pathOptions);
+        if (matchedReadPath) {
+            logger.warn(`[H-Class Protection] 🔒 Protected filesystem read scope blocked: tool=${toolName} ` +
+                `session=${context?.sessionId} channel=${context?.channel} peer=${context?.peerId} role=${context?.role}`);
+            return {
+                behavior: 'deny',
+                message: '🔒 文件读取范围包含受保护的 H 类配置/证书/快照路径，agent 不可直接操作',
+                matchedPath: matchedReadPath,
+            };
+        }
     }
     if (requestsFilesystemRoot(input.permissions) || requestsFilesystemRoot(input.additionalPermissions)) {
         logger.warn(`[H-Class Protection] 🔒 Permission grant covers filesystem root: tool=${toolName} ` +
@@ -1036,6 +1087,7 @@ export function checkHClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 请求的文件系统权限范围包含受保护的 H 类路径，已拒绝授权',
+                matchedPath: resolveProtectedCandidate(grantPath, pathOptions.cwd),
             };
         }
     }
@@ -1059,6 +1111,7 @@ export function checkHClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 请求的 project_roots 权限范围包含受保护的 H 类路径，已拒绝授权',
+                matchedPath: resolveProtectedCandidate(candidate, permissionWorkspace),
             };
         }
     }
@@ -1093,7 +1146,8 @@ export function checkHClassWrite(toolName, input, context) {
                 behavior: 'deny',
                 message: `🔒 此文件受保护，agent 不可直接写入\n\n` +
                     `文件：${filePath}\n` +
-                    `类型：配置/快照/证书等系统关键文件${suggestion}`
+                    `类型：配置/快照/证书等系统关键文件${suggestion}`,
+                matchedPath: resolveProtectedCandidate(filePath, pathOptions.cwd),
             };
         }
     }
@@ -1108,7 +1162,7 @@ export function checkLClassWrite(toolName, input, context) {
         const pathOptions = { cwd: context?.projectPath, root: context?.root };
         const lClassRead = protectedReadToolMatchesLClass(toolName, input, pathOptions);
         if (lClassRead && context?.permissionMode === 'readonly') {
-            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径' };
+            return { behavior: 'deny', message: '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径', matchedPath: lClassRead };
         }
         return { behavior: 'allow' };
     }
@@ -1149,6 +1203,7 @@ export function checkLClassWrite(toolName, input, context) {
                 message: context?.permissionMode === 'readonly'
                     ? '🔒 只读模式：visitor 最低权限不允许读取 L-class 路径'
                     : '🔒 L-class 路径允许读取，但当前 Bash 复合命令无法证明为只读，已拒绝执行。请改用受控的 EvolCore 读取命令或白名单只读命令',
+                matchedPath: protectedOperands.lClassPath,
             };
         }
         collectFilesystemWriteGrantPaths(input.additionalPermissions, writeGrantPaths, projectRootWriteSubpaths);
@@ -1167,6 +1222,7 @@ export function checkLClassWrite(toolName, input, context) {
             return {
                 behavior: 'deny',
                 message: '🔒 请求的文件系统写权限包含 L-class 只读路径，已拒绝授权',
+                matchedPath: resolveProtectedCandidate(grantPath, pathOptions.cwd),
             };
         }
     }
@@ -1188,6 +1244,7 @@ export function checkLClassWrite(toolName, input, context) {
         return {
             behavior: 'deny',
             message: `🔒 L-class 路径允许读取但禁止 Agent 直接修改、删除或移动\n\n文件：${filePath}\n\n💡 请使用对应的 EvolCore 受控命令修改`,
+            matchedPath: resolveProtectedCandidate(filePath, pathOptions.cwd),
         };
     }
     return { behavior: 'allow' };
@@ -1472,7 +1529,7 @@ export function evaluateToolPreflight(toolName, input, context) {
         allowProtectedMetadata: context.allowProtectedMetadata,
     });
     if (hClass.behavior === 'deny') {
-        return { behavior: 'deny', input: checkedInput, message: hClass.message, policyCode: 'h_class_protection' };
+        return { behavior: 'deny', input: checkedInput, message: hClass.message, policyCode: 'h_class_protection', matchedPath: hClass.matchedPath };
     }
     const lClass = checkLClassWrite(toolName, checkedInput, {
         sessionId: context.sessionId,
@@ -1486,7 +1543,7 @@ export function evaluateToolPreflight(toolName, input, context) {
         managedTempDir: context.managedTempDir,
     });
     if (lClass.behavior === 'deny') {
-        return { behavior: 'deny', input: checkedInput, message: lClass.message, policyCode: 'l_class_protection' };
+        return { behavior: 'deny', input: checkedInput, message: lClass.message, policyCode: 'l_class_protection', matchedPath: lClass.matchedPath };
     }
     const dangerous = checkDangerousCommand(toolName, checkedInput);
     if (dangerous.isDangerous