patchwarden 0.4.0 → 0.6.1

package/dist/tools/registry.js

@@ -3,7 +3,7 @@
  * Used by both stdio (index.ts) and HTTP (httpServer.ts) transports.
  */
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { getConfig } from "../config.js";
+import { getAllConfiguredTestCommands, getAllConfiguredDirectCommands, getConfig } from "../config.js";
 import { savePlan } from "../tools/savePlan.js";
 import { getPlan } from "../tools/getPlan.js";
 import { createTask } from "../tools/createTask.js";
@@ -23,7 +23,16 @@ import { getTaskSummary } from "../tools/getTaskSummary.js";
 import { waitForTask } from "../tools/waitForTask.js";
 import { errorPayload, PatchWardenError } from "../errors.js";
 import { auditTask } from "../tools/auditTask.js";
+import { safeStatus } from "../tools/safeStatus.js";
+import { logger } from "../logging.js";
 import { runTask } from "../runner/runTask.js";
+import { createDirectSession } from "../tools/createDirectSession.js";
+import { searchWorkspace } from "../tools/searchWorkspace.js";
+import { applyPatch } from "../tools/applyPatch.js";
+import { runVerification } from "../tools/runVerification.js";
+import { finalizeDirectSession } from "../tools/finalizeDirectSession.js";
+import { auditSession } from "../tools/auditSession.js";
+import { syncFile } from "../tools/syncFile.js";
 import { TASK_TEMPLATE_NAMES } from "./taskTemplates.js";
 import { buildToolCatalogSnapshot, getLastToolCatalogSnapshot, resolveToolProfile, selectToolsForProfile, } from "./toolCatalog.js";
 export function getToolDefs() {
@@ -32,18 +41,18 @@ export function getToolDefs() {
     const agentDescription = agentNames.length > 0
         ? `Configured local agent name. Available agents: ${agentNames.map((name) => JSON.stringify(name)).join(", ")}`
         : "Configured local agent name. No agents are currently configured.";
-    const testCommands = [...config.allowedTestCommands].sort();
+    const testCommands = getAllConfiguredTestCommands(config).sort();
     const tools = [
         {
             name: "save_plan",
-            description: "Save an execution plan — ChatGPT writes the plan, PatchWarden stores it for local agent execution.",
+            description: "Save an execution plan — ChatGPT writes the plan, PatchWarden stores it for local agent execution. Supports plan_ref to load a plan file already placed inside .patchwarden/plans.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    title: { type: "string", description: "Plan title" },
-                    content: { type: "string", description: "Plan content in Markdown" },
+                    title: { type: "string", description: "Plan title. Defaults to 'Inline plan' or 'Plan from file' when omitted." },
+                    content: { type: "string", description: "Plan content in Markdown. Required unless plan_ref is provided." },
+                    plan_ref: { type: "string", description: "Relative path to a plan file already inside .patchwarden/plans. When provided, the file content is loaded and title defaults to 'Plan from file' if title is empty." },
                 },
-                required: ["title", "content"],
             },
         },
         {
@@ -82,7 +91,7 @@ export function getToolDefs() {
         },
         {
             name: "create_task",
-            description: "Create a repo-scoped task from exactly one source. A stale watcher preserves the task but returns execution_blocked and directs the client to health_check; otherwise call wait_for_task until terminal.",
+            description: "Create a repo-scoped task from exactly one source. For ChatGPT, prefer the guarded inspect_only, feature_small, or fix_tests template when it fits. A stale watcher preserves the task but returns execution_blocked and directs the client to health_check; otherwise call wait_for_task until terminal. Use execution_mode=assess_only to pre-assess risk and get an assessment_id without creating a task; then invoke the returned next_tool_call using only execution_mode=execute and the full assessment_id.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -92,7 +101,7 @@ export function getToolDefs() {
                     template: {
                         type: "string",
                         enum: [...TASK_TEMPLATE_NAMES],
-                        description: "Built-in guarded task template. Use with goal; rollback_scope_violation also requires source_task_id.",
+                        description: "Built-in guarded task template. ChatGPT should prefer inspect_only for diagnosis, feature_small for a scoped change, and fix_tests for known failing verification. Use with goal; rollback_scope_violation also requires source_task_id.",
                     },
                     goal: { type: "string", description: "Required task goal when template is supplied." },
                     source_task_id: { type: "string", description: "Required source task for rollback_scope_violation review." },
@@ -119,7 +128,7 @@ export function getToolDefs() {
                             type: "string",
                             ...(testCommands.length > 0 ? { enum: testCommands } : {}),
                         },
-                        description: "Recommended allow-listed commands PatchWarden runs independently after the agent exits.",
+                        description: "Recommended exact-match commands PatchWarden runs independently after the agent exits. Repository-scoped commands are re-authorized after repo_path is resolved.",
                     },
                     timeout_seconds: {
                         type: "integer",
@@ -128,8 +137,18 @@ export function getToolDefs() {
                         default: config.defaultTaskTimeoutSeconds,
                         description: `Total task timeout in seconds (default ${config.defaultTaskTimeoutSeconds}, max ${config.maxTaskTimeoutSeconds})`,
                     },
+                    execution_mode: {
+                        type: "string",
+                        enum: ["assess_only", "execute"],
+                        default: "execute",
+                        description: "assess_only: run deterministic risk checks and return an assessment_id without creating a task. execute (default): create and queue the task. When combined with assessment_id, the task parameters are loaded from the assessment record and freshness is revalidated.",
+                    },
+                    assessment_id: {
+                        type: "string",
+                        description: "Assessment ID from a prior assess_only call. When provided with execution_mode=execute, task parameters are loaded from the assessment record and locked to it. The full 128-bit ID (32 hex chars) must be provided; short IDs are display-only.",
+                    },
                 },
-                required: ["agent", "repo_path"],
+                required: [],
             },
         },
         {
@@ -202,13 +221,17 @@ export function getToolDefs() {
         },
         {
             name: "read_workspace_file",
-            description: "Read a file within the workspace. Sensitive files (secrets, keys, tokens) are blocked.",
+            description: "Read a file within the workspace. Sensitive files (secrets, keys, tokens) are blocked. In Direct mode (with session_id), reads are scoped to the session's repo_path and return sha256.",
             inputSchema: {
                 type: "object",
                 properties: {
                     path: {
                         type: "string",
-                        description: "Relative path to a file inside the workspace",
+                        description: "Relative path to a file inside the workspace or session repo",
+                    },
+                    session_id: {
+                        type: "string",
+                        description: "Optional Direct session ID. When provided, read scope is limited to the session's repo_path and sha256 is returned.",
                     },
                 },
                 required: ["path"],
@@ -333,18 +356,20 @@ export function getToolDefs() {
         },
         {
             name: "get_task_summary",
-            description: "Return one structured acceptance summary: terminal status, scope violations, verification evidence, changed files, artifact availability, warnings, and errors.",
+            description: "Return structured acceptance evidence. Use view=compact first for bounded counts and risk excerpts; use standard only when full changed-file and log-tail detail is required.",
             inputSchema: {
                 type: "object",
                 properties: {
                     task_id: { type: "string", description: "Task ID" },
+                    view: { type: "string", enum: ["compact", "standard"], default: "standard", description: "Compact returns bounded acceptance evidence; standard preserves the full legacy summary." },
+                    max_items: { type: "integer", minimum: 1, maximum: 50, default: 8, description: "Maximum entries per compact evidence group." },
                 },
                 required: ["task_id"],
             },
         },
         {
             name: "audit_task",
-            description: "Independently audit a task's outputs. Verifies status, result.md, test.log, git.diff, repo_path consistency, cross-references agent claims with package.json scripts, and flags unverified release/publish claims. Writes independent-review.md to the task directory.",
+            description: "Independently audit a task's outputs. Verifies status, result.md, test.log, git.diff, repo_path consistency, cross-references agent claims with package.json scripts, and flags unverified release/publish claims. Evidence-backed failures, possible heuristic false positives, and manual-verification items are returned separately. Writes independent-review.md to the task directory.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -353,7 +378,138 @@ export function getToolDefs() {
                 required: ["task_id"],
             },
         },
+        {
+            name: "safe_status",
+            description: "Return minimal task lifecycle status without exposing diff, log content, file contents, or sensitive paths. Use this when only task state is needed and content-bearing tools may be blocked by upper-layer security.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID to check" },
+                },
+                required: ["task_id"],
+            },
+        },
     ];
