> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt > Use this file to discover all available pages before exploring further. # 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 3–5 word label for the task, shown in the UI. Full task description given to the sub-agent as its initial user message. 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). Custom system prompt for the sub-agent. Overrides the default. Maximum number of turns for the sub-agent (Rust implementation). Defaults to `MAX_TURNS_DEFAULT`. Model alias to use for the sub-agent: `"sonnet"`, `"opus"`, or `"haiku"`. Defaults to the session model. Launch the sub-agent as a background task and return a task ID immediately. Named agent for messaging via `SendMessage`. Associate this agent with a named team (swarm). Isolation strategy: `"worktree"` (dedicated git worktree) or `"remote"` (remote session). ### Return value **Synchronous (run\_in\_background: false):** `"completed"` on success. Final assistant message from the sub-agent. **Asynchronous (run\_in\_background: true):** `"async_launched"`. ID of the launched background agent; use with `TaskOutputTool` to retrieve results. ### Example ```json theme={null} { "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 Short title for the task. Detailed description of what the task involves. Arbitrary key-value metadata attached to the task. ### Return value Unique task ID. Task title. *** ## TaskGetTool Retrieve a task's current status, description, and dependency information. **Tool name:** `TaskGet`\ **Gate:** Requires `isTodoV2Enabled()`. ### Parameters ID of the task to retrieve. ### Return value `null` if no task with that ID exists. Task ID. Task title. Full description. Current status: `pending`, `in_progress`, `completed`, `failed`, or `killed`. Task IDs that this task blocks. 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 ID of the task to update. New status. Use `"deleted"` to remove the task entirely. Valid values: `"pending"`, `"in_progress"`, `"completed"`, `"failed"`, `"killed"`, `"deleted"`. Updated title. Updated description. Task IDs that this task should now block. Task IDs that now block this task. Assign ownership to an agent name. Updated metadata. ### Return value Whether the update succeeded. ID of the updated task. List of field names that changed. Present when status changed: `{ from, to }`. 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 Task ID. Task title. Current status. Assigned agent, if any. 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 ID of the task to stop. Returned when a task was launched with `run_in_background: true`. ### Return value Confirmation message. ID of the stopped task. 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 ID of the task to read output from. When `true`, wait until the task reaches a terminal state before returning. Maximum wait time in milliseconds when `block` is `true`. Range: 0–600 000 ms. ### Return value `"success"`, `"timeout"`, or `"not_ready"`. `null` when `retrieval_status` is not `"success"`. Task ID. Terminal status: `completed`, `failed`, or `killed`. Task description. Captured output text. Exit code for bash tasks. Final message text for agent tasks. 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 Recipient address: * Agent name (in-process or mailbox) * `"*"` to broadcast to all agents * `"uds:"` for a Unix domain socket * `"bridge:"` for a cross-machine bridge (requires user consent) 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 }` Short summary shown in the UI activity feed. ### Notes * Bridge messages (`bridge:`) 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 Standard 5-field cron expression in local time: `"M H DoM Mon DoW"` (e.g. `"0 9 * * 1-5"` for weekdays at 9 AM). The prompt to enqueue at each scheduled fire time. `true` — fire on every matching cron time (auto-expires after the configured max-age).\ `false` — fire once then auto-delete. `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 Job ID for use with `CronDelete` and `CronList`. Human-readable schedule description (e.g. `"Every weekday at 09:00"`). Whether the job recurs. 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 Job ID. Cron expression. Human-readable schedule. Prompt that fires on schedule. Whether the job recurs. 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 Job ID returned by `CronCreate`. ### Return value 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 Name of the skill to invoke, or `"list"` to enumerate available skills. The name maps to a `.md` file in the commands directory. Arguments to substitute for `$ARGUMENTS` in the skill template. ### How skills work 1. Claurst resolves `.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 1–4 questions to ask. Each question has: The question text. Optional header displayed above the question. 2–4 answer options. Each option has `label`, `value`, and optional `description`. Allow selecting multiple options. ### Return value The original questions. 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 Search query. Use `"select:"` for exact lookup (e.g. `"select:WebFetch"`), or plain keywords for fuzzy search (e.g. `"search files"`). Maximum number of tools to return. ### Return value Tool names that matched the query. The query that was run. Total number of deferred tools available to search. MCP servers still loading whose tools are not yet searchable. ### How scoring works | Match type | Score | | --------------------------- | -------------------------------------- | | `select:` 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:`, the full tool schema is injected into the conversation context as a `tool_reference` block.