@winspan/claude-forge 8.28.2 → 8.30.0

package/README.md

@@ -1,258 +1,111 @@
-# Claude Forge v3
+# Claude Forge
 
-> 极简治理引擎 — 4 条核心通路，4000 行代码
+> 为 Claude Code 设计的会话治理引擎 —— 通过 Hook 机制把方法论、路由、治理规则注入到 AI 开发流程中。
 
-Claude Forge 是一个为 Claude Code 设计的轻量级治理引擎，通过 Hook 机制在后台运行，提供规则阻断、技能推荐、质量检查和历史记录功能。
+Claude Forge 是一个在本地运行的守护进程，通过 Claude Code 的 Hook API 拦截 `UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop` 等事件，在其中做意图分类、方法论匹配、Agent 路由、规则阻断、治理建议。
 
-## 核心特性
+**版本**: 8.29.0 · **Node**: >= 18 · **License**: MIT
 
-### 1. 规则阻断（PreToolUse）
-基于 DSL 的规则引擎，实时阻断危险操作：
-- 阻止 `rm -rf /` 等破坏性命令
-- 警告 `git push --force` 等风险操作
-- 支持自定义 YAML 规则
-
-### 2. 技能推荐（UserPromptSubmit）
-自动分析用户意图，推荐相关技能：
-- 意图分类：simple / moderate / complex
-- 关键词匹配技能库
-- 注入技能内容到 systemMessage
+---
 
-### 3. 质量检查（PostToolUse）
-AI 驱动的代码质量审查：
-- 每 3 次 Write/Edit 触发一次审查
-- 检测安全漏洞、代码质量问题
-- 终端红色警告 + 修复建议注入
+## 核心能力
 
-### 4. 历史记录（Stop）
-会话结束时自动生成：
-- `decisions.md` — 决策摘要
-- `timeline.md` — 时间线
-- `.claude-forge/history/YYYY-MM-DD-{session}.md` — 完整历史
+### 1. Hook 驱动的治理
+daemon 以 Unix socket 形式与 Claude Code 的 Hook 脚本通信。每次 `UserPromptSubmit` / `PostToolUse` 等事件，daemon 在 100ms 内决定要不要往上下文注入额外指令或建议。
 
-## 快速开始
+### 2. 方法论执行引擎
+内置两种方法论（`harness-engineering`、`bmad`），AI Planner 根据任务复杂度自动生成多阶段执行计划。执行分两种模式：
 
-### 安装
+- **前台（foreground）** —— 指令注入到当前 Claude Code 会话，由主对话按 plan 调用 `Task(subagent_type=...)` 完成每个阶段
+- **后台（background）** —— daemon 直接 spawn 独立的 `claude -p` 子进程，与当前会话完全隔离地跑完整条 plan，用户离场也能自动完成
 
-```bash
-npm install -g @winspan/claude-forge
-```
+两种模式共享 plan / phase 数据模型，可在 Web 后台随时切换。
 
-### 初始化
+### 3. Agent 路由
+基于 intent 分析（`complexity`、`taskType`）和 YAML 规则，UserPromptSubmit 阶段建议 Claude 用哪个子 agent（`researcher`、`tester`、`coder` 等）。路由决策全程记录到 `routing_events` 表，可用于离线分析和 A/B 实验。
 
-```bash
-cf init
-```
-
-这会：
-1. 创建 `~/.claude-forge/` 目录
-2. 复制 Hook 脚本到 `~/.claude-forge/hooks/`
-3. 复制规则文件到 `~/.claude/conventions/`
-4. 注入 Hooks 到 Claude Code settings.json
-
-### 启动守护进程
-
-```bash
-cf daemon start
-```
+### 4. Web 管理后台
+`claude-forge daemon start` 默认在 `http://127.0.0.1:3721` 开放一个 React 管理后台，覆盖：会话浏览、事件流、执行追踪、方法论执行启动/取消、Agent/Skill 编辑、AI 配置、实时 SSE 日志。
 
-守护进程会在后台运行，监听 Claude Code 的 Hook 事件。
-
-### 查看状态
-
-```bash
-cf status
-```
+---
 
