patchwarden 1.1.0 → 1.5.1

package/dist/tools/dispatch/releaseDispatch.js

@@ -0,0 +1,45 @@
+/**
+ * Dispatch handlers for release-mode tools (v1.3.0+).
+ *
+ * Wraps releaseCheck, releasePrepare, releaseVerify, and releaseCleanup
+ * from releaseMode.ts.
+ */
+import { releaseCheck, releasePrepare, releaseVerify, releaseCleanup, } from "../releaseMode.js";
+import { toResult } from "./types.js";
+export const releaseHandlers = {
+    release_check: async (args) => {
+        return toResult(await releaseCheck({
+            repo_path: String(args?.repo_path ?? ""),
+            target_stage: String(args?.target_stage ?? "local_ready"),
+            package_name: args?.package_name ? String(args.package_name) : undefined,
+            version: args?.version ? String(args.version) : undefined,
+            github_repo: args?.github_repo ? String(args.github_repo) : undefined,
+            branch: args?.branch ? String(args.branch) : undefined,
+        }));
+    },
+    release_prepare: async (args) => {
+        return toResult(releasePrepare({
+            repo_path: String(args?.repo_path ?? ""),
+            required_commands: Array.isArray(args?.required_commands)
+                ? args.required_commands.map(String)
+                : undefined,
+            timeout_seconds: args?.timeout_seconds !== undefined ? Number(args.timeout_seconds) : undefined,
+        }));
+    },
+    release_verify: async (args) => {
+        return toResult(await releaseVerify({
+            repo_path: String(args?.repo_path ?? ""),
+            package_name: args?.package_name ? String(args.package_name) : undefined,
+            version: args?.version ? String(args.version) : undefined,
+            github_repo: args?.github_repo ? String(args.github_repo) : undefined,
+            branch: args?.branch ? String(args.branch) : undefined,
+        }));
+    },
+    release_cleanup: async (args) => {
+        return toResult(releaseCleanup({
+            repo_path: String(args?.repo_path ?? ""),
+            dry_run: args?.dry_run !== undefined ? Boolean(args.dry_run) : undefined,
+            patterns: Array.isArray(args?.patterns) ? args.patterns.map(String) : undefined,
+        }));
+    },
+};

package/dist/tools/dispatch/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared types and helpers for the dispatch map.
+ *
+ * Each domain dispatch file exports a `ToolHandlerMap` whose handlers
+ * directly call the existing tool functions — no logic is rewritten.
+ */
+export type ToolHandler = (args: Record<string, unknown> | undefined) => Promise<{
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+}>;
+export type ToolHandlerMap = Record<string, ToolHandler>;
+/**
+ * Wrap a plain data value into the MCP CallToolResult content envelope.
+ * Mirrors the original `toResult` helper from registry.ts.
+ */
+export declare function toResult(data: unknown): {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+};

package/dist/tools/dispatch/types.js

@@ -0,0 +1,15 @@
+/**
+ * Shared types and helpers for the dispatch map.
+ *
+ * Each domain dispatch file exports a `ToolHandlerMap` whose handlers
+ * directly call the existing tool functions — no logic is rewritten.
+ */
+/**
+ * Wrap a plain data value into the MCP CallToolResult content envelope.
+ * Mirrors the original `toResult` helper from registry.ts.
+ */
+export function toResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}

package/dist/tools/evidencePack.d.ts

@@ -0,0 +1,45 @@
+import { type SafeTaskLineage } from "./taskLineage.js";
+export interface SafeEvidencePack {
+    evidence_pack_id: string;
+    lineage_id: string;
+    generated_at: string;
+    path: string;
+    files: {
+        json: string;
+        markdown: string;
+        risk: string;
+        verify: string;
+        diffstat: string;
+        lineage: string;
+        attestation: string;
+        redactions: string;
+    };
+    lineage: SafeTaskLineage;
+    policy: {
+        valid: boolean;
+        issue_count: number;
+        release_readiness: unknown;
+    };
+    catalog: {
+        server_version: string;
+        schema_epoch: string;
+        tool_profile: string | null;
+        tool_count: number | null;
+        tool_manifest_sha256: string | null;
+    };
+    omitted: string[];
+    next_action: string;
+    bounded: true;
+}
+export declare function exportTaskEvidencePack(input: {
+    lineage_id: string;
+    max_items?: number;
+}): SafeEvidencePack;
+export declare function listEvidencePacks(options?: {
+    max_items?: number;
+}): {
+    evidence_packs: SafeEvidencePack[];
+    total: number;
+    truncated: boolean;
+};
+export declare function readEvidencePack(lineageId: string): SafeEvidencePack | null;

