@daihum/tool-authority

The transport-agnostic contract for tool calling — the port any agent surface (in-process, HTTP, MCP, cloud) implements, plus the authority facts that make a tool's blast radius legible before it runs. Elevated from carrel's proven ops-protocol assistant-tools surface.

import type { AssistantToolAuthorityPortV0 } from "@daihum/tool-authority";
import { deriveAuthorityFactsFromEffectClassV0 } from "@daihum/tool-authority";

// A tool's authority facts derive from its effect class:
const facts = deriveAuthorityFactsFromEffectClassV0("delete", { idempotencyPolicy: "recommended" });
// → { effectClass: "delete", permissionProfile: "destructive-mutation",
//     approvalPolicy: "always", approvalReviewer: "user",
//     decisionScope: "single-invocation", idempotencyPolicy: "recommended" }

What it defines

• AssistantToolAuthorityPortV0 — listTools() + invokeTool(). The single seam between an agent loop (e.g. @daihum/agent-loop's ToolRunnerPort) and a product's command surface.
• Four-state invoke response — completed | waiting-approval | denied | failed. Approval is a first-class value, not an exception: waiting-approval carries an approvalTicketId + resumeHandle so a turn can pause and resume durably (see @daihum/approval-resume).
• Six-axis authority facts — effectClass, permissionProfile, approvalPolicy, approvalReviewer, decisionScope, idempotencyPolicy.
• Pure policy tables — permissionProfileForEffectClassV0, approvalPolicyForEffectClassV0, approvalReviewerForEffectClassV0, decisionScopeForEffectClassV0, composed by deriveAuthorityFactsFromEffectClassV0. Total over all seven effect classes.

Boundaries

• Contract + policy only, zero dependencies. No transport, no registry, no execution. Deriving the effect class from a host command descriptor is host-specific and stays in the host; the host composes its derived class with the policy tables here.
• Frozen literals. Type names and the carrel.* schema literals are kept verbatim — they are frozen wire/persistence contracts, so carrel adopts this package by import-swap with no wire change.