-### 配置 API Key
+## 快速开始
 
 ```bash
-# 方式 1：环境变量
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# 方式 2：配置文件
-cf config edit
-# 添加：
-# distill:
-#   api_key: sk-ant-...
-```
-
-## 架构
-
-```
-src/
-├── cli/           363 行  — 4 个命令（init, daemon, status, config）
-├── core/          532 行  — 类型、配置、存储、AI、工具
-├── daemon/        825 行  — 守护进程 + 4 个 handler
-├── engine/       1743 行  — RuleEngine + DSL
-├── intelligence/  465 行  — 意图分析、质量门禁、蒸馏
-└── skills/        118 行  — 技能注册、匹配
-```
-
-### 4 条数据通路
-
-```
-UserPromptSubmit → IntentClassifier → SkillRegistry → 注入技能推荐
-PreToolUse       → RuleEngine → block/warn/allow
-PostToolUse      → QualityGate → 注入纠偏 + 终端警告
-Stop             → Distiller → 导出历史
-```
-
-## 内置规则库
-
-Forge v3 包含 11 个技术栈专项规范（980 行规则）：
-
-| 规范文件 | 覆盖范围 | 规则数 |
-|---------|---------|--------|
-| `basic-security.yaml` | 通用安全（Git、文件系统、数据库） | 10 |
-| `git-safety.yaml` | Git 操作安全 | 12 |
-| `code-quality.yaml` | 代码质量（调试残留、类型安全） | 8 |
-| `dependency-safety.yaml` | 依赖安全 | 10 |
-| `react-best-practices.yaml` | React/前端开发 | 6 |
-| `python-best-practices.yaml` | Python 开发 | 6 |
-| `go-best-practices.yaml` | Go 开发 | 5 |
-| `database-safety.yaml` | 数据库操作 | 5 |
-| `docker-safety.yaml` | Docker/容器化 | 4 |
-| `ts-quality.yaml` | TypeScript 质量 | 3 |
-| `strict-security.yaml` | 严格安全模式 | 2 |
-
-### 规则示例
-
-**React XSS 防护**：
-```yaml
-- id: "no-dangerously-set-inner-html"
-  when: |
-    tool.in(["Write", "Edit"])
-    && file_ext.in([".jsx", ".tsx"])
-    && (args.content ?? args.new_string ?? "").match(/dangerouslySetInnerHTML/).ok()
-  level: warn
-  message: "检测到 dangerouslySetInnerHTML，存在 XSS 风险"
-```
-
-**Python 命令注入防护**：
-```yaml
-- id: "no-shell-injection"
-  when: |
-    tool.in(["Write", "Edit"])
-    && file_ext == ".py"
-    && (args.content ?? args.new_string ?? "").match(/subprocess\.(call|run|Popen)\([^)]*shell\s*=\s*True/).ok()
-  level: warn
-  message: "检测到 subprocess 使用 shell=True，存在命令注入风险"
-```
-
-**数据库误删防护**：
-```yaml
-- id: "warn-delete-without-where"
-  when: |
-    tool.in(["Write", "Edit", "Bash"])
-    && (args.content ?? args.new_string ?? args.command ?? "").lower().match(/delete\s+from\s+\w+\s*;/).ok()
-  level: block
-  message: "检测到无 WHERE 条件的 DELETE，会删除全表数据"
-```
-
-## 自定义规则
-
-编辑 `~/.claude/conventions/*.yaml` 添加项目特定规则：
-
-```yaml
-id: "my-rules"
-name: "项目自定义规则"
-version: "1.0.0"
-triggers: ["custom", "project"]
-
-forbidden:
-  - id: no-force-push
-    when: tool == 'Bash' && args.command.contains('push --force')
-    level: warn
-    message: Force push 会覆盖远程历史
+# 1. 安装
+npm install -g @winspan/claude-forge
 
-principles: |
-  ## 项目规范
-  - 禁止强制推送
-```
+# 2. 初始化（把 hook 脚本装到 ~/.claude/hooks/）
+cf init
 
-重启 daemon 生效：
+# 3. 配置 AI Provider（可选，但未配置时方法论规划走降级规则）
+cf config
 
-```bash
-cf daemon stop
+# 4. 启动 daemon
 cf daemon start
-```
 
-## 自定义技能
+# 5. 打开管理后台
+open http://127.0.0.1:3721
+```
 
-在 `~/.claude/skills/` 创建 Markdown 文件：
+之后在任何目录下开 Claude Code 会话，daemon 会自动接管 hook 事件。
 
-```markdown
----
-name: React 组件开发
-keywords: [react, 组件, component]
 ---
 
-# React 组件开发最佳实践
+## 方法论执行模式
 