+    // Direct session tools
+    const directCommands = getAllConfiguredDirectCommands(config);
+    tools.push({
+        name: "create_direct_session",
+        description: "Create a Direct editing session for ChatGPT to apply patches directly. Requires enableDirectProfile: true in config.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo_path: {
+                    type: "string",
+                    description: "Repository path inside workspaceRoot (e.g., 'my-project')",
+                },
+                title: {
+                    type: "string",
+                    description: "Optional title describing the session's purpose",
+                },
+            },
+            required: ["repo_path"],
+        },
+    });
+    tools.push({
+        name: "search_workspace",
+        description: "Search file contents (grep-like) within a Direct session's repo_path. Skips .git, node_modules, dist, release, and sensitive files.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Session ID from create_direct_session" },
+                query: { type: "string", description: "Search query string" },
+                max_results: { type: "number", description: "Max results (default 20)" },
+                case_sensitive: { type: "boolean", description: "Case sensitive search (default false)" },
+                max_preview_chars: { type: "number", description: "Max preview chars per match (default 200)" },
+                include_globs: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional file name glob patterns to include (e.g., ['*.ts', '*.js'])",
+                },
+            },
+            required: ["session_id", "query"],
+        },
+    });
+    tools.push({
+        name: "apply_patch",
+        description: "Apply JSON patch operations to a file within a Direct session's repo_path. Validates expected_sha256 before applying. Supports replace_exact, insert_before, insert_after, replace_whole_file.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Session ID" },
+                path: { type: "string", description: "Relative file path within the session repo" },
+                expected_sha256: { type: "string", description: "Expected SHA-256 hash of the current file content" },
+                operations: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            type: { type: "string", enum: ["replace_exact", "insert_before", "insert_after", "replace_whole_file"] },
+                            old_text: { type: "string", description: "Text to find (required for replace_exact, insert_before, insert_after)" },
+                            new_text: { type: "string", description: "Replacement or insertion text" },
+                            occurrence: { type: "string", enum: ["first", "all", "exactly_once"], description: "Match mode for replace_exact (default first)" },
+                        },
+                        required: ["type", "new_text"],
+                    },
+                },
+            },
+            required: ["session_id", "path", "expected_sha256", "operations"],
+        },
+    });
+    tools.push({
+        name: "run_verification",
+        description: "Run a whitelisted verification command within a Direct session. Command must be in the Direct allowlist.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Session ID" },
+                command: {
+                    type: "string",
+                    description: "Verification command to run",
+                    ...(directCommands.length > 0 ? { enum: directCommands } : {}),
+                },
+                timeout_seconds: { type: "number", description: "Timeout in seconds (default 120)" },
+            },
+            required: ["session_id", "command"],
+        },
+    });
+    tools.push({
+        name: "finalize_direct_session",
+        description: "Finalize a Direct session: capture after snapshot, generate diff/summary/change artifacts, mark session as finalized. Must be called before audit_session.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Session ID to finalize" },
+            },
+            required: ["session_id"],
+        },
+    });
+    tools.push({
+        name: "audit_session",
+        description: "Independently audit a Direct session's changes. Performs 16 deterministic checks and returns pass/warn/fail decision. Requires session to be finalized first.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Session ID to audit" },
+            },
+            required: ["session_id"],
+        },
+    });
+    tools.push({
+        name: "sync_file",
+        description: "Copy a file from source to target within the same Direct session repo. Both paths must be inside the session repo_path. Returns before/after sha256 hashes and whether the target changed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Direct session ID" },
+                source_path: { type: "string", description: "Relative path to source file within repo" },
+                target_path: { type: "string", description: "Relative path to target file within repo" },
+                expected_source_sha256: { type: "string", description: "Optional: expected sha256 of source file" },
+                expected_target_sha256: { type: "string", description: "Optional: expected sha256 of target file before copy" },
+            },
+            required: ["session_id", "source_path", "target_path"],
+        },
+    });
     // run_task: only available when explicitly enabled
     if (config.enableRunTaskTool === true) {
         tools.push({
@@ -369,7 +525,7 @@ export function getToolDefs() {
         });
     }
     const profile = resolveToolProfile(config.toolProfile);
-    const selected = selectToolsForProfile(tools, profile);
+    const selected = selectToolsForProfile(tools, profile, config.enableDirectProfile);
     buildToolCatalogSnapshot(selected, profile);
     return selected;
 }
