@phamvuhoang/otto-core 0.22.0 → 0.24.0

package/dist/tools-cli.d.ts

@@ -0,0 +1,55 @@
+import { type SafetyPolicy } from "./safety-policy.js";
+import { type ToolConfig, type ToolDefinition, type ToolSelection } from "./tools.js";
+/**
+ * Injectable host surface for {@link runTools} so the bin stays unit-testable
+ * without touching real cwd/env/stdio or spawning processes (mirrors
+ * `SkillsDeps`). `health` is injected so tests don't shell out.
+ */
+export type ToolsDeps = {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    out: (msg: string) => void;
+    err: (msg: string) => void;
+    /** Run a tool's health-check command; resolves to its availability. */
+    health: (tool: ToolDefinition) => Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+};
+/** Render the tool registry inventory. Pure. */
+export declare function formatToolsList(tools: ToolDefinition[], config: ToolConfig): string;
+/** One governance problem with the tool registry. */
+export type ToolAuditFinding = {
+    kind: "unreachable" | "no-health-check" | "policy-conflict";
+    subject: string;
+    detail: string;
+};
+/**
+ * Audit the registry against config + safety policy. Flags tools that are
+ * enabled but reachable from no stage (`unreachable`), command/mcp/proxy/http
+ * tools with no way to verify availability (`no-health-check`), and tools whose
+ * declared scope a non-empty repo policy already forbids (`policy-conflict`),
+ * e.g. a network domain outside `allowedNetworkDomains`. Pure over its inputs.
+ */
+export declare function auditTools(tools: ToolDefinition[], config: ToolConfig): ToolAuditFinding[];
+/**
+ * Audit each tool's declared scope against a non-empty repo policy: a tool that
+ * declares a network domain or write root the policy forbids is a standing
+ * `policy-conflict` (the authorization layer would block every such invocation).
+ * Separated from {@link auditTools} so it can take the workspace policy. Pure.
+ */
+export declare function auditToolPolicyConflicts(tools: ToolDefinition[], policy: SafetyPolicy): ToolAuditFinding[];
+/** Render audit findings. Pure. */
+export declare function formatToolsAudit(findings: ToolAuditFinding[]): string;
+/** Render which tools are available for a stage and why. Pure. */
+export declare function formatToolsWhy(stage: string, selections: ToolSelection[]): string;
+/**
+ * Drive the read-only `otto-tools` operator command over `.otto/tools/`.
+ * Subcommands: `list` (default) inventories the registry + config state;
+ * `audit` flags governance problems (unreachable, missing health check, policy
+ * conflict); `why <stage>` shows which tools a stage may use and why; `health`
+ * runs each tool's health-check. Read-only — it never invokes a tool's actual
+ * adapter, only its health probe. Resolves to the process exit code.
+ */
+export declare function runTools(argv: string[], deps?: ToolsDeps): Promise<number>;
+//# sourceMappingURL=tools-cli.d.ts.map

package/dist/tools-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-cli.d.ts","sourceRoot":"","sources":["../src/tools-cli.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAML,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,uEAAuE;IACvE,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5E,CAAC;AA2CF,gDAAgD;AAChD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,EAAE,UAAU,GACjB,MAAM,CAiBR;AAED,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,aAAa,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,EAAE,UAAU,GACjB,gBAAgB,EAAE,CAwBpB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,EAAE,YAAY,GACnB,gBAAgB,EAAE,CAyBpB;AAED,mCAAmC;AACnC,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAKrE;AAED,kEAAkE;AAClE,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,aAAa,EAAE,GAC1B,MAAM,CASR;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,SAAuB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAyDjB"}

package/dist/tools-cli.js