-1. 使用函数组件 + Hooks
-2. Props 类型定义用 TypeScript interface
-3. 状态管理优先 useState，复杂场景用 useReducer
-...
-```
+创建执行有两种途径：
 
-## 开发
+- **UserPromptSubmit 自动触发** → 默认走**前台**。用户发出类似"帮我重构 xxx"时，daemon 识别 refactor 类任务自动创建 methodology execution，并把阶段 1 指令注入到当前 Claude Code 会话。
+- **Web 管理后台手动创建** → 默认走**后台**。在 `/methodologies` 页面点"新建执行"，选择方法论、session id、mode，daemon 立即 spawn `claude -p` 子进程按 plan 顺序跑完所有阶段。
 
-### 构建
-
-```bash
-npm run build
-```
+> **前台模式的边界**：如果 Claude 主会话没有任何新输入，daemon 无法主动推 —— 只有 UserPromptSubmit / Stop hook 被触发时才能搭便车注入指令。Stop hook 会检测"当前阶段未推进"并把指令写入 pending 队列，下一次 UserPrompt 时自动消费。**实际生效需要用户至少输入一次任意内容**。
 
-### 测试
+后台模式不受此影响，但消耗额外 API 预算（每个阶段默认上限 `$2`）。
 
-```bash
-npm run test
-```
+---
 
-### 端到端测试
+## CLI 命令
 
-```bash
-# 启动 daemon
-cf daemon start -f
+| 命令 | 说明 |
+|---|---|
+| `cf init` | 初始化 hook 脚本到 `~/.claude/hooks/` |
+| `cf daemon {start,stop,status}` | daemon 生命周期 |
+| `cf config` | AI Provider 配置（API key、base_url、model） |
+| `cf status` | 当前 daemon + Web + 存储概况 |
+| `cf logs [--tail]` | 查看 daemon 日志 |
+| `cf stats` | 近期 intent / 路由 / 方法论统计 |
+| `cf rules` | 查看/编辑治理规则（YAML） |
+| `cf agents` | 列出已注册 agent |
+| `cf skills` | 列出可用 skills |
+| `cf menu` | 交互式菜单（推荐入口） |
 
-# 另一个终端发送测试事件
-./test-e2e.sh
-```
+也可用 `claude-forge` 作为 `cf` 的完整别名。
 
-## 对比 v2
+---
 
-| 指标 | v2 | v3 | 变化 |
-|------|----|----|------|
-| 文件数 | 212 | 37 | -82.5% |
-| 代码行数 | 35,617 | 4,046 | -88.6% |
-| CLI 命令 | 14 | 4 | 精简 |
-| Web UI | 有 | 无 | 第一版移除 |
-| 核心通路 | 4（被淹没） | 4（清晰可见） | ✅ |
+## Web 管理后台
 
-v3 移除了：
-- Web UI（可单独重写）
-- Pipeline 编排系统
-- 知识图谱
-- 技能自进化
-- CLAUDE.md 自动精炼
-- Convention 管理
+主要页面：
 
-保留了：
-- RuleEngine + DSL（完整复用）
-- SQLite 存储（精简 schema）
-- AI Provider（Claude only）
-- Hook 脚本（完整复用）
+- `/dashboard` — 总览
+- `/sessions` — 会话列表 + 详情
+- `/events` — Hook 事件流
+- `/execution-trace` — 路由决策追踪（含 SSE 实时）
+- `/methodologies` — 方法论执行列表（mode 徽章 + 新建入口）
+- `/methodologies/:id` — 执行详情（实时 SSE 事件流 + 每阶段 output/error）
+- `/agents` / `/skills` — 在线编辑 `~/.claude/agents/*.md` 和 `~/.claude/skills/*.md`
+- `/ai-config` — 切换 AI Provider / 测试连接
+- `/routing` — 路由规则查看
 
-## 许可证
+所有列表支持搜索 + JSON/CSV 导出。
 
-MIT
+---
 
 ## 贡献
 
-欢迎提交 Issue 和 PR。
+开发者文档见 [DEVELOPMENT.md](./DEVELOPMENT.md)，包含仓库布局、构建/测试流程、架构说明、如何新增方法论或 Agent。
 
-## 相关链接
+## License
 
-- [Claude Code](https://claude.ai/code)
-- [Anthropic API](https://docs.anthropic.com/)
+MIT © 2026 winspan

package/dist/capability/execution-manager.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ExecutionManager — daemon 进程内单例，统筹所有 methodology_executions 的后台执行。
+ *
+ * 职责：
+ *  1. 提供 `start({session_id, plan, mode})` 入口：为前台/后台两种模式分别使用合适的 executor
+ *  2. 跟踪活跃的 orchestrator，让 cancel() 能真正 kill 子进程
+ *  3. 在 daemon 启动时扫一遍 listRunningBackgroundExecutions() —— 对应 worker
+ *     已不在了（孤儿 execution），标记为 failed（"crashed")
+ *
+ * 不负责：路由决策 / planner / UI。
+ */
+import type { SQLiteStorage } from '../core/storage/sqlite.js';
+import type { MethodologyRegistry } from './methodology-registry.js';
+import type { ExecutionPlan } from './types.js';
+import type { ExecutorEventListener } from './executor/types.js';
+import { type BackgroundExecutorOptions } from './executor/background-executor.js';
+export interface StartExecutionInput {
+    session_id: string;
+    methodology_id: string;
+    plan: ExecutionPlan;
+    mode: 'foreground' | 'background';
+}
+export interface ExecutionManagerOptions {
+    background?: BackgroundExecutorOptions;
+}
+export declare class ExecutionManager {
+    private storage;
+    private registry;
+    private foregroundExecutor;
+    private backgroundExecutor;
+    private activeOrchestrators;
+    private listeners;
+    private reconcileTimer;
+    constructor(storage: SQLiteStorage, registry: MethodologyRegistry, options?: ExecutionManagerOptions);
+    /**
+     * Create the execution row + kick off orchestrator.
+     * Returns the newly created execution id.
+     */
+    start(input: StartExecutionInput): number;
+    cancel(execution_id: number): Promise<void>;
+    /**
+     * Subscribe to all executor events. Returns an unsubscribe function.
+     */
+    subscribe(listener: ExecutorEventListener): () => void;
+    /**
+     * At daemon startup: find background executions whose worker_pid is no longer
+     * alive. Mark them failed so the UI shows a definitive state.
+     */
+    reconcileOrphansOnStartup(): void;
+    private isPidAlive;
+    /**
+     * Start a periodic reconcile loop — picks up workers killed while daemon
+     * was running (e.g. user kill -9'd the pid). Safe to call once at startup.
+     * Returns a stop function.
+     */
+    startReconcileLoop(intervalMs?: number): () => void;
+    stopReconcileLoop(): void;
+}
+//# sourceMappingURL=execution-manager.d.ts.map

