Agent & task tools

Spawn sub-agents, manage background tasks, coordinate agent swarms, schedule cron jobs, and invoke skills.

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 TaskCreateTool

Use 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

id · 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

id · 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

id · 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

to · 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

id · 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

id · 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

id · string · required

Job ID returned by CronCreate.

Return value

id · 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

1. Claurst resolves <skill>.md from the project commands directory first, then the user commands directory.
2. YAML frontmatter is stripped.
3. $ARGUMENTS placeholders are replaced with the provided arguments string.
4. 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.