Agent & task tools

Claurst exposes a rich set of tools for orchestrating work across multiple agents and across time. This page covers agent spawning, task management, team/swarm control, scheduling, and several utility tools.

AgentTool

Spawn a sub-agent that runs its own agentic query loop to complete an independent task. The parent agent waits for the result (synchronous) or receives a task ID immediately (asynchronous/background). Tool name: Agent (alias Task)

When to use AgentTool vs TaskCreateToolUse AgentTool when you want to delegate a complete sub-task to another Claude instance — it gets its own conversation, tool set, and model call budget.Use TaskCreateTool when you want to track a piece of work in the shared task board — a lightweight record with status, description, and dependency links, not a running agent.

Parameters

description

string

required

3–5 word label for the task, shown in the UI.

prompt

string

required

Full task description given to the sub-agent as its initial user message.

tools

string[]

Subset of tool names to make available in the sub-agent. When omitted, the sub-agent inherits the parent’s tool set (minus AgentTool itself, to prevent unbounded recursion).

system_prompt

string

Custom system prompt for the sub-agent. Overrides the default.

max_turns

integer

Maximum number of turns for the sub-agent (Rust implementation). Defaults to MAX_TURNS_DEFAULT.

model

string

Model alias to use for the sub-agent: "sonnet", "opus", or "haiku". Defaults to the session model.

run_in_background

boolean

Launch the sub-agent as a background task and return a task ID immediately.

name

string

Named agent for messaging via SendMessage.

team_name

string

Associate this agent with a named team (swarm).

isolation

string

Isolation strategy: "worktree" (dedicated git worktree) or "remote" (remote session).

Return value

Synchronous (run_in_background: false):

status

string

required

"completed" on success.

result

string

required

Final assistant message from the sub-agent.

Asynchronous (run_in_background: true):

status

string

required

"async_launched".

agentId

string

required

ID of the launched background agent; use with TaskOutputTool to retrieve results.

Example

{
  "description": "Write unit tests",
  "prompt": "Write comprehensive unit tests for the functions in src/parser.rs. Cover edge cases including empty input, unicode, and error paths.",
  "tools": ["Read", "Write", "Bash"],
  "model": "sonnet"
}

TaskCreateTool

Create a task record on the shared task board. Returns a task ID for later reference. Tool name: TaskCreate
Gate: Requires isTodoV2Enabled() (V2 task system).

Parameters

subject

string

required

Short title for the task.

description

string

required

Detailed description of what the task involves.

metadata

object

Arbitrary key-value metadata attached to the task.

Return value

task

object

required

Show properties

string

Unique task ID.

subject

string

Task title.

TaskGetTool

Retrieve a task’s current status, description, and dependency information. Tool name: TaskGet
Gate: Requires isTodoV2Enabled().

Parameters

taskId

string

required

ID of the task to retrieve.

Return value

task

object

null if no task with that ID exists.

Show properties

string

Task ID.

subject

string

Task title.

description

string

Full description.

status

string

Current status: pending, in_progress, completed, failed, or killed.

blocks

string[]

Task IDs that this task blocks.

blockedBy

string[]

Task IDs that must complete before this task can run.

TaskUpdateTool

Update a task’s status, subject, description, dependencies, or ownership. Tool name: TaskUpdate
Gate: Requires isTodoV2Enabled().

Parameters

taskId

string

required

ID of the task to update.

status

string

New status. Use "deleted" to remove the task entirely. Valid values: "pending", "in_progress", "completed", "failed", "killed", "deleted".

subject

string

Updated title.

description

string

Updated description.

addBlocks

string[]

Task IDs that this task should now block.

addBlockedBy

string[]

Task IDs that now block this task.

owner

string

Assign ownership to an agent name.

metadata

object

Updated metadata.

Return value

success

boolean

required

Whether the update succeeded.

taskId

string

required

ID of the updated task.

updatedFields

string[]

required

List of field names that changed.

statusChange

object

Present when status changed: { from, to }.

error

string

Error message if success is false.

TaskListTool

