patchwarden 0.6.4 → 1.1.0

package/dist/watcherStatus.js

@@ -157,7 +157,7 @@ export function derivePendingReason(task, watcher) {
             return "queued_but_watcher_unreadable";
         return "queued_waiting_for_watcher";
     }
-    if (task.status !== "running")
+    if (task.status !== "running" && task.status !== "collecting_artifacts")
         return null;
     if (task.phase === "executing_agent")
         return "agent_running";
@@ -167,3 +167,94 @@ export function derivePendingReason(task, watcher) {
         return "collecting_artifacts";
     return "preparing";
 }
+// ── v0.7.0: Watcher ownership helpers ─────────────────────────────
+/**
+ * Read the current watcher's instance_id from the heartbeat file.
+ * Returns null when the heartbeat is missing or unreadable.
+ *
+ * This is the source of truth for "which watcher is currently alive".
+ * Tasks whose runtime.watcher_instance_id differs from this value are
+ * considered orphaned by the diagnosis layer.
+ */
+export function readWatcherInstanceId(config = getConfig()) {
+    const heartbeatPath = getWatcherHeartbeatPath(config);
+    if (!existsSync(heartbeatPath))
+        return null;
+    try {
+        const raw = readFileSync(heartbeatPath, "utf-8");
+        const data = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+        return typeof data.instance_id === "string" ? data.instance_id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * v0.7.0: Determine whether the current watcher still owns a task.
+ *
+ * Ownership is established by comparing the watcher_instance_id recorded in
+ * the task's runtime.json with the instance_id of the currently alive
+ * watcher. A task is considered "owned" only when:
+ *   - the current watcher heartbeat is healthy, AND
+ *   - the task runtime recorded a watcher_instance_id, AND
+ *   - both instance IDs match.
+ *
+ * If the task has no recorded watcher_instance_id (legacy tasks created
+ * before v0.7.0), ownership cannot be confirmed and this returns false.
+ * The diagnosis layer treats "no owner" as a stale signal, not as active.
+ */
+export function isWatcherOwningTask(taskDir, config = getConfig()) {
+    const runtimePath = join(taskDir, "runtime.json");
+    let taskWatcherInstanceId = null;
+    if (existsSync(runtimePath)) {
+        try {
+            const runtime = JSON.parse(readFileSync(runtimePath, "utf-8"));
+            if (typeof runtime.watcher_instance_id === "string") {
+                taskWatcherInstanceId = runtime.watcher_instance_id;
+            }
+        }
+        catch {
+            // corrupted runtime — treat as no record
+        }
+    }
+    if (!taskWatcherInstanceId) {
+        return {
+            owned: false,
+            reason: "no_runtime_record",
+            task_watcher_instance_id: null,
+            current_watcher_instance_id: null,
+        };
+    }
+    const watcher = readWatcherStatus(config);
+    if (watcher.status !== "healthy") {
+        return {
+            owned: false,
+            reason: watcher.status === "missing" ? "watcher_missing" : "watcher_unhealthy",
+            task_watcher_instance_id: taskWatcherInstanceId,
+            current_watcher_instance_id: watcher.instance_id,
+        };
+    }
+    const currentInstanceId = watcher.instance_id;
+    if (!currentInstanceId) {
+        return {
+            owned: false,
+            reason: "watcher_missing",
+            task_watcher_instance_id: taskWatcherInstanceId,
+            current_watcher_instance_id: null,
+        };
+    }
+    if (currentInstanceId !== taskWatcherInstanceId) {
+        return {
+            owned: false,
+            reason: "instance_mismatch",
+            task_watcher_instance_id: taskWatcherInstanceId,
+            current_watcher_instance_id: currentInstanceId,
+        };
+    }
+    return {
+        owned: true,
+        reason: "owned",
+        task_watcher_instance_id: taskWatcherInstanceId,
+        current_watcher_instance_id: currentInstanceId,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "patchwarden",
-  "version": "0.6.4",
-  "description": "A secure local MCP bridge: clients save plans, local agents execute tasks, and results are returned through workspace-scoped files.",
+  "version": "1.1.0",
+  "description": "Secure local MCP bridge for ChatGPT and local agents, with workspace-scoped tasks, safe summaries, audits, and Direct editing.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,6 +50,7 @@
     "test:watcher-supervisor": "npm run build && node scripts/checks/watcher-supervisor-smoke.js",
     "check:tool-manifest": "npm run build && node scripts/checks/mcp-manifest-check.js",
     "check:direct-tool-manifest": "npm run build && node scripts/checks/mcp-manifest-check.js --profile chatgpt_direct",
+    "check:search-tool-manifest": "npm run build && node scripts/checks/mcp-manifest-check.js --profile chatgpt_search",
     "check:brand": "node scripts/checks/brand-check.js",
     "test:mcp": "npm run build && node scripts/checks/mcp-smoke.js",
     "test:http-mcp": "npm run build && node scripts/checks/http-mcp-smoke.js",

package/scripts/checks/control-smoke.js

@@ -76,7 +76,7 @@ try {
     ready: false,
     pid: null,
     tool_profile: "chatgpt_direct",
-    tool_count: 9,
+    tool_count: 13,
     tools_ready: true,
   }), "utf8");
   writeFileSync(join(directRuntime, "tunnel-client.pid"), String(fakeTunnel.pid), "utf8");
@@ -114,7 +114,7 @@ try {
     reason_code: "stale_fixture",
     last_error: "stale failure",
     tool_profile: "chatgpt_core",
-    tool_count: 16,
+    tool_count: 21,
     tools_ready: true,
   }), "utf8");
   healthServer = spawn(

package/scripts/checks/doctor-smoke.js

@@ -42,6 +42,7 @@ try {
     "[OK]   Task directory writable",
     "[OK]   Example task directory read/write",
     "[OK]   allowedTestCommands is non-empty",
+    "[OK]   Release gate module loadable",
   ];
   for (const line of requiredLines) {
     if (!result.stdout.includes(line)) throw new Error(`doctor output missing stable line: ${line}`);

package/scripts/checks/lifecycle-smoke.js

@@ -12,6 +12,10 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 
+// v0.7.2: tasks complete with "done_by_agent" (pending acceptance) instead of "done".
+// Both are valid successful completion statuses for lifecycle smoke tests.
+const isDoneStatus = (s) => s === "done" || s === "done_by_agent";
+
 const tempRoot = mkdtempSync(join(tmpdir(), "patchwarden-lifecycle-"));
 const workspaceRoot = join(tempRoot, "workspace");
 const repoPath = join(workspaceRoot, "repo");
@@ -178,7 +182,7 @@ try {
       verify_commands: ["node --check main.js", "node --check second.js"],
     });
     const result = await runTask(task.task_id);
-    if (result.status !== "done") throw new Error(`Writer task ended ${result.status}: ${result.error}`);
+    if (!isDoneStatus(result.status)) throw new Error(`Writer task ended ${result.status}: ${result.error}`);
     const status = getTaskStatus(task.task_id);
     const changed = status.changed_files || [];
     if (!changed.some((file) => file.path === "README.md" && file.change === "modified")) {
@@ -253,7 +257,7 @@ try {
     });
     const result = await runTask(task.task_id);
     const verify = JSON.parse(readFileSync(join(task.path, "verify.json"), "utf-8"));
-    if (result.status !== "done" || verify.status !== "passed" || verify.commands.length !== 1) {
+    if (!isDoneStatus(result.status) || verify.status !== "passed" || verify.commands.length !== 1) {
       throw new Error(`Legacy verification mismatch: ${JSON.stringify({ result, verify })}`);
     }
     if (verify.commands[0].cwd !== repoPath || !("stdout_tail" in verify.commands[0]) || !("stderr_tail" in verify.commands[0])) {
@@ -265,7 +269,7 @@ try {
     const plan = savePlan({ title: "No diff", content: "Do not change files." });
     const task = createTask({ plan_id: plan.plan_id, agent: "noop", repo_path: "repo" });
     const result = await runTask(task.task_id);
-    if (result.status !== "done") throw new Error(`No-op task failed: ${JSON.stringify(result)}`);
+    if (!isDoneStatus(result.status)) throw new Error(`No-op task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
     const verify = JSON.parse(readFileSync(join(task.path, "verify.json"), "utf-8"));
     if (verify.status !== "skipped") throw new Error(`Expected skipped verification: ${JSON.stringify(verify)}`);
@@ -286,7 +290,7 @@ try {
     const plan = savePlan({ title: "Large diff", content: "Create a large text file." });
     const task = createTask({ plan_id: plan.plan_id, agent: "largewriter", repo_path: "repo" });
     const result = await runTask(task.task_id);
-    if (result.status !== "done") throw new Error(`Large task failed: ${JSON.stringify(result)}`);
+    if (!isDoneStatus(result.status)) throw new Error(`Large task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
     const patchSize = readFileSync(join(task.path, "diff.patch"), "utf-8").length;
     if (!diff.truncated || !diff.patch_head || !diff.diff_patch_path || patchSize <= diff.content.length) {
@@ -298,7 +302,7 @@ try {
     const plan = savePlan({ title: "Non-Git evidence", content: "Modify files in a non-Git repository." });
     const task = createTask({ plan_id: plan.plan_id, agent: "writer", repo_path: "plain-repo" });
     const result = await runTask(task.task_id);
-    if (result.status !== "done") throw new Error(`Non-Git task failed: ${JSON.stringify(result)}`);
+    if (!isDoneStatus(result.status)) throw new Error(`Non-Git task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
     if (
       diff.patch_mode !== "hash_only" ||
@@ -313,7 +317,7 @@ try {
     const plan = savePlan({ title: "Binary evidence", content: "Create a binary fixture." });
     const task = createTask({ plan_id: plan.plan_id, agent: "binarywriter", repo_path: "repo" });
     const result = await runTask(task.task_id);
-    if (result.status !== "done") throw new Error(`Binary task failed: ${JSON.stringify(result)}`);
+    if (!isDoneStatus(result.status)) throw new Error(`Binary task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
     if (diff.patch_mode !== "textual" || !diff.content.includes("GIT binary patch")) {
       throw new Error(`Binary patch evidence mismatch: ${JSON.stringify(diff)}`);
@@ -324,7 +328,7 @@ try {
     const plan = savePlan({ title: "Artifact hygiene", content: "Generate representative task outputs." });
     const task = createTask({ plan_id: plan.plan_id, agent: "artifactwriter", repo_path: "repo" });
     const result = await runTask(task.task_id);
-    if (result.status !== "done") throw new Error(`Artifact task failed: ${JSON.stringify(result)}`);
+    if (!isDoneStatus(result.status)) throw new Error(`Artifact task failed: ${JSON.stringify(result)}`);
     const standard = getTaskSummary(task.task_id);
     const compact = getTaskSummary(task.task_id, { view: "compact", max_items: 1 });
     const counts = standard.artifact_hygiene?.counts || {};
@@ -353,7 +357,7 @@ try {
     const plan = savePlan({ title: "Delete fixture", content: "Delete the designated fixture file." });
     const task = createTask({ plan_id: plan.plan_id, agent: "deleter", repo_path: "repo" });
     const result = await runTask(task.task_id);
-    if (result.status !== "done") throw new Error(`Delete task failed: ${JSON.stringify(result)}`);
+    if (!isDoneStatus(result.status)) throw new Error(`Delete task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
     if (!diff.file_stats?.some((file) => file.path === "delete-me.txt" && file.status === "deleted")) {
       throw new Error(`Deleted file stats missing: ${JSON.stringify(diff.file_stats)}`);
@@ -504,7 +508,7 @@ try {
     const task = createTask({ plan_id: plan.plan_id, agent: "noop", repo_path: "repo", verify_commands: ["node --check main.js"] });
     const result = await runTask(task.task_id);
 
-    if (result.status !== "done") {
+    if (!isDoneStatus(result.status)) {
       throw new Error(`Expected done, got: ${JSON.stringify(result)}`);
     }
     const structured = JSON.parse(readFileSync(join(task.path, "result.json"), "utf-8"));

package/scripts/checks/mcp-manifest-check.js

@@ -4,18 +4,20 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES } from "../../dist/tools/toolCatalog.js";
+import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES, CHATGPT_SEARCH_TOOL_NAMES } from "../../dist/tools/toolCatalog.js";
 
 const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
 const jsonOnly = process.argv.includes("--json");
 const profileIndex = process.argv.indexOf("--profile");
 const profile = profileIndex >= 0 ? process.argv[profileIndex + 1] : "chatgpt_core";
-if (profile !== "chatgpt_core" && profile !== "chatgpt_direct") {
+if (profile !== "chatgpt_core" && profile !== "chatgpt_direct" && profile !== "chatgpt_search") {
   throw new Error(`Unsupported manifest profile "${profile}".`);
 }
 const expectedTools = profile === "chatgpt_direct"
   ? [...CHATGPT_DIRECT_TOOL_NAMES]
-  : [...CHATGPT_CORE_TOOL_NAMES];
+  : profile === "chatgpt_search"
+    ? [...CHATGPT_SEARCH_TOOL_NAMES]
+    : [...CHATGPT_CORE_TOOL_NAMES];
 const defaultConfigPath = resolve(root, "patchwarden.config.json");
 const transportEnv = {
   ...process.env,
@@ -102,13 +104,31 @@ try {
     if (!summaryProperties.includes("view") || !summaryProperties.includes("max_items")) {
       throw new Error("get_task_summary schema must expose view and max_items");
     }
-  } else {
+    const safeRequirements = {
+      safe_result: ["task_id"],
+      safe_audit: ["task_id"],
+      safe_test_summary: ["task_id"],
+      safe_diff_summary: ["task_id"],
+    };
+    for (const [toolName, requiredProperties] of Object.entries(safeRequirements)) {
+      const tool = listed.tools.find((entry) => entry.name === toolName);
+      const properties = Object.keys(tool?.inputSchema?.properties || {});
+      for (const property of requiredProperties) {
+        if (!properties.includes(property)) {
+          throw new Error(`${toolName} schema is missing ${property}`);
+        }
+      }
+    }
+  } else if (profile === "chatgpt_direct") {
     const directRequirements = {
       create_direct_session: ["repo_path"],
       apply_patch: ["session_id", "path", "expected_sha256", "operations"],
       run_verification: ["session_id", "command"],
       finalize_direct_session: ["session_id"],
       audit_session: ["session_id"],
+      safe_direct_summary: ["session_id"],
+      safe_finalize_direct_session: ["session_id"],
+      safe_audit_direct_session: ["session_id"],
     };
     for (const [toolName, requiredProperties] of Object.entries(directRequirements)) {
       const tool = listed.tools.find((entry) => entry.name === toolName);
@@ -119,6 +139,21 @@ try {
         }
       }
     }
+  } else {
+    const searchRequirements = {
+      discover_tools: ["query"],
+      explain_tool: ["name"],
+      invoke_discovered_tool: ["toolName", "arguments", "discoveryToken"],
+    };
+    for (const [toolName, requiredProperties] of Object.entries(searchRequirements)) {
+      const tool = listed.tools.find((entry) => entry.name === toolName);
+      const properties = Object.keys(tool?.inputSchema?.properties || {});
+      for (const property of requiredProperties) {
+        if (!properties.includes(property)) {
+          throw new Error(`${toolName} schema is missing ${property}`);
+        }
+      }
+    }
   }
   const healthResult = await client.callTool({ name: "health_check", arguments: {} });
   if (healthResult.isError) throw new Error(String(healthResult.content?.[0]?.text || "health_check failed"));
@@ -127,7 +162,8 @@ try {
     health.tool_profile !== profile ||
     health.tool_count !== expectedTools.length ||
     !health.tool_manifest_sha256 ||
-    (profile === "chatgpt_direct" && health.direct_profile_enabled !== true)
+    (profile === "chatgpt_direct" && health.direct_profile_enabled !== true) ||
+    (profile === "chatgpt_search" && health.search_tool_count !== expectedTools.length)
   ) {
     throw new Error(`health_check catalog mismatch: ${JSON.stringify(health)}`);
   }
@@ -164,12 +200,23 @@ try {
       health_check: ["detail"],
       list_tasks: ["repo_path", "active_only"],
       get_task_summary: ["view", "max_items"],
-    } : {
+      safe_result: ["task_id"],
+      safe_audit: ["task_id"],
+      safe_test_summary: ["task_id"],
+      safe_diff_summary: ["task_id"],
+    } : profile === "chatgpt_direct" ? {
       create_direct_session: ["repo_path"],
       apply_patch: ["session_id", "path", "expected_sha256", "operations"],
       run_verification: ["session_id", "command"],
       finalize_direct_session: ["session_id"],
       audit_session: ["session_id"],
+      safe_direct_summary: ["session_id"],
+      safe_finalize_direct_session: ["session_id"],
+      safe_audit_direct_session: ["session_id"],
+    } : {
+      discover_tools: ["query"],
+      explain_tool: ["name"],
+      invoke_discovered_tool: ["toolName", "arguments", "discoveryToken"],
     },
   };
   console.log(jsonOnly ? JSON.stringify(output) : JSON.stringify(output, null, 2));

package/scripts/checks/mcp-smoke.js

@@ -103,12 +103,21 @@ try {
   const tools = await client.listTools();
   const names = tools.tools.map((tool) => tool.name).sort();
   const expected = [
+    "accept_subgoal",
     "apply_patch",
     "audit_session",
     "audit_task",
     "cancel_task",
+    "check_release_gate",
     "create_direct_session",
+    "create_goal",
+    "create_subgoal_task",
     "create_task",
+    "diagnose_task",
+    "discard_worktree",
+    "discover_tools",
+    "explain_tool",
+    "export_handoff",
     "finalize_direct_session",
     "get_diff",
     "get_plan",
@@ -121,16 +130,31 @@ try {
     "get_task_summary",
     "get_test_log",
     "health_check",
+    "invoke_discovered_tool",
     "kill_task",
     "list_agents",
+    "list_goals",
     "list_tasks",
     "list_workspace",
+    "merge_worktree",
+    "read_goal",
     "read_workspace_file",
+    "reconcile_tasks",
+    "reject_subgoal",
     "retry_task",
     "run_verification",
+    "safe_audit",
+    "safe_audit_direct_session",
+    "safe_diff_summary",
+    "safe_direct_summary",
+    "safe_finalize_direct_session",
+    "safe_result",
     "safe_status",
+    "safe_test_summary",
     "save_plan",
     "search_workspace",
+    "suggest_next_subgoal",
+    "summarize_goal_progress",
     "sync_file",
     "wait_for_task",
   ];
@@ -143,7 +167,7 @@ try {
   if (!tools._meta || typeof tools._meta.tool_manifest_sha256 !== "string" || tools._meta.tool_manifest_sha256.length !== 64) {
     throw new Error(`tools/list _meta missing manifest hash: ${JSON.stringify(tools._meta || null)}`);
   }
-  if (tools._meta.tool_profile !== "full" || tools._meta.tool_count !== 30) {
+  if (tools._meta.tool_profile !== "full" || tools._meta.tool_count !== 54) {
     throw new Error(`tools/list _meta profile/count mismatch: ${JSON.stringify(tools._meta)}`);
   }
   if (typeof tools._meta.schema_epoch !== "string" || typeof tools._meta.server_version !== "string") {
@@ -296,8 +320,8 @@ try {
 
   const statusPath = join(task.path, "status.json");
   const statusAfter = JSON.parse(readFileSync(statusPath, "utf-8"));
-  if (statusAfter.status !== "done") {
-    throw new Error(`runner status should be done, got ${statusAfter.status}`);
+  if (statusAfter.status !== "done" && statusAfter.status !== "done_by_agent") {
+    throw new Error(`runner status should be done or done_by_agent, got ${statusAfter.status}`);
   }
   for (const fileName of ["result.md", "result.json", "diff.patch", "git.diff", "file-stats.json", "test.log", "verify.json", "verify.log"]) {
     if (!existsSync(join(task.path, fileName))) {
@@ -393,7 +417,7 @@ try {
   await disabledClient.close();
   ok("chatgpt_direct disabled exposes only health_check with diagnostic");
 
-  // 2. chatgpt_direct enabled: 10 tools + minimal create_direct_session
+  // 2. chatgpt_direct enabled: 13 tools + minimal create_direct_session
   const enabledConfigPath = join(tempRoot, "direct-enabled.json");
   const directRepo = join(workspaceRoot, "direct-fixture");
   mkdirSync(join(directRepo, "src"), { recursive: true });
@@ -450,14 +474,17 @@ try {
     "list_workspace",
     "read_workspace_file",
     "run_verification",
+    "safe_audit_direct_session",
+    "safe_direct_summary",
+    "safe_finalize_direct_session",
     "search_workspace",
     "sync_file",
   ];
   if (JSON.stringify(enabledNames) !== JSON.stringify(expectedDirect)) {
     throw new Error(`chatgpt_direct enabled tools mismatch: ${enabledNames.join(", ")}`);
   }
-  if (enabledTools._meta.tool_count !== 10) {
-    throw new Error(`chatgpt_direct enabled tool_count should be 10, got ${enabledTools._meta.tool_count}`);
+  if (enabledTools._meta.tool_count !== 13) {
+    throw new Error(`chatgpt_direct enabled tool_count should be 13, got ${enabledTools._meta.tool_count}`);
   }
 
   // Minimal create_direct_session
@@ -477,12 +504,12 @@ try {
   if (enabledHealth.direct_profile_enabled !== true) {
     throw new Error(`direct_profile_enabled should be true, got ${enabledHealth.direct_profile_enabled}`);
   }
-  if (enabledHealth.direct_tool_count !== 10) {
-    throw new Error(`direct_tool_count should be 10, got ${enabledHealth.direct_tool_count}`);
+  if (enabledHealth.direct_tool_count !== 13) {
+    throw new Error(`direct_tool_count should be 13, got ${enabledHealth.direct_tool_count}`);
   }
 
   await enabledClient.close();
-  ok("chatgpt_direct enabled exposes 10 tools and create_direct_session works");
+  ok("chatgpt_direct enabled exposes 13 tools and create_direct_session works");
 } catch (error) {
   fail("MCP smoke test", error);
 } finally {

package/scripts/checks/watcher-supervisor-smoke.js

@@ -105,7 +105,7 @@ function createFixture(name) {
     server_version: "0.6.0",
     schema_epoch: "2026-06-22-v6",
     tool_profile: "chatgpt_core",
-    tool_count: 16,
+    tool_count: 21,
     tool_names: [],
     tool_manifest_sha256: "a".repeat(64),
   });
@@ -167,7 +167,7 @@ function fixtureEnv(fixture, mode, lifetimeMs) {
     ...process.env,
     APPDATA: fixture.appData,
     LOCALAPPDATA: fixture.localAppData,
-    CONTROL_PLANE_API_KEY: "watcher-supervisor-smoke-secret",
+    CONTROL_PLANE_API_KEY: "test-key",
     WATCHER_FIXTURE_MODE: mode,
     TUNNEL_FIXTURE_LIFETIME_MS: String(lifetimeMs),
   };

package/src/agents/agentRouter.ts

@@ -0,0 +1,149 @@
+import { PatchWardenError } from "../errors.js";
+
+// ── Types ─────────────────────────────────────────────────────────
+
+export interface AgentRouteInput {
+  goal?: string;
+  scope?: string[];
+  inline_plan?: string;
+  template?: string;
+  configuredAgents: string[];
+}
+
+export interface AgentRouteResult {
+  recommended_agent: string;
+  reason: string;
+  fallback: boolean;
+}
+
+// ── Routing rules (roadmap 9.3) ───────────────────────────────────
+
+export const AGENT_ROUTING_RULES = {
+  /** 大规模代码修改 → opencode */
+  largeScope: {
+    agent: "opencode",
+    threshold: 10, // scope.length > threshold
+  },
+  /** 单文件修改 → patchwarden-direct */
+  singleFile: {
+    agent: "patchwarden-direct",
+  },
+  /** 验收审计 → patchwarden-audit */
+  audit: {
+    agent: "patchwarden-audit",
+    keywords: ["审计", "audit", "验收", "verify"],
+  },
+  /** 复杂推理和重构 → codex */
+  refactor: {
+    agent: "codex",
+    keywords: ["重构", "refactor", "跨模块", "redesign"],
+  },
+  /** 文档整理 → claude（fallback 到 opencode） */
+  documentation: {
+    agent: "claude",
+    fallbackAgent: "opencode",
+    keywords: ["文档", "readme", "changelog", "doc"],
+  },
+} as const;
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+function containsAny(text: string, keywords: readonly string[]): boolean {
+  return keywords.some((keyword) => text.includes(keyword));
+}
+
+function resolveRoute(
+  preferred: string,
+  reason: string,
+  configuredAgents: string[]
+): AgentRouteResult {
+  if (configuredAgents.includes(preferred)) {
+    return { recommended_agent: preferred, reason, fallback: false };
+  }
+  const fallback = configuredAgents[0];
+  return {
+    recommended_agent: fallback,
+    reason: `fallback: ${preferred} not configured, using ${fallback}`,
+    fallback: true,
+  };
+}
+
+// ── Route agent ───────────────────────────────────────────────────
+
+export function routeAgent(input: AgentRouteInput): AgentRouteResult {
+  if (!input.configuredAgents || input.configuredAgents.length === 0) {
+    throw new PatchWardenError(
+      "no_agent_configured",
+      "No agent is configured for routing.",
+      "Configure at least one agent in patchwarden.config.json under the agents field."
+    );
+  }
+
+  const scopeCount = input.scope?.length ?? 0;
+  const text = `${input.goal || ""} ${input.inline_plan || ""}`.toLowerCase();
+
+  // Rule 1: 大规模代码修改 → opencode (scope files > 10)
+  if (scopeCount > AGENT_ROUTING_RULES.largeScope.threshold) {
+    return resolveRoute(
+      AGENT_ROUTING_RULES.largeScope.agent,
+      `large scope (${scopeCount} files)`,
+      input.configuredAgents
+    );
+  }
+
+  // Rule 2: 单文件修改 → patchwarden-direct (scope files === 1)
+  if (scopeCount === 1) {
+    return resolveRoute(
+      AGENT_ROUTING_RULES.singleFile.agent,
+      "single file scope",
+      input.configuredAgents
+    );
+  }
+
+  // Rule 3: 验收审计 → patchwarden-audit
+  if (containsAny(text, AGENT_ROUTING_RULES.audit.keywords)) {
+    return resolveRoute(
+      AGENT_ROUTING_RULES.audit.agent,
+      "audit keywords",
+      input.configuredAgents
+    );
+  }
+
+  // Rule 4: 复杂推理和重构 → codex
+  if (containsAny(text, AGENT_ROUTING_RULES.refactor.keywords)) {
+    return resolveRoute(
+      AGENT_ROUTING_RULES.refactor.agent,
+      "refactor keywords",
+      input.configuredAgents
+    );
+  }
+
+  // Rule 5: 文档整理 → claude（fallback 到 opencode）
+  if (containsAny(text, AGENT_ROUTING_RULES.documentation.keywords)) {
+    const preferred = AGENT_ROUTING_RULES.documentation.agent;
+    const fallbackAgent = AGENT_ROUTING_RULES.documentation.fallbackAgent;
+    if (input.configuredAgents.includes(preferred)) {
+      return { recommended_agent: preferred, reason: "documentation keywords", fallback: false };
+    }
+    if (input.configuredAgents.includes(fallbackAgent)) {
+      return {
+        recommended_agent: fallbackAgent,
+        reason: `fallback: ${preferred} not configured, using ${fallbackAgent}`,
+        fallback: true,
+      };
+    }
+    const firstAgent = input.configuredAgents[0];
+    return {
+      recommended_agent: firstAgent,
+      reason: `fallback: ${preferred} not configured, using ${firstAgent}`,
+      fallback: true,
+    };
+  }
+
+  // Rule 6: 无匹配 → fallback 到 configuredAgents[0]
+  return {
+    recommended_agent: input.configuredAgents[0],
+    reason: `no specific routing rule matched, using default agent ${input.configuredAgents[0]}`,
+    fallback: true,
+  };
+}

package/src/config.ts

@@ -21,7 +21,7 @@ export interface PatchWardenConfig {
   defaultTaskTimeoutSeconds: number;
   maxTaskTimeoutSeconds: number;
   watcherStaleSeconds: number;
-  toolProfile?: "full" | "chatgpt_core" | "chatgpt_direct";
+  toolProfile?: "full" | "chatgpt_core" | "chatgpt_direct" | "chatgpt_search";
   repoAliases?: Record<string, string>;
   enableAgentAssessment?: boolean;
   agentAssessmentTimeoutSeconds?: number;
@@ -224,8 +224,14 @@ function normalizeConfig(config: PatchWardenConfig): PatchWardenConfig {
   if (!Number.isInteger(config.watcherStaleSeconds) || config.watcherStaleSeconds < 5 || config.watcherStaleSeconds > 3600) {
     throw new Error("watcherStaleSeconds must be an integer from 5 to 3600");
   }
-  if (config.toolProfile !== undefined && config.toolProfile !== "full" && config.toolProfile !== "chatgpt_core" && config.toolProfile !== "chatgpt_direct") {
-    throw new Error('toolProfile must be "full", "chatgpt_core", or "chatgpt_direct"');
+  if (
+    config.toolProfile !== undefined &&
+    config.toolProfile !== "full" &&
+    config.toolProfile !== "chatgpt_core" &&
+    config.toolProfile !== "chatgpt_direct" &&
+    config.toolProfile !== "chatgpt_search"
+  ) {
+    throw new Error('toolProfile must be "full", "chatgpt_core", "chatgpt_direct", or "chatgpt_search"');
   }
   if (config.enableAgentAssessment !== undefined && typeof config.enableAgentAssessment !== "boolean") {
     throw new Error("enableAgentAssessment must be a boolean");