> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools and approval

> Public tools and approval signatures and configuration in @agentium/core 4.0.0.

Import these **35 exports** from `@agentium/core`. Read the [tools and approval guide](/agents/tools) for setup and behavior, or return to the [package reference](/api-reference/core).

A `?` marks an optional field. These are declarations for lookup; run the examples in the linked guide. Follow related-type links for Agentium types and source links for imported dependency types.

## AgentiumSchema

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/schema.ts)

```typescript theme={null}
/** Public schema boundary accepts Zod 3, Zod 4 Classic and Zod 4 Mini. */
export type AgentiumSchema = Zod3Schema | z4.$ZodType;
```

## ApprovalConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/approval.ts)

```typescript theme={null}
export interface ApprovalConfig {
    /** Which tools require approval: "none" (default), "all", or an array of tool names. */
    policy: "none" | "all" | string[];
    /** Callback invoked when approval is needed. Return a decision. */
    onApproval?: (request: ApprovalRequest) => Promise<ApprovalDecision>;
    /** Timeout in ms for waiting on human response. Default: 300000 (5 min). */
    timeout?: number;
    /** Default action when approval times out. Default: "deny". */
    timeoutAction?: "approve" | "deny" | "throw";
}
```

Related: [`ApprovalDecision`](/api-reference/core/tools#approvaldecision), [`ApprovalRequest`](/api-reference/core/tools#approvalrequest).

## ApprovalDecision

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/approval.ts)

```typescript theme={null}
export interface ApprovalDecision {
    approved: boolean;
    reason?: string;
}
```

## ApprovalManager

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/approval.ts)

```typescript theme={null}
/** A host-owned dispatcher that may be shared by concurrent run-local executors. */
export declare class ApprovalManager {
    constructor(config: ApprovalConfig & {
        eventBus?: EventBus;
    });
    /** Unfiltered access is for the trusted owner; hosted callers must supply verified scope. */
    listPending(scope?: {
        runId?: string;
        sessionId?: string;
        userId?: string;
        tenantId?: string;
    }): ApprovalRequest[];
    needsApproval(toolName: string, args: Record<string, unknown>, toolRequiresApproval?: boolean | ((args: Record<string, unknown>) => boolean)): boolean;
    check(toolName: string, args: unknown, ctx: RunContext, agentName: string): Promise<ApprovalDecision>;
    approve(requestId: string, reason?: string): void;
    deny(requestId: string, reason?: string): void;
    cancelRun(runId: string, reason?: string): void;
    close(): void;
}
```

Related: [`ApprovalConfig`](/api-reference/core/tools#approvalconfig), [`ApprovalDecision`](/api-reference/core/tools#approvaldecision), [`ApprovalRequest`](/api-reference/core/tools#approvalrequest), [`EventBus`](/api-reference/core/events#eventbus), [`RunContext`](/api-reference/core/agent#runcontext).

## ApprovalRequest

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/approval.ts)

```typescript theme={null}
export interface ApprovalRequest {
    requestId: string;
    toolName: string;
    args: unknown;
    agentName: string;
    runId: string;
    sessionId?: string;
    userId?: string;
    tenantId?: string;
}
```

## Artifact

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/types.ts)

```typescript theme={null}
export interface Artifact {
    type: string;
    data: unknown;
    mimeType?: string;
}
```

## convertJsonSchema

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/json-schema.ts)

```typescript theme={null}
/** Public dual-version schema conversion boundary.
 * Zod 4 schemas use native conversion; Zod 3 keeps its compatible converter.
 * JSON Schema describes input shape, not arbitrary executable checks. */
export declare function convertJsonSchema(schema: AgentiumSchema): {
    schema: Record<string, unknown>;
    diagnostics: SchemaConversionDiagnostic[];
    dialect: "zod3" | "zod4";
};
```

Related: [`AgentiumSchema`](/api-reference/core/tools#agentiumschema), [`SchemaConversionDiagnostic`](/api-reference/core/tools#schemaconversiondiagnostic).

## createPollResultTool

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/async-handle.ts)

```typescript theme={null}
/**
 * Returns the `pollResult` companion tool that retrieves results from
 * `defineAsyncTool` handles. Add this once to your agent's tool list.
 */
export declare function createPollResultTool(): ToolDef;
```

