{
  "name": "@forge-sdk/tool",
  "language": "typescript",
  "version": "0.1.0",
  "description": "Tool definition, execution, approval, and registry for the Forge SDK",
  "manifest": "forge-ts/packages/forge-tool/package.json",
  "manifestSha256": "399a1ea4cdf322574e953cc436a839576469826c8061168ad486983141f8f9cb",
  "status": "source-reference",
  "registryPublicationVerified": false,
  "route": "/libraries/typescript/tool",
  "features": {},
  "files": [
    {
      "path": "forge-ts/packages/forge-tool/src/approval.ts",
      "sha256": "b46992776447278b15f73ef023e9e199c814a9b7e8bd364daf015f7e524977b4",
      "artifactSha256": "93b11dfa8a7e82f824dce23e597e7a8f2a731a877eb391ff63f965ceac4da1bf",
      "url": "/reference/source/forge-ts/packages/forge-tool/src/approval.ts.txt",
      "declarations": [
        {
          "name": "ApprovalHandler",
          "line": 44,
          "signature": "export interface ApprovalHandler {\n  /**\n   * Checks whether a tool call should be approved, denied, or modified.\n   *\n   * @param call - The tool call to evaluate.\n   * @param tier - The tool's tier classification.\n   * @returns A ToolApproval indicating the decision.\n   */\n  check(call: ToolCall, tier: ToolTier): Promise<ToolApproval>;\n}",
          "documentation": "Interface for tool approval handlers.\n\nImplementors decide whether a tool call should proceed, be denied, or be\nmodified before execution. The approval handler is invoked after schema\nvalidation but before execution.\n\nANVIL Spec section 8.6: The approval step is mandatory."
        },
        {
          "name": "AutoApprove",
          "line": 72,
          "signature": "export class AutoApprove implements ApprovalHandler {\n  async check(_call: ToolCall, _tier: ToolTier): Promise<ToolApproval>;\n}",
          "documentation": ""
        },
        {
          "name": "DenyAll",
          "line": 99,
          "signature": "export class DenyAll implements ApprovalHandler {\n  constructor(reason: string);\n  async check(_call: ToolCall, _tier: ToolTier): Promise<ToolApproval>;\n}",
          "documentation": "An approval handler that always denies tool calls with a configured reason.\n\nUseful for testing denial flows, maintenance mode, and as a fallback\nwhen no authorization context is available."
        },
        {
          "name": "TierBasedApproval",
          "line": 147,
          "signature": "export class TierBasedApproval implements ApprovalHandler {\n  async check(call: ToolCall, tier: ToolTier): Promise<ToolApproval>;\n}",
          "documentation": "A tier-based approval handler that auto-approves Platform and Embedded tools\nbut denies External-tier tools.\n\nThis is the default ANVIL-compliant approval policy:\n\n| Tier | Decision | Rationale |\n|------|----------|-----------|\n| Platform (1) | Approve | Always available, sandbox-confined |\n| External (2) | Deny | Requires Arsenal ACT authorization |\n| Embedded (3) | Approve | Module-scoped, sandbox-confined |\n\nANVIL Spec section 8.1: External-tier tools execute outside the sandbox and\nMUST be authorized via Arsenal ACTs. Without ACT integration, this handler\nconservatively denies all External-tier calls."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-tool/src/definition.ts",
      "sha256": "cd329423d7fca733da0482c4d98e45532ee36e4c31438d0c1c33d5b149be4042",
      "artifactSha256": "fa1565dec16415407b8965c193516272ea8e92508363c9ba4c0faa38775c2cb6",
      "url": "/reference/source/forge-ts/packages/forge-tool/src/definition.ts.txt",
      "declarations": [
        {
          "name": "ToolBuilder",
          "line": 46,
          "signature": "export class ToolBuilder {\n  constructor(name: string);\n  description(desc: string): this;\n  tier(tier: ToolTier): this;\n  parameters(schema: JsonSchema): this;\n  executor(executor: ToolExecutor): this;\n  handler(handler: (call: ToolCall) => ToolResult | Promise<ToolResult>): this;\n  build(): [ToolDefinition, ToolExecutor | undefined];\n}",
          "documentation": "A fluent builder for constructing tool definitions with optional executors.\n\nToolBuilder pairs a ToolDefinition with an optional ToolExecutor,\nproducing both in a single build step.\n\nANVIL Spec section 8.2: Every tool has a unique name, human-readable\ndescription, parameter schema, and tier classification."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-tool/src/error.ts",
      "sha256": "d242d4eda016a543d53ad7472c8bf988ea4f5e23ddf2b014064021f5fd4f5dca",
      "artifactSha256": "fee21414402113135e2ab021b2f527950d9091c060f1f9b537860852fb47398e",
      "url": "/reference/source/forge-ts/packages/forge-tool/src/error.ts.txt",
      "declarations": [
        {
          "name": "export const ForgeToolErrorCode = {",
          "line": 16,
          "signature": "export const ForgeToolErrorCode /* type inferred in source */;",
          "documentation": "Error types for the forge-tool package.\n\nAll errors are typed, actionable, and include sufficient context for\ndiagnosis without reading source code.\n\nANVIL Spec section 14.2 -- Error Handling requires all errors carry contextual\ninformation suitable for audit trail entries.\nError codes for tool operations."
        },
        {
          "name": "ForgeToolErrorCodeType",
          "line": 32,
          "signature": "export type ForgeToolErrorCodeType = (typeof ForgeToolErrorCode)[keyof typeof ForgeToolErrorCode];",
          "documentation": "A forge-tool error code value."
        },
        {
          "name": "ForgeToolError",
          "line": 47,
          "signature": "export class ForgeToolError extends Error {\n  readonly code: ForgeToolErrorCodeType;\n  readonly toolName?: string;\n  static toolNotFound(name: string): ForgeToolError;\n  static executionFailed(name: string, reason: string): ForgeToolError;\n  static approvalDenied(name: string, reason: string): ForgeToolError;\n  static schemaValidation(name: string, path: string, reason: string): ForgeToolError;\n  static invalidTier(name: string, expected: string, actual: string): ForgeToolError;\n  static registryError(reason: string): ForgeToolError;\n}",
          "documentation": "Error type for tool operations.\n\nCovers tool lookup failures, execution errors, approval denials,\nschema violations, tier mismatches, and registry errors."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-tool/src/execution.ts",
      "sha256": "55e38f75ec08327a76b8771800420975893fee9135d44c9a464c8b1cdf665c79",
      "artifactSha256": "43b4ac97b3f9c852ec3c2c23c2de11a346119157fca47a4acc1f4d26b643f752",
      "url": "/reference/source/forge-ts/packages/forge-tool/src/execution.ts.txt",
      "declarations": [
        {
          "name": "ToolExecutor",
          "line": 45,
          "signature": "export interface ToolExecutor {\n  /** The name of the tool this executor handles. */\n  readonly name: string;\n\n  /**\n   * Executes the tool with the given call arguments.\n   *\n   * @param call - The tool call containing the call ID, tool name, and JSON arguments.\n   * @returns A ToolResult with the execution output.\n   * @throws {ForgeToolError} If the tool logic fails.\n   */\n  execute(call: ToolCall): Promise<ToolResult>;\n}",
          "documentation": "Interface for tool execution implementations.\n\nImplementors provide the actual logic that runs when an agent invokes a tool.\nEach executor is associated with a single tool by name.\n\nANVIL Spec section 8.5: The executor receives a validated, approved ToolCall\nand returns a ToolResult. The executor MUST NOT perform its own authorization\nchecks -- that is the approval handler's responsibility."
        },
        {
          "name": "FnToolExecutor",
          "line": 75,
          "signature": "export class FnToolExecutor implements ToolExecutor {\n  readonly name: string;\n  constructor(\n    name: string,\n    handler: (call: ToolCall) => ToolResult | Promise<ToolResult>\n  );\n  async execute(call: ToolCall): Promise<ToolResult>;\n}",
          "documentation": "A tool executor that wraps a synchronous or async function.\n\nFnToolExecutor allows defining simple tools as functions without\nimplementing the full ToolExecutor interface."
        },
        {
          "name": "executeToolCall",
          "line": 141,
          "signature": "export async function executeToolCall(\n  call: ToolCall,\n  definition: ToolDefinition,\n  executor: ToolExecutor,\n  approvalHandler: ApprovalHandler\n): Promise<ToolResult>;",
          "documentation": "Executes a tool call through the full pipeline: schema validation, approval, execution.\n\nThis function implements the complete ANVIL tool execution lifecycle:\n1. Schema validation -- Validates call.arguments against the tool's parameter schema.\n2. Approval gate -- Checks with the approval handler whether the call is permitted.\n3. Execution -- Delegates to the tool executor.\n\nANVIL Spec section 8.5--8.6: The execution pipeline is mandatory."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-tool/src/index.ts",
      "sha256": "8098d42cbc84b002ac61bbf19aa88ddbd7020eb3757af6e269a2b5002503bf40",
      "artifactSha256": "b89d9f848d33338fcdb8d77b50f706ea6d2e2137e5e0a7c291acc0c4181b9066",
      "url": "/reference/source/forge-ts/packages/forge-tool/src/index.ts.txt",
      "declarations": [
        {
          "name": "export { ForgeToolError, ForgeToolErrorCode, type ForgeToolErrorCodeType } from './error.js';",
          "line": 32,
          "signature": "export { ForgeToolError, ForgeToolErrorCode, type ForgeToolErrorCodeType } from './error.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 35,
          "signature": "export {\n  ExecutionContext,\n  type TierClassification,\n  classifyTier,\n  tierRequiresAuthorization,\n  executionContextFor,\n} from './tiers.js';",
          "documentation": ""
        },
        {
          "name": "export { type ToolExecutor, FnToolExecutor, executeToolCall } from './execution.js';",
          "line": 44,
          "signature": "export { type ToolExecutor, FnToolExecutor, executeToolCall } from './execution.js';",
          "documentation": ""
        },
        {
          "name": "export { type ApprovalHandler, AutoApprove, DenyAll, TierBasedApproval } from './approval.js';",
          "line": 47,
          "signature": "export { type ApprovalHandler, AutoApprove, DenyAll, TierBasedApproval } from './approval.js';",
          "documentation": ""
        },
        {
          "name": "export { ToolBuilder } from './definition.js';",
          "line": 50,
          "signature": "export { ToolBuilder } from './definition.js';",
          "documentation": ""
        },
        {
          "name": "export { ToolRegistry } from './registry.js';",
          "line": 53,
          "signature": "export { ToolRegistry } from './registry.js';",
          "documentation": ""
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-tool/src/registry.ts",
      "sha256": "9b70a071e8f88dbcfbd9134fc416b6f8ba568feccbeab2223029a62a20c77779",
      "artifactSha256": "3161e17426d08688a32cb7bdc01aad7098b8b60604a15b2c5940c88ed1b54deb",
      "url": "/reference/source/forge-ts/packages/forge-tool/src/registry.ts.txt",
      "declarations": [
        {
          "name": "ToolRegistry",
          "line": 40,
          "signature": "export class ToolRegistry {\n  register(definition: ToolDefinition, executor: ToolExecutor): void;\n  get(name: string): [ToolDefinition, ToolExecutor] | undefined;\n  list(): ToolDefinition[];\n  definitions(): ToolDefinition[];\n  get size(): number;\n  get isEmpty(): boolean;\n  remove(name: string): [ToolDefinition, ToolExecutor] | undefined;\n  contains(name: string): boolean;\n}",
          "documentation": "A registry that maps tool names to their definitions and executors.\n\nThe registry provides:\n- Registration -- adding tools with definitions and executors.\n- Lookup -- retrieving a tool by name in O(1) time.\n- Listing -- enumerating all registered tools.\n\nANVIL Spec section 8.3: Tools are registered during agent initialization.\nDuplicate registrations are rejected."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-tool/src/tiers.ts",
      "sha256": "927f5ded546cdbfb698716869b9d468a6443f7fcbcb6b7e50cd3ec18c4926846",
      "artifactSha256": "260028aef6a98871729c4c3a36423d0b76256032ac7f2f6a831d8b21aa6a0c44",
      "url": "/reference/source/forge-ts/packages/forge-tool/src/tiers.ts.txt",
      "declarations": [
        {
          "name": "export const ExecutionContext = {",
          "line": 33,
          "signature": "export const ExecutionContext /* type inferred in source */;",
          "documentation": "The execution context for a tool based on its tier classification.\n\nDetermines whether the tool runs inside the WASM sandbox or outside it\nvia host function calls.\n\nANVIL Spec section 8.1:\n- InSandbox: Platform (Tier 1) and Embedded (Tier 3) tools run inside the sandbox.\n- OutOfSandbox: External (Tier 2) tools run outside the sandbox via host functions."
        },
        {
          "name": "ExecutionContext",
          "line": 41,
          "signature": "export type ExecutionContext = (typeof ExecutionContext)[keyof typeof ExecutionContext];",
          "documentation": "Execution context type."
        },
        {
          "name": "TierClassification",
          "line": 56,
          "signature": "export interface TierClassification {\n  /** The name of the tool that was classified. */\n  readonly toolName: string;\n  /** The tool's tier classification. */\n  readonly tier: ToolTier;\n  /** Whether this tool requires Arsenal ACT authorization before execution. */\n  readonly requiresAuthorization: boolean;\n  /** The execution context (sandbox or host) for this tool. */\n  readonly executionContext: ExecutionContext;\n}",
          "documentation": "The result of classifying a tool by its tier.\n\nContains the tier, whether authorization is required, and the execution\ncontext (sandbox or host)."
        },
        {
          "name": "classifyTier",
          "line": 95,
          "signature": "export function classifyTier(toolName: string, tier: ToolTier): TierClassification;",
          "documentation": ""
        },
        {
          "name": "tierRequiresAuthorization",
          "line": 138,
          "signature": "export function tierRequiresAuthorization(tier: ToolTier): boolean;",
          "documentation": "Returns `true` if the given tier requires Arsenal ACT authorization.\n\nAccepts both `'external'` and `'host'` (legacy alias) for Tier 2."
        },
        {
          "name": "executionContextFor",
          "line": 155,
          "signature": "export function executionContextFor(tier: ToolTier): ExecutionContext;",
          "documentation": "Returns the ExecutionContext for a given tier."
        }
      ]
    }
  ]
}