Grok tasks, goals, and scheduled work

This page describes the Grok Build dialect. These tool names are not universal. Scheduler, goal and workflow tools are root-session capabilities rather than tools offered recursively to every child. Check the active catalog before requesting them.

Background commands

run_terminal_cmd requires command and description. Optional timeout controls the command deadline; background: true returns a task identifier. Shell escalation uses sandbox_permissions and justification, independently of the background setting.

{"command":"git status --short","description":"Inspect the checkout without changing it","background":false}

A background task is still running after its initial tool call returns. Completion is reported automatically; use the tools below for one bounded wait or an inspection, not a loop of polling calls. An exit code, not the mere creation of a task, establishes completion.

Tool | Inputs | Behavior | 

get_task_output | task_ids array; optional timeout_ms | Omitted/0 timeout gives a snapshot; positive timeout waits for completion, capped at 600,000 ms | 

wait_tasks | task_ids, mode of wait_any or wait_all; optional timeout_ms | Wait for first/all completion, capped at 600,000 ms | 

kill_task | Required task_id | Stops the addressed background work; it does not reverse completed file or service changes | 

{"task_ids":["REPLACE_WITH_RETURNED_TASK_ID"],"timeout_ms":1000}

Do not substitute a persisted conversation ID for a Grok task ID. If a task is missing, inspect the original launch result and current session rather than starting duplicate work.

Typed subtasks

task requires prompt and description. Optional subagent_type selects general-purpose, explore or plan; types can restrict the child's tool set. Additional fields are run_in_background, resume_from, cwd, model, and isolation (none or worktree).

{"prompt":"Locate the configuration parser and report its file path; do not edit files.","description":"Find the configuration entry point","subagent_type":"explore","run_in_background":true,"isolation":"none"}

The task description should name an independently verifiable result. A worktree isolates files, not external credentials or remote effects. Model selection must satisfy the host policy. Inspect output, review changes and run checks before integrating a child's result.

Event monitors

monitor runs a command with a required description. Each stdout line becomes an event; process exit ends the watch. Print meaningful state changes and use line-buffered pipelines to avoid delayed events. The optional timeout_ms defaults to and is capped at 36,000,000 (10 hours). persistent: true instead watches for the session lifetime.

Record the returned task identifier and stop it with the available task-control tool when finished. A monitor is an executing program: it needs the same command review as an ordinary shell invocation. It is not a durable service that survives the session.

Bounded autonomous goals

/goal Investigate the failing test and propose a minimal correction --budget 10

Use /goal status to inspect progress, /goal pause to pause, /goal resume to continue and /goal clear to remove the objective. Choose a bounded objective; do not interpret a budget as permission to perform unrelated changes. The positive integer budget is an advisory token budget, not money or an enforced spending cap. This runtime stores goal state in memory, not a durable scheduler; do not assume restarting restores it. Check status before resuming work.

The model's update_goal accepts optional message, completed and blocked_reason. Completion ends goal mode. A blocked reason pauses it; the model should report repeated failed attempts rather than loop indefinitely. Updating an absent or inactive goal is rejected. A model's completion report must still be checked against the actual requested result.

Recurring prompts

scheduler_create creates a recurring task with interval and prompt. Intervals include 60s, 5m, 2h and 1d; minimum 60 seconds. At most 50 schedules exist and they expire after seven days. fire_immediately defaults to false.

{"interval":"5m","prompt":"Inspect the explicitly agreed build status and report only changes. Do not modify files or publish anything.","fire_immediately":false}

Supply an existing task_id to update its interval or prompt in place; omitted fields remain unchanged. scheduler_list inspects schedules and scheduler_delete removes the selected schedule using its required id field. Listing takes no arguments and reports identifiers, prompts, intervals and next-fire times. If deletion reports an unknown identifier, list again instead of guessing. Deletion stops future fires, not already-completed effects.

This host supports session-only, detached child-agent fires.durable: true, foreground: true and one-shot scheduling are rejected. Closing the session is not a way to keep scheduled work running. Deleting a schedule is not evidence that effects from earlier fires were undone; inspect active tasks and relevant external state before declaring cleanup complete.

Named research workflow

The current host provides deep-research. The workflow tool accepts name, args (a string or an object with query or objective) and validate_only.

{"name":"deep-research","args":{"query":"Compare the public compatibility requirements of the two proposed libraries"},"validate_only":true}

Validate before launching; then explicitly request execution with validate_only: false. Use /workflow runs to inspect runs or /workflow deep-research QUESTION to launch from the prompt.

Although present in the dialect schema, custom agent_budget, inline script, script_path and resume_from_run_id are unsupported by this host. This is not a general Rhai execution service. Research results require source review; availability of a workflow does not establish the reliability of every external source it reads.