Related: [`ToolDef`](/api-reference/core/tools#tooldef).

## defineAsyncTool

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/async-handle.ts)

```typescript theme={null}
/**
 * Wrap a long-running execute function in the async-handle pattern.
 * The returned tool fires the work in the background and returns
 * `{ handle: "ah:..." }` immediately.
 */
export declare function defineAsyncTool<T extends ToolParameterSchema>(config: DefineAsyncToolConfig<T>): ToolDef;
```

Related: [`DefineAsyncToolConfig`](/api-reference/core/tools#defineasynctoolconfig), [`ToolDef`](/api-reference/core/tools#tooldef), [`ToolParameterSchema`](/api-reference/core/tools#toolparameterschema).

## DefineAsyncToolConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/async-handle.ts)

```typescript theme={null}
export interface DefineAsyncToolConfig<T extends ToolParameterSchema> {
    name: string;
    description: string;
    parameters: T;
    /** The long-running implementation. Runs in the background. */
    execute: (args: SchemaOutput<T>, ctx: RunContext) => Promise<string | ToolResult>;
    /** TTL for the cached result in seconds. Default 600 (10 minutes). */
    ttlSeconds?: number;
}
```

Related: [`RunContext`](/api-reference/core/agent#runcontext), [`SchemaOutput`](/api-reference/core/tools#schemaoutput), [`ToolParameterSchema`](/api-reference/core/tools#toolparameterschema), [`ToolResult`](/api-reference/core/tools#toolresult).

## defineTool

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/define-tool.ts)

```typescript theme={null}
export declare function defineTool<T extends ToolParameterSchema>(config: {
    name: string;
    description: string;
    parameters: T;
    execute: (args: SchemaOutput<T>, ctx: RunContext) => Promise<string | ToolResult>;
    cache?: ToolCacheConfig;
    sandbox?: boolean | SandboxConfig;
    requiresApproval?: boolean | ((args: Record<string, unknown>) => boolean);
    strict?: boolean;
    /** N-shot examples that demonstrate valid tool calls to the LLM. */
    inputExamples?: Array<SchemaOutput<T>>;
    /** Async transformer applied to the tool result before it is appended to the LLM context. */
    toModelOutput?: (result: string | ToolResult, ctx: RunContext) => Promise<string | ToolResult>;
}): ToolDef;
```

Related: [`RunContext`](/api-reference/core/agent#runcontext), [`SandboxConfig`](/api-reference/core/tools#sandboxconfig), [`SchemaOutput`](/api-reference/core/tools#schemaoutput), [`ToolCacheConfig`](/api-reference/core/tools#toolcacheconfig), [`ToolDef`](/api-reference/core/tools#tooldef), [`ToolParameterSchema`](/api-reference/core/tools#toolparameterschema), [`ToolResult`](/api-reference/core/tools#toolresult).

## evaluateExecutionPolicy

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/execution-policy.ts)

```typescript theme={null}
export declare function evaluateExecutionPolicy(policy: ExecutionPolicy | undefined, call: ValidatedToolCall, ctx: RunContext): Promise<ExecutionDecision>;
```

Related: [`ExecutionDecision`](/api-reference/core/tools#executiondecision), [`ExecutionPolicy`](/api-reference/core/tools#executionpolicy), [`RunContext`](/api-reference/core/agent#runcontext), [`ValidatedToolCall`](/api-reference/core/tools#validatedtoolcall).

## ExecutionDecision

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/execution-policy.ts)

```typescript theme={null}
export interface ExecutionDecision {
    action: "allow" | "ask" | "deny";
    reason?: string;
}
```

## ExecutionPolicy

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/execution-policy.ts)

```typescript theme={null}
/**
 * Host-supplied mandatory policy. Model arguments and MCP annotations are not
 * effect authority. The validated arguments must support Node's structured
 * serialization (ordinary data, dates, maps and typed arrays; not functions).
 * Mutating reviewed arguments fails closed before execution.
 */
export interface ExecutionPolicy {
    decide: (call: ValidatedToolCall, ctx: RunContext) => ExecutionDecision | Promise<ExecutionDecision>;
    /** Classifies the complete tool execution, including its result transformer. */
    resolveEffect?: (call: ValidatedToolCall, ctx: RunContext) => ToolEffect | Promise<ToolEffect>;
}
```