package/dist/capability/execution-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-manager.d.ts","sourceRoot":"","sources":["../../src/capability/execution-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAiB,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAKvG,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,YAAY,GAAG,YAAY,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,yBAAyB,CAAC;CACxC;AAED,qBAAa,gBAAgB;IAQzB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,QAAQ;IARlB,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,cAAc,CAA+B;gBAG3C,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EACrC,OAAO,GAAE,uBAA4B;IAevC;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM;IAkDnC,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAKtD;;;OAGG;IACH,yBAAyB,IAAI,IAAI;IAkBjC,OAAO,CAAC,UAAU;IASlB;;;;OAIG;IACH,kBAAkB,CAAC,UAAU,SAAS,GAAG,MAAM,IAAI;IAiBnD,iBAAiB,IAAI,IAAI;CAI1B"}

package/dist/capability/execution-manager.js

@@ -0,0 +1,168 @@
+/**
+ * ExecutionManager — daemon 进程内单例，统筹所有 methodology_executions 的后台执行。
+ *
+ * 职责：
+ *  1. 提供 `start({session_id, plan, mode})` 入口：为前台/后台两种模式分别使用合适的 executor
+ *  2. 跟踪活跃的 orchestrator，让 cancel() 能真正 kill 子进程
+ *  3. 在 daemon 启动时扫一遍 listRunningBackgroundExecutions() —— 对应 worker
+ *     已不在了（孤儿 execution），标记为 failed（"crashed")
+ *
+ * 不负责：路由决策 / planner / UI。
+ */
+import { ForegroundExecutor } from './executor/foreground-executor.js';
+import { BackgroundExecutor } from './executor/background-executor.js';
+import { Orchestrator } from './executor/orchestrator.js';
+import { probeWorkerAuth, WorkerAuthError } from './executor/worker-auth-probe.js';
+import { logger } from '../core/utils/logger.js';
+export class ExecutionManager {
+    storage;
+    registry;
+    foregroundExecutor;
+    backgroundExecutor;
+    activeOrchestrators = new Map();
+    listeners = new Set();
+    reconcileTimer = null;
+    constructor(storage, registry, options = {}) {
+        this.storage = storage;
+        this.registry = registry;
+        this.foregroundExecutor = new ForegroundExecutor(storage, registry);
+        this.backgroundExecutor = new BackgroundExecutor(storage, registry, options.background);
+        // Relay executor events to external subscribers (SSE, metrics, ...)
+        const relay = (ev) => {
+            for (const l of this.listeners) {
+                try {
+                    l(ev);
+                }
+                catch (err) {
+                    logger.debug(`[ExecutionManager] relay failed: ${err}`);
+                }
+            }
+        };
+        this.foregroundExecutor.subscribe(relay);
+        this.backgroundExecutor.subscribe(relay);
+    }
+    /**
+     * Create the execution row + kick off orchestrator.
+     * Returns the newly created execution id.
+     */
+    start(input) {
+        // 后台模式：前置认证探测，给调用方明确错误而不是等 worker 起来后才报错
+        if (input.mode === 'background') {
+            const probe = probeWorkerAuth();
+            if (!probe.available) {
+                throw new WorkerAuthError(probe);
+            }
+        }
+        const executionId = this.storage.createMethodologyExecution({
+            session_id: input.session_id,
+            methodology_id: input.methodology_id,
+            plan_json: JSON.stringify(input.plan),
+            mode: input.mode,
+        });
+        // Seed the first phase_executions row so listings show immediately
+        if (input.plan.phases[0]) {
+            const p0 = input.plan.phases[0];
+            this.storage.createPhaseExecution({
+                methodology_execution_id: executionId,
+                phase_id: p0.id,
+                phase_index: 0,
+                agent_name: p0.agent,
+                prompt: p0.prompt,
+            });
+        }
+        const executor = input.mode === 'background' ? this.backgroundExecutor : this.foregroundExecutor;
+        const orch = new Orchestrator(this.storage, executor);
+        this.activeOrchestrators.set(executionId, orch);
+        // Fire-and-forget; errors are logged but don't crash the daemon.
+        orch.run(executionId)
+            .catch(err => {
+            logger.warn(`[ExecutionManager] orchestrator for ${executionId} threw: ${err}`);
+            try {
+                this.storage.updateMethodologyExecution(executionId, {
+                    status: 'failed',
+                    completed_at: Date.now(),
+                    worker_pid: null,
+                });
+            }
+            catch { /* swallow */ }
+        })
+            .finally(() => {
+            this.activeOrchestrators.delete(executionId);
+        });
+        return executionId;
+    }
+    async cancel(execution_id) {
+        const exec = this.storage.getMethodologyExecution(execution_id);
+        if (!exec)
+            throw new Error(`execution ${execution_id} not found`);
+        const executor = exec.mode === 'background'
+            ? this.backgroundExecutor
+            : this.foregroundExecutor;
+        await executor.cancel(execution_id);
+    }
+    /**
+     * Subscribe to all executor events. Returns an unsubscribe function.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /**
+     * At daemon startup: find background executions whose worker_pid is no longer
+     * alive. Mark them failed so the UI shows a definitive state.
+     */
+    reconcileOrphansOnStartup() {
+        const rows = this.storage.listRunningBackgroundExecutions();
+        for (const row of rows) {
+            const pid = row.worker_pid;
+            const alive = pid ? this.isPidAlive(pid) : false;
+            if (!alive) {
+                logger.warn(`[ExecutionManager] execution=${row.id} has stale worker_pid=${pid}; marking failed`);
+                this.storage.updateMethodologyExecution(row.id, {
+                    status: 'failed',
+                    completed_at: Date.now(),
+                    worker_pid: null,
+                });
+            }
+        }
+    }
+    isPidAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Start a periodic reconcile loop — picks up workers killed while daemon
+     * was running (e.g. user kill -9'd the pid). Safe to call once at startup.
+     * Returns a stop function.
+     */
+    startReconcileLoop(intervalMs = 60_000) {
+        if (this.reconcileTimer)
+            clearInterval(this.reconcileTimer);
+        this.reconcileTimer = setInterval(() => {
+            try {
+                this.reconcileOrphansOnStartup();
+            }
+            catch (err) {
+                logger.debug(`[ExecutionManager] periodic reconcile failed: ${err}`);
+            }
+        }, intervalMs);
+        // Don't keep the event loop alive just for this.
+        this.reconcileTimer.unref?.();
+        return () => {
+            if (this.reconcileTimer)
+                clearInterval(this.reconcileTimer);
+            this.reconcileTimer = null;
+        };
+    }
+    stopReconcileLoop() {
+        if (this.reconcileTimer)
+            clearInterval(this.reconcileTimer);
+        this.reconcileTimer = null;
+    }
+}
+//# sourceMappingURL=execution-manager.js.map

package/dist/capability/execution-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-manager.js","sourceRoot":"","sources":["../../src/capability/execution-manager.ts"],"names":[],"mappings":"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"}

package/dist/capability/executor/background-executor.d.ts

@@ -0,0 +1,57 @@
+/**
+ * BackgroundExecutor —— spawn `claude -p` 子进程独立执行一个 phase。
+ *
+ * 与 ForegroundExecutor 的差异：
+ *  - 真正调用 CLI 并等待结束，所以 `executePhase` 返回的是最终 status
+ *    ('completed' | 'failed'), 不是 'injected'
+ *  - 不会改 pending queue —— 后台执行路径跟 Claude 主会话完全隔离
+ *  - 进度通过 subscribe() 的 ExecutorEvent 对外暴露（SSE 可订阅）
+ */
+import type { MethodologyExecution, PlannedPhase } from '../types.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import type { MethodologyRegistry } from '../methodology-registry.js';
+import type { ExecutorEventListener, PhaseExecutionResult, PhaseExecutor } from './types.js';
+export interface BackgroundExecutorOptions {
+    /** claude CLI 可执行文件路径（默认走 PATH） */
+    claudeBin?: string;
+    /** 子进程 cwd；默认为当前项目目录 */
+    cwd?: string;
+    /** 项目根目录，作为 --add-dir 的参数；默认走 cwd */
+    projectRoot?: string;
+    /** 每个 phase 的最大预算美元（默认 2） */
+    maxBudgetUsdPerPhase?: number;
+    /** 权限模式（默认 bypassPermissions） */
+    permissionMode?: 'acceptEdits' | 'bypassPermissions' | 'default' | 'dontAsk' | 'plan';
+    /** 默认禁用的工具（逗号分隔） */
+    disallowedTools?: string;
+    /** phase 级 wall-clock 超时（ms），默认 30 分钟 */
+    phaseTimeoutMs?: number;
+    /** stream-json 日志根目录 */
+    logDir?: string;
+    /**
+     * worker 专用 settings.json 路径。若未提供，会懒生成到
+     * `$HOME/.claude-forge/worker-settings.json`，内容为 `{"hooks": {}}`。
+     * 目的：让 worker 子进程跳过 daemon hooks，避免递归触发。
+     */
+    settingsPath?: string;
+}
+export declare class BackgroundExecutor implements PhaseExecutor {
+    private storage;
+    private registry;
+    readonly mode: "background";
+    private listeners;
+    private running;
+    private readonly opts;
+    constructor(storage: SQLiteStorage, registry: MethodologyRegistry, options?: BackgroundExecutorOptions);
+    executePhase(execution: MethodologyExecution, phase: PlannedPhase, phaseIndex: number): Promise<PhaseExecutionResult>;
+    cancel(execution_id: number): Promise<void>;
+    subscribe(listener: ExecutorEventListener): () => void;
+    private emit;
+    /**
+     * @internal test-only: 构建 spawn 参数。生产代码请走 `executePhase`。
+     */
+    buildArgs(): string[];
+    /** @internal test-only */
+    getSettingsPath(): string;
+}
+//# sourceMappingURL=background-executor.d.ts.map

package/dist/capability/executor/background-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-executor.d.ts","sourceRoot":"","sources":["../../../src/capability/executor/background-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAiB,MAAM,aAAa,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAEV,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AAWpB,MAAM,WAAW,yBAAyB;IACxC,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iCAAiC;IACjC,cAAc,CAAC,EAAE,aAAa,GAAG,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IACtF,oBAAoB;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAcD,qBAAa,kBAAmB,YAAW,aAAa;IAOpD,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,QAAQ;IAPlB,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,OAAO,CAAqD;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsF;gBAGjG,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EACrC,OAAO,GAAE,yBAA8B;IAiBnC,YAAY,CAChB,SAAS,EAAE,oBAAoB,EAC/B,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,oBAAoB,CAAC;IA4M1B,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjD,SAAS,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAKtD,OAAO,CAAC,IAAI;IAMZ;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAoBrB,0BAA0B;IAC1B,eAAe,IAAI,MAAM;CAG1B"}