AIWorkhub

Overview Schema Source Related Servers Discussions Admin

aiworkhub_agent_launch_task

Launches one validated local Claude or Codex worker process for a pending task card, after dual approval checks on writes, runner, topic, adapter, and collision guard.

Instructions

DUAL-GATED: launch one exact local Claude/Codex worker process.

Requires both AIWORKHUB_ALLOW_LAUNCH=1 and AIWORKHUB_ALLOW_WRITES=1. The task card, runner, topic, pending state, allowed-write scope, collision guard, adapter, and process limit are all validated before a shell-free child process can start. timeout_seconds is retained only as non-enforcing compatibility metadata; this API never installs a provider wall-clock deadline.

runner, topic and adapter_id are optional because the server already owns them: the card carries runner and topic (the launcher refused any value that differed, so typing them asserted rather than decided), and the adapter is a pure function of the runner narrowed to the first pinnable, policy-allowed entry in canonical tuple order. Omit them and the reply's launch_identity_derivation records exactly what was derived; pass them and the explicit value wins and is validated as before. The manager identity codex is never a worker runner.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "task_id": "<task_id>"
    },
    "name": "aiworkhub_agent_launch_task"
  }
}

Input Schema

Name	Required	Description
`model`	No	Optional model override for the worker; omit to use the adapter default.
`topic`	No	Topic of the card; omit to use the card's topic (a differing value is refused).
`runner`	No	Runner that works the card; omit to use the card's runner (a differing value is refused). The manager identity codex is never a worker runner.
`task_id`	Yes	Id of the pending task card to launch a worker for.
`adapter_id`	No	Adapter that runs the worker; omit to derive it from the runner (first pinnable, policy-allowed adapter). An explicit value wins and is validated.
`owner_prompt`	No	Optional extra instructions from the launching owner for the worker; default empty.
`timeout_seconds`	No	Compatibility metadata only, default 7200; no provider wall-clock deadline is enforced and the value is echoed in the reply.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.12.67Oct 26, 2026

addedInput schema / properties / adapter_id / description

Added value: +"Adapter that runs the worker; omit to derive it from the runner (first pinnable, policy-allowed adapter). An explicit value wins and is validated."

addedInput schema / properties / model / description

Added value: +"Optional model override for the worker; omit to use the adapter default."

addedInput schema / properties / owner_prompt / description

Added value: +"Optional extra instructions from the launching owner for the worker; default empty."

addedInput schema / properties / runner / description

Added value: +"Runner that works the card; omit to use the card's runner (a differing value is refused). The manager identity codex is never a worker runner."

addedInput schema / properties / task_id / description

Added value: +"Id of the pending task card to launch a worker for."

addedInput schema / properties / timeout_seconds / description

Added value: +"Compatibility metadata only, default 7200; no provider wall-clock deadline is enforced and the value is echoed in the reply."

addedInput schema / properties / topic / description

Added value: +"Topic of the card; omit to use the card's topic (a differing value is refused)."

First observedv0.1.0Oct 20, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses that this is a dual-gated launch requiring environment variables and multiple validation checks before a shell-free child process starts. It also clarifies that timeout_seconds is non-enforcing compatibility metadata and explains how omitted runner/topic/adapter_id values are derived, which is substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The dual-gated requirement is front-loaded and the information is relevant, but the description is dense and somewhat verbose, with long parenthetical explanations around parameter derivation. It remains useful and structured, but is not maximally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and full schema description coverage, the description provides all the additional context an agent needs: environment prerequisites, validation behavior, launch identity derivation, and the non-enforcing timeout. No critical launch behavior appears omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema already has 100% description coverage, the description adds important meaning: runner, topic, and adapter_id are optional because the server derives them from the card and runner, omitted values are recorded in launch_identity_derivation, explicit values win and are validated, and codex is never a worker runner. It also explicitly clarifies that timeout_seconds is not enforced.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'launch one exact local Claude/Codex worker process' for a pending task card. It clearly distinguishes this from task creation, status, cancellation, and other manager tools by tying the action to an exact worker process for a specific task_id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives strong usage context: both AIWORKHUB_ALLOW_LAUNCH=1 and AIWORKHUB_ALLOW_WRITES=1 are required, and the card, runner, topic, pending state, allowed-write scope, collision guard, adapter, and process limit are validated before launch. It does not explicitly name alternative sibling tools or when-not-to-use cases, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server