@praneeth_54/agentdoctor 2.0.0 → 2.1.0

package/dist/mcp/intelligence/handlers.js

@@ -1,15 +1,49 @@
 import { buildC4Views } from "../../architecture/c4.js";
+import { checkArchitectureAtRoot } from "../../architecture/contract.js";
+import { analyzeChange, inspectEvidence } from "../../assurance/change.js";
+import { inspectProof } from "../../assurance/proof.js";
 import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
+import { graphStatus } from "../../intelligence/graph/incremental.js";
 import { analyzeGitIntelligence } from "../../intelligence/git/analyze.js";
 import { listKnowledge, retrieveAuthoritative } from "../../knowledge/store.js";
 import { analyzeRenameImpact, analyzeTestImpact, buildRepositoryGraph, evaluateAgentAction, } from "../../platform/index.js";
+import { redactSecrets } from "../../platform/security/redact.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 import { CONTRACTS_VERSION } from "../../contracts/index.js";
 import { assertSafeRepoTarget } from "./path-safety.js";
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function redactDeep(value) {
+    if (typeof value === "string") {
+        return redactSecrets(value).text;
+    }
+    if (Array.isArray(value)) {
+        return value.map(redactDeep);
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = redactDeep(v);
+        }
+        return out;
+    }
+    return value;
+}
+function invalidArgument(message) {
+    return { ok: false, error: { code: "invalid_argument", message } };
+}
+function pathEscape() {
+    return { ok: false, error: { code: "path_escape", message: "path escapes repository root" } };
+}
 export async function handleRepoOverview(rootInput) {
     const root = resolveRepoRoot(rootInput);
     const graph = await buildIntelligenceGraph({ root, mode: "auto" });
-    return {
+    return redactDeep({
         ok: true,
         contractsVersion: CONTRACTS_VERSION,
         root,
@@ -17,15 +51,13 @@ export async function handleRepoOverview(rootInput) {
         nodeCount: graph.nodes.length,
         edgeCount: graph.edges.length,
         limitations: graph.limitations,
-    };
+    });
 }
 export async function handleCodebaseSearch(rootInput, args) {
     const root = resolveRepoRoot(rootInput);
-    const query = String(args.query ?? "")
-        .toLowerCase()
-        .trim();
+    const query = requireString(args, "query")?.toLowerCase() ?? "";
     if (!query) {
-        return { ok: false, error: { code: "invalid_argument", message: "query required" } };
+        return invalidArgument("query required");
     }
     const graph = await buildIntelligenceGraph({ root, mode: "auto" });
     const hits = graph.nodes
@@ -33,47 +65,44 @@ export async function handleCodebaseSearch(rootInput, args) {
         n.id.toLowerCase().includes(query) ||
         (n.path ?? "").toLowerCase().includes(query))
         .slice(0, 50);
-    return {
+    return redactDeep({
         ok: true,
         query,
         hits,
         confidence: graph.builder === "typescript-ast" ? 0.85 : 0.55,
         evidenceKind: graph.builder === "typescript-ast" ? "observed" : "inferred",
         limitations: graph.limitations,
-    };
+    });
 }
 export async function handleSymbolLookup(rootInput, args) {
     const root = resolveRepoRoot(rootInput);
-    const name = String(args.name ?? "").trim();
+    const name = requireString(args, "name");
     if (!name) {
-        return { ok: false, error: { code: "invalid_argument", message: "name required" } };
+        return invalidArgument("name required");
     }
     const graph = await buildIntelligenceGraph({ root, mode: "auto" });
     const matches = graph.nodes.filter((n) => (n.kind === "function" || n.kind === "class" || n.kind === "module") &&
         (n.label === name || n.label.endsWith(`.${name}`)));
-    return {
+    return redactDeep({
         ok: true,
         name,
         matches,
         confidence: matches.length > 0 ? 0.8 : 0.2,
         limitations: ["Import/call resolution is best-effort; unsupported languages omitted."],
-    };
+    });
 }
 export async function handleDependencyLookup(rootInput, args) {
     const root = resolveRepoRoot(rootInput);
-    const target = String(args.target ?? "").trim();
+    const target = requireString(args, "target");
     if (!target) {
-        return { ok: false, error: { code: "invalid_argument", message: "target required" } };
+        return invalidArgument("target required");
     }
     let safeRelative = null;
     try {
         safeRelative = assertSafeRepoTarget(root, target);
     }
     catch {
-        return {
-            ok: false,
-            error: { code: "path_escape", message: "path escapes repository root" },
-        };
+        return pathEscape();
     }
     const graph = await buildIntelligenceGraph({ root, mode: "auto" });
     const lookupKeys = [target, safeRelative].filter((v) => Boolean(v));
@@ -81,82 +110,85 @@ export async function handleDependencyLookup(rootInput, args) {
         (n.path !== undefined && lookupKeys.includes(n.path)) ||
         lookupKeys.includes(n.label));
     if (!node) {
-        return { ok: true, target, edges: [], limitations: ["Target not found in graph"] };
+        return redactDeep({ ok: true, target, edges: [], limitations: ["Target not found in graph"] });
     }
     const edges = graph.edges.filter((e) => e.from === node.id || e.to === node.id);
-    return { ok: true, target: node, edges, confidence: 0.75 };
+    return redactDeep({ ok: true, target: node, edges, confidence: 0.75 });
 }
 export async function handleCallGraphLookup(rootInput, args) {
     const root = resolveRepoRoot(rootInput);
-    const symbol = String(args.symbol ?? "").trim();
+    const symbol = requireString(args, "symbol");
     if (!symbol) {
-        return { ok: false, error: { code: "invalid_argument", message: "symbol required" } };
+        return invalidArgument("symbol required");
     }
     const graph = await buildIntelligenceGraph({ root, mode: "auto" });
     const calls = graph.edges.filter((e) => e.kind === "calls" && (e.from.includes(symbol) || e.to.includes(symbol)));
-    return {
+    return redactDeep({
         ok: true,
         symbol,
         calls,
         confidence: graph.builder === "typescript-ast" ? 0.7 : 0.4,
         limitations: ["Call edges may be incomplete for dynamic/dispatch patterns."],
-    };
+    });
 }
 export async function handleTestImpactTool(rootInput) {
     const root = resolveRepoRoot(rootInput);
     const impact = await analyzeTestImpact(root);
-    return {
+    return redactDeep({
         ok: true,
         impact,
         resultKind: impact.gitAvailable ? "graph-inferred" : "unknown",
         limitations: ["Coverage-backed mapping requires external coverage data (not bundled)."],
-    };
+    });
 }
 export async function handleRefactorImpactTool(rootInput, args) {
     const root = resolveRepoRoot(rootInput);
-    const symbol = String(args.symbol ?? "").trim();
+    const symbol = requireString(args, "symbol");
     if (!symbol) {
-        return { ok: false, error: { code: "invalid_argument", message: "symbol required" } };
+        return invalidArgument("symbol required");
     }
     const graph = await buildRepositoryGraph(root);
     const impact = await analyzeRenameImpact({ root, symbol, graph });
-    return { ok: true, impact };
+    return redactDeep({ ok: true, impact });
 }
 export async function handleCodeHealthTool(rootInput) {
     const root = resolveRepoRoot(rootInput);
     const report = await analyzeGitIntelligence(root);
-    return {
+    return redactDeep({
         ok: true,
         report,
         methodDisclosure: report.hotspots[0]?.method ?? "see per-metric method fields",
         limitations: report.limitations,
-    };
+    });
 }
 export async function handleArchitectureTool(rootInput) {
     const root = resolveRepoRoot(rootInput);
     const graph = await buildIntelligenceGraph({ root, mode: "auto" });
     const views = buildC4Views(graph);
-    return {
+    return redactDeep({
         ok: true,
         views,
         label: "Inferred/proposed from graph evidence — not approved architecture facts",
-    };
+    });
 }
 export async function handleKnowledgeTool(rootInput, args) {
     const root = resolveRepoRoot(rootInput);
     const list = await listKnowledge(root);
-    const query = String(args.query ?? "").trim();
+    const query = typeof args.query === "string" ? args.query.trim() : "";
     if (!query) {
-        return { ok: true, records: list.filter((r) => r.status === "approved").slice(0, 50) };
+        return redactDeep({
+            ok: true,
+            records: list.filter((r) => r.status === "approved").slice(0, 50),
+        });
     }
     const result = retrieveAuthoritative(list, query);
-    return { ok: true, ...result };
+    return redactDeep({ ok: true, ...result });
 }
 export async function handlePolicyEvalTool(rootInput, args) {
     const root = resolveRepoRoot(rootInput);
-    const command = String(args.command ?? "").trim();
+    const command = requireString(args, "command");
     if (!command) {
-        return { ok: false, error: { code: "invalid_argument", message: "command required" } };
+        return invalidArgument("command required");
     }
     const verdict = await evaluateAgentAction(root, {
         actionId: `mcp_${Date.now()}`,
@@ -166,10 +198,167 @@ export async function handlePolicyEvalTool(rootInput, args) {
         params: { command },
         repositoryRoot: root,
     });
-    return {
+    return redactDeep({
         ok: true,
         verdict,
         executionResult: "not-executed",
         notice: "Evaluate-only: AgentDoctor MCP does not execute shell commands.",
-    };
+    });
+}
+export async function handleChangeAnalyzeTool(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const since = typeof args.since === "string" && args.since.trim() ? args.since.trim() : undefined;
+    const changeId = typeof args.changeId === "string" && args.changeId.trim() ? args.changeId.trim() : undefined;
+    if (args.coveragePath !== undefined) {
+        if (typeof args.coveragePath !== "string" || !args.coveragePath.trim()) {
+            return invalidArgument("coveragePath must be a non-empty string when provided");
+        }
+        try {
+            assertSafeRepoTarget(root, args.coveragePath);
+        }
+        catch {
+            return pathEscape();
+        }
+    }
+    const assessment = await analyzeChange({
+        root,
+        ...(since ? { since } : {}),
+        ...(changeId ? { changeId } : {}),
+        ...(typeof args.coveragePath === "string" ? { coveragePath: args.coveragePath } : {}),
+    });
+    return redactDeep({
+        ok: true,
+        assessment,
+        limitations: assessment.limitations,
+    });
+}
+export async function handleArchitectureCheckTool(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const graph = await buildRepositoryGraph(root);
+    const result = await checkArchitectureAtRoot(root, graph);
+    return redactDeep({
+        ok: true,
+        result,
+        violationCount: result.violations.length,
+    });
+}
+export async function handleProofInspectTool(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const id = requireString(args, "id");
+    if (!id) {
+        return invalidArgument("id required");
+    }
+    if (id.includes("/") || id.includes("\\") || id.includes("..")) {
+        try {
+            assertSafeRepoTarget(root, id);
+        }
+        catch {
+            return pathEscape();
+        }
+    }
+    const inspected = await inspectProof(root, id);
+    if (!inspected.ok) {
+        return {
+            ok: false,
+            error: { code: "not_found", message: inspected.error ?? "proof not found" },
+        };
+    }
+    return redactDeep({
+        ok: true,
+        proof: inspected.proof,
+        path: inspected.path,
+        notice: "Integrity/inspect only — engineering correctness is not claimed",
+    });
+}
+export async function handleEvidenceInspectTool(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const changeId = requireString(args, "changeId");
+    if (!changeId) {
+        return invalidArgument("changeId required");
+    }
+    if (changeId.includes("/") || changeId.includes("\\") || changeId.includes("..")) {
+        try {
+            assertSafeRepoTarget(root, changeId);
+        }
+        catch {
+            return pathEscape();
+        }
+    }
+    const inspected = await inspectEvidence({ root, changeId });
+    if (!inspected.ok) {
+        return {
+            ok: false,
+            error: { code: "not_found", message: inspected.error ?? "evidence not found" },
+        };
+    }
+    return redactDeep({
+        ok: true,
+        directory: inspected.directory,
+        manifest: inspected.manifest,
+        presentFiles: inspected.presentFiles,
+    });
+}
+export async function handleGraphQueryTool(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const query = requireString(args, "query");
+    if (!query) {
+        return invalidArgument("query required");
+    }
+    const kindFilter = typeof args.kind === "string" && args.kind.trim() ? args.kind.trim().toLowerCase() : null;
+    const limitRaw = args.limit;
+    const limit = typeof limitRaw === "number" && Number.isFinite(limitRaw)
+        ? Math.max(1, Math.min(100, Math.floor(limitRaw)))
+        : 25;
+    if (args.path !== undefined) {
+        if (typeof args.path !== "string" || !args.path.trim()) {
+            return invalidArgument("path must be a non-empty string when provided");
+        }
+        try {
+            assertSafeRepoTarget(root, args.path);
+        }
+        catch {
+            return pathEscape();
+        }
+    }
+    const graph = await buildIntelligenceGraph({ root, mode: "auto" });
+    const status = await graphStatus({ root });
+    const q = query.toLowerCase();
+    const pathFilter = typeof args.path === "string" ? args.path.trim().toLowerCase().replace(/\\/g, "/") : null;
+    const nodes = graph.nodes
+        .filter((n) => {
+        if (kindFilter && n.kind.toLowerCase() !== kindFilter)
+            return false;
+        if (pathFilter && !(n.path ?? "").toLowerCase().includes(pathFilter))
+            return false;
+        return (n.id.toLowerCase().includes(q) ||
+            n.label.toLowerCase().includes(q) ||
+            (n.path ?? "").toLowerCase().includes(q));
+    })
+        .slice(0, limit);
+    const nodeIds = new Set(nodes.map((n) => n.id));
+    const edges = graph.edges
+        .filter((e) => nodeIds.has(e.from) ||
+        nodeIds.has(e.to) ||
+        e.from.toLowerCase().includes(q) ||
+        e.to.toLowerCase().includes(q) ||
+        e.kind.toLowerCase().includes(q))
+        .slice(0, limit);
+    return redactDeep({
+        ok: true,
+        query,
+        kind: kindFilter,
+        path: pathFilter,
+        nodes,
+        edges,
+        index: {
+            present: status.present,
+            nodeCount: status.nodeCount,
+            edgeCount: status.edgeCount,
+            corrupt: status.corrupt ?? false,
+        },
+        limitations: [
+            "Query is substring match over in-memory / rebuilt graph — not a production graph DB",
+            ...graph.limitations,
+        ],
+    });
 }

package/dist/mcp/intelligence/path-safety.d.ts

@@ -1,7 +1,5 @@
-/**
- * Decode a single layer of URI encoding. Rejects malformed sequences by returning null.
- */
-export declare function tryDecodeUriComponent(value: string): string | null;
+import { tryDecodeUriComponent } from "../../security/paths.js";
+export { tryDecodeUriComponent };
 /**
  * Validate a user-supplied repository-relative or in-repo target.
  * Returns a normalized path relative to root (POSIX) when the target is path-like and safe,

package/dist/mcp/intelligence/path-safety.js

@@ -1,16 +1,7 @@
 import path from "node:path";
-import { isPathInsideRoot, sanitizeForOutput } from "../../utils/path.js";
-/**
- * Decode a single layer of URI encoding. Rejects malformed sequences by returning null.
- */
-export function tryDecodeUriComponent(value) {
-    try {
-        return decodeURIComponent(value);
-    }
-    catch {
-        return null;
-    }
-}
+import { PathEscapeError, rejectHostilePathInput, resolveSafeRepoPath, tryDecodeUriComponent, } from "../../security/paths.js";
+import { sanitizeForOutput } from "../../utils/path.js";
+export { tryDecodeUriComponent };
 /**
  * Validate a user-supplied repository-relative or in-repo target.
  * Returns a normalized path relative to root (POSIX) when the target is path-like and safe,
@@ -33,10 +24,8 @@ export function assertSafeRepoTarget(root, rawTarget) {
         throw new Error("invalid target");
     }
     const candidates = decoded === cleaned ? [cleaned] : [cleaned, decoded];
+    let pathLike = false;
     for (const candidate of candidates) {
-        if (candidate.includes("\0")) {
-            throw new Error("invalid target");
-        }
         const looksLikePath = path.isAbsolute(candidate) ||
             candidate.includes("..") ||
             candidate.includes("/") ||
@@ -45,38 +34,30 @@ export function assertSafeRepoTarget(root, rawTarget) {
         if (!looksLikePath) {
             continue;
         }
-        // Reject any .. segment forms before resolve (prevents src/x/../../etc tricks).
-        const normalizedSlashes = candidate.replace(/\\/g, "/");
-        if (normalizedSlashes === ".." ||
-            normalizedSlashes.includes("/../") ||
-            normalizedSlashes.startsWith("../") ||
-            normalizedSlashes.endsWith("/..") ||
-            normalizedSlashes.includes("/..") ||
-            /(^|\/)\.\.($|\/)/.test(normalizedSlashes)) {
-            throw new Error("path escapes repository root");
+        pathLike = true;
+        try {
+            rejectHostilePathInput(candidate);
+            resolveSafeRepoPath(root, candidate);
         }
-        // Always reject Windows drive-absolute forms (even on POSIX hosts).
-        if (/^[A-Za-z]:[\\/]/.test(candidate)) {
-            throw new Error("path escapes repository root");
-        }
-        // Resolve relative to root; absolute candidates resolve to themselves.
-        const resolved = path.isAbsolute(candidate)
-            ? path.resolve(candidate)
-            : path.resolve(root, candidate);
-        if (!isPathInsideRoot(root, resolved)) {
-            throw new Error("path escapes repository root");
+        catch (error) {
+            if (error instanceof PathEscapeError) {
+                throw new Error(error.message);
+            }
+            throw new Error("invalid target");
         }
     }
-    // Prefer decoded form for relative path returns when path-like.
-    const primary = candidates[candidates.length - 1];
-    const looksLikePath = path.isAbsolute(primary) ||
-        primary.includes("..") ||
-        primary.includes("/") ||
-        primary.includes("\\") ||
-        /^[A-Za-z]:[\\/]/.test(primary);
-    if (!looksLikePath) {
+    if (!pathLike) {
         return null;
     }
-    const resolved = path.isAbsolute(primary) ? path.resolve(primary) : path.resolve(root, primary);
-    return path.relative(root, resolved).split(path.sep).join("/");
+    const primary = candidates[candidates.length - 1];
+    try {
+        const abs = resolveSafeRepoPath(root, primary);
+        return path.relative(root, abs).split(path.sep).join("/");
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            throw new Error(error.message);
+        }
+        throw new Error("invalid target");
+    }
 }

package/dist/mcp/intelligence/registry.d.ts

@@ -1,5 +1,5 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-export declare const INTELLIGENCE_MCP_TOOL_NAMES: readonly ["repo_overview", "codebase_search", "symbol_lookup", "dependency_lookup", "call_graph_lookup", "test_impact", "refactor_impact", "code_health", "architecture_info", "knowledge_retrieve", "policy_evaluate"];
+export declare const INTELLIGENCE_MCP_TOOL_NAMES: readonly ["repo_overview", "codebase_search", "symbol_lookup", "dependency_lookup", "call_graph_lookup", "test_impact", "refactor_impact", "code_health", "architecture_info", "architecture_check", "knowledge_retrieve", "policy_evaluate", "change_analyze", "proof_inspect", "evidence_inspect", "graph_query"];
 export type IntelligenceMcpToolName = (typeof INTELLIGENCE_MCP_TOOL_NAMES)[number];
 export declare function listIntelligenceMcpTools(): Tool[];
 export declare function invokeIntelligenceMcpTool(root: string, name: string, args: Record<string, unknown>): Promise<{

package/dist/mcp/intelligence/registry.js

@@ -1,4 +1,4 @@
-import { handleArchitectureTool, handleCallGraphLookup, handleCodeHealthTool, handleCodebaseSearch, handleDependencyLookup, handleKnowledgeTool, handlePolicyEvalTool, handleRefactorImpactTool, handleRepoOverview, handleSymbolLookup, handleTestImpactTool, } from "./handlers.js";
+import { handleArchitectureCheckTool, handleArchitectureTool, handleCallGraphLookup, handleChangeAnalyzeTool, handleCodeHealthTool, handleCodebaseSearch, handleDependencyLookup, handleEvidenceInspectTool, handleGraphQueryTool, handleKnowledgeTool, handlePolicyEvalTool, handleProofInspectTool, handleRefactorImpactTool, handleRepoOverview, handleSymbolLookup, handleTestImpactTool, } from "./handlers.js";
 export const INTELLIGENCE_MCP_TOOL_NAMES = [
     "repo_overview",
     "codebase_search",
@@ -9,8 +9,13 @@ export const INTELLIGENCE_MCP_TOOL_NAMES = [
     "refactor_impact",
     "code_health",
     "architecture_info",
+    "architecture_check",
     "knowledge_retrieve",
     "policy_evaluate",
+    "change_analyze",
+    "proof_inspect",
+    "evidence_inspect",
+    "graph_query",
 ];
 const emptyObjectSchema = {
     type: "object",
@@ -89,6 +94,11 @@ export function listIntelligenceMcpTools() {
             description: "READ: C4-style views inferred from graph evidence (labeled proposed/inferred).",
             inputSchema: emptyObjectSchema,
         },
+        {
+            name: "architecture_check",
+            description: "READ: Check import edges against .agentdoctor/architecture.json|.yml contract (repo-local).",
+            inputSchema: emptyObjectSchema,
+        },
         {
             name: "knowledge_retrieve",
             description: "READ: Governed knowledge retrieval. Abstains when no approved authoritative record matches.",
@@ -108,6 +118,54 @@ export function listIntelligenceMcpTools() {
                 additionalProperties: false,
             },
         },
+        {
+            name: "change_analyze",
+            description: "READ: Change assurance assessment (evidence/heuristics). Never claims verified engineering correctness.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    since: { type: "string" },
+                    changeId: { type: "string" },
+                    coveragePath: { type: "string", description: "Repo-relative coverage file path" },
+                },
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "proof_inspect",
+            description: "READ: Inspect ChangeProof by proofId or changeId (hash integrity metadata only).",
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string" } },
+                required: ["id"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "evidence_inspect",
+            description: "READ: Inspect change evidence bundle artifacts for a changeId.",
+            inputSchema: {
+                type: "object",
+                properties: { changeId: { type: "string" } },
+                required: ["changeId"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "graph_query",
+            description: "READ: Substring query over intelligence graph nodes/edges. Optional kind/path filters; path validated.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string" },
+                    kind: { type: "string" },
+                    path: { type: "string" },
+                    limit: { type: "number" },
+                },
+                required: ["query"],
+                additionalProperties: false,
+            },
+        },
     ];
 }
 export async function invokeIntelligenceMcpTool(root, name, args) {
@@ -131,10 +189,20 @@ export async function invokeIntelligenceMcpTool(root, name, args) {
                 return { structured: await handleCodeHealthTool(root), isError: false };
             case "architecture_info":
                 return { structured: await handleArchitectureTool(root), isError: false };
+            case "architecture_check":
+                return { structured: await handleArchitectureCheckTool(root), isError: false };
             case "knowledge_retrieve":
                 return { structured: await handleKnowledgeTool(root, args), isError: false };
             case "policy_evaluate":
                 return { structured: await handlePolicyEvalTool(root, args), isError: false };
+            case "change_analyze":
+                return { structured: await handleChangeAnalyzeTool(root, args), isError: false };
+            case "proof_inspect":
+                return { structured: await handleProofInspectTool(root, args), isError: false };
+            case "evidence_inspect":
+                return { structured: await handleEvidenceInspectTool(root, args), isError: false };
+            case "graph_query":
+                return { structured: await handleGraphQueryTool(root, args), isError: false };
             default:
                 return {
                     structured: {

package/dist/platform/firewall/evaluate.d.ts

@@ -26,8 +26,9 @@ export interface FirewallPolicyDocument {
 }
 export interface PolicyLoadResult {
     policy: FirewallPolicyDocument;
-    source: "file" | "default" | "fail-closed-deny";
+    source: "file" | "default" | "fail-closed-deny" | "composed";
     validationError?: string;
+    composeSources?: Array<"builtin" | "repo">;
 }
 declare const EVALUATE_ONLY = "Evaluate-only: no commands are executed and no agents are intercepted.";
 declare const DEFAULT_POLICY: FirewallPolicyDocument;
@@ -38,8 +39,10 @@ export declare function validateFirewallPolicy(raw: unknown): {
 };
 /**
  * Load local action-policy document.
- * Invalid file + failClosed (file flag or option) → deny-all.
- * Invalid file + default → documented fallback DEFAULT_POLICY.
+ * Layers: composed builtin pack + `.agentdoctor/policy.json` (fail-closed on malformed repo policy),
+ * then optional platform `firewall-policy.json` overlay (highest precedence when valid).
+ * Invalid platform file + failClosed → deny-all.
+ * Invalid platform file + default → composed policy (or DEFAULT_POLICY when compose unavailable).
  */
 export declare function loadFirewallPolicy(root: string, options?: {
     failClosed?: boolean;