@bolloon/bolloon-agent 0.1.0

package/src/agents/workflow-engine.ts

@@ -0,0 +1,332 @@
+/**
+ * WorkflowEngine - Execution layer for document processing workflows
+ * Part of OpenClaw dual-layer architecture (Constraint Layer + Execution Layer)
+ */
+
+import { documentReader, DocumentContent } from '../documents/reader.js';
+import { getMinimax } from '../constraints/index.js';
+import { p2pNetwork } from '../network/p2p.js';
+import { ConstraintLayer, WorkflowContext } from './constraint-layer.js';
+
+export interface WorkflowStepConfig {
+  path?: string;
+  requirements?: string;
+  context?: string;
+  peerId?: string;
+  message?: string;
+  content?: string;
+  maxChunkSize?: number;
+}
+
+export interface WorkflowStep {
+  id: string;
+  type: 'read' | 'chunk' | 'summarize' | 'improve' | 'review' | 'send' | 'report';
+  config?: WorkflowStepConfig;
+  retry: {
+    max: number;
+    current: number;
+    backoffMs: number;
+  };
+  onFail: 'skip' | 'abort' | 'retry';
+  guardrail?: (context: WorkflowContext) => Promise<boolean>;
+  guardrailOnRetry?: boolean;
+}
+
+export interface StepResult {
+  status: 'success' | 'failed' | 'skipped' | 'blocked';
+  result?: unknown;
+  error?: string;
+  guardrailFailed?: string;
+}
+
+export interface Workflow {
+  id: string;
+  steps: WorkflowStep[];
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  results: Map<string, StepResult>;
+}
+
+export interface ImprovementRequest {
+  originalPath: string;
+  requirements: string;
+  context?: string;
+}
+
+/**
+ * WorkflowEngine executes document processing workflows with retry logic and guardrails
+ * Implements the execution layer of the OpenClaw dual-layer architecture
+ */
+export class WorkflowEngine {
+  private constraintLayer: ConstraintLayer;
+
+  constructor(constraintLayer?: ConstraintLayer) {
+    this.constraintLayer = constraintLayer || new ConstraintLayer();
+  }
+
+  /**
+   * Execute a complete workflow with all steps
+   */
+  async executeWorkflow(
+    steps: WorkflowStep[],
+    initialContext?: Partial<WorkflowContext>
+  ): Promise<Workflow> {
+    const workflow: Workflow = {
+      id: `wf-${Date.now()}`,
+      steps,
+      status: 'running',
+      results: new Map()
+    };
+
+    const context: WorkflowContext = {
+      peers: p2pNetwork.getPeers(),
+      logs: [],
+      ...initialContext
+    };
+
+    for (const step of steps) {
+      const result = await this.executeStep(step, context);
+      workflow.results.set(step.id, result);
+
+      // Handle blocked or critical failures
+      if (result.status === 'blocked') {
+        this.constraintLayer.log(
+          `Workflow blocked at step ${step.id}`,
+          { guardrailFailed: result.guardrailFailed },
+          'blocked'
+        );
+        workflow.status = 'failed';
+        return workflow;
+      }
+
+      if (result.status === 'failed' && step.onFail === 'abort') {
+        workflow.status = 'failed';
+        return workflow;
+      }
+    }
+
+    workflow.status = 'completed';
+    return workflow;
+  }
+
+  /**
+   * Execute a single workflow step with retry logic
+   */
+  async executeStep(step: WorkflowStep, context: WorkflowContext): Promise<StepResult> {
+    // Pre-execution guardrail check
+    if (step.guardrail) {
+      const guardrailPassed = await this.runGuardrail(step, context, true);
+      if (!guardrailPassed) {
+        this.constraintLayer.log(
+          `Pre-check guardrail failed: ${step.guardrail.name}`,
+          { stepId: step.id },
+          'blocked'
+        );
+        return { status: 'blocked', guardrailFailed: step.guardrail.name };
+      }
+    }
+
+    // Execute step with retry logic
+    for (let attempt = 0; attempt <= step.retry.max; attempt++) {
+      try {
+        const result = await this.runStep(step, context);
+
+        // Post-execution guardrail check (unless explicitly disabled for retries)
+        if (step.guardrailOnRetry !== false && step.guardrail) {
+          const guardrailPassed = await this.runGuardrail(step, context, false);
+          if (!guardrailPassed) {
+            this.constraintLayer.log(
+              `Post-check guardrail failed: ${step.guardrail.name}`,
+              { stepId: step.id },
+              'blocked'
+            );
+            return { status: 'blocked', guardrailFailed: step.guardrail.name };
+          }
+        }
+
+        return { status: 'success', result };
+      } catch (error) {
+        if (attempt === step.retry.max) {
+          this.constraintLayer.log(
+            `Step ${step.id} failed after ${attempt + 1} attempts`,
+            { error: String(error) },
+            'failed'
+          );
+          return {
+            status: step.onFail === 'skip' ? 'skipped' : 'failed',
+            error: String(error)
+          };
+        }
+
+        // Exponential backoff
+        const backoffMs = step.retry.backoffMs * Math.pow(2, attempt);
+        this.constraintLayer.log(
+          `Step ${step.id} attempt ${attempt + 1} failed, retrying in ${backoffMs}ms`,
+          {},
+          'warn'
+        );
+        await this.sleep(backoffMs);
+      }
+    }
+
+    return { status: 'failed', error: 'Max retries exceeded' };
+  }
+
+  /**
+   * Run the actual step logic
+   */
+  private async runStep(step: WorkflowStep, context: WorkflowContext): Promise<unknown> {
+    switch (step.type) {
+      case 'read': {
+        const path = step.config?.path;
+        if (!path) throw new Error('Read step requires path config');
+        const content = await documentReader.read(path);
+        context.document = content;
+        return content;
+      }
+
+      case 'chunk': {
+        if (!context.document) throw new Error('No document loaded');
+        const maxSize = step.config?.maxChunkSize || 4000;
+        return documentReader.chunk(context.document.text, maxSize);
+      }
+
+      case 'summarize': {
+        if (!context.document) throw new Error('No document loaded');
+        if (!this.isMinimaxAvailable()) {
+          throw new Error('Minimax LLM not available');
+        }
+        
+        const llm = getMinimax();
+        const chunks = documentReader.chunk(
+          context.document.text,
+          step.config?.maxChunkSize || 4000
+        );
+        const summaries: string[] = [];
+        let totalQuality = 0;
+
+        for (const chunk of chunks) {
+          const result = await llm.summarize(chunk, step.config?.context);
+          summaries.push(result.summary);
+          totalQuality += result.qualityScore;
+        }
+
+        context.summary = summaries.join('\n\n');
+        context.qualityScore = totalQuality / chunks.length;
+        return { summary: context.summary, qualityScore: context.qualityScore };
+      }
+
+      case 'improve': {
+        if (!context.document) throw new Error('No document loaded');
+        if (!this.isMinimaxAvailable()) {
+          throw new Error('Minimax LLM not available');
+        }
+
+        const llm = getMinimax();
+        const improved = await llm.improveContent(
+          context.document.text,
+          step.config?.requirements || '',
+          step.config?.context
+        );
+        context.improved = improved;
+        return { improved };
+      }
+
+      case 'review': {
+        return {
+          status: 'reviewed',
+          qualityScore: context.qualityScore,
+          hasDocument: !!context.document,
+          hasSummary: !!context.summary
+        };
+      }
+
+      case 'send': {
+        const peerId = step.config?.peerId;
+        const message = step.config?.message || context.summary || '';
+        if (!peerId) throw new Error('Send step requires peerId config');
+
+        // Check constraint layer for unknown peer
+        const checkResult = await this.constraintLayer.checkGuardrails(context, step);
+        if (!checkResult.passed) {
+          throw new Error(`Guardrail blocked: ${checkResult.blocked?.name}`);
+        }
+
+        await p2pNetwork.sendMessage(peerId, 'message', message);
+        this.constraintLayer.log(
+          `Sent message to ${peerId}`,
+          { peerId, messageLength: message.length },
+          'success'
+        );
+        return { sent: true, peerId };
+      }
+
+      case 'report': {
+        const content = step.config?.content || context.summary || '';
+        await p2pNetwork.broadcast('report', content);
+        this.constraintLayer.log(
+          'Broadcast report',
+          { contentLength: content.length },
+          'success'
+        );
+        return { broadcasted: true };
+      }
+
+      default:
+        throw new Error(`Unknown step type: ${step.type}`);
+    }
+  }
+
+  /**
+   * Run a guardrail check with error handling
+   */
+  private async runGuardrail(
+    step: WorkflowStep,
+    context: WorkflowContext,
+    isPreCheck: boolean
+  ): Promise<boolean> {
+    if (!step.guardrail) return true;
+    try {
+      return await step.guardrail(context);
+    } catch (error) {
+      this.constraintLayer.log(
+        `Guardrail ${step.guardrail.name} error`,
+        { error: String(error), isPreCheck },
+        'failed'
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Check if Minimax LLM is available
+   */
+  private isMinimaxAvailable(): boolean {
+    try {
+      getMinimax();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Sleep utility for retry backoff
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Get the constraint layer instance
+   */
+  getConstraintLayer(): ConstraintLayer {
+    return this.constraintLayer;
+  }
+
+  /**
+   * Set a custom constraint layer
+   */
+  setConstraintLayer(layer: ConstraintLayer): void {
+    this.constraintLayer = layer;
+  }
+}

package/src/bollharness/.boll/CLAUDE.md.template

@@ -0,0 +1,34 @@
+# CLAUDE.md — {{PROJECT_NAME}}
+
+> Generated by bollharness installer. Customize freely; rerunning
+> `/lead install bollharness --auto` will NOT overwrite user edits
+> outside the `<!-- bollharness:begin -->` / `<!-- bollharness:end -->`
+> fences.
+
+## Project overview
+
+{{PROJECT_OVERVIEW_PLACEHOLDER}}
+
+## bollharness contract
+
+<!-- bollharness:begin -->
+
+This project uses the bollharness local AI development harness. The
+harness provides fail-closed gates (L1-L5) that run during every Claude
+Code session:
+
+- L1 hooks: runtime guard + stop-early evaluator
+- L2 checks: pre-commit + INV-4 existence claim guards
+- L3 rules: lazy-loaded path-scoped rules
+- L4 skills: the `lead` 8-gate state machine
+- L5 ADR: decision records scaffold
+
+See `.boll/MANIFEST.yaml` for the active registry and
+`{{HARNESS_DOCS_URL}}` for the upstream contract.
+
+<!-- bollharness:end -->
+
+## Language
+
+All user-facing responses: {{DEFAULT_LANGUAGE}}. Technical identifiers
+(API names, file paths) stay in their original form.

package/src/bollharness/.boll/MANIFEST.yaml

@@ -0,0 +1,213 @@
+# bollharness install manifest — machine-readable truth source
+#
+# Owner: WP-01b (skeleton, manifest_version) + WP-03 (registry fill).
+# WP-11 adds one PreToolUse Read/Bash matcher entry to
+# settings_command_registry (+1 physical_files). WP-SEC-1 CI consumes
+# rebaseline_triggers + bash_read_keywords.
+#
+# Schema: ADR-043 §4 + §13.5
+
+manifest_version: "0.1.0"
+schema_owner: "PLAN-086 WP-01b (skeleton) + WP-03 (registry fill)"
+notes: >
+  WP-01b wrote skeleton with empty registries. WP-03 filled L1-L5 and
+  settings_command_registry. WP-11 increments physical_files to 18 when
+  install skill lands. All field semantics defined in ADR-043 §4 + §13.5.
+
+# ---------------------------------------------------------------------------
+# Five-layer registries — authoritative lists that L2 checks consume.
+# (check_fragment_integrity / check_skill_parity / check_hook_installed)
+# ---------------------------------------------------------------------------
+
+L1_registry:
+  - auto-ts-node.ts
+  - deploy-progress-on-session-end.ts
+  - failure-analyzer.ts
+  - find-project-root.sh
+  - initializer-agent.ts
+  - loop-detection.ts
+  - precompact.sh
+  - review-agent-gatekeeper.ts
+  - risk-tracker.ts
+  - sanitize-on-read.ts
+  - session-reflection.ts
+  - session-start-magic-docs.ts
+  - session-start-reset-risk.ts
+  - session-start-toolkit-reminder.ts
+  - stop-evaluator.md
+  - stop-evaluator.ts
+  - tool-call-counter.ts
+  - trace-analyzer.ts
+  - guard-feedback.ts
+  - deploy-guard.ts
+  - context_router.ts
+  - guard_router.ts
+  # H 系列 sync (2026-04-29, from boll @ dff58afb)
+  - _hook_output.ts            # 16 hook IO helpers (PLAN-098 / ADR-058)
+  - owner-guard.ts             # PreToolUse Edit/Write owner enforcement (H2)
+  - inbox-write-ledger.ts     # H9 邮箱 ledger
+  - inbox-validate.ts         # H9 邮箱 schema-v1 校验
+  - inbox-inject-on-start.ts  # H9 邮箱 SessionStart 注入
+  - inbox-poll.sh             # H9 邮箱主窗口轮询
+  - inbox-ack.ts              # H9 邮箱 ack 回送
+
+L2_registry:
+  - check_api_types.ts
+  - check_artifact_link.ts
+  - check_bugfix_binding.ts
+  - check_bugfix_binding_ci.ts
+  - check_doc_file_references.ts
+  - check_doc_freshness.ts
+  - check_doc_links.ts
+  - check_file_existence_claims.ts
+  - check_fragment_integrity.ts
+  - check_hook_installed.ts
+  - check_issue_closure.ts
+  - check_security.ts
+  - check_skill_parity.ts
+  - check_versions.ts
+  - regenerate_magic_docs.ts
+  # H 系列 sync (2026-04-29, from boll @ dff58afb)
+  - check_adr_plan_numbering.ts    # pre-commit ADR/PLAN 编号唯一性
+  - next_decision_number.sh         # 起草助手（pull-mode 查可用号）
+
+L3_registry:
+  # H 系列 sync (2026-04-29)
+  - hanis-protocol.md   # H 系列治理协议（H0 元规约 + 9 站速查 + H4/H5 哲学边界）
+
+L4_registry:
+  - lead
+  - crystal-learn
+  - guardian-fixer
+
+L5_registry:
+  - ADR-030-guard-signal-protocol-and-governance-reload.md
+  - ADR-038-harness-optimization-strategy.md
+  - ADR-041-codex-claude-code-division-of-labor.md
+  # H 系列 sync (2026-04-29, from boll @ dff58afb) — 9 ADR + 8 PLAN
+  - ADR-H0-meta-charter.md
+  - ADR-H1-crystal-learn-revival.md
+  - ADR-H2-identity-isolation.md
+  - ADR-H3-memory-scope.md
+  - ADR-H4-prompt-governance.md
+  - ADR-H5-gate-quantization.md
+  - ADR-H6-state-file-health.md
+  - ADR-H8-issue-and-doc-compliance.md
+  - ADR-H9-mailbox.md
+  - PLAN-H1-crystal-learn-revival.md
+  - PLAN-H2-identity-isolation.md
+  - PLAN-H3-memory-scope.md
+  - PLAN-H4-prompt-governance.md
+  - PLAN-H5-gate-quantization.md
+  - PLAN-H6-state-file-health.md
+  - PLAN-H8-issue-and-doc-compliance.md
+  - PLAN-H9-mailbox.md
+
+# ---------------------------------------------------------------------------
+# settings_command_registry — authoritative list of all hook commands
+# declared in .boll/settings.json. Must match settings.json exactly.
+# ---------------------------------------------------------------------------
+
+settings_command_registry:
+  - { stage: PostToolUse,        matcher: "Edit|Write", script: scripts/guard-feedback.ts,                      timeout: 30 }
+  - { stage: PostToolUse,        matcher: "Edit|Write", script: scripts/hooks/loop-detection.ts,                timeout: 5  }
+  - { stage: PostToolUse,        matcher: "Edit|Write", script: scripts/hooks/risk-tracker.ts,                  timeout: 3  }
+  - { stage: PreToolUse,         matcher: "Bash",       script: scripts/deploy-guard.ts,                        timeout: 10 }
+  - { stage: PreToolUse,         matcher: "Bash",       script: scripts/hooks/auto-ts-node.ts,                  timeout: 5,  if: "Bash(npx ts-node *)" }
+  - { stage: PreToolUse,         matcher: "*",          script: scripts/hooks/tool-call-counter.ts,             timeout: 3 }
+  - { stage: PreToolUse,         matcher: "Task",       script: scripts/hooks/review-agent-gatekeeper.ts,       timeout: 5 }
+  - { stage: PreToolUse,         matcher: "Read|Bash",  script: scripts/hooks/sanitize-on-read.ts,             timeout: 10 }
+  - { stage: PreCompact,         matcher: "*",          script: scripts/hooks/precompact.sh,                    timeout: 5 }
+  - { stage: SessionStart,       matcher: "*",          script: scripts/hooks/session-start-reset-risk.ts,      timeout: 3 }
+  - { stage: SessionStart,       matcher: "*",          script: scripts/hooks/session-start-magic-docs.ts,      timeout: 10 }
+  - { stage: SessionStart,       matcher: "*",          script: scripts/hooks/session-start-toolkit-reminder.ts, timeout: 5 }
+  - { stage: Stop,               matcher: "*",          script: scripts/hooks/stop-evaluator.ts,                timeout: 10 }
+  - { stage: SessionEnd,         matcher: "*",          script: scripts/hooks/session-reflection.ts,            timeout: 10 }
+  - { stage: SessionEnd,         matcher: "*",          script: scripts/hooks/trace-analyzer.ts,                timeout: 30, args: "analyze --days 1 --min-samples 3" }
+  - { stage: SessionEnd,         matcher: "*",          script: scripts/hooks/deploy-progress-on-session-end.ts, timeout: 5 }
+  - { stage: PostToolUseFailure, matcher: "*",          script: scripts/hooks/failure-analyzer.ts,              timeout: 5 }
+
+# ---------------------------------------------------------------------------
+# rebaseline_triggers — WP-SEC-1 detect_rebaseline_triggers.ts consumption.
+# If a PR touches any of these, CI forces a plan-level rebaseline step.
+# ---------------------------------------------------------------------------
+
+rebaseline_triggers:
+  - .boll/MANIFEST.yaml
+  - .boll/issue-adapter.yaml
+  - .boll/deploy-allowlist.yaml
+  - .boll/settings.json
+  - scripts/lib/claim_patterns.ts
+  - scripts/sanitize.ts
+  # vNext / WP-040 backport (2026-04-29) — schema 真相源
+  - .boll/plugins/boll-review-toolkit/contracts/review-contract.yaml
+  - .boll/plugins/boll-mode-toolkit/contracts/mode-contract.md
+  - .boll/agents/review-base.yaml
+  - .boll/toolkit-index.yaml
+
+# ---------------------------------------------------------------------------
+# vNext_plugin_registry — WP-040 backport（2026-04-29 sync from boll @ f3ad6585）
+# H 系列引用消费的中间层；H5/H6 schema 落地点（review-contract.yaml）。
+# 不在 settings_command_registry，因为 plugin hook 由 plugin.json 自注册。
+# ---------------------------------------------------------------------------
+
+vNext_plugin_registry:
+  boll-review-toolkit:
+    plugin_json: .boll/plugins/boll-review-toolkit/.boll-plugin/plugin.json
+    reviewer_agent: .boll/plugins/boll-review-toolkit/agents/reviewer.md
+    contracts:
+      - .boll/plugins/boll-review-toolkit/contracts/review-contract.yaml
+      - .boll/plugins/boll-review-toolkit/contracts/evidence-packet-schema.json
+    hooks:
+      - .boll/plugins/boll-review-toolkit/hooks/verify-gate.ts   # Stop hook
+  boll-mode-toolkit:
+    plugin_json: .boll/plugins/boll-mode-toolkit/.boll-plugin/plugin.json
+    contracts:
+      - .boll/plugins/boll-mode-toolkit/contracts/mode-contract.md
+    hooks:
+      - .boll/plugins/boll-mode-toolkit/hooks/capability-router.ts  # PreToolUse
+      - .boll/plugins/boll-mode-toolkit/hooks/evidence-emit.ts    # PostToolUse
+    skills:
+      - .boll/plugins/boll-mode-toolkit/skills/mode/SKILL.md
+      - .boll/plugins/boll-mode-toolkit/skills/mode/transition.ts
+      - .boll/plugins/boll-mode-toolkit/skills/mode/build.sh
+      - .boll/plugins/boll-mode-toolkit/skills/mode/plan.sh
+      - .boll/plugins/boll-mode-toolkit/skills/mode/release.sh
+      - .boll/plugins/boll-mode-toolkit/skills/mode/shadow-review.sh
+      - .boll/plugins/boll-mode-toolkit/skills/mode/verify.sh
+  toolkit_skill:
+    skill: .boll/skills/toolkit/SKILL.md
+    discover_script: .boll/skills/toolkit/list.sh
+
+# ---------------------------------------------------------------------------
+# physical_files — WP-SEC-1 CI double-commit count assertion.
+#   WP-03 commit: 17 (15 hooks + 2 root scripts)
+#   WP-11 commit: 18 (+ install-bollharness SKILL.md)
+#   post-audit: 22 (+ risk-tracker, session-start-reset-risk, sanitize-on-read,
+#                     context_router, guard_router)
+#   H series sync 2026-04-29: 51 (+ 7 hooks + 2 numbering + 1 rule + 1 schema
+#                     + 17 H decisions + 1 .githooks/pre-commit = +29)
+#   vNext sync 2026-04-29: 71 (+ 5 review-toolkit + 11 mode-toolkit + 2 toolkit
+#                     skill + 1 review-base.yaml + 1 toolkit-index.yaml = +20)
+# ---------------------------------------------------------------------------
+
+physical_files: 71
+
+# ---------------------------------------------------------------------------
+# bash_read_keywords — Bash matcher read-only classification.
+# Consumed by WP-11 sanitize-on-read.ts and WP-SEC-1 test 12 (double-diff).
+# ---------------------------------------------------------------------------
+
+bash_read_keywords:
+  - cat
+  - head
+  - tail
+  - less
+  - "git log"
+  - "git show"
+  - rg
+  - grep
+  - jq
+  - cut
+  - awk
+  - sed

package/src/bollharness/.boll/agents/review-base.yaml

@@ -0,0 +1,108 @@
+# Review Agent Tool Isolation — 共享白名单规范
+# [来源: ADR-038 D11.1 + OpenDev arXiv 2603.05344 — Plan mode planner schema-level read-only exclusion]
+#
+# 这个文件不是 agent definition，而是**机器可读的白名单规范**。
+# 所有审查类 agent 的 frontmatter 必须遵循这个白名单。
+# 治理规则在 .boll/rules/review-agent-isolation.md。
+#
+# 关键原则：
+# 1. 审查 agent 的工作是"看 + 报告"，不是"改"
+# 2. schema-level 隔离比 prompt-level 约束可靠 100x（OpenDev 论文证据）
+# 3. 不允许 Edit/Write/Bash/NotebookEdit — 这些有潜在副作用
+# 4. WebFetch + Read + Grep + Glob 足够支持任何审查工作
+#
+# 适用范围（非穷尽）：
+# - 任何 PR review / code review 类 agent
+# - Stop hook 的 Evaluator subagent
+# - Gate 2/4/6/8 审查 subagent
+# - Silent failure / type design / security review 类 agent
+# - Architectural consistency 检查 agent
+
+version: 1.0.0
+last_updated: "2026-04-07"
+spec_source: "ADR-038 D11"
+
+# ──────────────────────────────────────────────────────────────────────────
+# 允许的工具（白名单 — 完整列表）
+# ──────────────────────────────────────────────────────────────────────────
+tools_allowed:
+  # 信息读取
+  - Read              # 读文件
+  - Glob              # 文件路径模式匹配
+  - Grep              # 内容搜索（内置 ripgrep）
+
+  # 外部资源（只读）
+  - WebFetch          # 查文档、ADR 引用、外部规范
+  - WebSearch         # 搜索（不修改任何东西）
+
+  # 自我管理（不影响 host 系统）
+  - TodoWrite         # 自己的检查清单
+  - TaskCreate        # 创建跟进 task
+  - TaskUpdate        # 更新自己 task 状态
+  - TaskList          # 查看 task 列表
+  - TaskGet           # 读 task 详情
+
+  # MCP 只读工具（按需选择）
+  - mcp__boll__boll_*  # boll 协议查询（agents/demands/runs 等只读 tool）
+
+# ──────────────────────────────────────────────────────────────────────────
+# 禁用的工具（黑名单 — 必须显式拒绝）
+# ──────────────────────────────────────────────────────────────────────────
+tools_denied:
+  # 写入类 — 一律拒绝
+  - Edit              # 改文件
+  - Write             # 写新文件
+  - NotebookEdit      # 改 Jupyter notebook
+
+  # Shell 类 — 一律拒绝（即使"只读"命令也可能有副作用）
+  - Bash              # 包括 git push, rm, scp, npm install 等
+
+  # Worktree / 长任务类 — 审查不应改 git 状态
+  - EnterWorktree
+  - ExitWorktree
+
+  # 远程触发类 — 审查不应启动 cron
+  - CronCreate
+  - CronDelete
+
+  # 写权限的 MCP 工具（按 MCP server 列出）
+  - mcp__boll__boll_register
+  - mcp__boll__boll_login
+  - mcp__boll__boll_logout
+  - mcp__boll__boll_*_create
+  - mcp__boll__boll_*_delete
+  - mcp__boll__boll_*_update
+  - mcp__boll__boll_send_message
+  - mcp__boll__boll_*_respond
+  - mcp__boll__boll_*_confirm
+
+# ──────────────────────────────────────────────────────────────────────────
+# 候选 Bash 只读子集（v4 仅文档化，未实施 — 需要 PreToolUse hook 强制）
+# ──────────────────────────────────────────────────────────────────────────
+# 设计上 review agent 不应该用 Bash，但如果必须，只允许这些模式：
+bash_allowed_patterns:
+  - "git status"
+  - "git diff*"
+  - "git log*"
+  - "git show*"
+  - "git blame*"
+  - "ls *"            # 应该用 Glob 替代
+
+# ──────────────────────────────────────────────────────────────────────────
+# 应用清单：哪些 agent 必须遵循
+# ──────────────────────────────────────────────────────────────────────────
+# 本地 / 插件 review agents（直接由 frontmatter 控制）：
+#   - .boll/plugins/boll-review-toolkit/agents/reviewer.md (WP-040 backport；reference implementation)
+#
+# 插件 review agents（无法改 frontmatter，需要在调用层用约束 prompt 引用本规范）：
+#   - pr-review-toolkit:code-reviewer
+#   - pr-review-toolkit:silent-failure-hunter
+#   - pr-review-toolkit:type-design-analyzer
+#   - pr-review-toolkit:comment-analyzer
+#   - pr-review-toolkit:pr-test-analyzer
+#   - feature-dev:code-explorer
+#   - feature-dev:code-reviewer
+#
+# Stop hook Evaluator (scripts/hooks/stop-evaluator.md)：
+#   - 不是 subagent，而是 hook 注入的 prompt
+#   - 该 prompt 不能调用任何工具（只输出文字反馈）