---
title: Tools
description: Use tools with AI SDK harnesses.
---

# Harness Tools

Harnesses have three tool surfaces:

- Built-in tools exposed by the underlying harness runtime, such as file reads,
  edits, shell commands, and web search.
- AI SDK tools that you pass to `HarnessAgent` with the `tools` setting.
- External MCP tools configured through the harness adapter's `mcpServers`
  setting.

This page covers harness-specific behavior. For general AI SDK tool concepts,
schemas, tool results, and `tool()` usage, see [Tools](/docs/foundations/tools).

## Built-in Tools

Each adapter declares the built-in tools its runtime can call natively.
`HarnessAgent` merges those built-ins with your host-defined tools and exposes
the combined tool set through `agent.tools`.

```ts
const agent = new HarnessAgent({
  harness: claudeCode,
});

agent.tools.bash;
agent.tools.read;
agent.tools.write;
```

Built-in calls are executed by the harness runtime, not by your application
process. Stream parts use `providerExecuted: true` when the runtime already
performed the call.

Adapters use common names where possible:

- `read`
- `write`
- `edit`
- `bash`
- `grep`
- `glob`
- `webSearch`

Some runtimes also expose native tools without a common cross-harness name.
Those appear under their native names.

## Host-Executed Tools

Pass AI SDK tools to `HarnessAgent` the same way you do for a `ToolLoopAgent`:

```ts
import { HarnessAgent } from '@ai-sdk/harness/agent';
import { claudeCode } from '@ai-sdk/harness-claude-code';
import { tool } from 'ai';
import { z } from 'zod';

const weather = tool({
  description: 'Get the current temperature for a city.',
  inputSchema: z.object({
    city: z.string(),
  }),
  execute: async ({ city }) => {
    const temperatures: Record<string, number> = {
      Paris: 12,
      Tokyo: 18,
      Reykjavik: 3,
    };

    return { city, celsius: temperatures[city] ?? 20 };
  },
});

const agent = new HarnessAgent({
  harness: claudeCode,
  tools: { weather },
});
```

When the harness calls `weather`, `HarnessAgent` executes the tool in your host
process, then submits the result back to the harness runtime.

Host-executed tools can declare a `contextSchema` and receive turn-scoped
context through `toolsContext`:

```ts
const lookupAccount = tool({
  inputSchema: z.object({}),
  contextSchema: z.object({ userId: z.string() }),
  execute: async (_, { context }) => {
    return loadAccount(context.userId);
  },
});

const agent = new HarnessAgent({
  harness: claudeCode,
  tools: { lookupAccount },
  toolsContext: {
    lookupAccount: { userId: 'user-123' },
  },
});
```

Use `prepareCall` to replace `toolsContext` when the value depends on custom
call options. The type of `toolsContext` follows the tool set: it is rejected
when no tool declares a context schema, required when a tool requires a
context object, and optional when every context object is optional.
`HarnessAgent` validates each entry against the tool's `contextSchema` before
execution and exposes the configured map in step results and lifecycle
callbacks.

Tool context remains host-only and is not serialized into suspended-turn state.
When recreating a session for an unfinished turn, rebind it explicitly:

```ts
const session = await agent.createSession({
  sessionId,
  continueFrom,
  sandboxSession,
  toolsContext: {
    lookupAccount: { userId: 'user-123' },
  },
});
```

Missing or invalid context fails validation before the host tool executes. The
validation error returned to the harness runtime is intentionally generic so
host-only context values and schema details are not disclosed to the model.
Stream parts and UI messages carry an error with the same generic message. The
detailed validation error is only passed to host callbacks such as
`onToolExecutionEnd`.

## Client-Side Tools

Omit `execute` when a browser, user interaction, or another external process
provides the tool result:

```ts
const weather = tool({
  description: 'Get the current temperature for a city.',
  inputSchema: z.object({ city: z.string() }),
});
```

When the harness calls a tool without `execute`, the returned result slice ends
after the tool-call step while the underlying turn waits for a result.
`session.hasUnfinishedTurn()` remains `true`, and `session.suspendTurn()`
includes the pending tool call in its serializable continuation state.

In UI flows, pass the model messages produced after `addToolOutput` to the next
`stream()` or `generate()` call. `HarnessAgent` extracts the trailing tool
result and continues the paused turn automatically.

For direct agent calls, provide the raw result to `continueStream()` or
`continueGenerate()`:

```ts
const continued = await agent.continueStream({
  session,
  toolResultContinuations: [
    {
      toolCallId,
      output: { city: 'Paris', celsius: 12 },
    },
  ],
});
```

Set `isError: true` when the external tool failed. To continue in another
process, call `suspendTurn()`, recreate the session with `continueFrom`, and
then pass the result to `continueStream()` or `continueGenerate()`.

## Tool Filtering

