{
  "access": "public",
  "type": "reference",
  "format": "markdown",
  "title": "Tasks Tools Reference",
  "chunked": true,
  "url": "https://library.datagrout.ai/tasks-tools",
  "summary": "The Tasks suite gives agents a durable control plane for long-running work. When a tool call is promoted to the background, DataGrout returns a `task_ref` instead of forcing the caller to wait inline. The Tasks tools let the caller poll, reattach briefly, inspect, retrieve, and cancel that work.",
  "content_markdown": "# Tasks Tools\n\nThe Tasks suite gives agents a durable control plane for long-running work. When a tool call is promoted to the background, DataGrout returns a `task_ref` instead of forcing the caller to wait inline. The Tasks tools let the caller poll, reattach briefly, inspect, retrieve, and cancel that work.\n\n## Why it exists\n\nAutonomous systems regularly trigger work that may outlive a single MCP response:\n\n- multi-step plans that need more than one round-trip\n- slow upstream APIs\n- workflows waiting on approval or feedback\n- jobs intentionally detached from the inline response path\n\nRather than losing that work, DataGrout persists a task record and exposes it through five first-party tools.\n\n## Tools\n\n### `tasks.status`\n\nCheck the current state of a task by `task_ref`.\n\nUse it when:\n\n- you want to know whether a promoted task is still running\n- you need the current status message or poll interval\n- you want to confirm whether the task finished, failed, or was cancelled\n\nExample:\n\n```json\n{\n  \"name\": \"data-grout@1/tasks.status@1\",\n  \"arguments\": {\n    \"task_ref\": \"task_abc123\"\n  }\n}\n```\n\n### `tasks.wait`\n\nWait up to a bounded window for a task to finish.\n\nUse it when:\n\n- you want a reattach-like experience without committing to pure polling\n- the task might complete soon, but you still need to stay under MCP/client timeout ceilings\n- you want either the terminal result or a fresh in-progress snapshot in one call\n\nExample:\n\n```json\n{\n  \"name\": \"data-grout@1/tasks.wait@1\",\n  \"arguments\": {\n    \"task_ref\": \"task_abc123\",\n    \"wait_ms\": 25000\n  }\n}\n```\n\n### `tasks.list`\n\nList recent background tasks for the current server context.\n\nUse it when:\n\n- you lost the original response but want to rediscover active tasks\n- you want to review recent background activity\n- you want to locate a task before calling `tasks.status` or `tasks.result`\n\nExample:\n\n```json\n{\n  \"name\": \"data-grout@1/tasks.list@1\",\n  \"arguments\": {}\n}\n```\n\n### `tasks.result`\n\nFetch the final result payload for a completed task.\n\nUse it when:\n\n- `tasks.status` shows the task is completed\n- you want the background result without re-running the original tool\n\nExample:\n\n```json\n{\n  \"name\": \"data-grout@1/tasks.result@1\",\n  \"arguments\": {\n    \"task_ref\": \"task_abc123\"\n  }\n}\n```\n\n### `tasks.cancel`\n\nCancel a running background task.\n\nUse it when:\n\n- the user no longer wants the result\n- the task is stale or no longer relevant\n\nExample:\n\n```json\n{\n  \"name\": \"data-grout@1/tasks.cancel@1\",\n  \"arguments\": {\n    \"task_ref\": \"task_abc123\"\n  }\n}\n```\n\n## MCP timeout promotion\n\nThe MCP gateway can automatically promote work to a background task shortly before the protocol timeout wall. In that case, the inline response includes a `task_ref` and points agents toward `tasks.wait` for ergonomic reattach, while keeping `tasks.status` and `tasks.result` as the canonical explicit polling APIs.\n\nTypical flow:\n\n1. Call a long-running tool.\n2. Receive a response saying the work was moved to the background, with a `task_ref`.\n3. Reattach with `tasks.wait`, or poll with `tasks.status`.\n4. Call `tasks.result` when the task is complete.\n\n## Composing with other suites\n\n- Use with `flow.into` when a workflow may outlive a single inline response.\n- Use with `discovery.perform` when an execution plan is promoted to background work. Task-monitoring reads routed through `discovery.perform` are fast-pathed so intelligent-interface clients can reattach cheaply without tripping duplicate-call protections.\n- Use with `scheduler` and `governor` to inspect or cancel long-lived autonomous activity from another session.\n"
}