helloagents 3.0.12 → 3.0.16-beta.1

package/scripts/delivery-gate.mjs

@@ -12,24 +12,13 @@ import { getVisualEvidenceStatus } from './visual-state.mjs'
 import { buildDeliveryGateHint, getDeliveryAction, getWorkflowRecommendation, getWorkflowSnapshot } from './workflow-state.mjs'
 import { getReviewEvidenceStatus } from './review-state.mjs'
 import { getVerifyEvidenceStatus } from './verify-state.mjs'
+import { buildDeliveryBlockReason, buildUnderSpecifiedDetails } from './delivery-gate-messages.mjs'
 
 function selectGatePlans(snapshot) {
   if (snapshot.activePlans.length > 0) return snapshot.activePlans
   return snapshot.plans
 }
 
-function buildUnderSpecifiedDetails(entry) {
-  return entry.taskSummary.underSpecifiedItems
-    .slice(0, 3)
-    .map((item) => {
-      const missing = []
-      if (item.files.length === 0) missing.push('missing files')
-      if (!item.acceptance) missing.push('missing acceptance')
-      if (!item.validation) missing.push('missing validation')
-      return `${item.text} (${missing.join(', ')})`
-    })
-}
-
 function collectTaskMetadataIssues(entry, issues) {
   if (entry.taskSummary.underSpecifiedCount === 0) return
   issues.push({
@@ -48,7 +37,7 @@ function collectPlanIssues(planEntries) {
       issues.push({
         type: 'missing-files',
         planName: entry.planName,
-        details: entry.missingFiles.map((file) => `missing ${file}`),
+        details: entry.missingFiles.map((file) => `缺少 ${file}`),
       })
     }
 
@@ -64,7 +53,7 @@ function collectPlanIssues(planEntries) {
       issues.push({
         type: 'missing-task-checklist',
         planName: entry.planName,
-        details: ['tasks.md does not contain any checklist items'],
+        details: ['tasks.md 没有可执行检查项'],
       })
       continue
     }
@@ -140,65 +129,6 @@ function collectGateIssues(planEntries, verificationStatus, reviewStatus, adviso
   return issues
 }
 
-function issueHeading(issue) {
-  switch (issue.type) {
-    case 'missing-files':
-      return 'active plan package is missing required artifacts'
-    case 'template-placeholders':
-      return 'active plan package still contains template placeholders'
-    case 'missing-task-checklist':
-      return 'active plan package has no executable tasks'
-    case 'unfinished-tasks':
-      return 'active plan package still has unfinished tasks'
-    case 'under-specified-tasks':
-      return 'active plan package has under-specified task metadata'
-    case 'missing-contract':
-      return 'active plan package is missing a trustworthy structured contract'
-    case 'missing-verify-evidence':
-      return 'current workflow is missing fresh verification evidence'
-    case 'missing-review-evidence':
-      return 'current workflow is missing fresh review evidence'
-    case 'missing-advisor-evidence':
-      return 'current workflow is missing fresh advisor evidence'
-    case 'missing-visual-evidence':
-      return 'current workflow is missing fresh visual validation evidence'
-    case 'missing-closeout-evidence':
-      return 'current workflow is missing fresh closeout evidence'
-    default:
-      return 'active plan package is not ready for delivery'
-  }
-}
-
-function buildBlockReason(issues, recommendation, gateHint) {
-  const lines = ['[Delivery Gate] Delivery is blocked because the current workflow state is not closed yet:']
-
-  for (const issue of issues) {
-    lines.push(`- ${issue.planName}: ${issueHeading(issue)}`)
-    for (const detail of issue.details) {
-      lines.push(`  - ${detail}`)
-    }
-    if (issue.extraCount) {
-      lines.push(`  - ...and ${issue.extraCount} more`)
-    }
-  }
-
-  lines.push('')
-  if (recommendation?.nextPath) {
-    lines.push(`Recommended path: ${recommendation.nextPath}`)
-  }
-  if (issues.some((issue) => issue.type === 'missing-closeout-evidence')) {
-    lines.push('Next closeout step: write `.helloagents/.ralph-closeout.json` with `requirementsCoverage` and `deliveryChecklist` before reporting completion.')
-  }
-  if (issues.some((issue) => issue.type === 'missing-visual-evidence')) {
-    lines.push('Next visual step: write `.helloagents/.ralph-visual.json` with `tooling`, `screensChecked`, `statesChecked`, `status`, and `summary` before reporting completion.')
-  }
-  if (gateHint) {
-    lines.push(gateHint)
-  }
-  lines.push('Do not report completion yet. First finish or explicitly close the remaining tasks, or repair the active plan package so it becomes a trustworthy delivery record.')
-  return lines.join('\n')
-}
-
 function main() {
   let data = {}
   try {
@@ -208,11 +138,12 @@ function main() {
   const workflowOptions = { payload: data }
   const snapshot = getWorkflowSnapshot(cwd, workflowOptions)
   const recommendation = getWorkflowRecommendation(cwd, workflowOptions)
-  const verificationStatus = getVerifyEvidenceStatus(cwd)
+  const verificationStatus = getVerifyEvidenceStatus(cwd, workflowOptions)
   const deliveryAction = getDeliveryAction(cwd, workflowOptions)
   const gatePlans = selectGatePlans(snapshot)
   const reviewStatus = getReviewEvidenceStatus(cwd, {
     required: deliveryAction?.phase === 'verify' && deliveryAction?.mode === 'review-first',
+    ...workflowOptions,
   })
   if (gatePlans.length === 0) {
     process.stdout.write(JSON.stringify({ suppressOutput: true }))
@@ -223,12 +154,14 @@ function main() {
   const advisorStatus = getAdvisorEvidenceStatus(cwd, {
     required: advisorRequirements.some((entry) => entry.required),
     focus: advisorRequirements.flatMap((entry) => entry.focus || []),
+    ...workflowOptions,
   })
   const visualRequirements = gatePlans.map((entry) => getVisualValidationRequirement(entry.contract))
   const visualStatus = getVisualEvidenceStatus(cwd, {
     required: visualRequirements.some((entry) => entry.required),
     screens: visualRequirements.flatMap((entry) => entry.screens || []),
     states: visualRequirements.flatMap((entry) => entry.states || []),
+    ...workflowOptions,
   })
   const closeoutRequired = (
     gatePlans.every((entry) => entry.missingFiles.length === 0 && entry.templateIssues.length === 0 && entry.taskSummary.total > 0 && entry.taskSummary.open === 0 && entry.taskSummary.underSpecifiedCount === 0)
@@ -239,6 +172,7 @@ function main() {
   )
   const closeoutStatus = getCloseoutEvidenceStatus(cwd, {
     required: closeoutRequired,
+    ...workflowOptions,
   })
 
   const issues = collectGateIssues(gatePlans, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
@@ -249,7 +183,7 @@ function main() {
 
   process.stdout.write(JSON.stringify({
     decision: 'block',
-    reason: buildBlockReason(issues, recommendation, buildDeliveryGateHint(cwd, workflowOptions)),
+    reason: buildDeliveryBlockReason(issues, recommendation, buildDeliveryGateHint(cwd, workflowOptions)),
     suppressOutput: true,
   }))
 }

package/scripts/guard-rules.mjs

@@ -2,29 +2,29 @@ import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
 export const DANGEROUS_PATTERNS = [
-  { 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' },
-  { pattern: /\bcmd(?:\.exe)?\s*\/c\b/i, reason: 'Nested cmd invocation bypasses PowerShell safety rules' },
-  { pattern: /\bStart-Process\s+cmd(?:\.exe)?\b/i, reason: 'Nested cmd invocation bypasses PowerShell safety rules' },
-  { pattern: /git\s+push\s+(-f|--force)/, reason: 'Force push (specify branch explicitly)' },
-  { pattern: /git\s+reset\s+--hard/, reason: 'Hard reset (destructive operation)' },
-  { pattern: /DROP\s+(DATABASE|TABLE|SCHEMA)/i, reason: 'Database destruction command' },
-  { pattern: /\bTRUNCATE(?:\s+TABLE)?\b/i, reason: 'Table truncation' },
-  { pattern: /chmod\s+777/, reason: 'World-writable permissions' },
-  { pattern: /mkfs\b/, reason: 'Filesystem format command' },
-  { pattern: /dd\s+.*of=\/dev\//, reason: 'Direct device write' },
-  { pattern: /FLUSHALL|FLUSHDB/i, reason: 'Redis data flush' },
+  { pattern: /(sudo\s+)?rm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?(-[a-zA-Z]*r[a-zA-Z]*\s+)?(\/|~|\*)/, reason: '递归删除关键路径' },
+  { pattern: /(sudo\s+)?rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+)?(-[a-zA-Z]*f[a-zA-Z]*\s+)?(\/|~|\*)/, reason: '递归删除关键路径' },
+  { pattern: /(sudo\s+)?rm\s+--recursive/, reason: '递归删除命令' },
+  { pattern: /(sudo\s+)?rm\s+-[a-zA-Z]*r[a-zA-Z]*\s+\.\.?(\s|$)/, reason: '递归删除当前目录或父目录' },
+  { pattern: /\bcmd(?:\.exe)?\s*\/c\b/i, reason: '嵌套 cmd 会绕过 PowerShell 安全规则' },
+  { pattern: /\bStart-Process\s+cmd(?:\.exe)?\b/i, reason: '嵌套 cmd 会绕过 PowerShell 安全规则' },
+  { pattern: /git\s+push\s+(-f|--force)/, reason: '强制推送风险高，必须明确分支与授权' },
+  { pattern: /git\s+reset\s+--hard/, reason: '硬重置会丢弃本地变更' },
+  { pattern: /DROP\s+(DATABASE|TABLE|SCHEMA)/i, reason: '数据库破坏性命令' },
+  { pattern: /\bTRUNCATE(?:\s+TABLE)?\b/i, reason: '表数据清空命令' },
+  { pattern: /chmod\s+777/, reason: '全局可写权限风险高' },
+  { pattern: /mkfs\b/, reason: '文件系统格式化命令' },
+  { pattern: /dd\s+.*of=\/dev\//, reason: '直接写入设备' },
+  { pattern: /FLUSHALL|FLUSHDB/i, reason: 'Redis 数据清空命令' },
 ]
 
 export const HIGH_RISK_COMMAND_PATTERNS = [
-  { pattern: /\bnpm\s+publish\b/i, reason: 'Package publish command', gate: 'post-verify' },
-  { pattern: /\bgh\s+release\s+create\b/i, reason: 'Release publication command', gate: 'post-verify' },
-  { pattern: /\bterraform\s+(apply|destroy)\b/i, reason: 'Infrastructure apply/destroy command', gate: 'post-verify' },
-  { pattern: /\b(kubectl|helm)\s+(apply|delete|upgrade|rollback|set|rollout)\b/i, reason: 'Cluster deployment command', gate: 'post-verify' },
-  { pattern: /\b(prisma|drizzle-kit|sequelize-cli|typeorm)\b.*\b(migrate|migration)\b/i, reason: 'Database migration command', gate: 'plan-first' },
-  { pattern: /\b(vercel|wrangler|netlify|flyctl|fly)\b.*\b(deploy|publish)\b/i, reason: 'Deployment command', gate: 'post-verify' },
+  { pattern: /\bnpm\s+publish\b/i, reason: '包发布命令', gate: 'post-verify' },
+  { pattern: /\bgh\s+release\s+create\b/i, reason: '发布 release 命令', gate: 'post-verify' },
+  { pattern: /\bterraform\s+(apply|destroy)\b/i, reason: '基础设施变更命令', gate: 'post-verify' },
+  { pattern: /\b(kubectl|helm)\s+(apply|delete|upgrade|rollback|set|rollout)\b/i, reason: '集群变更命令', gate: 'post-verify' },
+  { pattern: /\b(prisma|drizzle-kit|sequelize-cli|typeorm)\b.*\b(migrate|migration)\b/i, reason: '数据库迁移命令', gate: 'plan-first' },
+  { pattern: /\b(vercel|wrangler|netlify|flyctl|fly)\b.*\b(deploy|publish)\b/i, reason: '部署命令', gate: 'post-verify' },
 ]
 
 export const IDEA_SIDE_EFFECT_COMMAND_PATTERNS = [
@@ -36,20 +36,20 @@ export const IDEA_SIDE_EFFECT_COMMAND_PATTERNS = [
 ]
 
 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' },
+  { pattern: /AKIA[0-9A-Z]{16}/, reason: '检测到 AWS Access Key ID' },
+  { pattern: /ghp_[a-zA-Z0-9]{36}/, reason: '检测到 GitHub Personal Access Token' },
+  { pattern: /github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}/, reason: '检测到 GitHub Fine-grained PAT' },
+  { pattern: /sk-[a-zA-Z0-9]{20,}/, reason: '检测到 API secret key（sk-）' },
+  { pattern: /key-[a-zA-Z0-9]{20,}/, reason: '检测到 API key（key-）' },
+  { pattern: /-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----/, reason: '检测到私钥' },
+  { pattern: /password\s*[:=]\s*["'][^"']{4,}["']/i, reason: '检测到硬编码密码' },
+  { pattern: /secret\s*[:=]\s*["'][^"']{4,}["']/i, reason: '检测到硬编码密钥' },
+  { pattern: /AIza[0-9A-Za-z\-_]{35}/, reason: '检测到 Google API Key' },
+  { pattern: /xox[bpras]-[0-9a-zA-Z\-]+/, reason: '检测到 Slack Token' },
+  { pattern: /eyJ[A-Za-z0-9\-_]+\.eyJ[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_.+/=]+/, reason: '检测到 JWT token' },
+  { pattern: /(postgres|mysql|mongodb(\+srv)?):\/\/[^:]+:[^@]+@/i, reason: '检测到包含凭据的数据库连接串' },
+  { pattern: /sk_live_[a-zA-Z0-9]{24,}/, reason: '检测到 Stripe Secret Key' },
+  { pattern: /sk-ant-[a-zA-Z0-9\-]{20,}/, reason: '检测到 Anthropic API Key' },
 ]
 
 export function scanForSecrets(content) {
@@ -81,13 +81,13 @@ export function scanShellSafetyWarnings(command = '') {
       .map((entry) => entry.trim())
       .filter(Boolean)
     if (logicalLines.length > 3) {
-      warnings.push('PowerShell inline script exceeds 3 logical lines; prefer a temporary .ps1 file')
+      warnings.push('PowerShell 内联脚本超过 3 个逻辑行，建议改用临时 .ps1 文件')
     }
   }
 
   const fileOps = normalized.match(/\b(remove-item|move-item|copy-item|new-item|set-content|add-content|out-file|mkdir|md|touch|cp|copy|mv|move|ren|rename|del|erase|rm|rmdir)\b/ig) || []
   if (fileOps.length > 1 && /[;\r\n]/.test(normalized)) {
-    warnings.push('Multiple file operations are chained in one shell command; split them into separate commands')
+    warnings.push('单条 shell 命令串联了多个文件操作，建议拆成独立命令')
   }
 
   return warnings
@@ -99,11 +99,11 @@ export function scanUnrequestedFiles(filePath, toolName) {
   const warnings = []
 
   const patterns = [
-    { pattern: /^(SUMMARY|NOTES|TODO|SCRATCH|TEMP)\.(md|txt)$/i, reason: `Unrequested file creation: ${basename}` },
+    { pattern: /^(SUMMARY|NOTES|TODO|SCRATCH|TEMP)\.(md|txt)$/i, reason: `检测到未请求的文件创建：${basename}` },
     {
       pattern: /^README.*\.md$/i,
       matches: () => filePath.replace(/\\/g, '/').split('/').length > 4,
-      reason: `Suspicious README creation in nested path: ${basename}`,
+      reason: `检测到嵌套路径中的可疑 README 创建：${basename}`,
     },
   ]
 
@@ -120,12 +120,12 @@ export function scanDangerousPackages(content, filePath) {
   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)')
+      warnings.push('package.json 中存在潜在危险的生命周期脚本（preinstall/postinstall 调用 curl、wget、bash 或 eval）')
     }
   }
   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')
+    warnings.push('检测到不安全的依赖安装写法')
   }
   return warnings
 }
@@ -136,12 +136,12 @@ export function scanEnvCoverage(filePath) {
   for (let i = 0; i < 10; i += 1) {
     try {
       const gitignore = readFileSync(join(dir, '.gitignore'), 'utf-8')
-      return gitignore.includes('.env') ? [] : ['.env file written but .gitignore does not contain .env pattern']
+      return gitignore.includes('.env') ? [] : ['写入了 .env 文件，但 .gitignore 未包含 .env 规则']
     } catch {
       const parent = dirname(dir)
       if (parent === dir) break
       dir = parent
     }
   }
-  return ['.env file written but no .gitignore found']
+  return ['写入了 .env 文件，但未找到 .gitignore']
 }

package/scripts/guard.mjs

@@ -52,13 +52,14 @@ function emitHookPayload(payload) {
   process.stdout.write(JSON.stringify(payload))
 }
 
-function emitGuardEvent(cwd, event, source, reason, details = {}) {
+function emitGuardEvent(cwd, event, source, reason, details = {}, payload = {}) {
   appendReplayEvent(cwd, {
     host: HOST,
     event,
     source,
     reason,
     details,
+    payload,
   })
 }
 
@@ -67,7 +68,7 @@ function buildHighRiskGate(matches, cwd, payload = {}) {
   const stateSyncHint = buildStateSyncHint(cwd, workflowOptions)
   if (stateSyncHint) {
     return {
-      reason: `[HelloAGENTS Guard] Blocked T3 command until project recovery state is synced.\n${stateSyncHint}`,
+      reason: `[HelloAGENTS Guard] 已阻止 T3 命令：项目恢复状态尚未同步。\n${stateSyncHint}`,
     }
   }
 
@@ -75,25 +76,26 @@ function buildHighRiskGate(matches, cwd, payload = {}) {
   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}`,
+      reason: `[HelloAGENTS Guard] 已阻止 T3 命令：当前工作流尚未进入 VERIFY / CONSOLIDATE。\n当前工作流：${recommendation.summary}\n建议路径：${recommendation.nextPath}\n${recommendation.guidance}`,
     }
   }
   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}`,
+      reason: `[HelloAGENTS Guard] 已阻止 T3 命令：高风险 schema 变更前仍需先完成 ~plan。\n当前工作流：${recommendation.summary}\n建议路径：${recommendation.nextPath}\n${recommendation.guidance}`,
     }
   }
   return null
 }
 
 function buildIdeaBoundaryReason(kind) {
-  return `[HelloAGENTS Guard] Blocked ${kind} during ~idea.\n当前路由：~idea 是只读探索；先停留在比较方案。若要写文件、改代码、创建知识库或执行有副作用的命令，请先升级到 ~plan / ~build / ~prd / ~auto。`
+  return `[HelloAGENTS Guard] 已阻止 ~idea 中的${kind}。\n当前路由：~idea 是只读探索；先停留在比较方案。若要写文件、改代码、创建知识库或执行有副作用的命令，请先升级到 ~plan / ~build / ~prd / ~auto。`
 }
 
 function detectIdeaBoundaryContext(data) {
   return getApplicableRouteContext({
     cwd: data.cwd || process.cwd(),
     filePath: data.tool_input?.file_path || '',
+    payload: data,
   })
 }
 
@@ -106,17 +108,24 @@ function emitIdeaBoundaryBlock(data, kind, target) {
       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',
-  })
+  emitGuardEvent(
+    data.cwd || process.cwd(),
+    'guard_blocked',
+    kind === 'write' ? 'pre-write' : 'command',
+    buildIdeaBoundaryReason(kind),
+    {
+      command: kind === '有副作用命令' ? target.replace(/^命令：\s*/, '') : '',
+      target: kind === '写入操作' ? target.replace(/^目标：\s*/, '') : '',
+      guardType: kind === '写入操作' ? 'idea-write-boundary' : 'idea-command-boundary',
+    },
+    data,
+  )
 }
 
 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)'}`)
+  emitIdeaBoundaryBlock(data, '写入操作', `目标：${data.tool_input?.file_path || '未知文件'}`)
 }
 
 function buildPostWriteWarnings(data) {
@@ -146,23 +155,23 @@ function postWriteScan(data) {
   emitGuardEvent(data.cwd || process.cwd(), 'guard_warning', 'post-write', '', {
     warnings,
     guardType: 'post-write-l2',
-  })
+  }, data)
 }
 
 function handleDangerousCommand(data, command) {
   for (const { pattern, reason } of DANGEROUS_PATTERNS) {
     if (!pattern.test(command)) continue
     emitHookPayload({
-      hookSpecificOutput: {
-        hookEventName: HOOK_EVENT,
-        permissionDecision: 'deny',
-        permissionDecisionReason: `[HelloAGENTS Guard] Blocked: ${reason}\nCommand: ${command.slice(0, 200)}`,
-      },
+        hookSpecificOutput: {
+          hookEventName: HOOK_EVENT,
+          permissionDecision: 'deny',
+          permissionDecisionReason: `[HelloAGENTS Guard] 已阻止：${reason}\n命令：${command.slice(0, 200)}`,
+        },
     })
     emitGuardEvent(data.cwd || process.cwd(), 'guard_blocked', 'command', reason, {
       command: command.slice(0, 200),
       guardType: 'dangerous-command',
-    })
+    }, data)
     return true
   }
   return false
@@ -179,14 +188,14 @@ function handleHighRiskCommand(data, command) {
       hookSpecificOutput: {
         hookEventName: HOOK_EVENT,
         permissionDecision: 'deny',
-        permissionDecisionReason: `${gate.reason}\nCommand: ${command.slice(0, 200)}`,
+        permissionDecisionReason: `${gate.reason}\n命令：${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),
-    })
+    }, data)
     return null
   }
   return warnings.map((warning) => warning.reason)
@@ -215,14 +224,14 @@ function emitShellWarnings(data, command, highRiskWarnings, shellSafetyWarnings)
       guardType: 'high-risk-warning',
       command: command.slice(0, 200),
       warnings: highRiskWarnings,
-    })
+    }, data)
   }
   if (shellSafetyWarnings.length > 0) {
     emitGuardEvent(cwd, 'guard_warning', 'command', '', {
       guardType: 'shell-safety-warning',
       command: command.slice(0, 200),
       warnings: shellSafetyWarnings,
-    })
+    }, data)
   }
 }
 
@@ -236,7 +245,7 @@ function handleShellCommand(data) {
   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)}`)
+      emitIdeaBoundaryBlock(data, '有副作用命令', `命令：${command.slice(0, 200)}`)
       return
     }
   }
@@ -265,4 +274,15 @@ async function main() {
   handleShellCommand(data)
 }
 
-main().catch(() => {})
+main().catch((error) => {
+  const reason = `[HelloAGENTS Guard] 守卫脚本执行异常，已阻止本次操作以避免静默放行。\n原因：${error?.message || error}`
+  emitHookPayload({
+    hookSpecificOutput: {
+      hookEventName: HOOK_EVENT,
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  })
+  process.stderr.write(`${reason}\n`)
+  process.exitCode = 1
+})

package/scripts/notify-context.mjs

@@ -1,6 +1,5 @@
 import { join } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { readFileSync } from 'node:fs';
 import { buildCommandRouteHint, buildStateSyncHint, buildWorkflowRouteHint, readStateSnapshot } from './workflow-state.mjs';
 import { buildCapabilityHint } from './capability-registry.mjs';
 import {
@@ -15,35 +14,27 @@ const COMMAND_ALIASES = {
   review: 'verify',
 };
 
-function buildPackageRootBlock(pkgRoot) {
+function buildRuntimeRootBlock(pkgRoot) {
   if (!pkgRoot) return '';
-  return `## 当前 HelloAGENTS 包根目录\n\`\`\`text\n${pkgRoot}\n\`\`\``;
-}
-
-function resolveStandbyHostRoot(host) {
-  const home = homedir();
-  const map = {
-    claude: join(home, '.claude', 'helloagents'),
-    codex: join(home, '.codex', 'helloagents'),
-    gemini: join(home, '.gemini', 'helloagents'),
-  };
-  return map[host] || '';
+  return `## 当前 HelloAGENTS 运行根目录\n\`\`\`text\n${pkgRoot}\n\`\`\``;
 }
 
 function resolveReadRoot({ cwd, pkgRoot, host, settings }) {
-  if (settings.install_mode === 'standby') {
-    const standbyRoot = resolveStandbyHostRoot(host);
-    if (standbyRoot && existsSync(standbyRoot)) {
-      return { source: 'standby-home', root: standbyRoot };
-    }
-  }
-
-  return { source: 'package', root: pkgRoot };
+  void cwd
+  void host
+  void settings
+  return { source: 'runtime-root', root: pkgRoot }
 }
 
 function buildReadRootBlock(readRoot) {
   if (!readRoot?.root) return '';
-  return `## 本轮 HelloAGENTS 读取根目录\n\`\`\`json\n${JSON.stringify(readRoot, null, 2)}\n\`\`\``;
+  const block = {
+    ...readRoot,
+    scriptRoot: join(readRoot.root, 'scripts'),
+    turnStateCommand: 'helloagents-turn-state write --kind complete --role main',
+    turnStateUsage: '仅在运行时需要识别完成、等待或阻塞时调用；普通问答不调用',
+  };
+  return `## 本轮 HelloAGENTS 读取根目录\n\`\`\`json\n${JSON.stringify(block, null, 2)}\n\`\`\``;
 }
 
 export function resolveCanonicalCommandSkill(skillName) {
@@ -89,10 +80,10 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
     summaryParts.push(bootstrap);
   }
 
-  const packageRootBlock = buildPackageRootBlock(pkgRoot);
-  if (packageRootBlock) {
+  const runtimeRootBlock = buildRuntimeRootBlock(pkgRoot);
+  if (runtimeRootBlock) {
     summaryParts.push('');
-    summaryParts.push(packageRootBlock);
+    summaryParts.push(runtimeRootBlock);
   }
 
   const readRootBlock = buildReadRootBlock(resolveReadRoot({ cwd, pkgRoot, host, settings }));
@@ -123,7 +114,7 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
 
 export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host, cwd, payload = {} }) {
   const workflowOptions = { payload };
-  const packageRootBlock = buildPackageRootBlock(pkgRoot);
+  const runtimeRootBlock = buildRuntimeRootBlock(pkgRoot);
   const readRootBlock = buildReadRootBlock(resolveReadRoot({ cwd, pkgRoot, host, settings }));
   const workflowHint = buildWorkflowRouteHint(cwd, workflowOptions);
   const capabilityHint = buildCapabilityHint({ cwd, options: workflowOptions });
@@ -135,7 +126,7 @@ export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host,
     : '';
 
   let context = bootstrap;
-  if (packageRootBlock) context += `\n\n${packageRootBlock}`;
+  if (runtimeRootBlock) context += `\n\n${runtimeRootBlock}`;
   if (readRootBlock) context += `\n\n${readRootBlock}`;
   if (projectStorageBlock) context += `\n\n${projectStorageBlock}`;
   if (workflowHint) context += `\n\n## 当前工作流提示\n${workflowHint}`;

package/scripts/notify-events.mjs

@@ -1,5 +1,7 @@
 export function shouldIgnoreCodexNotifyClient(client) {
-  return !!client && client !== 'codex-tui';
+  if (!client) return false;
+  const normalized = String(client).trim().toLowerCase().replace(/[_\s]+/g, '-');
+  return normalized !== 'codex' && !normalized.startsWith('codex-');
 }
 
 export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {

package/scripts/notify-gates.mjs

@@ -27,6 +27,7 @@ function emitGateError({
     event: 'runtime_gate_error',
     source,
     reason,
+    payload,
   })
   output({
     decision: 'block',
@@ -119,6 +120,7 @@ export function runGateScript({
       event: blockEvent,
       source,
       reason: gateOutput.reason || '',
+      payload,
     })
     output(gateOutput)
     return true

package/scripts/notify-route.mjs

@@ -1,8 +1,7 @@
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { isProjectRuntimeActive } from './runtime-scope.mjs'
 
 export function resolveBootstrapFile(cwd, installMode) {
-  const isActivated = existsSync(join(cwd, '.helloagents'))
+  const isActivated = isProjectRuntimeActive(cwd)
   return (installMode === 'global' || isActivated) ? 'bootstrap.md' : 'bootstrap-lite.md'
 }
 
@@ -12,7 +11,7 @@ function shouldBypassRoute(prompt) {
 
 function buildHelpExtraRules(skillName) {
   if (skillName !== 'help') return ''
-  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前上下文中已注入的“当前用户设置”，只有上下文不存在该信息时才尝试读取 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式或已激活项目中生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
+  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前会话上下文中已注入的“当前用户设置”、配置文件原始 JSON 或此前读取结果摘要，上下文不存在或缺少要展示的配置项时才读取一次 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式或已激活项目中生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
 }
 
 function routeExplicitCommand({
@@ -37,6 +36,7 @@ function routeExplicitCommand({
     cwd,
     skillName: canonicalSkillName,
     sourceSkillName: skillName,
+    payload,
   })
   appendReplayEvent(cwd, {
     host,
@@ -44,6 +44,7 @@ function routeExplicitCommand({
     source: 'route',
     skillName: canonicalSkillName,
     sourceSkillName: skillName,
+    payload,
   })
   suppress(buildRouteInstruction({
     skillName,
@@ -75,7 +76,7 @@ export function handleRouteCommand({
   const prompt = (payload.prompt || '').trim()
   const cwd = payload.cwd || process.cwd()
   if (shouldBypassRoute(prompt)) {
-    clearRouteContext()
+    clearRouteContext({ cwd, payload })
     emptySuppress()
     return
   }
@@ -98,17 +99,18 @@ export function handleRouteCommand({
 
   const bootstrapFile = resolveBootstrapFile(cwd, settings.install_mode)
   if (bootstrapFile === 'bootstrap.md') {
-    clearRouteContext()
+    clearRouteContext({ cwd, payload })
     appendReplayEvent(cwd, {
       host,
       event: 'semantic_route_prompted',
       source: 'route',
       recommendation: getWorkflowRecommendation(cwd, { payload }),
+      payload,
     })
     suppress(buildSemanticRouteInstruction(cwd, payload))
     return
   }
 
-  clearRouteContext()
+  clearRouteContext({ cwd, payload })
   emptySuppress()
 }