List all non-deleted tasks in the current session. Tool name: TaskList
Gate: Requires isTodoV2Enabled().
Input: No parameters required.

Return value

tasks

object[]

required

Show task properties

string

Task ID.

subject

string

Task title.

status

string

Current status.

owner

string

Assigned agent, if any.

blockedBy

string[]

IDs of blocking tasks that are not yet completed.

TaskStopTool

Stop a running background task (bash task or agent task). Tool name: TaskStop (alias KillShell)

Parameters

task_id

string

ID of the task to stop. Returned when a task was launched with run_in_background: true.

Return value

message

string

required

Confirmation message.

task_id

string

required

ID of the stopped task.

task_type

string

required

Type of task that was stopped.

Notes

The task must be in a non-terminal state (pending or running).
In the Rust implementation, stopping a task sets its status to Failed.

TaskOutputTool

Read the output of a background task, optionally blocking until it completes. Tool name: TaskOutput

Parameters

task_id

string

required

ID of the task to read output from.

block

boolean

default:"true"

When true, wait until the task reaches a terminal state before returning.

timeout

number

default:"30000"

Maximum wait time in milliseconds when block is true. Range: 0–600 000 ms.

Return value

retrieval_status

string

required

"success", "timeout", or "not_ready".

task

object

null when retrieval_status is not "success".

Show properties

task_id

string

Task ID.

status

string

Terminal status: completed, failed, or killed.

description

string

Task description.

output

string

Captured output text.

exitCode

integer

Exit code for bash tasks.

result

string

Final message text for agent tasks.

error

string

Error message for failed tasks.

SendMessageTool

Send a message to a named agent, broadcast to all agents, or route via a Unix domain socket or bridge session. Tool name: SendMessage
Gate: Requires isAgentSwarmsEnabled().

Parameters

string

required

Recipient address:

Agent name (in-process or mailbox)
"*" to broadcast to all agents
"uds:<path>" for a Unix domain socket
"bridge:<session-id>" for a cross-machine bridge (requires user consent)

message

string

required

Message text, or a structured message object. Structured types:

{ type: "shutdown_request", reason?: string }
{ type: "shutdown_response", status: "ok" | "error", message?: string }
{ type: "plan_approval_response", approved: boolean, comment?: string, requestId: string }

summary

string

Short summary shown in the UI activity feed.

Notes

Bridge messages (bridge:<session-id>) always require explicit user approval regardless of permission mode.
In the Rust implementation, messages are delivered to the INBOX in-memory store; broadcast (*) delivers to all current recipients.

CronCreateTool

Schedule a prompt to run automatically on a cron schedule. Tool name: CronCreate
Gate: Requires feature('KAIROS') + isKairosCronEnabled().

Parameters

cron

string

required

Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "0 9 * * 1-5" for weekdays at 9 AM).

prompt

string

required

The prompt to enqueue at each scheduled fire time.

recurring

boolean

default:"true"

true — fire on every matching cron time (auto-expires after the configured max-age).
false — fire once then auto-delete.

durable

boolean

default:"false"

true — persist the job to .claude/scheduled_tasks.json so it survives process restarts.
false — in-memory only; job is lost when the session ends.

Return value

string

required

Job ID for use with CronDelete and CronList.

humanSchedule

string

required

Human-readable schedule description (e.g. "Every weekday at 09:00").

recurring

boolean

required

Whether the job recurs.

durable

boolean

Whether the job is durable.

Notes

Maximum 50 concurrent scheduled jobs.
The cron expression must match at least one date within the next year.
Durable crons are not supported for teammate agents.

CronListTool

List all scheduled cron jobs visible to the current agent. Tool name: CronList
Input: No parameters required.

Return value

jobs

object[]

required

Show job properties

string

Job ID.

cron

string

Cron expression.

humanSchedule

string

Human-readable schedule.

prompt

string

Prompt that fires on schedule.

recurring

boolean

Whether the job recurs.

durable

boolean

Whether the job persists across restarts.

Notes

Teammate agents only see their own jobs. The team lead sees all jobs.

CronDeleteTool

Cancel a scheduled cron job. Tool name: CronDelete

