helloagents 3.0.3-beta.1 → 3.0.8-beta.1

package/scripts/guard.mjs

@@ -4,214 +4,264 @@
  * Runs on PreToolUse hook for Bash/shell commands.
  * Runs on PostToolUse hook for Write/Edit (L2 scan).
  */
-import { readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
 
-const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json');
+import { buildStateSyncHint, getWorkflowRecommendation } from './workflow-state.mjs'
+import { getApplicableRouteContext } from './runtime-context.mjs'
+import { appendReplayEvent } from './replay-state.mjs'
+import {
+  DANGEROUS_PATTERNS,
+  IDEA_SIDE_EFFECT_COMMAND_PATTERNS,
+  scanDangerousPackages,
+  scanEnvCoverage,
+  scanForSecrets,
+  scanHighRiskCommands,
+  scanShellSafetyWarnings,
+  scanUnrequestedFiles,
+} from './guard-rules.mjs'
 
-// Hook event name: read from env or infer from CLI mode + --gemini flag.
-// Claude: PreToolUse/PostToolUse, Gemini: BeforeTool/AfterModel.
-const IS_GEMINI = process.argv.includes('--gemini');
-const IS_POST_WRITE = process.argv.includes('post-write');
+const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json')
+const IS_GEMINI = process.argv.includes('--gemini')
+const HOST = IS_GEMINI ? 'gemini' : 'claude'
 const HOOK_EVENT = process.env.HELLOAGENTS_HOOK_EVENT
-  || (IS_POST_WRITE ? (IS_GEMINI ? 'AfterModel' : 'PostToolUse') : (IS_GEMINI ? 'BeforeTool' : 'PreToolUse'));
+  || (
+    process.argv.includes('post-write')
+      ? (IS_GEMINI ? 'AfterModel' : 'PostToolUse')
+      : (IS_GEMINI ? 'BeforeTool' : 'PreToolUse')
+  )
 
 function readSettings() {
-  try { return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8')); } catch {}
-  return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'))
+  } catch {
+    return {}
+  }
 }
 
-function emitHookPayload(payload) {
-  process.stdout.write(JSON.stringify(payload));
-}
-
-const DANGEROUS_PATTERNS = [
-  // Destructive file operations (including sudo prefix and long options)
-  { pattern: /(sudo\s+)?rm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?(-[a-zA-Z]*r[a-zA-Z]*\s+)?(\/|~|\*)/, reason: 'Recursive delete of critical path' },
-  { pattern: /(sudo\s+)?rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+)?(-[a-zA-Z]*f[a-zA-Z]*\s+)?(\/|~|\*)/, reason: 'Recursive delete of critical path' },
-  { pattern: /(sudo\s+)?rm\s+--recursive/, reason: 'Recursive delete (long option)' },
-  { pattern: /(sudo\s+)?rm\s+-[a-zA-Z]*r[a-zA-Z]*\s+\.\.?(\s|$)/, reason: 'Recursive delete of current/parent directory' },
-  // Force push
-  { pattern: /git\s+push\s+(-f|--force)/, reason: 'Force push (specify branch explicitly)' },
-  // Hard reset
-  { pattern: /git\s+reset\s+--hard/, reason: 'Hard reset (destructive operation)' },
-  // Database destruction
-  { pattern: /DROP\s+(DATABASE|TABLE|SCHEMA)/i, reason: 'Database destruction command' },
-  { pattern: /TRUNCATE\s+TABLE/i, reason: 'Table truncation' },
-  // Dangerous system commands
-  { pattern: /chmod\s+777/, reason: 'World-writable permissions' },
-  { pattern: /mkfs\b/, reason: 'Filesystem format command' },
-  { pattern: /dd\s+.*of=\/dev\//, reason: 'Direct device write' },
-  // Redis flush
-  { pattern: /FLUSHALL|FLUSHDB/i, reason: 'Redis data flush' },
-];
-
-// ── L2 Semantic Security Patterns (advisory, non-blocking) ──────────────────
-
-const SECRET_PATTERNS = [
-  { pattern: /AKIA[0-9A-Z]{16}/, reason: 'AWS Access Key ID detected' },
-  { pattern: /ghp_[a-zA-Z0-9]{36}/, reason: 'GitHub Personal Access Token detected' },
-  { pattern: /github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}/, reason: 'GitHub Fine-grained PAT detected' },
-  { pattern: /sk-[a-zA-Z0-9]{20,}/, reason: 'API secret key pattern detected (sk-)' },
-  { pattern: /key-[a-zA-Z0-9]{20,}/, reason: 'API key pattern detected (key-)' },
-  { pattern: /-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----/, reason: 'Private key detected' },
-  { pattern: /password\s*[:=]\s*["'][^"']{4,}["']/i, reason: 'Hardcoded password detected' },
-  { pattern: /secret\s*[:=]\s*["'][^"']{4,}["']/i, reason: 'Hardcoded secret detected' },
-  { pattern: /AIza[0-9A-Za-z\-_]{35}/, reason: 'Google API Key detected' },
-  { pattern: /xox[bpras]-[0-9a-zA-Z\-]+/, reason: 'Slack Token detected' },
-  { pattern: /eyJ[A-Za-z0-9\-_]+\.eyJ[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_.+/=]+/, reason: 'JWT token detected' },
-  { pattern: /(postgres|mysql|mongodb(\+srv)?):\/\/[^:]+:[^@]+@/i, reason: 'Database connection string with credentials detected' },
-  { pattern: /sk_live_[a-zA-Z0-9]{24,}/, reason: 'Stripe Secret Key detected' },
-  { pattern: /sk-ant-[a-zA-Z0-9\-]{20,}/, reason: 'Anthropic API Key detected' },
-];
-
-function scanForSecrets(content) {
-  const warnings = [];
-  for (const { pattern, reason } of SECRET_PATTERNS) {
-    if (pattern.test(content)) {
-      warnings.push(reason);
-    }
-  }
-  return warnings;
-}
-
-// ── Post-Write L2 Scan ──────────────────────────────────────────────────────
-// Triggered by PostToolUse matcher: Write|Edit|NotebookEdit (see hooks.json).
-// If Claude Code adds new file-writing tools, update the matcher accordingly.
-
-/** Check for unrequested file creation (Write tool only). */
-function scanUnrequestedFiles(filePath, toolName) {
-  if (!filePath || toolName?.toLowerCase() !== 'write') return [];
-  const basename = filePath.split(/[/\\]/).pop() || '';
-  const UNREQUESTED_PATTERNS = [
-    { pattern: /^(SUMMARY|NOTES|TODO|SCRATCH|TEMP)\.(md|txt)$/i, reason: `Unrequested file creation: ${basename}` },
-    { pattern: /^README.*\.md$/i, test: () => {
-      const depth = filePath.replace(/\\/g, '/').split('/').length;
-      return depth > 4;
-    }, reason: `Suspicious README creation in nested path: ${basename}` },
-  ];
-  const warnings = [];
-  for (const { pattern, test, reason } of UNREQUESTED_PATTERNS) {
-    if (pattern.test(basename) && (!test || test())) warnings.push(reason);
+function readHookInput() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
   }
-  return warnings;
 }
 
