Tools

A tool is a typed definition (ToolDef) that the model can call. This page lists the built-in tools and shows how to rename them, run shell commands in the background and ask a human for input. MCP servers add more tools.

Built-in tools#

The basic preset (zidane/presets) has:

basicTools is the same set without spawn:

import { basicTools, definePreset } from 'zidane/presets'

createAgent({ ...definePreset({ name: 'researcher', tools: basicTools }), provider })

Opt-in tools:

Tools the apps add#

In the terminal and desktop apps, each session gets the tools of its agent profile. The Build and Codemode profiles have the basic tools plus glob, grep, web_search and fetch_url. The Plan profile has only read_file, list_files, glob, grep, web_search and fetch_url. Plan shares Build's agent: the request keeps Build's tool list, and a gate refuses the tools Plan does not have (profiles). The apps then add these tools:

A /side session gets only the Plan tools and read_parent_session. The apps add none of the tools above to it.

Aliasing and descriptions#

toolAliases changes the name the model sees:

createAgent({ provider, tools: { shell }, toolAliases: { shell: 'Bash' } })

toolDescriptions overrides any description, native or MCP, with a string or a function of the current one:

createAgent({
  provider,
  toolDescriptions: {
    shell: cur => `${cur}\nNever invoke sudo.`,
    mcp_github_create_pull_request: 'Open a PR. Always target `develop`.',
  },
})

Background tasks#

With run_in_background: true, shell returns a bash_<n> handle at once. Output goes to a log file that the model reads with read_file. shell_kill stops the task. wait_task blocks until the task exits. When a task finishes, the next turn gets a <task-notification> block, so the model does not have to poll.

Set a log directory to turn it on:

import { createAgent, resolveTasksDir } from 'zidane'

const tasksDir = resolveTasksDir({ userDir: '/var/lib/my-agent', sessionId: session.id })
const agent = createAgent({
  provider,
  session,
  behavior: { tasksDir }, // required
})

The built-in shell hides run_in_background from the model, and the agent does not register shell_kill and wait_task, in each of these cases:

• behavior.tasksDir is unset.
• behavior.disableBackgroundTasks is true.
• behavior.disableBackgroundTasks is 'non-durable' and the detached tasks of the context are not durable.
• The context cannot detach tasks.

The full lifecycle is in docs/RUN_IN_BACKGROUND.md.

agent.destroy() sends SIGTERM to each task's process group and flushes its log before tearing down the execution handle.

Interaction tool#

createInteractionTool pauses the agent until onRequest returns the structured input of a human. It takes schema, onRequest and an optional name and description. No preset includes it. The apps have their own ask_user and present_plan (approvals).

import { createInteractionTool } from 'zidane'

const askUser = createInteractionTool({
  name: 'ask_user',
  schema: { type: 'object', properties: { question: { type: 'string' } }, required: ['question'] },
  onRequest: async ({ question }) => ({ answer: await promptUser(question) }),
})

createAgent({ provider, tools: { ...basicTools, ask_user: askUser } })

Calls a crash cut off#

ToolDef.replay says what a durable run does with a call of the tool that a process death left unfinished. 'safe' runs it again, for reads with no side effect. 'unsafe' (the default) reports it to the model as interrupted. See safe and unsafe tools.

Related#

Reference#

• zidane/tools
• zidane/tools/web-search
• zidane/tools/fetch-url
• zidane/tools/prompts
• zidane/codemode