Skip to contents

Create the Agent tool

Source: R/tools_agent.R
agent_tool.Rd

When btw is available, delegates to btw_tool_agent_subagent() which provides isolated chat sessions with resumable state. Falls back to codeagent's own sub-agent loop otherwise.

Usage

agent_tool(
  model = "claude-sonnet-4-6",
  mode = "default",
  rules = list(),
  max_turns = 30L,
  worktree_isolation = FALSE,
  hooks = NULL,
  ask_fn = NULL,
  async = FALSE,
  data_shield = NULL,
  parent_chat = NULL,
  security_context = NULL
)

Arguments

model

Character. Model for sub-agents (fallback only).

mode

Character. Permission mode (inherited from parent).

rules

List. Permission rules (inherited).

max_turns

Integer. Max turns for sub-agent fallback (default 30).

worktree_isolation

Logical. Run sub-agent in an isolated git worktree.

hooks

A HookRegistry or NULL. Fires SubagentStart/Stop on the codeagent fallback sub-agent. Only applies to the fallback implementation; btw subagent handles its own isolation.

ask_fn

Function or NULL. Parent permission callback. Sub-agents run in "bubble" mode, so any "ask" decision is forwarded to this function.

async

Logical. If TRUE and the parent turn is async (concurrent streaming), run sub-agents via codeagent's promise-based loop so multiple Agent calls in one turn execute concurrently; falls back to synchronous sub-agents otherwise. Default FALSE.

data_shield

Optional DataShield inherited from the parent. When set, the sub-agent's own tools are wrapped before its first LLM request.

parent_chat

Optional parent ellmer::Chat. The owned Agent path clones this Chat, clears history/tools, and verifies provider + Model inheritance.

security_context

Internal immutable parent security snapshot used to preserve tool sets, capabilities, overrides and sandbox settings.

Value

An ellmer::tool() object.