Parameters

string

required

Job ID returned by CronCreate.

Return value

string

required

ID of the cancelled job.

Notes

Teammate agents can only delete their own jobs.

SkillTool

Invoke a user-defined skill — a prompt macro stored as a Markdown file in .claude/commands/ or ~/.claude/commands/. Tool name: Skill

Parameters

skill

string

required

Name of the skill to invoke, or "list" to enumerate available skills. The name maps to a <skill>.md file in the commands directory.

arguments

string

Arguments to substitute for $ARGUMENTS in the skill template.

How skills work

Claurst resolves <skill>.md from the project commands directory first, then the user commands directory.
YAML frontmatter is stripped.
$ARGUMENTS placeholders are replaced with the provided arguments string.
The resulting text is returned as the tool result, and Claude uses it as its next instruction.

Skills are the primary way to package reusable prompt workflows without writing code.

AskUserQuestionTool

Pause task execution and prompt you for a choice before continuing. Tool name: AskUserQuestion

Parameters

questions

object[]

required

1–4 questions to ask. Each question has:

Show question properties

question

string

required

The question text.

header

string

Optional header displayed above the question.

options

object[]

required

2–4 answer options. Each option has label, value, and optional description.

multiSelect

boolean

Allow selecting multiple options.

Return value

questions

object[]

required

The original questions.

answers

object

required

Map of question → selected answer value(s).

Notes

Not available when --channels flag is active (no terminal available).
In non-interactive mode (Rust implementation with non_interactive: true), returns an error.

ToolSearchTool

Discover available tools by keyword or exact name. Tool name: ToolSearch

Parameters

query

string

required

Search query. Use "select:<ToolName>" for exact lookup (e.g. "select:WebFetch"), or plain keywords for fuzzy search (e.g. "search files").

max_results

integer

default:"5"

Maximum number of tools to return.

Return value

matches

string[]

required

Tool names that matched the query.

query

string

required

The query that was run.

total_deferred_tools

integer

required

Total number of deferred tools available to search.

pending_mcp_servers

string[]

MCP servers still loading whose tools are not yet searchable.

How scoring works

Match type	Score
`select:<name>` exact match	100 (Rust) / exact lookup (TypeScript)
Exact tool name match	20 (Rust) / 10 (TypeScript)
Name contains query	10 (Rust) / 5 (TypeScript)
Description contains query	5 (Rust) / 2 (TypeScript)
Keyword/hint match	8 (Rust) / 4 (TypeScript)

When a match is found via select:<name>, the full tool schema is injected into the conversation context as a tool_reference block.

Commands

Tools

Architecture

​AgentTool

​Parameters

​Return value

​Example

​TaskCreateTool

​Parameters

​Return value

​TaskGetTool

​Parameters

​Return value

​TaskUpdateTool

​Parameters

​Return value

​TaskListTool

​Return value

​TaskStopTool

​Parameters

​Return value

​Notes

​TaskOutputTool

​Parameters

​Return value

​SendMessageTool

​Parameters

​Notes

​CronCreateTool

​Parameters

​Return value

​Notes

​CronListTool

​Return value

​Notes

​CronDeleteTool

​Parameters

​Return value

​Notes

​SkillTool

​Parameters

​How skills work

​AskUserQuestionTool

​Parameters

​Return value

​Notes

​ToolSearchTool

​Parameters

​Return value

​How scoring works

Build docs developers (and LLMs) love

AgentTool

Parameters

Return value

Example

TaskCreateTool

Parameters

Return value

TaskGetTool

Parameters

Return value

TaskUpdateTool

Parameters

Return value

TaskListTool

Return value

TaskStopTool

Parameters

Return value

Notes

TaskOutputTool

Parameters

Return value

SendMessageTool

Parameters

Notes

CronCreateTool

Parameters

Return value

Notes

CronListTool

Return value

Notes

CronDeleteTool

Parameters

Return value

Notes

SkillTool

Parameters

How skills work

AskUserQuestionTool

Parameters

Return value

Notes

ToolSearchTool

Parameters

Return value

How scoring works