Related: [`ExecutionDecision`](/api-reference/core/tools#executiondecision), [`RunContext`](/api-reference/core/agent#runcontext), [`ToolEffect`](/api-reference/core/tools#tooleffect), [`ValidatedToolCall`](/api-reference/core/tools#validatedtoolcall).

## parseSchema

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/schema.ts)

```typescript theme={null}
export declare function parseSchema<T extends AgentiumSchema>(schema: T, value: unknown): SchemaOutput<T>;
```

Related: [`AgentiumSchema`](/api-reference/core/tools#agentiumschema), [`SchemaOutput`](/api-reference/core/tools#schemaoutput).

## resolveSandboxConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/sandbox.ts)

```typescript theme={null}
export declare function resolveSandboxConfig(toolLevel?: boolean | SandboxConfig, agentLevel?: boolean | SandboxConfig): SandboxConfig | null;
```

Related: [`SandboxConfig`](/api-reference/core/tools#sandboxconfig).

## RunMode

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/execution-policy.ts)

```typescript theme={null}
export type RunMode = "execute" | "plan";
```

## safeParseSchema

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/schema.ts)

```typescript theme={null}
export declare function safeParseSchema<T extends AgentiumSchema>(schema: T, value: unknown): SchemaParseResult<SchemaOutput<T>>;
```

Related: [`AgentiumSchema`](/api-reference/core/tools#agentiumschema), [`SchemaOutput`](/api-reference/core/tools#schemaoutput).

## Sandbox

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/sandbox.ts)

```typescript theme={null}
export declare class Sandbox {
    constructor(config: SandboxConfig);
    execute(toolExecuteFn: (args: Record<string, unknown>, ctx: RunContext) => Promise<string | ToolResult>, args: Record<string, unknown>, _ctx: RunContext): Promise<string | ToolResult>;
}
```

Related: [`RunContext`](/api-reference/core/agent#runcontext), [`SandboxConfig`](/api-reference/core/tools#sandboxconfig), [`ToolResult`](/api-reference/core/tools#toolresult).

## SandboxConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/types.ts)

```typescript theme={null}
export interface SandboxConfig {
    /** Explicit on/off toggle. Defaults to true when config object is provided. */
    enabled?: boolean;
    /** Execution timeout in milliseconds. Default: 30000 (30s). */
    timeout?: number;
    /** Maximum heap memory in MB. Default: 256. */
    maxMemoryMB?: number;
    /** Allow outbound network from the sandbox. Default: false. */
    allowNetwork?: boolean;
    /** Allow filesystem access. Default: false. */
    allowFS?: boolean | {
        readOnly?: string[];
        readWrite?: string[];
    };
    /** Whitelisted environment variables forwarded to the sandbox. */
    env?: Record<string, string>;
}
```

## SchemaConversionDiagnostic

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/json-schema.ts)

```typescript theme={null}
export interface SchemaConversionDiagnostic {
    path: string;
    kind: "transform" | "refinement";
    message: string;
}
```

## SchemaOutput

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/schema.ts)

```typescript theme={null}
export type SchemaOutput<T extends AgentiumSchema> = T extends z4.$ZodType ? z4.output<T> : T extends Zod3Schema ? T["_output"] : never;
```

Related: [`AgentiumSchema`](/api-reference/core/tools#agentiumschema).

## schemaShape

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/schema.ts)

```typescript theme={null}
export declare function schemaShape(schema: ToolParameterSchema): Record<string, AgentiumSchema>;
```

Related: [`AgentiumSchema`](/api-reference/core/tools#agentiumschema), [`ToolParameterSchema`](/api-reference/core/tools#toolparameterschema).

## ToolCacheConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/types.ts)

```typescript theme={null}
export interface ToolCacheConfig {
    /** Time-to-live in milliseconds. Cached results expire after this duration. */
    ttl: number;
}
```

## ToolCallResult

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/types.ts)