package/dist/tools/evidencePack.js

@@ -0,0 +1,375 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig } from "../config.js";
+import { guardReadPath, guardWorkspacePath } from "../security/pathGuard.js";
+import { countRedactionsByCategory, redactSensitiveValue } from "../security/contentRedaction.js";
+import { getProjectPolicySummary } from "../policy/projectPolicy.js";
+import { getTaskLineage } from "./taskLineage.js";
+import { getLastToolCatalogSnapshot } from "./toolCatalog.js";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
+import { PatchWardenError } from "../errors.js";
+export function exportTaskEvidencePack(input) {
+    const lineageId = normalizeLineageId(input.lineage_id);
+    const maxItems = normalizeMaxItems(input.max_items);
+    const config = getConfig();
+    const lineage = getTaskLineage(lineageId, { max_items: maxItems });
+    const packDir = resolve(config.workspaceRoot, ".patchwarden", "evidence-packs", lineageId);
+    guardWorkspacePath(packDir, config.workspaceRoot);
+    mkdirSync(packDir, { recursive: true });
+    const policySummary = readPolicySummary(lineage.repo_path);
+    const catalog = safeCatalog();
+    const generatedAt = new Date().toISOString();
+    const filePaths = {
+        json: join(packDir, "evidence.json"),
+        markdown: join(packDir, "EVIDENCE.md"),
+        risk: join(packDir, "risk.json"),
+        verify: join(packDir, "verify.json"),
+        diffstat: join(packDir, "diffstat.json"),
+        lineage: join(packDir, "lineage.json"),
+        attestation: join(packDir, "attestation.json"),
+        redactions: join(packDir, "redactions.json"),
+    };
+    // Build v2 structured artifact contents (raw, before redaction).
+    const riskContent = buildRiskContent(lineage);
+    const verifyContent = buildVerifyContent(lineage);
+    const diffstatContent = buildDiffstatContent(lineage, config);
+    const lineageSummary = buildLineageSummary(lineage);
+    const attestationContent = buildAttestation(catalog, generatedAt);
+    // Count redactions across all v2 raw contents for the audit trail.
+    const v2RawPayloads = [
+        riskContent,
+        verifyContent,
+        diffstatContent,
+        lineageSummary,
+        attestationContent,
+    ].map((value) => JSON.stringify(value));
+    const aggregated = new Map();
+    for (const raw of v2RawPayloads) {
+        for (const entry of countRedactionsByCategory(raw)) {
+            const existing = aggregated.get(entry.category);
+            if (existing)
+                existing.count += entry.count;
+            else
+                aggregated.set(entry.category, { category: entry.category, reason: entry.reason, count: entry.count });
+        }
+    }
+    const redactionsList = [...aggregated.values()];
+    const redactionsContent = {
+        redactions: redactionsList,
+        total_redacted: redactionsList.reduce((sum, entry) => sum + entry.count, 0),
+        bounded: true,
+        note: "Only categories and counts are recorded; original secret values are never persisted.",
+    };
+    // Redact and write each v2 file.
+    writeFileSync(filePaths.risk, JSON.stringify(redactSensitiveValue(riskContent).value, null, 2) + "\n", "utf-8");
+    writeFileSync(filePaths.verify, JSON.stringify(redactSensitiveValue(verifyContent).value, null, 2) + "\n", "utf-8");
+    writeFileSync(filePaths.diffstat, JSON.stringify(redactSensitiveValue(diffstatContent).value, null, 2) + "\n", "utf-8");
+    writeFileSync(filePaths.lineage, JSON.stringify(redactSensitiveValue(lineageSummary).value, null, 2) + "\n", "utf-8");
+    writeFileSync(filePaths.attestation, JSON.stringify(redactSensitiveValue(attestationContent).value, null, 2) + "\n", "utf-8");
+    writeFileSync(filePaths.redactions, JSON.stringify(redactSensitiveValue(redactionsContent).value, null, 2) + "\n", "utf-8");
+    const safePack = redactSensitiveValue({
+        evidence_pack_id: `evidence_${lineageId}`,
+        lineage_id: lineageId,
+        generated_at: generatedAt,
+        path: packDir,
+        files: filePaths,
+        lineage,
+        policy: {
+            valid: policySummary.valid,
+            issue_count: policySummary.issues.length,
+            release_readiness: policySummary.release_readiness,
+        },
+        catalog,
+        omitted: [
+            "stdout",
+            "stderr",
+            "diff",
+            "verification command logs",
+            "full artifact markdown",
+            "sensitive file contents",
+            "raw secret values (redactions.json stores only categories and counts)",
+            "full diff content (diffstat.json stores only file-level line counts)",
+        ],
+        next_action: buildNextAction(lineage),
+        bounded: true,
+    }).value;
+    writeFileSync(safePack.files.json, JSON.stringify(safePack, null, 2) + "\n", "utf-8");
+    writeFileSync(safePack.files.markdown, buildEvidenceMarkdown(safePack), "utf-8");
+    return safePack;
+}
+export function listEvidencePacks(options = {}) {
+    const maxItems = normalizeMaxItems(options.max_items);
+    const config = getConfig();
+    const root = resolve(config.workspaceRoot, ".patchwarden", "evidence-packs");
+    guardWorkspacePath(root, config.workspaceRoot);
+    if (!existsSync(root))
+        return { evidence_packs: [], total: 0, truncated: false };
+    const packs = readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => readEvidencePack(entry.name))
+        .filter((entry) => entry !== null)
+        .sort((a, b) => b.generated_at.localeCompare(a.generated_at));
+    return {
+        evidence_packs: packs.slice(0, maxItems),
+        total: packs.length,
+        truncated: packs.length > maxItems,
+    };
+}
+export function readEvidencePack(lineageId) {
+    const safeLineageId = normalizeLineageId(lineageId);
+    const config = getConfig();
+    const filePath = resolve(config.workspaceRoot, ".patchwarden", "evidence-packs", safeLineageId, "evidence.json");
+    guardReadPath(filePath, config.workspaceRoot, ".patchwarden/evidence-packs");
+    if (!existsSync(filePath))
+        return null;
+    const raw = readFileSync(filePath, "utf-8").replace(/^\uFEFF/, "");
+    return redactSensitiveValue(JSON.parse(raw)).value;
+}
+function normalizeLineageId(value) {
+    const lineageId = String(value || "").trim();
+    if (!/^[A-Za-z0-9_-]+$/.test(lineageId)) {
+        throw new PatchWardenError("invalid_lineage_id", "lineage_id may contain only letters, numbers, underscores, and hyphens.", "Pass a lineage_id returned by run_task_loop.", true, { lineage_id: lineageId });
+    }
+    return lineageId;
+}
+function normalizeMaxItems(value) {
+    if (value === undefined)
+        return 12;
+    if (!Number.isInteger(value) || value < 1 || value > 50) {
+        throw new Error("max_items must be an integer from 1 to 50.");
+    }
+    return value;
+}
+function readPolicySummary(repoPath) {
+    try {
+        const policy = getProjectPolicySummary(repoPath || ".");
+        return {
+            valid: Boolean(policy.valid),
+            issues: Array.isArray(policy.issues) ? policy.issues : [],
+            release_readiness: policy.release_readiness || null,
+        };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            issues: [{ code: "policy_unavailable", message: err instanceof Error ? err.message : String(err) }],
+            release_readiness: null,
+        };
+    }
+}
+function safeCatalog() {
+    try {
+        const catalog = getLastToolCatalogSnapshot();
+        if (!catalog)
+            throw new Error("catalog snapshot unavailable");
+        return {
+            server_version: catalog.server_version,
+            schema_epoch: catalog.schema_epoch,
+            tool_profile: catalog.tool_profile,
+            tool_count: catalog.tool_count,
+            tool_manifest_sha256: catalog.tool_manifest_sha256,
+        };
+    }
+    catch {
+        return {
+            server_version: PATCHWARDEN_VERSION,
+            schema_epoch: TOOL_SCHEMA_EPOCH,
+            tool_profile: null,
+            tool_count: null,
+            tool_manifest_sha256: null,
+        };
+    }
+}
+function buildNextAction(lineage) {
+    if (lineage.stop_reason === "success")
+        return "Use this evidence pack for review or release readiness.";
+    return lineage.next_action || "Review lineage before exporting release evidence.";
+}
+function buildRiskContent(lineage) {
+    const risks = [];
+    for (const round of lineage.rounds) {
+        for (const check of round.fail_checks) {
+            risks.push({ source: "round", task_id: round.task_id, severity: "high", category: "fail_check", detail: check });
+        }
+        for (const check of round.warn_checks) {
+            risks.push({ source: "round", task_id: round.task_id, severity: "medium", category: "warn_check", detail: check });
+        }
+    }
+    for (const warning of lineage.warnings) {
+        risks.push({ source: "lineage", severity: "low", category: "warning", detail: warning });
+    }
+    const by_severity = {
+        high: risks.filter((risk) => risk.severity === "high").length,
+        medium: risks.filter((risk) => risk.severity === "medium").length,
+        low: risks.filter((risk) => risk.severity === "low").length,
+    };
+    return { risks, count: risks.length, by_severity };
+}
+function buildVerifyContent(lineage) {
+    const records = [];
+    for (const round of lineage.rounds) {
+        records.push({
+            source: "round",
+            task_id: round.task_id,
+            role: round.role,
+            verification_status: round.verification_status,
+            audit_verdict: round.audit_verdict,
+            passed: round.verification_status === "passed",
+        });
+    }
+    for (const session of lineage.tasks.direct_sessions) {
+        records.push({
+            source: "direct_session",
+            session_id: session.session_id,
+            verification_status: session.status || "unknown",
+            audit_verdict: session.audit_decision || "not_run",
+            passed: session.status === "passed",
+            command_count: session.command_count,
+            passed_commands: session.passed_commands,
+            failed_commands: session.failed_commands,
+        });
+    }
+    const passed = records.filter((record) => record.passed).length;
+    return {
+        records,
+        count: records.length,
+        summary: { total: records.length, passed, failed: records.length - passed },
+        latest_status: lineage.verification.latest_status,
+        overall_passed: lineage.verification.passed,
+    };
+}
+function buildDiffstatContent(lineage, config) {
+    const taskIds = [
+        lineage.tasks.main,
+        ...lineage.tasks.fix,
+        ...lineage.tasks.cleanup,
+    ].filter((id) => Boolean(id));
+    const files = [];
+    let totalAdditions = 0;
+    let totalDeletions = 0;
+    for (const taskId of taskIds) {
+        if (!/^[A-Za-z0-9_-]+$/.test(taskId))
+            continue;
+        const statsPath = resolve(config.workspaceRoot, config.tasksDir, taskId, "file-stats.json");
+        try {
+            guardWorkspacePath(statsPath, config.workspaceRoot);
+            if (!existsSync(statsPath))
+                continue;
+            const raw = readFileSync(statsPath, "utf-8").replace(/^\uFEFF/, "");
+            const stats = JSON.parse(raw);
+            if (!Array.isArray(stats.files))
+                continue;
+            for (const file of stats.files) {
+                const additions = Number(file.additions) || 0;
+                const deletions = Number(file.deletions) || 0;
+                files.push({
+                    path: String(file.path || ""),
+                    status: String(file.status || "unknown"),
+                    additions,
+                    deletions,
+                    task_id: taskId,
+                });
+                totalAdditions += additions;
+                totalDeletions += deletions;
+            }
+        }
+        catch {
+            // Skip unreadable or malformed file-stats.json entries.
+        }
+    }
+    return {
+        files,
+        count: files.length,
+        totals: { additions: totalAdditions, deletions: totalDeletions },
+    };
+}
+function buildLineageSummary(lineage) {
+    return {
+        lineage_id: lineage.lineage_id,
+        goal: lineage.goal,
+        final_status: lineage.final_status,
+        stop_reason: lineage.stop_reason,
+        iterations_count: lineage.rounds.length,
+        task_counts: {
+            main: lineage.tasks.main ? 1 : 0,
+            fix: lineage.tasks.fix.length,
+            cleanup: lineage.tasks.cleanup.length,
+            direct_sessions: lineage.tasks.direct_sessions.length,
+        },
+        verification: lineage.verification,
+        worktree: {
+            isolation_mode: lineage.worktree.isolation_mode,
+            status: lineage.worktree.status,
+        },
+        agent_routing: lineage.agent_routing ? { selected_agent: lineage.agent_routing.selected_agent } : null,
+        warnings_count: lineage.warnings.length,
+        errors_count: lineage.errors.length,
+        truncated: lineage.truncated,
+    };
+}
+function readGitCommitShort() {
+    try {
+        return execSync("git rev-parse --short HEAD", { encoding: "utf-8", timeout: 5000 }).trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+function buildAttestation(catalog, generatedAt) {
+    return {
+        patchwarden_version: PATCHWARDEN_VERSION,
+        package_version: PATCHWARDEN_VERSION,
+        commit: readGitCommitShort(),
+        node_version: process.version,
+        os: { platform: process.platform, arch: process.arch },
+        tool_profile: catalog.tool_profile,
+        schema_epoch: catalog.schema_epoch,
+        generated_at: generatedAt,
+    };
+}
+function buildEvidenceMarkdown(pack) {
+    const direct = pack.lineage.tasks.direct_sessions
+        .map((entry) => `- ${entry.session_id}: status=${entry.status || "unknown"}, audit=${entry.audit_decision || "unknown"}`)
+        .join("\n");
+    const rounds = pack.lineage.rounds
+        .map((round) => `- ${round.role} ${round.task_id}: status=${round.status}, verification=${round.verification_status}, audit=${round.audit_verdict}`)
+        .join("\n");
+    return [
+        "# PatchWarden Evidence Pack",
+        "",
+        `- Evidence pack: ${pack.evidence_pack_id}`,
+        `- Lineage: ${pack.lineage_id}`,
+        `- Generated: ${pack.generated_at}`,
+        `- Final status: ${pack.lineage.final_status}`,
+        `- Stop reason: ${pack.lineage.stop_reason}`,
+        `- Worktree: ${pack.lineage.worktree.isolation_mode} (${pack.lineage.worktree.status})`,
+        `- Tool manifest: ${pack.catalog.tool_manifest_sha256 || "unavailable"}`,
+        "",
+        "## Verification Rounds",
+        rounds || "- None.",
+        "",
+        "## Direct Evidence",
+        direct || "- None.",
+        "",
+        "## Policy And Release",
+        `- Policy valid: ${pack.policy.valid}`,
+        `- Policy issue count: ${pack.policy.issue_count}`,
+        "",
+        "## Evidence Pack v2 Files",
+        "- `evidence.json` — full bounded evidence pack (machine-readable).",
+        "- `EVIDENCE.md` — human-readable evidence summary.",
+        "- `risk.json` — aggregated risk items with severity (high/medium/low).",
+        "- `verify.json` — structured verification records per round and direct session.",
+        "- `diffstat.json` — file-level additions/deletions without full diff content.",
+        "- `lineage.json` — bounded lineage summary (goal, status, task counts).",
+        "- `attestation.json` — version, commit, Node/OS, tool profile, schema epoch.",
+        "- `redactions.json` — redaction categories and counts (no original secret values).",
+        "",
+        "## Omitted",
+        ...pack.omitted.map((item) => `- ${item}`),
+        "",
+        `Next action: ${pack.next_action}`,
+        "",
+    ].join("\n");
+}

package/dist/tools/finalizeDirectSession.d.ts

@@ -16,4 +16,4 @@ export interface FinalizeDirectSessionOutput {
     finalized: boolean;
     next_action: string;
 }
-export declare function finalizeDirectSession(input: FinalizeDirectSessionInput): FinalizeDirectSessionOutput;
+export declare function finalizeDirectSession(input: FinalizeDirectSessionInput): Promise<FinalizeDirectSessionOutput>;

package/dist/tools/finalizeDirectSession.js

@@ -3,15 +3,15 @@ import { readDirectSession, finalizeDirectSessionRecord, getDirectSessionDir, }
 import { guardDirectSessionActive } from "../direct/directGuards.js";
 import { captureRepoSnapshot, buildChangeArtifacts, } from "../runner/changeCapture.js";
 // ── Main function ──────────────────────────────────────────────────
-export function finalizeDirectSession(input) {
+export async function finalizeDirectSession(input) {
     const { session_id } = input;
     // 1. Read session and guard active (not expired, not finalized)
     const session = readDirectSession(session_id);
     guardDirectSessionActive(session);
     // 2. Capture after snapshot
-    const afterSnapshot = captureRepoSnapshot(session.resolved_repo_path);
+    const afterSnapshot = await captureRepoSnapshot(session.resolved_repo_path);
     // 3. Build change artifacts from before/after snapshots
-    const changeArtifacts = buildChangeArtifacts(session.resolved_repo_path, session.workspace_snapshot_before, afterSnapshot);
+    const changeArtifacts = await buildChangeArtifacts(session.resolved_repo_path, session.workspace_snapshot_before, afterSnapshot);
     // 4. Finalize session record — writes changed-files.json, diff.patch,
     //    summary.json, summary.md and marks the session as finalized.
     finalizeDirectSessionRecord(session_id, afterSnapshot, changeArtifacts);

package/dist/tools/goalSubgoalTask.d.ts

@@ -48,4 +48,4 @@ export interface CreateSubgoalTaskOutput {
  * @throws PatchWardenError("invalid_dependency") 当 depends_on 引用不存在的 subgoal
  * @throws PatchWardenError("invalid_execution_mode") 当 execution_mode 为 "assess_only"
  */
-export declare function createSubgoalTask(input: CreateSubgoalTaskInput): CreateSubgoalTaskOutput;
+export declare function createSubgoalTask(input: CreateSubgoalTaskInput): Promise<CreateSubgoalTaskOutput>;

package/dist/tools/goalSubgoalTask.js

@@ -27,7 +27,7 @@ import { PatchWardenError } from "../errors.js";
  * @throws PatchWardenError("invalid_dependency") 当 depends_on 引用不存在的 subgoal
  * @throws PatchWardenError("invalid_execution_mode") 当 execution_mode 为 "assess_only"
  */
-export function createSubgoalTask(input) {
+export async function createSubgoalTask(input) {
     // assess_only 不产生 task，无法关联到 subgoal
     if (input.execution_mode === "assess_only") {
         throw new PatchWardenError("invalid_execution_mode", "createSubgoalTask does not support execution_mode \"assess_only\"", "Use execution_mode \"execute\" (default) so a task is created and linked to the subgoal.", true, { goal_id: input.goal_id, execution_mode: input.execution_mode });
@@ -57,7 +57,7 @@ export function createSubgoalTask(input) {
     // 3. 调用 createTask 创建关联任务（强制 execute 模式，确保返回 CreateTaskOutput）
     let taskId;
     try {
-        const taskResult = createTask({
+        const taskResult = await createTask({
             plan_id: input.plan_id,
             inline_plan: input.inline_plan,
             plan_title: input.plan_title,

package/dist/tools/healthCheck.js

@@ -185,7 +185,7 @@ function directoryStatus(path, allowCreatable, createRoot) {
                 accessSync(parent, constants.R_OK | constants.W_OK);
                 return { available: true, path, readable: false, writable: true, reason: "Directory will be created on first use." };
             }
-            catch { }
+            catch { } // probe failure handled by return value
         }
         return { available: false, path, readable: false, writable: false, reason: "Directory does not exist." };
     }
@@ -195,12 +195,12 @@ function directoryStatus(path, allowCreatable, createRoot) {
         accessSync(path, constants.R_OK);
         readable = true;
     }
-    catch { }
+    catch { } // probe failure handled by return value
     try {
         accessSync(path, constants.W_OK);
         writable = true;
     }
-    catch { }
+    catch { } // probe failure handled by return value
     return {
         available: readable && writable,
         path,

package/dist/tools/recommendAgentForTask.d.ts

@@ -0,0 +1,19 @@
+export interface RecommendAgentForTaskInput {
+    repo_path: string;
+    goal: string;
+    scope_files?: string[];
+    template?: string;
+    risk_hint?: string;
+}
+export interface RecommendAgentForTaskOutput {
+    repo_path: string;
+    resolved_repo_path: string;
+    recommended_agent: string;
+    fallback_agent: string | null;
+    fallback: boolean;
+    reason: string;
+    risk_notes: string[];
+    suggested_verify_commands: string[];
+    bounded: true;
+}
+export declare function recommendAgentForTask(input: RecommendAgentForTaskInput): RecommendAgentForTaskOutput;

package/dist/tools/recommendAgentForTask.js

@@ -0,0 +1,56 @@
+import { getConfig } from "../config.js";
+import { guardWorkspacePath } from "../security/pathGuard.js";
+import { routeAgent } from "../agents/agentRouter.js";
+export function recommendAgentForTask(input) {
+    const config = getConfig();
+    const repoPath = String(input.repo_path || "").trim();
+    const goal = String(input.goal || "").trim();
+    if (!repoPath)
+        throw new Error("repo_path is required.");
+    if (!goal)
+        throw new Error("goal is required.");
+    const resolvedRepoPath = guardWorkspacePath(repoPath, config.workspaceRoot);
+    const configuredAgents = Object.keys(config.agents);
+    const route = routeAgent({
+        goal,
+        scope: normalizeScope(input.scope_files),
+        inline_plan: input.risk_hint,
+        template: input.template,
+        configuredAgents,
+    });
+    return {
+        repo_path: repoPath,
+        resolved_repo_path: resolvedRepoPath,
+        recommended_agent: route.recommended_agent,
+        fallback_agent: route.fallback ? route.recommended_agent : configuredAgents.find((name) => name !== route.recommended_agent) || null,
+        fallback: route.fallback,
+        reason: route.reason,
+        risk_notes: buildRiskNotes(goal, input.risk_hint),
+        suggested_verify_commands: suggestVerifyCommands(config.allowedTestCommands),
+        bounded: true,
+    };
+}
+function normalizeScope(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.map((entry) => String(entry).trim()).filter(Boolean).slice(0, 50);
+}
+function buildRiskNotes(goal, riskHint) {
+    const text = `${goal} ${riskHint || ""}`.toLowerCase();
+    const notes = [];
+    if (/release|publish|push|tag|npm/.test(text)) {
+        notes.push("release_or_remote_write_language_detected");
+    }
+    if (/secret|token|cookie|\.env|ssh/.test(text)) {
+        notes.push("sensitive_file_language_detected");
+    }
+    if (/refactor|rewrite|redesign|migration/.test(text)) {
+        notes.push("broad_change_language_detected");
+    }
+    return notes.slice(0, 8);
+}
+function suggestVerifyCommands(commands) {
+    const preferred = ["npm test", "npm run test", "npm run build", "npm run lint"];
+    const configured = new Set(commands);
+    return preferred.filter((command) => configured.has(command)).slice(0, 4);
+}

package/dist/tools/registry.d.ts

@@ -16,9 +16,9 @@ export interface ToolDef {
 export declare function getToolDefs(): ToolDef[];
 export declare function getToolCatalogSnapshot(): ToolCatalogSnapshot;
 export declare function handleToolCall(name: string, args: Record<string, unknown> | undefined): Promise<{
-    content: {
-        type: "text";
+    content: Array<{
+        type: string;
         text: string;
-    }[];
+    }>;
 }>;
 export declare function registerTools(server: Server): void;