@@ -379,12 +535,33 @@ export function getToolCatalogSnapshot() {
     return buildToolCatalogSnapshot(tools, resolveToolProfile(config.toolProfile));
 }
 // ── Request handler ───────────────────────────────────────────────
+function guardDirectProfileEnabled() {
+    const config = getConfig();
+    if (!config.enableDirectProfile) {
+        throw new PatchWardenError("direct_profile_disabled", "Direct profile is disabled by local config.", "Set enableDirectProfile: true in patchwarden.config.json to use Direct session tools.", true, { operation: "direct_tool_call" });
+    }
+}
 export async function handleToolCall(name, args) {
+    const startTime = Date.now();
+    const taskId = args?.task_id ? String(args.task_id) : args?.session_id ? String(args.session_id) : undefined;
+    try {
+        const result = await handleToolCallInternal(name, args);
+        logger.audit(name, true, Date.now() - startTime, undefined, taskId);
+        return result;
+    }
+    catch (err) {
+        const errorReason = err instanceof Error ? err.message : String(err);
+        logger.audit(name, false, Date.now() - startTime, errorReason, taskId);
+        throw err;
+    }
+}
+async function handleToolCallInternal(name, args) {
     switch (name) {
         case "save_plan": {
             return toResult(savePlan({
                 title: String(args?.title ?? ""),
-                content: String(args?.content ?? ""),
+                content: args?.content !== undefined ? String(args.content) : "",
+                plan_ref: args?.plan_ref ? String(args.plan_ref) : undefined,
             }));
         }
         case "get_plan": {
@@ -407,6 +584,8 @@ export async function handleToolCall(name, args) {
                 timeout_seconds: args?.timeout_seconds !== undefined
                     ? Number(args.timeout_seconds)
                     : undefined,
+                execution_mode: args?.execution_mode === "assess_only" ? "assess_only" : "execute",
+                assessment_id: args?.assessment_id ? String(args.assessment_id) : undefined,
             }));
         }
         case "get_task_status": {
@@ -428,7 +607,11 @@ export async function handleToolCall(name, args) {
             return toResult(listWorkspace(args?.path ? String(args.path) : undefined));
         }
         case "read_workspace_file": {
-            return toResult(readWorkspaceFile(String(args?.path ?? "")));
+            const sessionId = args?.session_id ? String(args.session_id) : undefined;
+            return toResult(readWorkspaceFile({
+                path: String(args?.path ?? ""),
+                session_id: sessionId,
+            }));
         }
         case "list_tasks": {
             return toResult(listTasks({
@@ -472,11 +655,17 @@ export async function handleToolCall(name, args) {
             return toResult(await waitForTask(String(args?.task_id ?? ""), waitSeconds));
         }
         case "get_task_summary": {
-            return toResult(getTaskSummary(String(args?.task_id ?? "")));
+            return toResult(getTaskSummary(String(args?.task_id ?? ""), {
+                view: normalizeSummaryView(args?.view),
+                max_items: args?.max_items !== undefined ? Number(args.max_items) : undefined,
+            }));
         }
         case "audit_task": {
             return toResult(auditTask(String(args?.task_id ?? "")));
         }
+        case "safe_status": {
+            return toResult(safeStatus(String(args?.task_id ?? "")));
+        }
         case "run_task": {
             const config = getConfig();
             if (config.enableRunTaskTool !== true) {
@@ -486,6 +675,60 @@ export async function handleToolCall(name, args) {
             const result = await runTask(taskId);
             return toResult(result);
         }
+        case "create_direct_session": {
+            guardDirectProfileEnabled();
+            return toResult(createDirectSession({
+                repo_path: String(args?.repo_path ?? ""),
+                title: args?.title ? String(args.title) : undefined,
+            }));
+        }
+        case "search_workspace": {
+            guardDirectProfileEnabled();
+            return toResult(searchWorkspace({
+                session_id: String(args?.session_id ?? ""),
+                query: String(args?.query ?? ""),
+                max_results: args?.max_results ? Number(args.max_results) : undefined,
+                case_sensitive: args?.case_sensitive !== undefined ? Boolean(args.case_sensitive) : undefined,
+                max_preview_chars: args?.max_preview_chars ? Number(args.max_preview_chars) : undefined,
+                include_globs: Array.isArray(args?.include_globs) ? args.include_globs.map(String) : undefined,
+            }));
+        }
+        case "apply_patch": {
+            guardDirectProfileEnabled();
+            return toResult(applyPatch({
+                session_id: String(args?.session_id ?? ""),
+                path: String(args?.path ?? ""),
+                expected_sha256: String(args?.expected_sha256 ?? ""),
+                operations: Array.isArray(args?.operations) ? args.operations : [],
+            }));
+        }
+        case "run_verification": {
+            guardDirectProfileEnabled();
+            return toResult(await runVerification({
+                session_id: String(args?.session_id ?? ""),
+                command: String(args?.command ?? ""),
+                timeout_seconds: args?.timeout_seconds ? Number(args.timeout_seconds) : undefined,
+            }));
+        }
+        case "finalize_direct_session": {
+            guardDirectProfileEnabled();
+            return toResult(finalizeDirectSession({
+                session_id: String(args?.session_id ?? ""),
+            }));
+        }
+        case "audit_session": {
+            guardDirectProfileEnabled();
+            return toResult(auditSession({
+                session_id: String(args?.session_id ?? ""),
+            }));
+        }
+        case "sync_file": {
+            guardDirectProfileEnabled();
+            return toResult(syncFile(String(args?.session_id ?? ""), String(args?.source_path ?? ""), String(args?.target_path ?? ""), {
+                expected_source_sha256: args?.expected_source_sha256 ? String(args.expected_source_sha256) : undefined,
+                expected_target_sha256: args?.expected_target_sha256 ? String(args.expected_target_sha256) : undefined,
+            }));
+        }
         default:
             throw new Error(`Unknown tool: ${name}`);
     }
@@ -499,6 +742,14 @@ function normalizeWaitSeconds(args) {
     const value = preferred ?? legacy;
     return value === undefined ? undefined : Number(value);
 }
+function normalizeSummaryView(value) {
+    if (value === undefined)
+        return "standard";
+    if (value !== "compact" && value !== "standard") {
+        throw new Error('view must be "compact" or "standard".');
+    }
+    return value;
+}
 function toResult(data) {
     return {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -547,7 +798,7 @@ export function registerTools(server) {
                         arguments: { detail: "self_diagnostic" },
                     },
                     connector_refresh_steps: [
-                        "1. Run Check-PatchWarden-Health.cmd locally to confirm the active profile and manifest hash.",
+                        "1. Run PatchWarden.cmd health locally to confirm the active profile and manifest hash.",
                         "2. In ChatGPT Platform, refresh or reconnect the Connector (do not reuse an old session).",
                         "3. Open a NEW ChatGPT conversation; old conversations retain their cached tool catalog.",
                         "4. Call health_check in the new conversation and verify tool_manifest_sha256 matches the local report.",

package/dist/tools/runVerification.d.ts

@@ -0,0 +1,16 @@
+export interface RunVerificationInput {
+    session_id: string;
+    command: string;
+    timeout_seconds?: number;
+}
+export interface RunVerificationOutput {
+    command: string;
+    exit_code: number | null;
+    passed: boolean;
+    timed_out: boolean;
+    stdout_tail: string;
+    stderr_tail: string;
+    log_path: string;
+    next_action: string;
+}
+export declare function runVerification(input: RunVerificationInput): Promise<RunVerificationOutput>;

package/dist/tools/runVerification.js

@@ -0,0 +1,32 @@
+import { readDirectSession, appendDirectSessionVerificationRun, } from "../direct/directSessionStore.js";
+import { guardDirectSessionActive } from "../direct/directGuards.js";
+import { runDirectVerification } from "../direct/directVerification.js";
+export async function runVerification(input) {
+    // 1. Read session and guard active
+    const session = readDirectSession(input.session_id);
+    guardDirectSessionActive(session);
+    // 2. Call runDirectVerification with command, resolvedRepoPath,
+    //    sessionId, and timeoutSeconds
+    const timeoutSeconds = input.timeout_seconds ?? 120;
+    const result = await runDirectVerification({
+        command: input.command,
+        resolvedRepoPath: session.resolved_repo_path,
+        sessionId: input.session_id,
+        timeoutSeconds,
+    });
+    // 3. Append verification run to session
+    appendDirectSessionVerificationRun(input.session_id, result.run);
+    // 4. Return result
+    return {
+        command: result.run.command,
+        exit_code: result.run.exit_code,
+        passed: result.run.passed,
+        timed_out: result.run.timed_out,
+        stdout_tail: result.run.stdout_tail,
+        stderr_tail: result.run.stderr_tail,
+        log_path: result.run.log_path,
+        next_action: result.run.passed
+            ? "Call finalize_direct_session to complete the session."
+            : "Review the verification output and apply_patch to fix issues.",
+    };
+}

package/dist/tools/safeStatus.d.ts

@@ -0,0 +1,19 @@
+import { type PatchWardenConfig } from "../config.js";
+import type { TaskStatus, TaskPhase } from "./createTask.js";
+export interface SafeStatusOutput {
+    task_id: string;
+    status: TaskStatus | "not_found";
+    phase: TaskPhase | null;
+    created_at: string | null;
+    started_at: string | null;
+    updated_at: string | null;
+    finished_at: string | null;
+    last_heartbeat_at: string | null;
+    current_command: string | null;
+    verify_status: "passed" | "failed" | "skipped" | null;
+    artifact_status: string | null;
+    watcher_state: string | null;
+    error_code: string | null;
+    error_summary: string | null;
+}
+export declare function safeStatus(taskId: string, config?: PatchWardenConfig): SafeStatusOutput;

package/dist/tools/safeStatus.js

@@ -0,0 +1,72 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { getTasksDir, getConfig } from "../config.js";
+import { guardReadPath } from "../security/pathGuard.js";
+import { guardSensitivePath } from "../security/sensitiveGuard.js";
+import { readTaskRuntime } from "../taskRuntime.js";
+import { readWatcherStatus } from "../watcherStatus.js";
+export function safeStatus(taskId, config) {
+    const cfg = config || getConfig();
+    const tasksDir = getTasksDir(cfg);
+    const taskDir = resolve(tasksDir, taskId);
+    const statusFile = join(taskDir, "status.json");
+    // Check existence BEFORE guardReadPath so that a non-existent task
+    // returns a structured not_found response instead of throwing.
+    if (!existsSync(statusFile)) {
+        return {
+            task_id: taskId,
+            status: "not_found",
+            phase: null,
+            created_at: null,
+            started_at: null,
+            updated_at: null,
+            finished_at: null,
+            last_heartbeat_at: null,
+            current_command: null,
+            verify_status: null,
+            artifact_status: null,
+            watcher_state: null,
+            error_code: null,
+            error_summary: null,
+        };
+    }
+    guardReadPath(statusFile, cfg.workspaceRoot, cfg.tasksDir);
+    guardSensitivePath(statusFile);
+    const raw = readFileSync(statusFile, "utf-8");
+    const status = JSON.parse(raw);
+    const runtime = readTaskRuntime(taskDir);
+    const phase = (runtime.phase || status.phase || "queued");
+    const watcher = readWatcherStatus(cfg);
+    // Extract short error summary — never the full error text
+    let errorCode = null;
+    let errorSummary = null;
+    if (status.error && typeof status.error === "string") {
+        const errorStr = status.error;
+        // Keep only the first 200 chars as summary
+        errorSummary = errorStr.length > 200 ? errorStr.slice(0, 200) + "..." : errorStr;
+        // Try to extract an error code from the status
+        if (typeof status.status === "string" && status.status.startsWith("failed")) {
+            errorCode = status.status;
+        }
+    }
+    else if (typeof status.status === "string" && status.status.startsWith("failed")) {
+        errorCode = status.status;
+        errorSummary = `Task ended with status: ${status.status}`;
+    }
+    return {
+        task_id: taskId,
+        status: status.status || "not_found",
+        phase,
+        created_at: typeof status.created_at === "string" ? status.created_at : null,
+        started_at: typeof status.started_at === "string" ? status.started_at : null,
+        updated_at: typeof status.updated_at === "string" ? status.updated_at : null,
+        finished_at: typeof status.finished_at === "string" ? status.finished_at : null,
+        last_heartbeat_at: runtime.last_heartbeat_at || (typeof status.last_heartbeat_at === "string" ? status.last_heartbeat_at : null),
+        current_command: runtime.current_command ?? (typeof status.current_command === "string" ? status.current_command : null) ?? null,
+        verify_status: typeof status.verify_status === "string" ? status.verify_status : null,
+        artifact_status: typeof status.artifact_status === "string" ? status.artifact_status : null,
+        watcher_state: watcher.status,
+        error_code: errorCode,
+        error_summary: errorSummary,
+    };
+}

package/dist/tools/savePlan.d.ts

@@ -1,6 +1,7 @@
 export interface SavePlanInput {
     title: string;
     content: string;
+    plan_ref?: string;
 }
 export interface SavePlanOutput {
     plan_id: string;

package/dist/tools/savePlan.js

@@ -1,24 +1,55 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve, join } from "node:path";
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { resolve, join, relative } from "node:path";
 import { getPlansDir, getConfig } from "../config.js";
 import { guardPath } from "../security/pathGuard.js";
 import { guardPlanContent } from "../security/planGuard.js";
+import { PatchWardenError } from "../errors.js";
 export function savePlan(input) {
     const config = getConfig();
     const plansDir = getPlansDir(config);
-    guardPlanContent(input.title, input.content);
-    const planId = `plan_${Date.now()}_${sanitizeTitle(input.title)}`;
+    let content = input.content || "";
+    let title = input.title || "";
+    if (input.plan_ref) {
+        // 收缩 #3: plan_ref 只能读取 .patchwarden/plans 内文件，禁止任意路径
+        // plan_ref is relative to plansDir, not workspaceRoot
+        const targetPath = resolve(plansDir, input.plan_ref);
+        // Guard: must stay inside workspace and inside plansDir
+        guardPath(targetPath, config.workspaceRoot, config.plansDir);
+        const relativeToPlans = relative(plansDir, targetPath);
+        if (relativeToPlans.startsWith("..")) {
+            throw new PatchWardenError("plan_ref_outside_plans_dir", `plan_ref must point to a file inside .patchwarden/plans.`, "Use a path relative to .patchwarden/plans/.", true, { plan_ref: input.plan_ref, resolved: targetPath });
+        }
+        if (!existsSync(targetPath)) {
+            throw new PatchWardenError("plan_ref_not_found", `plan_ref file not found: "${input.plan_ref}".`, "Place the plan file under .patchwarden/plans/ first, then reference it.", true, { plan_ref: input.plan_ref });
+        }
+        content = readFileSync(targetPath, "utf-8");
+        if (!title || title.trim() === "") {
+            title = "Plan from file";
+        }
+    }
+    else {
+        // Without plan_ref, content is required
+        if (!content || content.trim() === "") {
+            throw new PatchWardenError("plan_content_required", "save_plan requires content or plan_ref.", "Pass content with the plan text, or use plan_ref to load a file from .patchwarden/plans.");
+        }
+    }
+    // Default title when empty
+    if (!title || title.trim() === "") {
+        title = "Inline plan";
+    }
+    guardPlanContent(title, content);
+    const planId = `plan_${Date.now()}_${sanitizeTitle(title)}`;
     const planDir = resolve(plansDir, planId);
     // Guards: plan dir & file must stay inside workspace
     guardPath(planDir, config.workspaceRoot, config.plansDir);
     mkdirSync(planDir, { recursive: true });
     const planFile = join(planDir, "plan.md");
-    const header = `# ${input.title}\n\n> Plan ID: ${planId}\n> Created: ${new Date().toISOString()}\n\n`;
-    writeFileSync(planFile, header + input.content, "utf-8");
+    const header = `# ${title}\n\n> Plan ID: ${planId}\n> Created: ${new Date().toISOString()}\n\n`;
+    writeFileSync(planFile, header + content, "utf-8");
     return {
         plan_id: planId,
         path: planFile,
-        title: input.title,
+        title: title,
     };
 }
 function sanitizeTitle(title) {