-/** Check for dangerous npm scripts and unsafe dependency patterns. */
-function scanDangerousPackages(content, filePath) {
-  const warnings = [];
-  if (filePath.endsWith('package.json')) {
-    const dangerousScripts = /("(preinstall|postinstall|preuninstall)")\s*:\s*"[^"]*\b(curl|wget|bash|sh|eval|exec)\b/i;
-    if (dangerousScripts.test(content)) {
-      warnings.push('Potentially dangerous lifecycle script in package.json (preinstall/postinstall with curl/wget/bash/eval)');
+function emitHookPayload(payload) {
+  process.stdout.write(JSON.stringify(payload))
+}
+
+function emitGuardEvent(cwd, event, source, reason, details = {}) {
+  appendReplayEvent(cwd, {
+    host: HOST,
+    event,
+    source,
+    reason,
+    details,
+  })
+}
+
+function buildHighRiskGate(matches, cwd) {
+  const stateSyncHint = buildStateSyncHint(cwd)
+  if (stateSyncHint) {
+    return {
+      reason: `[HelloAGENTS Guard] Blocked T3 command until project recovery state is synced.\n${stateSyncHint}`,
     }
   }
-  const unsafeInstall = /npm install\s+[^-].*--ignore-scripts\s*=\s*false|pip install\s+--trusted-host|pip install\s+http:/i;
-  if (unsafeInstall.test(content)) {
-    warnings.push('Unsafe dependency installation pattern detected');
+
+  const recommendation = getWorkflowRecommendation(cwd)
+  if (!recommendation) return null
+  if (matches.some((match) => match.gate === 'post-verify')) {
+    return {
+      reason: `[HelloAGENTS Guard] Blocked T3 command until workflow reaches VERIFY / CONSOLIDATE.\n当前工作流：${recommendation.summary}\n建议路径：${recommendation.nextPath}\n${recommendation.guidance}`,
+    }
   }
-  return warnings;
-}
-
-/** Check if .env file is covered by .gitignore. */
-function scanEnvCoverage(filePath) {
-  if (!filePath.endsWith('.env') && !filePath.includes('.env.')) return [];
-  let dir = dirname(filePath);
-  for (let i = 0; i < 10; i++) {
-    try {
-      const gitignore = readFileSync(join(dir, '.gitignore'), 'utf-8');
-      return gitignore.includes('.env') ? [] : ['.env file written but .gitignore does not contain .env pattern'];
-    } catch {
-      const parent = dirname(dir);
-      if (parent === dir) break;
-      dir = parent;
+  if (matches.some((match) => match.gate === 'plan-first') && recommendation.nextCommand === 'plan') {
+    return {
+      reason: `[HelloAGENTS Guard] Blocked T3 command because the current workflow still requires ~plan before risky schema changes.\n当前工作流：${recommendation.summary}\n建议路径：${recommendation.nextPath}\n${recommendation.guidance}`,
     }
   }
-  return ['.env file written but no .gitignore found'];
+  return null
 }
 
-function postWriteScan(data) {
-  const settings = readSettings();
-  if (settings.guard_enabled === false) {
-    return;
-  }
+function buildIdeaBoundaryReason(kind) {
+  return `[HelloAGENTS Guard] Blocked ${kind} during ~idea.\n当前路由：~idea 是只读探索；先停留在比较方案。若要写文件、改代码、创建知识库或执行有副作用的命令，请先升级到 ~plan / ~build / ~prd / ~auto。`
+}
 
-  const content = data.tool_input?.content || data.tool_input?.new_string || '';
-  const filePath = data.tool_input?.file_path || '';
+function detectIdeaBoundaryContext(data) {
+  return getApplicableRouteContext({
+    cwd: data.cwd || process.cwd(),
+    filePath: data.tool_input?.file_path || '',
+  })
+}
 
-  if (!content && !filePath) {
-    return;
-  }
+function emitIdeaBoundaryBlock(data, kind, target) {
+  const reason = `${buildIdeaBoundaryReason(kind)}\n${target}`
+  emitHookPayload({
+    hookSpecificOutput: {
+      hookEventName: HOOK_EVENT,
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  })
+  emitGuardEvent(data.cwd || process.cwd(), 'guard_blocked', kind === 'write' ? 'pre-write' : 'command', buildIdeaBoundaryReason(kind), {
+    command: kind === 'side-effect command' ? target.replace(/^Command:\s*/, '') : '',
+    target: kind === 'write' ? target.replace(/^Target:\s*/, '') : '',
+    guardType: kind === 'write' ? 'idea-write-boundary' : 'idea-command-boundary',
+  })
+}
 
-  const warnings = [
+function preWriteGuard(data) {
+  if (readSettings().guard_enabled === false) return
+  if (!detectIdeaBoundaryContext(data)?.zeroSideEffect) return
+  emitIdeaBoundaryBlock(data, 'write', `Target: ${data.tool_input?.file_path || '(unknown file)'}`)
+}
+
+function buildPostWriteWarnings(data) {
+  const content = data.tool_input?.content || data.tool_input?.new_string || ''
+  const filePath = data.tool_input?.file_path || ''
+  return [
+    ...(detectIdeaBoundaryContext(data)?.zeroSideEffect
+      ? ['~idea 本轮要求只读探索；检测到写入工具落地，请回退到探索输出或升级到 ~plan / ~build / ~prd / ~auto 后再修改文件']
+      : []),
     ...scanUnrequestedFiles(filePath, data.tool_name),
     ...(content ? [...scanForSecrets(content), ...scanDangerousPackages(content, filePath)] : []),
     ...scanEnvCoverage(filePath),
-  ];
+  ]
+}
+
+function postWriteScan(data) {
+  if (readSettings().guard_enabled === false) return
+  const warnings = buildPostWriteWarnings(data)
+  if (warnings.length === 0) return
+
+  emitHookPayload({
+    hookSpecificOutput: {
+      hookEventName: HOOK_EVENT,
+      additionalContext: `⚠️ [HelloAGENTS L2 安全扫描] 检测到潜在问题:\n${warnings.map((warning) => `  - ${warning}`).join('\n')}\n请检查以上问题。`,
+    },
+  })
+  emitGuardEvent(data.cwd || process.cwd(), 'guard_warning', 'post-write', '', {
+    warnings,
+    guardType: 'post-write-l2',
+  })
+}
 
-  if (warnings.length > 0) {
+function handleDangerousCommand(data, command) {
+  for (const { pattern, reason } of DANGEROUS_PATTERNS) {
+    if (!pattern.test(command)) continue
     emitHookPayload({
       hookSpecificOutput: {
         hookEventName: HOOK_EVENT,
-        additionalContext: `⚠️ [HelloAGENTS L2 安全扫描] 检测到潜在问题:\n${warnings.map(w => `  - ${w}`).join('\n')}\n请检查以上问题。`,
+        permissionDecision: 'deny',
+        permissionDecisionReason: `[HelloAGENTS Guard] Blocked: ${reason}\nCommand: ${command.slice(0, 200)}`,
       },
-    });
+    })
+    emitGuardEvent(data.cwd || process.cwd(), 'guard_blocked', 'command', reason, {
+      command: command.slice(0, 200),
+      guardType: 'dangerous-command',
+    })
+    return true
   }
+  return false
 }
 
-// ── Main ──────────────────────────────────────────────────────────────────
-
-async function main() {
-  // Latest Codex rejects suppressOutput on PreToolUse/PostToolUse.
-  // For pass-through cases, emit nothing and exit 0.
+function handleHighRiskCommand(data, command) {
+  const warnings = scanHighRiskCommands(command)
+  if (warnings.length === 0) return []
 
-  // Check if running in post-write mode (PostToolUse)
-  const mode = process.argv[2] || '';
-  if (mode === 'post-write') {
-    let data = {};
-    try {
-      const input = readFileSync(0, 'utf-8');
-      data = JSON.parse(input);
-    } catch {}
-    postWriteScan(data);
-    return;
+  const cwd = data.cwd || process.cwd()
+  const gate = buildHighRiskGate(warnings, cwd)
+  if (gate) {
+    emitHookPayload({
+      hookSpecificOutput: {
+        hookEventName: HOOK_EVENT,
+        permissionDecision: 'deny',
+        permissionDecisionReason: `${gate.reason}\nCommand: ${command.slice(0, 200)}`,
+      },
+    })
+    emitGuardEvent(cwd, 'guard_blocked', 'command', gate.reason, {
+      command: command.slice(0, 200),
+      guardType: 'high-risk-gate',
+      matches: warnings.map((warning) => warning.reason),
+    })
+    return null
   }
+  return warnings.map((warning) => warning.reason)
+}
 
-  const settings = readSettings();
-  if (settings.guard_enabled === false) {
-    return;
+function emitShellWarnings(data, command, highRiskWarnings, shellSafetyWarnings) {
+  const sections = []
+  if (highRiskWarnings.length > 0) {
+    sections.push(`⚠️ [HelloAGENTS 高风险链路提醒] 检测到高风险命令:\n${highRiskWarnings.map((warning) => `  - ${warning}`).join('\n')}\n请确认已完成相应规划/审查并获得必要授权。`)
   }
-
-  let data = {};
-  try {
-    const input = readFileSync(0, 'utf-8');
-    data = JSON.parse(input);
-  } catch {}
-
-  // Only check Bash/shell tool calls
-  const toolName = (data.tool_name || '').toLowerCase();
-  if (!['bash', 'shell', 'terminal', 'command'].some(t => toolName.includes(t))) {
-    return;
+  if (shellSafetyWarnings.length > 0) {
+    sections.push(`⚠️ [HelloAGENTS Shell 安全提醒] 检测到建议调整的命令写法:\n${shellSafetyWarnings.map((warning) => `  - ${warning}`).join('\n')}\n当前仅提示，不中断执行。`)
   }
+  if (sections.length === 0) return
+
+  emitHookPayload({
+    hookSpecificOutput: {
+      hookEventName: HOOK_EVENT,
+      additionalContext: sections.join('\n\n'),
+    },
+  })
 
-  const command = data.tool_input?.command || data.tool_input?.input || '';
-  if (!command) {
-    return;
+  const cwd = data.cwd || process.cwd()
+  if (highRiskWarnings.length > 0) {
+    emitGuardEvent(cwd, 'guard_warning', 'command', '', {
+      guardType: 'high-risk-warning',
+      command: command.slice(0, 200),
+      warnings: highRiskWarnings,
+    })
+  }
+  if (shellSafetyWarnings.length > 0) {
+    emitGuardEvent(cwd, 'guard_warning', 'command', '', {
+      guardType: 'shell-safety-warning',
+      command: command.slice(0, 200),
+      warnings: shellSafetyWarnings,
+    })
   }
+}
 
-  for (const { pattern, reason } of DANGEROUS_PATTERNS) {
-    if (pattern.test(command)) {
-      emitHookPayload({
-        hookSpecificOutput: {
-          hookEventName: HOOK_EVENT,
-          permissionDecision: 'deny',
-          permissionDecisionReason: `[HelloAGENTS Guard] Blocked: ${reason}\nCommand: ${command.slice(0, 200)}`,
-        },
-      });
-      return;
+function handleShellCommand(data) {
+  const toolName = (data.tool_name || '').toLowerCase()
+  if (!['bash', 'shell', 'terminal', 'command'].some((name) => toolName.includes(name))) return
+
+  const command = data.tool_input?.command || data.tool_input?.input || ''
+  if (!command) return
+
+  if (detectIdeaBoundaryContext(data)?.zeroSideEffect) {
+    for (const pattern of IDEA_SIDE_EFFECT_COMMAND_PATTERNS) {
+      if (!pattern.test(command)) continue
+      emitIdeaBoundaryBlock(data, 'side-effect command', `Command: ${command.slice(0, 200)}`)
+      return
     }
   }
+
+  if (handleDangerousCommand(data, command)) return
+  const highRiskWarnings = handleHighRiskCommand(data, command)
+  if (highRiskWarnings === null) return
+
+  const shellSafetyWarnings = scanShellSafetyWarnings(command)
+  emitShellWarnings(data, command, highRiskWarnings, shellSafetyWarnings)
+}
+
+async function main() {
+  const mode = process.argv[2] || ''
+  const data = readHookInput()
+
+  if (mode === 'pre-write') {
+    preWriteGuard(data)
+    return
+  }
+  if (mode === 'post-write') {
+    postWriteScan(data)
+    return
+  }
+  if (readSettings().guard_enabled === false) return
+  handleShellCommand(data)
 }
 
-main().catch(() => {});
+main().catch(() => {})

package/scripts/notify-context.mjs

@@ -1,6 +1,19 @@
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { buildCommandRouteHint, buildStateSyncHint, buildWorkflowRouteHint } from './workflow-state.mjs';
+import { buildCapabilityHint } from './capability-registry.mjs';
+import {
+  buildProjectStorageBlock,
+  buildProjectStorageHint,
+  describeProjectStoreFile,
+} from './project-storage.mjs';
+
+const COMMAND_ALIASES = {
+  do: 'build',
+  design: 'plan',
+  review: 'verify',
+};
 
 function buildPackageRootBlock(pkgRoot) {
   if (!pkgRoot) return '';
@@ -18,11 +31,6 @@ function resolveStandbyHostRoot(host) {
 }
 
 function resolveReadRoot({ cwd, pkgRoot, host, settings }) {
-  const projectRoot = join(cwd, 'skills', 'helloagents');
-  if (existsSync(projectRoot)) {
-    return { source: 'project', root: projectRoot };
-  }
-
   if (settings.install_mode === 'standby') {
     const standbyRoot = resolveStandbyHostRoot(host);
     if (standbyRoot && existsSync(standbyRoot)) {
@@ -35,7 +43,24 @@ function resolveReadRoot({ cwd, pkgRoot, host, settings }) {
 
 function buildReadRootBlock(readRoot) {
   if (!readRoot?.root) return '';
-  return `## 当前 HelloAGENTS 读取根目录\n\`\`\`json\n${JSON.stringify(readRoot, null, 2)}\n\`\`\``;
+  return `## 本轮 HelloAGENTS 读取根目录\n\`\`\`json\n${JSON.stringify(readRoot, null, 2)}\n\`\`\``;
+}
+
+export function resolveCanonicalCommandSkill(skillName) {
+  return COMMAND_ALIASES[skillName] || skillName;
+}
+
+function buildAliasRouteNote(skillName) {
+  if (skillName === 'do') {
+    return '兼容别名映射：本次按 ~build 规则执行。';
+  }
+  if (skillName === 'design') {
+    return '兼容别名映射：本次按 ~plan 规则执行；方案文件使用 `plan.md`，项目级 UI 契约仍使用 `DESIGN.md`。';
+  }
+  if (skillName === 'review') {
+    return '兼容别名映射：本次按 ~verify 的审查优先模式执行。';
+  }
+  return '';
 }
 
 export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFile, host }) {
@@ -45,11 +70,13 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
 
   const cwd = payload.cwd || process.cwd();
   const statePath = join(cwd, '.helloagents', 'STATE.md');
+  const stateSyncHint = buildStateSyncHint(cwd);
   if (existsSync(statePath)) {
     try {
       const stateContent = readFileSync(statePath, 'utf-8');
       summaryParts.push('');
-      summaryParts.push('## 恢复快照（从 STATE.md 读取，读完即可接上工作）');
+      summaryParts.push('## 恢复快照（从 STATE.md 读取，只用于找回上次停在哪）');
+      summaryParts.push('恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续。');
       summaryParts.push(stateContent);
     } catch {}
   }
@@ -76,6 +103,18 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
     summaryParts.push(readRootBlock);
   }
 
+  const projectStorageBlock = buildProjectStorageBlock(cwd);
+  if (projectStorageBlock) {
+    summaryParts.push('');
+    summaryParts.push(projectStorageBlock);
+  }
+
+  if (stateSyncHint) {
+    summaryParts.push('');
+    summaryParts.push('## STATE.md 提醒');
+    summaryParts.push(stateSyncHint);
+  }
+
   if (Object.keys(settings).length) {
     summaryParts.push('');
     summaryParts.push(`## 当前用户设置\n\`\`\`json\n${JSON.stringify(settings, null, 2)}\n\`\`\``);
@@ -87,6 +126,10 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
 export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host, cwd }) {
   const packageRootBlock = buildPackageRootBlock(pkgRoot);
   const readRootBlock = buildReadRootBlock(resolveReadRoot({ cwd, pkgRoot, host, settings }));
+  const workflowHint = buildWorkflowRouteHint(cwd);
+  const capabilityHint = buildCapabilityHint({ cwd });
+  const projectStorageBlock = buildProjectStorageBlock(cwd);
+  const stateSyncHint = buildStateSyncHint(cwd);
   const settingsBlock = Object.keys(settings).length
     ? `\n\n## 当前用户设置\n\`\`\`json\n${JSON.stringify(settings, null, 2)}\n\`\`\``
     : '';
@@ -94,30 +137,42 @@ export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host,
   let context = bootstrap;
   if (packageRootBlock) context += `\n\n${packageRootBlock}`;
   if (readRootBlock) context += `\n\n${readRootBlock}`;
+  if (projectStorageBlock) context += `\n\n${projectStorageBlock}`;
+  if (workflowHint) context += `\n\n## 当前工作流提示\n${workflowHint}`;
+  if (capabilityHint) context += `\n\n## 当前按需能力\n${capabilityHint}`;
+  if (stateSyncHint) context += `\n\n## STATE.md 提醒\n${stateSyncHint}`;
   context += settingsBlock;
   if (source === 'resume' || source === 'compact') {
-    context += '\n\n> ⚠️ 会话已恢复/压缩，请先读取 .helloagents/STATE.md 恢复工作状态。';
+    context += '\n\n> ⚠️ 会话已恢复/压缩，请先读取 `.helloagents/STATE.md` 恢复工作状态；先看当前用户消息确认仍是同一任务，再按 STATE.md 接续。';
   }
   return context;
 }
 
 export function buildRouteInstruction({ skillName, extraRules = '', cwd, pkgRoot, host, settings }) {
   const readRoot = resolveReadRoot({ cwd, pkgRoot, host, settings });
-  const skillPath = join(readRoot.root, 'skills', 'commands', skillName, 'SKILL.md');
-  return `用户使用了 ~${skillName} 命令。当前命令技能文件已解析为：${skillPath}。请直接读取这个 SKILL.md；本轮不要再为同一个命令 skill 重复 Test-Path / Get-Content，也不要探测其他 helloagents 路径。${extraRules}`;
+  const canonicalSkillName = resolveCanonicalCommandSkill(skillName);
+  const skillPath = join(readRoot.root, 'skills', 'commands', canonicalSkillName, 'SKILL.md');
+  const aliasNote = buildAliasRouteNote(skillName);
+  const commandHint = buildCommandRouteHint(canonicalSkillName, cwd);
+  const capabilityHint = buildCapabilityHint({ cwd, skillName: canonicalSkillName });
+  const projectStorageHint = buildProjectStorageHint(cwd);
+  return `用户使用了 ~${skillName} 命令。当前命令技能文件已解析为：${skillPath}。请直接读取这个 SKILL.md；不要再探测其他 helloagents 路径。${aliasNote ? ` ${aliasNote}` : ''}${projectStorageHint ? ` ${projectStorageHint}` : ''}${commandHint ? ` ${commandHint}` : ''}${capabilityHint ? ` ${capabilityHint}` : ''}${extraRules}`;
 }
 
-export function detectNewProjectRoute(prompt) {
-  const newProjectPatterns = [
-    /(?:创建|新建|从零|搭建).*(?:项目|应用|系统|网站|游戏|工具|平台|小程序|APP)/,
-    /(?:做|写|开发|实现)[一个]*.*(?:项目|应用|系统|网站|游戏|工具|平台|小程序|APP)/,
-    /\b(build|create|design|make|new|start|init)\b.*\b(app|game|project|site|website|tool|system|platform)\b/i,
-  ];
-
-  for (const pattern of newProjectPatterns) {
-    if (pattern.test(prompt)) {
-      return '检测到可能是新项目/新应用任务。根据 HelloAGENTS 路由规则，新项目必须进入 ~design 设计流程。请引导用户进入 ~design。';
-    }
-  }
-  return '';
+export function buildSemanticRouteInstruction(cwd) {
+  const workflowHint = buildWorkflowRouteHint(cwd);
+  const capabilityHint = buildCapabilityHint({ cwd });
+  const projectStorageHint = buildProjectStorageHint(cwd);
+  return [
+    '当前消息未使用 ~command。',
+    '请根据用户请求的真实意图选路，不依赖关键词表。',
+    'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆链路。',
+    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动编排并自动衔接后续阶段。',
+    '若判定为 T3，默认先走 ~plan / ~prd；纯审查/验证请求才优先 ~verify。',
+    `涉及 UI 任务时，设计决策优先级：当前活跃 plan / PRD → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → 通用 UI 规则。`,
+    projectStorageHint,
+    workflowHint ? `项目状态：${workflowHint}` : '',
+    capabilityHint,
+    '意图明确时直接按对应路径推进，不要把选路过程暴露给用户。',
+  ].filter(Boolean).join(' ');
 }

package/scripts/notify-events.mjs

@@ -7,5 +7,9 @@ export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {
 }
 
 export function claimsTaskComplete(lastMsg) {
-  return /✅|完成|已修复|done|fixed|completed|finished/i.test(lastMsg);
+  if (!lastMsg) return false;
+  if (/^✅【HelloAGENTS】- .*(当前任务已完成|任务已完成|已修复|完成交付|done|fixed|completed|finished)/im.test(lastMsg)) {
+    return true;
+  }
+  return /(当前任务已完成|任务已完成|已全部完成|已修复|修复完成|\b(done|fixed|completed|finished)\b)/i.test(lastMsg);
 }