open-multi-agent-kit 0.78.0 → 0.78.1

package/dist/runtime/headroom-policy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * HeadroomPolicy — proactive context compaction trigger.
+ *
+ * Industrial control-loop policy: given current token usage and model
+ * context window, decide whether to compact BEFORE utilization reaches
+ * a configurable threshold (default 90%).
+ *
+ * Prefers the external `headroom` CLI compressor when available;
+ * falls back to the built-in `optimizeContextBudget` when not.
+ *
+ * Deterministic except for the injectable `runHeadroom` runner.
+ */
+export interface HeadroomDecision {
+    readonly shouldCompact: boolean;
+    readonly utilization: number;
+    readonly threshold: number;
+    readonly usedTokens: number;
+    readonly contextWindow: number;
+    readonly reason: string;
+}
+export interface HeadroomCompactResult {
+    readonly compacted: boolean;
+    readonly via: "headroom" | "fallback" | "none";
+}
+export declare function resolveHeadroomThreshold(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): number;
+export declare function isHeadroomEnabled(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
+export declare function evaluateHeadroom(input: {
+    usedTokens: number;
+    contextWindow: number;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}): HeadroomDecision;
+export declare function maybeCompactWithHeadroom(args: {
+    decision: HeadroomDecision;
+    text?: string;
+    runHeadroom?: (text: string) => Promise<string | null>;
+    fallback?: () => Promise<void>;
+}): Promise<HeadroomCompactResult>;

package/dist/runtime/headroom-policy.js

@@ -0,0 +1,122 @@
+/**
+ * HeadroomPolicy — proactive context compaction trigger.
+ *
+ * Industrial control-loop policy: given current token usage and model
+ * context window, decide whether to compact BEFORE utilization reaches
+ * a configurable threshold (default 90%).
+ *
+ * Prefers the external `headroom` CLI compressor when available;
+ * falls back to the built-in `optimizeContextBudget` when not.
+ *
+ * Deterministic except for the injectable `runHeadroom` runner.
+ */
+// ─── Defaults ────────────────────────────────────────────────────────────────
+const DEFAULT_THRESHOLD = 0.90;
+const MIN_THRESHOLD = 0.50;
+const MAX_THRESHOLD = 0.99;
+// ─── Threshold resolver ──────────────────────────────────────────────────────
+export function resolveHeadroomThreshold(env = process.env) {
+    const raw = env.OMK_HEADROOM_THRESHOLD;
+    if (raw === undefined || raw === "")
+        return DEFAULT_THRESHOLD;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_THRESHOLD;
+    return Math.min(MAX_THRESHOLD, Math.max(MIN_THRESHOLD, parsed));
+}
+// ─── Enabled check ───────────────────────────────────────────────────────────
+export function isHeadroomEnabled(env = process.env) {
+    const raw = env.OMK_HEADROOM;
+    if (raw === undefined || raw === "")
+        return true;
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "off" || normalized === "0" || normalized === "false")
+        return false;
+    return true;
+}
+// ─── Evaluate ────────────────────────────────────────────────────────────────
+export function evaluateHeadroom(input) {
+    const env = input.env ?? process.env;
+    const enabled = isHeadroomEnabled(env);
+    const threshold = resolveHeadroomThreshold(env);
+    const { usedTokens, contextWindow } = input;
+    if (!enabled) {
+        return {
+            shouldCompact: false,
+            utilization: 0,
+            threshold,
+            usedTokens,
+            contextWindow,
+            reason: "headroom disabled via OMK_HEADROOM",
+        };
+    }
+    if (contextWindow <= 0) {
+        return {
+            shouldCompact: false,
+            utilization: 0,
+            threshold,
+            usedTokens,
+            contextWindow,
+            reason: "context window size unknown (0)",
+        };
+    }
+    const utilization = usedTokens / contextWindow;
+    const shouldCompact = utilization >= threshold;
+    return {
+        shouldCompact,
+        utilization,
+        threshold,
+        usedTokens,
+        contextWindow,
+        reason: shouldCompact
+            ? `utilization ${(utilization * 100).toFixed(1)}% >= threshold ${(threshold * 100).toFixed(1)}%`
+            : `utilization ${(utilization * 100).toFixed(1)}% below threshold ${(threshold * 100).toFixed(1)}%`,
+    };
+}
+// ─── Compaction runner ───────────────────────────────────────────────────────
+const HEADROOM_CLI_TIMEOUT_MS = 15_000;
+async function defaultRunHeadroom(text) {
+    try {
+        const { runShell } = await import("../util/shell.js");
+        const result = await runShell("headroom", ["compact", "--stdin"], {
+            timeout: HEADROOM_CLI_TIMEOUT_MS,
+            input: text,
+        });
+        if (result.failed || result.exitCode !== 0)
+            return null;
+        const output = result.stdout.trim();
+        return output.length > 0 ? output : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function maybeCompactWithHeadroom(args) {
+    if (!args.decision.shouldCompact) {
+        return { compacted: false, via: "none" };
+    }
+    // Try headroom first
+    if (args.text) {
+        try {
+            const runner = args.runHeadroom ?? defaultRunHeadroom;
+            const result = await runner(args.text);
+            if (result !== null) {
+                return { compacted: true, via: "headroom" };
+            }
+        }
+        catch {
+            // Headroom threw — fall through to fallback
+        }
+    }
+    // Fall back to built-in optimizer
+    if (args.fallback) {
+        try {
+            await args.fallback();
+            return { compacted: true, via: "fallback" };
+        }
+        catch {
+            // Fallback also failed — graceful degradation
+        }
+    }
+    return { compacted: false, via: "none" };
+}

package/dist/runtime/ouroboros-policy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Ouroboros routing policy for OMK.
+ *
+ * Resolves whether to prefer the embedded Ouroboros spec-first flow
+ * for goal/spec/orchestration intents.  Detection is non-fatal and
+ * never triggers network access or implicit installs.
+ */
+export type OuroborosMode = "always" | "auto" | "off";
+/**
+ * Read the OMK_OUROBOROS env var and normalise it into a mode.
+ *
+ * - unset / anything other than the known tokens  → "always" (default)
+ * - "auto"                                        → "auto"
+ * - "off" / "0" / "false" (case-insensitive)      → "off"
+ */
+export declare function resolveOuroborosMode(env?: NodeJS.ProcessEnv): OuroborosMode;
+export interface OuroborosAvailability {
+    available: boolean;
+    via: "mcp" | "binary" | "none";
+    detail: string;
+}
+interface DetectOpts {
+    env?: NodeJS.ProcessEnv;
+    mcpConfigPath?: string;
+    which?: (cmd: string) => Promise<string | null>;
+}
+/**
+ * Check whether Ouroboros is reachable without network or installs.
+ *
+ * Strategy (non-fatal):
+ *   1. Look for an `ouroboros` key in ~/.omk/agent/mcp.json  (global)
+ *      and/or .omk/mcp.json  (project-scoped).
+ *   2. Optionally check for an `ouroboros` binary via an injectable which().
+ *
+ * Any I/O error silently yields `{ available: false, via: "none" }`.
+ */
+export declare function detectOuroborosAvailable(opts?: DetectOpts): Promise<OuroborosAvailability>;
+export interface OuroborosDecision {
+    use: boolean;
+    mode: OuroborosMode;
+    availability: OuroborosAvailability;
+    reason: string;
+}
+interface DecisionInput {
+    intent: string;
+    env?: NodeJS.ProcessEnv;
+    detect?: () => Promise<OuroborosAvailability>;
+}
+/**
+ * Decide whether the current run should route through Ouroboros.
+ *
+ * - use=true only when mode≠off AND available AND intent matches.
+ * - When mode=always but unavailable → use=false with fallback reason.
+ * - Never throws.
+ */
+export declare function resolveOuroborosDecision(input: DecisionInput): Promise<OuroborosDecision>;
+export {};

package/dist/runtime/ouroboros-policy.js

@@ -0,0 +1,134 @@
+/**
+ * Ouroboros routing policy for OMK.
+ *
+ * Resolves whether to prefer the embedded Ouroboros spec-first flow
+ * for goal/spec/orchestration intents.  Detection is non-fatal and
+ * never triggers network access or implicit installs.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Read the OMK_OUROBOROS env var and normalise it into a mode.
+ *
+ * - unset / anything other than the known tokens  → "always" (default)
+ * - "auto"                                        → "auto"
+ * - "off" / "0" / "false" (case-insensitive)      → "off"
+ */
+export function resolveOuroborosMode(env = process.env) {
+    const raw = (env.OMK_OUROBOROS ?? "").trim().toLowerCase();
+    if (raw === "off" || raw === "0" || raw === "false")
+        return "off";
+    if (raw === "auto")
+        return "auto";
+    return "always";
+}
+/**
+ * Check whether Ouroboros is reachable without network or installs.
+ *
+ * Strategy (non-fatal):
+ *   1. Look for an `ouroboros` key in ~/.omk/agent/mcp.json  (global)
+ *      and/or .omk/mcp.json  (project-scoped).
+ *   2. Optionally check for an `ouroboros` binary via an injectable which().
+ *
+ * Any I/O error silently yields `{ available: false, via: "none" }`.
+ */
+export async function detectOuroborosAvailable(opts) {
+    // --- binary check (fast, optional) ---
+    if (opts?.which) {
+        try {
+            const bin = await opts.which("ouroboros");
+            if (bin) {
+                return { available: true, via: "binary", detail: `found binary: ${bin}` };
+            }
+        }
+        catch {
+            // swallow
+        }
+    }
+    // --- MCP config check (non-fatal) ---
+    const home = homedir();
+    const candidates = [
+        opts?.mcpConfigPath ?? join(home, ".omk", "agent", "mcp.json"),
+        join(process.cwd(), ".omk", "mcp.json"),
+    ];
+    for (const configPath of candidates) {
+        try {
+            const raw = await readFile(configPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (isRecord(parsed) && isRecord(parsed.mcpServers)) {
+                if ("ouroboros" in parsed.mcpServers) {
+                    return {
+                        available: true,
+                        via: "mcp",
+                        detail: `ouroboros server found in ${configPath}`,
+                    };
+                }
+            }
+        }
+        catch {
+            // file missing or malformed → continue
+        }
+    }
+    return { available: false, via: "none", detail: "ouroboros not detected" };
+}
+/**
+ * Intent tokens (lowercased) that qualify for Ouroboros routing.
+ */
+const OUROBOROS_INTENT_KEYWORDS = [
+    "goal",
+    "plan",
+    "spec",
+    "seed",
+    "interview",
+    "orchestrate",
+    "feature",
+    "build",
+    "implement",
+    // Korean equivalents
+    "계획",
+    "스펙",
+    "구현",
+    "기획",
+];
+/**
+ * Decide whether the current run should route through Ouroboros.
+ *
+ * - use=true only when mode≠off AND available AND intent matches.
+ * - When mode=always but unavailable → use=false with fallback reason.
+ * - Never throws.
+ */
+export async function resolveOuroborosDecision(input) {
+    const mode = resolveOuroborosMode(input.env);
+    const detect = input.detect ?? (() => detectOuroborosAvailable({ env: input.env }));
+    let availability;
+    try {
+        availability = await detect();
+    }
+    catch {
+        availability = { available: false, via: "none", detail: "detection threw" };
+    }
+    if (mode === "off") {
+        return { use: false, mode, availability, reason: "ouroboros-mode-off" };
+    }
+    if (!availability.available) {
+        return {
+            use: false,
+            mode,
+            availability,
+            reason: "ouroboros-unavailable-fallback-native",
+        };
+    }
+    if (!isGoalLikeIntent(input.intent)) {
+        return { use: false, mode, availability, reason: "intent-not-goal-like" };
+    }
+    return { use: true, mode, availability, reason: "ouroboros-routing-active" };
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function isGoalLikeIntent(intent) {
+    const lowered = intent.toLocaleLowerCase();
+    return OUROBOROS_INTENT_KEYWORDS.some((kw) => lowered.includes(kw));
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}

package/dist/runtime/runtime-backed-task-runner.js

@@ -14,6 +14,7 @@ import { applyTaskRunContextToAgentTask, envFromWorkerManifest } from "./worker-
 import { createRuntimeRegistry } from "./runtime-registry.js";
 import { createRuntimeRouter } from "./runtime-router.js";
 import { createContextBroker } from "./context-broker.js";
+import { maybeCompactWithHeadroom } from "./headroom-policy.js";
 import { DeepSeekRuntime } from "./deepseek-runtime.js";
 import { CodexRuntime } from "./codex-runtime.js";
 import { createOpencodeCliAdapter } from "../adapters/opencode/opencode-cli-adapter.js";
@@ -128,7 +129,14 @@ export async function createRuntimeBackedTaskRunner(options) {
                     startedAt: new Date().toISOString(),
                 }
                 : undefined;
-            const { capsule } = await contextBroker.buildCapsule(node, runState);
+            const { capsule, headroomDecision } = await contextBroker.buildCapsule(node, runState);
+            // CTX guard: compact via headroom before the context window crosses the threshold (~90%).
+            if (headroomDecision?.shouldCompact) {
+                await maybeCompactWithHeadroom({
+                    decision: headroomDecision,
+                    text: JSON.stringify(capsule),
+                }).catch(() => undefined);
+            }
             const routing = capsule.node.routing;
             const providerFallbackChain = options.fallbackChain
                 ?? (routing?.fallbackProvider ? [routing.fallbackProvider] : []);

package/dist/runtime/tool-dispatch-contracts.d.ts

@@ -1,8 +1,64 @@
 import type { OmkToolCall, OmkToolDefinition } from "./tool-registry-contract.js";
+import { type ToolAuthorityDecision, type ToolOp } from "../safety/tool-authority-gate.js";
+import type { ProviderAuthorityLevel } from "../contracts/provider-health.js";
 export interface ToolDispatchResult<R = unknown> {
     readonly call: OmkToolCall;
     readonly status: "fulfilled" | "rejected";
     readonly value?: R;
     readonly reason?: unknown;
 }
-export declare function dispatchToolCallsByContract<A, R>(calls: readonly OmkToolCall<A>[], registry: ReadonlyMap<string, OmkToolDefinition<A, R>>, dispatchOne: (call: OmkToolCall<A>) => Promise<R>): Promise<ToolDispatchResult<R>[]>;
+/** Shadow = record only; enforce = a block/ask(non-TTY) verdict rejects the call. */
+export type ToolAuthorityMode = "shadow" | "enforce";
+/**
+ * Per-call verdict recorded at the dispatch checkpoint. Carries only coarse,
+ * non-secret signals (op class, authority levels, policy) — never tool args.
+ */
+export interface ToolAuthorityDecisionRecord {
+    readonly toolName: string;
+    readonly op: ToolOp;
+    readonly decision: ToolAuthorityDecision;
+    readonly mode: ToolAuthorityMode;
+    /** True only when the verdict actually rejected the call (enforce + block). */
+    readonly enforced: boolean;
+    /** Redacted, human-readable reason. Never includes args or secret values. */
+    readonly reason: string;
+}
+/**
+ * Authority wiring for one dispatch turn. All inputs are non-secret enum/bool
+ * signals. When omitted from {@link dispatchToolCallsByContract}, dispatch is
+ * byte-identical to the ungated path.
+ */
+export interface ToolAuthorityWiring {
+    readonly writeAuthority: ProviderAuthorityLevel;
+    readonly shellAuthority: ProviderAuthorityLevel;
+    readonly approvalPolicy: "interactive" | "auto" | "yolo" | "block";
+    readonly sandboxMode: "read-only" | "workspace-write";
+    readonly tty: boolean;
+    /**
+     * Enforcement opt-in. Default `false` => shadow mode (zero behavior change):
+     * verdicts are computed and recorded but never block. When `true`, a `block`
+     * verdict (and `ask` in a non-TTY context, fail-closed) rejects the call.
+     */
+    readonly enforce?: boolean;
+    /** Optional sink for computed verdicts (invoked in both shadow and enforce). */
+    readonly onDecision?: (record: ToolAuthorityDecisionRecord) => void;
+}
+/**
+ * Resolve the global enforcement opt-in from the environment. Default OFF means
+ * the gate runs in shadow mode (record only). Set `OMK_TOOL_AUTHORITY_ENFORCE=1`
+ * to enable fail-closed enforcement at the dispatch checkpoint.
+ */
+export declare function resolveToolAuthorityEnforcement(env?: Record<string, string | undefined>): boolean;
+/** Error used to reject a tool call rejected by the authority gate (enforce mode). */
+export declare class ToolAuthorityBlockedError extends Error {
+    readonly toolName: string;
+    readonly op: ToolOp;
+    readonly decision: ToolAuthorityDecision;
+    constructor(record: ToolAuthorityDecisionRecord);
+}
+/** Compute the gate verdict for a single call. Pure (no IO, no env reads). */
+export declare function evaluateToolAuthority(toolName: string, wiring: ToolAuthorityWiring): {
+    readonly record: ToolAuthorityDecisionRecord;
+    readonly blocked: boolean;
+};
+export declare function dispatchToolCallsByContract<A, R>(calls: readonly OmkToolCall<A>[], registry: ReadonlyMap<string, OmkToolDefinition<A, R>>, dispatchOne: (call: OmkToolCall<A>) => Promise<R>, authority?: ToolAuthorityWiring): Promise<ToolDispatchResult<R>[]>;

package/dist/runtime/tool-dispatch-contracts.js

@@ -1,10 +1,86 @@
 import { createToolExecutionBatches } from "./tool-registry-contract.js";
-export async function dispatchToolCallsByContract(calls, registry, dispatchOne) {
+import { decideToolAuthority, mapToolNameToOp, } from "../safety/tool-authority-gate.js";
+const ENFORCE_PATTERN = /^(1|true|yes|on)$/i;
+/**
+ * Resolve the global enforcement opt-in from the environment. Default OFF means
+ * the gate runs in shadow mode (record only). Set `OMK_TOOL_AUTHORITY_ENFORCE=1`
+ * to enable fail-closed enforcement at the dispatch checkpoint.
+ */
+export function resolveToolAuthorityEnforcement(env = process.env) {
+    return ENFORCE_PATTERN.test((env.OMK_TOOL_AUTHORITY_ENFORCE ?? "").trim());
+}
+/** Build a redacted reason string from non-secret authority signals only. */
+function redactedAuthorityReason(op, decision, wiring) {
+    return (`tool-authority ${decision} for ${op} op ` +
+        `(write=${wiring.writeAuthority}, shell=${wiring.shellAuthority}, ` +
+        `policy=${wiring.approvalPolicy}, sandbox=${wiring.sandboxMode}, tty=${wiring.tty})`);
+}
+/** Error used to reject a tool call rejected by the authority gate (enforce mode). */
+export class ToolAuthorityBlockedError extends Error {
+    toolName;
+    op;
+    decision;
+    constructor(record) {
+        super(record.reason);
+        this.name = "ToolAuthorityBlockedError";
+        this.toolName = record.toolName;
+        this.op = record.op;
+        this.decision = record.decision;
+    }
+}
+/** Compute the gate verdict for a single call. Pure (no IO, no env reads). */
+export function evaluateToolAuthority(toolName, wiring) {
+    const op = mapToolNameToOp(toolName);
+    const decision = decideToolAuthority({
+        op,
+        writeAuthority: wiring.writeAuthority,
+        shellAuthority: wiring.shellAuthority,
+        approvalPolicy: wiring.approvalPolicy,
+        sandboxMode: wiring.sandboxMode,
+        tty: wiring.tty,
+    });
+    const enforce = wiring.enforce === true;
+    // Fail-closed: a non-TTY "ask" is treated as a block (decideToolAuthority
+    // already returns "block" for non-TTY interactive; the second clause is a
+    // defensive guard in case the caller ever surfaces "ask" without a TTY).
+    const wouldBlock = decision === "block" || (decision === "ask" && !wiring.tty);
+    const blocked = enforce && wouldBlock;
+    return {
+        record: {
+            toolName,
+            op,
+            decision,
+            mode: enforce ? "enforce" : "shadow",
+            enforced: blocked,
+            reason: redactedAuthorityReason(op, decision, wiring),
+        },
+        blocked,
+    };
+}
+/**
+ * Wrap a dispatch function with the authority checkpoint. In shadow mode the
+ * wrapper records the verdict and always delegates to `dispatchOne`. In enforce
+ * mode a blocked verdict rejects the call with a redacted reason.
+ */
+function buildGatedDispatch(wiring, dispatchOne) {
+    return async (call) => {
+        const { record, blocked } = evaluateToolAuthority(call.toolName, wiring);
+        wiring.onDecision?.(record);
+        if (blocked) {
+            throw new ToolAuthorityBlockedError(record);
+        }
+        return dispatchOne(call);
+    };
+}
+export async function dispatchToolCallsByContract(calls, registry, dispatchOne, authority) {
+    // When no authority wiring is supplied the dispatch path is byte-identical to
+    // the pre-gate behavior (the checkpoint is a no-op).
+    const effectiveDispatch = authority ? buildGatedDispatch(authority, dispatchOne) : dispatchOne;
     const batches = createToolExecutionBatches(calls, registry);
     const appended = [];
     for (const batch of batches) {
         if (batch.kind === "parallel") {
-            const settled = await Promise.allSettled(batch.calls.map((call) => dispatchOne(call)));
+            const settled = await Promise.allSettled(batch.calls.map((call) => effectiveDispatch(call)));
             settled.forEach((result, index) => {
                 const call = batch.calls[index];
                 if (!call)
@@ -15,7 +91,7 @@ export async function dispatchToolCallsByContract(calls, registry, dispatchOne)
         }
         for (const call of batch.calls) {
             try {
-                appended.push({ call, status: "fulfilled", value: await dispatchOne(call) });
+                appended.push({ call, status: "fulfilled", value: await effectiveDispatch(call) });
             }
             catch (reason) {
                 appended.push({ call, status: "rejected", reason });

package/dist/safety/tool-authority-gate.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure tool-authority decision primitive.
+ *
+ * Decides allow / ask / block for a tool operation given the provider's
+ * write/shell authority, the active approval policy, the sandbox mode, and
+ * whether a TTY is attached. The function is intentionally pure: no IO, no
+ * environment reads, no secrets, no side effects.
+ *
+ * STATUS (0.78.2 stabilization): this primitive is NOT wired into any live
+ * tool-dispatch path. It exists so 0.78.3 can wire it into
+ * `dispatchToolCallsByContract` (src/runtime/tool-dispatch-contracts.ts) and
+ * the kimi runner tool loop without re-deriving the policy. Zero behavior
+ * change to current execution.
+ *
+ * Design rules (authority outranks policy; fail-closed):
+ *  1. read ops are always allowed.
+ *  2. a read-only sandbox is a hard floor: any non-read op is blocked.
+ *  3. authority must be satisfied for the op before policy is consulted:
+ *       write  -> writeAuthority === "full"
+ *       shell  -> shellAuthority === "full"
+ *       merge  -> writeAuthority === "full" AND shellAuthority === "full"
+ *  4. once authority is satisfied, the approval policy decides:
+ *       block       -> block
+ *       yolo        -> allow
+ *       auto        -> allow
+ *       interactive -> ask when a TTY is present, otherwise block
+ *                      (ask in a non-TTY context = deny-by-default).
+ */
+import type { ProviderAuthorityLevel } from "../contracts/provider-health.js";
+/** Coarse operation class used by the authority gate. */
+export type ToolOp = "read" | "write" | "shell" | "merge";
+/** Gate verdict for a single tool operation. */
+export type ToolAuthorityDecision = "allow" | "ask" | "block";
+/** Inputs to the authority decision. Fully self-contained and side-effect free. */
+export interface ToolAuthorityContext {
+    /** Operation class derived from the tool being invoked. */
+    readonly op: ToolOp;
+    /** Provider authority for write/mutation work. */
+    readonly writeAuthority: ProviderAuthorityLevel;
+    /** Provider authority for shell/CLI work. */
+    readonly shellAuthority: ProviderAuthorityLevel;
+    /** Active approval policy for the run. */
+    readonly approvalPolicy: "interactive" | "auto" | "yolo" | "block";
+    /** Active sandbox mode; "read-only" is a hard floor for non-read ops. */
+    readonly sandboxMode: "read-only" | "workspace-write";
+    /** Whether an interactive TTY is attached (gates "interactive" -> ask). */
+    readonly tty: boolean;
+}
+/**
+ * Map a raw tool name to its coarse {@link ToolOp} class.
+ *
+ * Matching is case-insensitive. Unrecognized tools fail closed to the most
+ * restrictive sensible op (`shell` = arbitrary effect execution) rather than
+ * `read`, so an unknown tool is never silently treated as harmless.
+ */
+export declare function mapToolNameToOp(toolName: string): ToolOp;
+/**
+ * Decide allow / ask / block for a tool operation. Pure and fail-closed.
+ *
+ * @see ToolAuthorityContext for the decision inputs and ordering rules.
+ */
+export declare function decideToolAuthority(ctx: ToolAuthorityContext): ToolAuthorityDecision;