@@ -0,0 +1,196 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { readSafetyPolicy } from "./safety-policy.js";
+import { authorizeToolInvocation, readToolConfig, readTools, selectToolsForStage, toolsDir, } from "./tools.js";
+/** Default health probe: run `healthCheck` in a shell, ok = exit 0. */
+function defaultHealth(tool) {
+    if (!tool.healthCheck) {
+        return Promise.resolve({ ok: false, detail: "no health check defined" });
+    }
+    const r = spawnSync(tool.healthCheck, {
+        shell: true,
+        timeout: tool.timeoutMs ?? 10_000,
+        encoding: "utf8",
+    });
+    if (r.status === 0)
+        return Promise.resolve({ ok: true, detail: "ok" });
+    const why = r.error?.message ??
+        (r.status === null ? "timed out / killed" : `exit ${r.status}`);
+    return Promise.resolve({ ok: false, detail: why });
+}
+const defaultDeps = {
+    env: process.env,
+    cwd: process.cwd(),
+    out: (m) => process.stdout.write(`${m}\n`),
+    err: (m) => process.stderr.write(`${m}\n`),
+    health: defaultHealth,
+};
+const USAGE = "Usage: otto-tools <list|audit|health>\n" + "       otto-tools why <stage>";
+function scopeLabel(tool) {
+    const parts = [];
+    if (tool.networkDomains.length)
+        parts.push(`net: ${tool.networkDomains.join(", ")}`);
+    if (tool.writeRoots.length)
+        parts.push(`write: ${tool.writeRoots.join(", ")}`);
+    if (tool.secretRefs.length)
+        parts.push(`secrets: ${tool.secretRefs.join(", ")}`);
+    return parts.length ? parts.join("  ") : "(no command/network/write scope)";
+}
+/** Render the tool registry inventory. Pure. */
+export function formatToolsList(tools, config) {
+    if (tools.length === 0) {
+        return "No tools. A tool is a .otto/tools/<name>.json adapter definition. Existing runs are unaffected.";
+    }
+    const lines = [];
+    for (const t of tools) {
+        const ov = config.overrides[t.name];
+        const enabled = ov?.enabled ?? t.enabled;
+        const stages = ov?.stages ?? t.stages;
+        lines.push(`- ${t.name}  [${t.kind}]  ${enabled ? "enabled" : "disabled"}  stages: ${stages.length ? stages.join(", ") : "(none)"}`);
+        if (t.capabilities.length)
+            lines.push(`    capabilities: ${t.capabilities.join(", ")}`);
+        lines.push(`    scope:        ${scopeLabel(t)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Audit the registry against config + safety policy. Flags tools that are
+ * enabled but reachable from no stage (`unreachable`), command/mcp/proxy/http
+ * tools with no way to verify availability (`no-health-check`), and tools whose
+ * declared scope a non-empty repo policy already forbids (`policy-conflict`),
+ * e.g. a network domain outside `allowedNetworkDomains`. Pure over its inputs.
+ */
+export function auditTools(tools, config) {
+    const findings = [];
+    for (const t of tools) {
+        const ov = config.overrides[t.name];
+        const enabled = ov?.enabled ?? t.enabled;
+        const stages = ov?.stages ?? t.stages;
+        if (enabled && stages.length === 0) {
+            findings.push({
+                kind: "unreachable",
+                subject: t.name,
+                detail: `tool "${t.name}" is enabled but has no stage allowlist — it can never be selected`,
+            });
+        }
+        if (!t.healthCheck && t.kind !== "sdk") {
+            findings.push({
+                kind: "no-health-check",
+                subject: t.name,
+                detail: `tool "${t.name}" (${t.kind}) has no healthCheck — availability cannot be verified`,
+            });
+        }
+    }
+    return findings.sort((a, b) => a.kind.localeCompare(b.kind) || a.subject.localeCompare(b.subject));
+}
+/**
+ * Audit each tool's declared scope against a non-empty repo policy: a tool that
+ * declares a network domain or write root the policy forbids is a standing
+ * `policy-conflict` (the authorization layer would block every such invocation).
+ * Separated from {@link auditTools} so it can take the workspace policy. Pure.
+ */
+export function auditToolPolicyConflicts(tools, policy) {
+    const findings = [];
+    for (const t of tools) {
+        for (const domain of t.networkDomains) {
+            const a = authorizeToolInvocation(policy, t, { domains: [domain] });
+            if (a.violations.some((v) => v.kind === "network-domain")) {
+                findings.push({
+                    kind: "policy-conflict",
+                    subject: t.name,
+                    detail: `tool "${t.name}" declares domain "${domain}" the repo policy forbids`,
+                });
+            }
+        }
+        for (const root of t.writeRoots) {
+            const a = authorizeToolInvocation(policy, t, { writePaths: [root] });
+            if (a.violations.some((v) => v.kind === "write-root")) {
+                findings.push({
+                    kind: "policy-conflict",
+                    subject: t.name,
+                    detail: `tool "${t.name}" declares write root "${root}" the repo policy forbids`,
+                });
+            }
+        }
+    }
+    return findings.sort((a, b) => a.subject.localeCompare(b.subject));
+}
+/** Render audit findings. Pure. */
+export function formatToolsAudit(findings) {
+    if (findings.length === 0)
+        return "Tool registry clean (no findings).";
+    const lines = [`Tool registry findings (${findings.length}):`];
+    for (const f of findings)
+        lines.push(`  - [${f.kind}] ${f.detail}`);
+    return lines.join("\n");
+}
+/** Render which tools are available for a stage and why. Pure. */
+export function formatToolsWhy(stage, selections) {
+    if (selections.length === 0)
+        return "No tools registered.";
+    const lines = [`Tools for stage "${stage}":`];
+    for (const s of selections) {
+        lines.push(`- ${s.name}  [${s.enabled ? "available" : "skip"}]  ${s.reason}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Drive the read-only `otto-tools` operator command over `.otto/tools/`.
+ * Subcommands: `list` (default) inventories the registry + config state;
+ * `audit` flags governance problems (unreachable, missing health check, policy
+ * conflict); `why <stage>` shows which tools a stage may use and why; `health`
+ * runs each tool's health-check. Read-only — it never invokes a tool's actual
+ * adapter, only its health probe. Resolves to the process exit code.
+ */
+export async function runTools(argv, deps = defaultDeps) {
+    const arg = argv[0];
+    if (arg === "-h" || arg === "--help") {
+        deps.out(USAGE);
+        return 0;
+    }
+    const known = ["list", "audit", "why", "health"];
+    if (arg !== undefined && !known.includes(arg)) {
+        deps.err(`Unknown subcommand '${arg}'.\n${USAGE}`);
+        return 1;
+    }
+    const workspaceDir = resolve(deps.env.OTTO_WORKSPACE ?? deps.cwd);
+    const tools = readTools(workspaceDir);
+    const config = readToolConfig(workspaceDir);
+    if (arg === "why") {
+        const stage = argv[1];
+        if (!stage) {
+            deps.err(`why needs a stage name.\n${USAGE}`);
+            return 1;
+        }
+        deps.out(formatToolsWhy(stage, selectToolsForStage(tools, config, stage)));
+        return 0;
+    }
+    if (arg === "audit") {
+        const policy = readSafetyPolicy(workspaceDir);
+        const findings = [
+            ...auditTools(tools, config),
+            ...auditToolPolicyConflicts(tools, policy),
+        ].sort((a, b) => a.kind.localeCompare(b.kind) || a.subject.localeCompare(b.subject));
+        deps.out(formatToolsAudit(findings));
+        return findings.length === 0 ? 0 : 1;
+    }
+    if (arg === "health") {
+        if (tools.length === 0) {
+            deps.out("No tools to health-check.");
+            return 0;
+        }
+        let allOk = true;
+        deps.out(`Tool health (${toolsDir(workspaceDir)})`);
+        for (const t of tools) {
+            const { ok, detail } = await deps.health(t);
+            if (!ok)
+                allOk = false;
+            deps.out(`  ${ok ? "ok  " : "FAIL"} ${t.name}  ${detail}`);
+        }
+        return allOk ? 0 : 1;
+    }
+    deps.out(`Tools (${toolsDir(workspaceDir)})`);
+    deps.out(formatToolsList(tools, config));
+    return 0;
+}
+//# sourceMappingURL=tools-cli.js.map

package/dist/tools-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-cli.js","sourceRoot":"","sources":["../src/tools-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAqB,MAAM,oBAAoB,CAAC;AACzE,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,SAAS,EACT,mBAAmB,EACnB,QAAQ,GAIT,MAAM,YAAY,CAAC;AAgBpB,uEAAuE;AACvE,SAAS,aAAa,CACpB,IAAoB;IAEpB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE;QACpC,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,IAAI,CAAC,SAAS,IAAI,MAAM;QACjC,QAAQ,EAAE,MAAM;KACjB,CAAC,CAAC;IACH,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,MAAM,GAAG,GACP,CAAC,CAAC,KAAK,EAAE,OAAO;QAChB,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAClE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,WAAW,GAAc;IAC7B,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;IAC1C,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;IAC1C,MAAM,EAAE,aAAa;CACtB,CAAC;AAEF,MAAM,KAAK,GACT,yCAAyC,GAAG,+BAA+B,CAAC;AAE9E,SAAS,UAAU,CAAC,IAAoB;IACtC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM;QAC5B,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvD,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM;QACxB,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM;QACxB,KAAK,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,kCAAkC,CAAC;AAC9E,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,eAAe,CAC7B,KAAuB,EACvB,MAAkB;IAElB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,iGAAiG,CAAC;IAC3G,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,EAAE,EAAE,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC;QACzC,MAAM,MAAM,GAAG,EAAE,EAAE,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC;QACtC,KAAK,CAAC,IAAI,CACR,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,aAAa,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CACzH,CAAC;QACF,IAAI,CAAC,CAAC,YAAY,CAAC,MAAM;YACvB,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/D,KAAK,CAAC,IAAI,CAAC,qBAAqB,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,KAAuB,EACvB,MAAkB;IAElB,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,EAAE,EAAE,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC;QACzC,MAAM,MAAM,GAAG,EAAE,EAAE,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC;QACtC,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,CAAC,CAAC,IAAI;gBACf,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,oEAAoE;aAC5F,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YACvC,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,iBAAiB;gBACvB,OAAO,EAAE,CAAC,CAAC,IAAI;gBACf,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,wDAAwD;aAC5F,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAClB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAC7E,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAuB,EACvB,MAAoB;IAEpB,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,KAAK,MAAM,MAAM,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,uBAAuB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACpE,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,gBAAgB,CAAC,EAAE,CAAC;gBAC1D,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,iBAAiB;oBACvB,OAAO,EAAE,CAAC,CAAC,IAAI;oBACf,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,sBAAsB,MAAM,2BAA2B;iBAC/E,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,uBAAuB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrE,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;gBACtD,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,iBAAiB;oBACvB,OAAO,EAAE,CAAC,CAAC,IAAI;oBACf,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,0BAA0B,IAAI,2BAA2B;iBACjF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,gBAAgB,CAAC,QAA4B;IAC3D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,oCAAoC,CAAC;IACvE,MAAM,KAAK,GAAa,CAAC,2BAA2B,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAC;IACzE,KAAK,MAAM,CAAC,IAAI,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACpE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,cAAc,CAC5B,KAAa,EACb,UAA2B;IAE3B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,sBAAsB,CAAC;IAC3D,MAAM,KAAK,GAAa,CAAC,oBAAoB,KAAK,IAAI,CAAC,CAAC;IACxD,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CACR,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,MAAM,EAAE,CAClE,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAc,EACd,OAAkB,WAAW;IAE7B,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACjD,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,IAAI,CAAC,GAAG,CAAC,uBAAuB,GAAG,OAAO,KAAK,EAAE,CAAC,CAAC;QACnD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IAE5C,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,GAAG,CAAC,4BAA4B,KAAK,EAAE,CAAC,CAAC;YAC9C,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3E,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAAC;QAC9C,MAAM,QAAQ,GAAG;YACf,GAAG,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC;YAC5B,GAAG,wBAAwB,CAAC,KAAK,EAAE,MAAM,CAAC;SAC3C,CAAC,IAAI,CACJ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CACrE,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrC,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;QACrB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;YACtC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACpD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC5C,IAAI,CAAC,EAAE;gBAAE,KAAK,GAAG,KAAK,CAAC;YACvB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,UAAU,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,164 @@
+import { type PolicyViolation, type SafetyPolicy } from "./safety-policy.js";
+import type { SafetyEvent } from "./run-report.js";
+/**
+ * External tool authority layer (issue #111 P19). Otto exposes external tools —
+ * local services, MCP servers, HTTP/proxy adapters, SDK shims — to stages only
+ * through a typed, repo-local registry under `.otto/tools/<name>.json`, governed
+ * by `.otto/policy.json`. A tool is a *declared capability with scope*: which
+ * stages may use it, which commands/domains/write-roots/secrets it touches, and
+ * how to health-check it. Authority is the INTERSECTION of the tool's declared
+ * scope and the repo safety policy — a tool can only narrow, never widen, what a
+ * run may do.
+ *
+ * Pure fs + JSON with safe defaults (absent/malformed → no tools, never throws),
+ * mirroring `skills.ts`/`safety-policy.ts`. **Substrate, inert on the loop**: the
+ * registry, contract, authorization predicate, and `ToolUsage` evidence type
+ * exist and are exercised by the read-only `otto-tools` bin, but no stage invokes
+ * a tool this slice — the first consumer is the P20 Headroom adapter. A workspace
+ * with no `.otto/tools/` behaves exactly as today.
+ *
+ * **AFK invariant:** authority comes ONLY from this repo-local registry. Personal
+ * MCP/plugin config (Claude/Codex user config) is never inherited into a run —
+ * it is not reproducible and not repo-governed.
+ */
+/** Transport kind an adapter speaks. */
+export type ToolKind = "command" | "mcp" | "http" | "proxy" | "sdk";
+/**
+ * One tool's adapter contract, stored as `.otto/tools/<name>.json`. Every scope
+ * field defaults to the most restrictive sensible value: `stages: []` means "no
+ * stage" (a tool must opt INTO stages), while the network/write/secret lists
+ * empty mean "touches none of that axis".
+ */
+export type ToolDefinition = {
+    /** Filesystem-safe registry key; also the `<name>.json` basename. */
+    name: string;
+    kind: ToolKind;
+    description?: string;
+    /** Capability tags (a selection/`why` key). */
+    capabilities: string[];
+    /** Stage names this tool may run in; empty = none (opt-in required). */
+    stages: string[];
+    /** command/proxy: the executable + args template. */
+    command?: string;
+    /** Env var NAMES the adapter reads (values come from the host env, never inlined). */
+    env: string[];
+    /** Network domains the tool may reach — checked against policy + this list. */
+    networkDomains: string[];
+    /** Workspace-relative roots the tool may write — checked against policy + this list. */
+    writeRoots: string[];
+    /** Secret env-var names the tool needs; surfaced for audit, never inlined. */
+    secretRefs: string[];
+    /** Per-invocation timeout (ms); absent = adapter default. */
+    timeoutMs?: number;
+    /** Shell command that exits 0 when the tool is available/healthy. */
+    healthCheck?: string;
+    /** High-risk action names that require approval (joined with policy). */
+    approvalActions: string[];
+    /** Registry-level enable flag; config can additionally disable per stage. */
+    enabled: boolean;
+};
+/**
+ * The structured result an adapter returns (issue #111 output contract). Beyond
+ * the payload it carries the levers Otto's evidence model needs: estimated token
+ * savings (for compressors like Headroom), any safety events the invocation
+ * raised, and a durable retrieval handle when the output is a reversible
+ * transform of original content.
+ */
+export type ToolResult = {
+    ok: boolean;
+    output?: unknown;
+    /** Estimated tokens saved (compression adapters); absent = not applicable. */
+    tokensSaved?: number;
+    safetyEvents?: SafetyEvent[];
+    /** Durable handle to retrieve the original/reversible content; absent = none. */
+    retrievalHandle?: string;
+};
+/** Per-tool override read from `.otto/config.json`'s `tools` block. */
+export type ToolOverride = {
+    enabled?: boolean;
+    stages?: string[];
+};
+/** The `tools` block of `.otto/config.json`: per-tool enable/stage overrides. */
+export type ToolConfig = {
+    overrides: Record<string, ToolOverride>;
+};
+/** Absolute path to the tools registry root (`.otto/tools`). */
+export declare function toolsDir(workspaceDir: string): string;
+/** Absolute path to one tool's definition (`.otto/tools/<name>.json`). */
+export declare function toolPath(workspaceDir: string, name: string): string;
+/**
+ * Normalize an untrusted parsed `<name>.json` into a {@link ToolDefinition},
+ * filling restrictive defaults. Returns null when it lacks a `name` (so a
+ * malformed file is skipped, not crashed on). `kind` defaults to `command`;
+ * `enabled` defaults to true; every scope list defaults to empty.
+ */
+export declare function parseTool(raw: unknown): ToolDefinition | null;
+/**
+ * Read every tool definition under `.otto/tools/` (the `*.json` files), skipping
+ * malformed ones, sorted by name. Absent/unreadable dir → `[]` (never throws).
+ * Reads ONLY the repo-local registry — personal MCP/plugin config is never
+ * consulted (the AFK invariant).
+ */
+export declare function readTools(workspaceDir: string): ToolDefinition[];
+/**
+ * Read the `tools` block of `.otto/config.json` (per-tool enable/stage
+ * overrides). Absent/malformed file or block → no overrides (never throws). Only
+ * the `tools` key is read; sibling config blocks (journal, branch) are untouched.
+ */
+export declare function readToolConfig(workspaceDir: string): ToolConfig;
+/** Whether a tool is enabled for `stage`, plus a human reason. Pure. */
+export declare function toolEnabledForStage(tool: ToolDefinition, config: ToolConfig, stage: string): {
+    enabled: boolean;
+    reason: string;
+};
+/** One tool's availability verdict for a stage (the `why` surface). */
+export type ToolSelection = {
+    name: string;
+    kind: ToolKind;
+    enabled: boolean;
+    reason: string;
+    capabilities: string[];
+};
+/**
+ * Rank tools for a stage: enabled-first, then name. Disabled tools are still
+ * returned (flagged, with the reason) so `otto-tools why <stage>` shows the full
+ * picture — including a tool that exists but is policy/stage-gated off. Pure.
+ */
+export declare function selectToolsForStage(tools: ToolDefinition[], config: ToolConfig, stage: string): ToolSelection[];
+/** A concrete tool action to authorize before it runs. */
+export type ToolInvocation = {
+    /** Resolved shell command, if the adapter shells out. */
+    command?: string;
+    /** Domains the invocation would reach. */
+    domains?: string[];
+    /** Workspace-relative paths the invocation would write. */
+    writePaths?: string[];
+    /** Named high-risk action (matched against approval lists). */
+    action?: string;
+};
+/** The authority verdict for a {@link ToolInvocation}. */
+export type ToolAuthorization = {
+    allowed: boolean;
+    violations: PolicyViolation[];
+    /** One blocked `policy-violation` {@link SafetyEvent} per violation. */
+    events: SafetyEvent[];
+};
+/**
+ * Authorize a tool invocation. Authority is the INTERSECTION of the repo safety
+ * policy and the tool's declared scope, so a tool can only narrow what a run may
+ * do:
+ *
+ * - command — blocked if it matches any repo `blockedCommands` pattern;
+ * - domains — each must satisfy BOTH the repo `allowedNetworkDomains` and the
+ *   tool's declared `networkDomains` (empty tool list = the tool declared no
+ *   network use, so any domain is out of scope);
+ * - writePaths — each must satisfy BOTH the repo `allowedWriteRoots` and the
+ *   tool's declared `writeRoots`;
+ * - action — denied if it appears in the repo `approvalRequiredActions` or the
+ *   tool's `approvalActions` (no human is present in AFK, so it is blocked).
+ *
+ * Every breach becomes a blocked `policy-violation` {@link SafetyEvent} for the
+ * evidence bundle. `allowed` is true only when there are no violations. Pure.
+ */
+export declare function authorizeToolInvocation(policy: SafetyPolicy, tool: ToolDefinition, invocation: ToolInvocation): ToolAuthorization;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

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

package/dist/tools.js

@@ -0,0 +1,228 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_POLICY, checkCommand, checkNetworkDomain, checkWritePath, } from "./safety-policy.js";
+const TOOL_KINDS = new Set([
+    "command",
+    "mcp",
+    "http",
+    "proxy",
+    "sdk",
+]);
+const TOOLS_REL = join(".otto", "tools");
+/** Absolute path to the tools registry root (`.otto/tools`). */
+export function toolsDir(workspaceDir) {
+    return join(workspaceDir, TOOLS_REL);
+}
+/** Absolute path to one tool's definition (`.otto/tools/<name>.json`). */
+export function toolPath(workspaceDir, name) {
+    return join(toolsDir(workspaceDir), `${name}.json`);
+}
+function stringArray(raw) {
+    return Array.isArray(raw)
+        ? raw.filter((s) => typeof s === "string")
+        : [];
+}
+/**
+ * Normalize an untrusted parsed `<name>.json` into a {@link ToolDefinition},
+ * filling restrictive defaults. Returns null when it lacks a `name` (so a
+ * malformed file is skipped, not crashed on). `kind` defaults to `command`;
+ * `enabled` defaults to true; every scope list defaults to empty.
+ */
+export function parseTool(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const o = raw;
+    if (typeof o.name !== "string" || o.name.length === 0)
+        return null;
+    const tool = {
+        name: o.name,
+        kind: typeof o.kind === "string" && TOOL_KINDS.has(o.kind)
+            ? o.kind
+            : "command",
+        capabilities: stringArray(o.capabilities),
+        stages: stringArray(o.stages),
+        env: stringArray(o.env),
+        networkDomains: stringArray(o.networkDomains),
+        writeRoots: stringArray(o.writeRoots),
+        secretRefs: stringArray(o.secretRefs),
+        approvalActions: stringArray(o.approvalActions),
+        enabled: o.enabled !== false,
+    };
+    if (typeof o.description === "string")
+        tool.description = o.description;
+    if (typeof o.command === "string")
+        tool.command = o.command;
+    if (typeof o.healthCheck === "string")
+        tool.healthCheck = o.healthCheck;
+    if (typeof o.timeoutMs === "number" && Number.isFinite(o.timeoutMs)) {
+        tool.timeoutMs = o.timeoutMs;
+    }
+    return tool;
+}
+/**
+ * Read every tool definition under `.otto/tools/` (the `*.json` files), skipping
+ * malformed ones, sorted by name. Absent/unreadable dir → `[]` (never throws).
+ * Reads ONLY the repo-local registry — personal MCP/plugin config is never
+ * consulted (the AFK invariant).
+ */
+export function readTools(workspaceDir) {
+    let names;
+    try {
+        names = readdirSync(toolsDir(workspaceDir))
+            .filter((f) => f.endsWith(".json"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const tools = [];
+    for (const file of names) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(toolsDir(workspaceDir), file), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const t = parseTool(parsed);
+        if (t)
+            tools.push(t);
+    }
+    return tools;
+}
+/**
+ * Read the `tools` block of `.otto/config.json` (per-tool enable/stage
+ * overrides). Absent/malformed file or block → no overrides (never throws). Only
+ * the `tools` key is read; sibling config blocks (journal, branch) are untouched.
+ */
+export function readToolConfig(workspaceDir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(join(workspaceDir, ".otto", "config.json"), "utf8"));
+    }
+    catch {
+        return { overrides: {} };
+    }
+    const block = raw.tools;
+    if (!block || typeof block !== "object" || Array.isArray(block)) {
+        return { overrides: {} };
+    }
+    const overrides = {};
+    for (const [name, v] of Object.entries(block)) {
+        if (!v || typeof v !== "object" || Array.isArray(v))
+            continue;
+        const ov = v;
+        const out = {};
+        if (typeof ov.enabled === "boolean")
+            out.enabled = ov.enabled;
+        if (Array.isArray(ov.stages))
+            out.stages = stringArray(ov.stages);
+        overrides[name] = out;
+    }
+    return { overrides };
+}
+/** Whether a tool is enabled for `stage`, plus a human reason. Pure. */
+export function toolEnabledForStage(tool, config, stage) {
+    const ov = config.overrides[tool.name];
+    const enabled = ov?.enabled ?? tool.enabled;
+    if (!enabled) {
+        return { enabled: false, reason: "disabled in registry/config" };
+    }
+    const stages = ov?.stages ?? tool.stages;
+    if (stages.length === 0) {
+        return { enabled: false, reason: "no stage allowlist (opt-in required)" };
+    }
+    if (!stages.includes(stage)) {
+        return {
+            enabled: false,
+            reason: `stage "${stage}" not in allowlist [${stages.join(", ")}]`,
+        };
+    }
+    return { enabled: true, reason: `enabled for stage "${stage}"` };
+}
+/**
+ * Rank tools for a stage: enabled-first, then name. Disabled tools are still
+ * returned (flagged, with the reason) so `otto-tools why <stage>` shows the full
+ * picture — including a tool that exists but is policy/stage-gated off. Pure.
+ */
+export function selectToolsForStage(tools, config, stage) {
+    return tools
+        .map((tool) => {
+        const { enabled, reason } = toolEnabledForStage(tool, config, stage);
+        return {
+            name: tool.name,
+            kind: tool.kind,
+            enabled,
+            reason,
+            capabilities: tool.capabilities,
+        };
+    })
+        .sort((a, b) => Number(b.enabled) - Number(a.enabled) || a.name.localeCompare(b.name));
+}
+/** A single-axis allow-list policy, to reuse the safety-policy predicates. */
+function scopedPolicy(field, values) {
+    return { ...DEFAULT_POLICY, [field]: values };
+}
+/**
+ * Authorize a tool invocation. Authority is the INTERSECTION of the repo safety
+ * policy and the tool's declared scope, so a tool can only narrow what a run may
+ * do:
+ *
+ * - command — blocked if it matches any repo `blockedCommands` pattern;
+ * - domains — each must satisfy BOTH the repo `allowedNetworkDomains` and the
+ *   tool's declared `networkDomains` (empty tool list = the tool declared no
+ *   network use, so any domain is out of scope);
+ * - writePaths — each must satisfy BOTH the repo `allowedWriteRoots` and the
+ *   tool's declared `writeRoots`;
+ * - action — denied if it appears in the repo `approvalRequiredActions` or the
+ *   tool's `approvalActions` (no human is present in AFK, so it is blocked).
+ *
+ * Every breach becomes a blocked `policy-violation` {@link SafetyEvent} for the
+ * evidence bundle. `allowed` is true only when there are no violations. Pure.
+ */
+export function authorizeToolInvocation(policy, tool, invocation) {
+    const violations = [];
+    if (invocation.command !== undefined) {
+        violations.push(...checkCommand(policy, invocation.command));
+    }
+    for (const domain of invocation.domains ?? []) {
+        violations.push(...checkNetworkDomain(policy, domain));
+        // Tool scope: an empty declared list means "no network", which must block.
+        if (tool.networkDomains.length === 0) {
+            violations.push({
+                kind: "network-domain",
+                subject: domain,
+                message: `tool "${tool.name}" declares no network access`,
+            });
+        }
+        else {
+            violations.push(...checkNetworkDomain(scopedPolicy("allowedNetworkDomains", tool.networkDomains), domain));
+        }
+    }
+    for (const path of invocation.writePaths ?? []) {
+        violations.push(...checkWritePath(policy, path));
+        if (tool.writeRoots.length > 0) {
+            violations.push(...checkWritePath(scopedPolicy("allowedWriteRoots", tool.writeRoots), path));
+        }
+    }
+    if (invocation.action !== undefined) {
+        const needsApproval = policy.approvalRequiredActions.includes(invocation.action) ||
+            tool.approvalActions.includes(invocation.action);
+        if (needsApproval) {
+            violations.push({
+                kind: "approval-required",
+                subject: invocation.action,
+                message: `action "${invocation.action}" requires human approval (unavailable in AFK)`,
+            });
+        }
+    }
+    const events = violations.map((v) => ({
+        category: "policy-violation",
+        kind: v.kind,
+        subject: v.subject,
+        message: v.message,
+        blocked: true,
+    }));
+    return { allowed: violations.length === 0, violations, events };
+}
+//# sourceMappingURL=tools.js.map