```typescript theme={null}
export interface ToolCallResult {
    toolCallId: string;
    toolName: string;
    result: string | ToolResult;
    error?: string;
    /** Structured fail-closed execution outcome. */
    denial?: "policy" | "approval_required" | "approval_denied" | "cancelled";
}
```

Related: [`ToolResult`](/api-reference/core/tools#toolresult).

## ToolDef

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/types.ts)

```typescript theme={null}
export interface ToolDef {
    name: string;
    description: string;
    parameters: ToolParameterSchema;
    execute: (args: Record<string, unknown>, ctx: RunContext) => Promise<string | ToolResult>;
    /** Raw JSON Schema to send to the LLM, bypassing Zod-to-JSON conversion (used by MCP tools). */
    rawJsonSchema?: Record<string, unknown>;
    /** Enable result caching for this tool. */
    cache?: ToolCacheConfig;
    /** Run this tool in a sandboxed subprocess. Off by default. */
    sandbox?: boolean | SandboxConfig;
    /**
     * Require approval before execution; no configured approval service denies the
     * call. False overrides legacy approval defaults, never mandatory host policy.
     */
    requiresApproval?: boolean | ((args: Record<string, unknown>) => boolean);
    /** Enable strict mode for OpenAI Structured Outputs on tool calls. Guarantees valid JSON matching the schema. */
    strict?: boolean;
    /**
     * Optional N-shot examples that demonstrate valid tool calls to the LLM.
     * Each example is rendered into the tool's JSON Schema description.
     */
    inputExamples?: Array<Record<string, unknown>>;
    /**
     * Optional async transformer applied to the tool result *after* execution but
     * *before* the result is appended to the LLM context. Use to compress, summarize,
     * redact, or otherwise reshape large outputs.
     */
    toModelOutput?: (result: string | ToolResult, ctx: RunContext) => Promise<string | ToolResult>;
}
```

Related: [`RunContext`](/api-reference/core/agent#runcontext), [`SandboxConfig`](/api-reference/core/tools#sandboxconfig), [`ToolCacheConfig`](/api-reference/core/tools#toolcacheconfig), [`ToolParameterSchema`](/api-reference/core/tools#toolparameterschema), [`ToolResult`](/api-reference/core/tools#toolresult).

## ToolEffect

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/execution-policy.ts)

```typescript theme={null}
export type ToolEffect = "read" | "write" | "execute" | "external" | "unknown";
```

## ToolExecutor

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/tool-executor.ts)

```typescript theme={null}
export declare class ToolExecutor {
    constructor(tools: ToolDef[], configOrConcurrency?: number | ToolExecutorConfig);
    getApprovalManager(): ApprovalManager | undefined;
    clearCache(): void;
    executeAll(toolCalls: ToolCall[], ctx: RunContext): Promise<ToolCallResult[]>;
    getToolDefinitions(): Array<{
        name: string;
        description: string;
        parameters: Record<string, unknown>;
        strict?: boolean;
    }>;
}
```

Related: [`ApprovalManager`](/api-reference/core/tools#approvalmanager), [`RunContext`](/api-reference/core/agent#runcontext), [`ToolCall`](/api-reference/core/models#toolcall), [`ToolCallResult`](/api-reference/core/tools#toolcallresult), [`ToolDef`](/api-reference/core/tools#tooldef), [`ToolExecutorConfig`](/api-reference/core/tools#toolexecutorconfig).

## ToolExecutorConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/tool-executor.ts)

```typescript theme={null}
export interface ToolExecutorConfig {
    concurrency?: number;
    sandbox?: boolean | SandboxConfig;
    approval?: ApprovalConfig & {
        eventBus?: EventBus;
    };
    /** Share a host-owned dispatcher across run-local executors. */
    approvalManager?: ApprovalManager;
    /** Additional borrowed dispatchers whose approval requirements must also pass. */
    additionalApprovalManagers?: readonly ApprovalManager[];
    executionPolicy?: ExecutionPolicy;
    agentName?: string;
    /** Observe authorized calls. Mutating arguments of a protected call denies execution. */
    onToolCall?: (ctx: RunContext, toolName: string, args: unknown) => Promise<void>;
    /**
     * Memory Pointer Pattern: tool outputs over `maxToolOutputBytes` are auto-stored
     * as artifacts and replaced with a `{ pointer, preview }` JSON string before being
     * appended to the LLM context.
     */
    artifacts?: {
        maxToolOutputBytes: number;
        previewChars: number;
    };
    /**
     * Tool-loop detection: when the same `(toolName, arguments)` pair is invoked
     * more than `maxRepeats` times within a single run, take the configured action.
     *   - `"abort"`: raise `ToolLoopError` and stop the run
     *   - `"hint"`: return a synthetic result reminding the model to change strategy
     */
    loopDetection?: {
        maxRepeats: number;
        action: "abort" | "hint";
    };
}
```

Related: [`ApprovalConfig`](/api-reference/core/tools#approvalconfig), [`ApprovalManager`](/api-reference/core/tools#approvalmanager), [`EventBus`](/api-reference/core/events#eventbus), [`ExecutionPolicy`](/api-reference/core/tools#executionpolicy), [`RunContext`](/api-reference/core/agent#runcontext), [`SandboxConfig`](/api-reference/core/tools#sandboxconfig).

## ToolLoopError

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/tool-executor.ts)

```typescript theme={null}
export declare class ToolLoopError extends Error {
    readonly toolName: string;
    readonly repeats: number;
    constructor(toolName: string, repeats: number);
}
```

## ToolParameterSchema

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/schema.ts)