Use `activeTools` or `inactiveTools` on `HarnessAgent` to control which tools the
harness can call. Both settings accept tool names from the combined tool set:
the built-in tools declared by the harness adapter and the AI SDK tools passed
with `tools`.

`activeTools` is an allowlist:

```ts
const agent = new HarnessAgent({
  harness: claudeCode,
  tools: { weather },
  activeTools: ['weather'],
});
```

`inactiveTools` is a denylist:

```ts
const agent = new HarnessAgent({
  harness: claudeCode,
  tools: { weather },
  inactiveTools: ['bash', 'write'],
});
```

Pass either `activeTools` or `inactiveTools`, not both. The TypeScript settings
type prevents combining them, and `HarnessAgent` also throws at runtime when
both are specified.

For host-executed tools, inactive tools are not passed to the underlying
harness runtime. If the runtime still attempts to call one, `HarnessAgent`
returns an execution-denied tool result.

For built-in tools, support depends on the harness adapter. Some adapters can
filter built-ins natively. Others enforce filtering through their built-in tool
approval mechanism by denying inactive built-in calls before they execute,
without emitting approval request or response stream parts. Adapters that
support neither mechanism throw when you filter built-in tools.

## Sandbox in Tool Execution

Host-executed tools receive the session sandbox through the same
`experimental_sandbox` execution option used by AI SDK tools elsewhere. The
value is a restricted sandbox session, so tools can read, write, and run
commands without being able to stop the network sandbox or change its network
policy.

```ts
const inspectFile = tool({
  description: 'Read a file from the harness workspace.',
  inputSchema: z.object({
    path: z.string(),
  }),
  execute: async ({ path }, { experimental_sandbox }) => {
    return {
      content: await experimental_sandbox?.readTextFile({ path }),
    };
  },
});
```

## Tool Approvals

Harnesses distinguish built-in tool permissions from host-executed tool
approvals.

Use `permissionMode` for adapter-native built-ins:

```ts
const agent = new HarnessAgent({
  harness: pi,
  permissionMode: 'allow-edits',
});
```

Available values are:

- `allow-all`: allow built-in reads, edits, and shell commands. This is the
  default.
- `allow-edits`: allow reads and edits, but request approval for shell commands
  when the adapter supports built-in approvals.
- `allow-reads`: allow reads, but request approval for edits and shell commands
  when the adapter supports built-in approvals.

Use `toolApproval` for host-executed tools:

```ts
const agent = new HarnessAgent({
  harness: claudeCode,
  tools: { weather },
  toolApproval: {
    weather: 'user-approval',
  },
});
```

`toolApproval` accepts the same status values as AI SDK tool approval status
objects: `not-applicable`, `approved`, `user-approval`, and `denied`.

When a host tool call is denied, the model and response messages receive an
`execution-denied` tool result with the denial reason, if provided. The tool's
`execute` and `toModelOutput` functions are not called for the denial.

When approval is required, the stream pauses after a `tool-approval-request`.
Continue the same session by sending a tool approval response message. In UI
flows, `useChat` sends those messages for you when you add the approval result.
In direct agent code, pass the approval response as `messages` on the next
`stream()` or `generate()` call.

### Native Tool Names

Built-in tool calls use the harness tool name, such as `bash`, `write`, or
`edit`, while their input follows the underlying runtime's schema. When an
adapter supplies a different native name, `HarnessAgent` exposes it as
`providerMetadata[harnessId].nativeToolName` on the streamed `tool-call` and
on the `toolCall` inside a `tool-approval-request`.

For example, a Claude Code approval request for `bash` includes
`toolCall.providerMetadata['claude-code'].nativeToolName: 'Bash'`. An approval
gate that works with Claude Code's native tool names can read it without
changing the harness-facing `toolName` or interpreting the input shape:

```ts
for await (const part of result.fullStream) {
  if (part.type === 'tool-approval-request') {
    const nativeToolName =
      part.toolCall.providerMetadata?.['claude-code']?.nativeToolName;
    console.log(nativeToolName ?? part.toolCall.toolName, part.toolCall.input);
  }
}
```

The metadata field is omitted when the adapter does not supply a native name
or when it matches `toolName`. Existing provider metadata is preserved.

## Built-in Approval Support

Most adapters can pause built-in tool calls for approval. Adapters that do not
support it will error if an unsupported tool approval mode is specified.

Host-executed tool approvals are handled by `HarnessAgent`, so they work across
adapters.

## File Changes and Compaction

Some harness events are not ordinary tool calls. For UI compatibility,
`HarnessAgent` projects them as dynamic, provider-executed tool parts:

- `fileChange`: emitted for opaque workspace file mutations.
- `compaction`: emitted when the runtime compacts context.

Check `part.dynamic` before assuming a tool part belongs to your typed tool set.