```typescript theme={null}
export type ToolParameterSchema = (Zod3Schema & {
    readonly _def: {
        readonly typeName: "ZodObject";
    };
    readonly _output: Record<string, unknown>;
    readonly shape: Record<string, Zod3Schema>;
}) | z4.$ZodObject;
```

## ToolResult

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/types.ts)

```typescript theme={null}
export interface ToolResult {
    content: string;
    artifacts?: Artifact[];
}
```

Related: [`Artifact`](/api-reference/core/tools#artifact).

## ToolRouter

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/tool-router.ts)

```typescript theme={null}
/**
 * Pre-selects a subset of relevant tools for a given user query using a
 * cheap model. This dramatically reduces prompt tokens when agents have
 * many tools (e.g. 50+ MCP tools) by only sending relevant tool schemas.
 *
 * If the selection fails for any reason, all tools are returned as a fallback.
 */
export declare class ToolRouter {
    constructor(config: ToolRouterConfig);
    select(query: string, tools: ToolDef[]): Promise<ToolDef[]>;
}
```

Related: [`ToolDef`](/api-reference/core/tools#tooldef), [`ToolRouterConfig`](/api-reference/core/tools#toolrouterconfig).

## ToolRouterConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/tool-router.ts)

```typescript theme={null}
export interface ToolRouterConfig {
    /** Cheap/fast model used to select relevant tools. */
    model: ModelProvider;
    /** Maximum tools to select per query. Default: 8 */
    maxTools?: number;
    /** Minimum tools to always return (in case selection fails). Default: 0 (fallback sends all) */
    minTools?: number;
    /** Temperature for the selection model. Default: 0 */
    temperature?: number;
    /** Optional logger for diagnostic output. When omitted, the router is silent. */
    logger?: Logger;
}
```

Related: [`Logger`](/api-reference/core/logger#logger), [`ModelProvider`](/api-reference/core/models#modelprovider).

## ValidatedToolCall

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/tools/execution-policy.ts)

```typescript theme={null}
export interface ValidatedToolCall {
    readonly toolCallId: string;
    readonly toolName: string;
    readonly args: Readonly<Record<string, unknown>>;
}
```

## Supporting types

These local shapes appear in public signatures but are not named exports of this entrypoint.

### Zod3Schema

```typescript theme={null}
/** Structural v3 contract avoids nominal private-field differences between
 * the standalone v3 package and the v3 compatibility copy shipped with v4. */
export interface Zod3Schema {
    readonly _def: {
        readonly typeName?: string;
    };
    readonly _output: unknown;
    parse(value: unknown): unknown;
    safeParse(value: unknown): SchemaParseResult<unknown>;
}
```

### SchemaParseResult

```typescript theme={null}
export type SchemaParseResult<T> = {
    success: true;
    data: T;
} | {
    success: false;
    error: {
        message: string;
        issues: readonly {
            path: readonly PropertyKey[];
            message: string;
        }[];
    };
};
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.