[DOCS] `TaskStop` and `TaskOutput` documentation does not mention cross-agent lookup or that lookup errors now list running agents by id and description (fixed in v2.1.203)

Open 💬 0 comments Opened Jul 7, 2026 by coygeek

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

The TaskOutput and TaskStop rows of the tools table (around the SendMessage/Skill/TaskCreate block in the alphabetical list), and the matching TaskOutput and TaskStop entries in the Agent SDK tool reference for TypeScript.

Current Documentation

From the tools table at https://code.claude.com/docs/en/tools-reference:

| TaskOutput | (Deprecated) Retrieves output from a background task. Prefer Read on the task's output file path | No |
| TaskStop | Stops a running background task by ID. {/ min-version: 2.1.198 /}As of v2.1.198, also accepts an agent-team teammate or a named background agent by agent ID or name | No |

The Agent SDK TypeScript tool reference describes the same two tools like this at https://code.claude.com/docs/en/agent-sdk/typescript#taskoutput and .../typescript#taskstop:

### TaskOutput

**Tool name:** `TaskOutput`

type TaskOutputInput = {
  task_id: string;
  block: boolean;
  timeout: number;
};

Retrieves output from a running or completed background task.

### TaskStop

**Tool name:** `TaskStop`

type TaskStopInput = {
  task_id?: string;
  shell_id?: string; // Deprecated: use task_id
};

Stops a running background task or shell by ID. {/* min-version: 2.1.198 */}As of v2.1.198, `task_id` also accepts an agent-team teammate or a named background agent by agent ID or name.

The v2.1.198 note ("accepts an agent-team teammate or a named background agent by agent ID or name") implies that the lookup reaches beyond the current conversation, but neither row says so explicitly and neither row describes what happens when no matching id or name is found.

What's Wrong or Missing?

A. The cross-agent visibility behavior changed in v2.1.203 and is not reflected in the docs

The v2.1.203 changelog records:

Fixed TaskStop and TaskOutput failing to find background agents spawned by another agent — errors now list running agents by id and description

Before v2.1.203, TaskStop and TaskOutput could resolve a background agent spawned by the same conversation that is calling them but failed to resolve an agent spawned by a different agent (such as a peer subagent the calling session only learned about through SendMessage, agent-team coordination, or a workflow step). The v2.1.198 note in tools-reference.md ("also accepts an agent-team teammate or a named background agent by agent ID or name") reads as if cross-agent lookup always worked, so the current text is misleading.

B. The post-fix error contract is a new, observable behavior the docs never described

After v2.1.203, when TaskStop or TaskOutput cannot resolve the supplied task_id/agent_id, the tool error now lists the running agents by id and description. That gives Claude a recovery path: re-read the agent list, pick the right id, and retry. Before v2.1.203 the failure surface offered no such hint, so an agent that misnamed its target kept retrying the same id and timed out. Neither the tools table row nor the Agent SDK TypeScript reference mentions this error shape, and there is no entry on either page describing the cross-agent lookup itself.

C. Both surfaces leave readers unable to recover from unmatched-agent lookup failures

A Claude agent or a developer reading these references has no documented signal that the failure mode is recoverable, has no documented hint that the error now names other running agents, and has no documented scope note clarifying which background agents the tool can actually see. The current text is consistent with the pre-fix behavior, which is exactly what the v2.1.203 changelog entry exists to invalidate.

Suggested Improvement

Update the TaskStop row in tools-reference.md so the description matches the v2.1.198 lookup scope plus the v2.1.203 cross-agent fix and the new error contract:

Before:

TaskStop | Stops a running background task by ID. {/ min-version: 2.1.198 /}As of v2.1.198, also accepts an agent-team teammate or a named background agent by agent ID or name | No |

After:

TaskStop | Stops a running background task by ID. {/ min-version: 2.1.198 /}As of v2.1.198, also accepts an agent-team teammate or a named background agent by agent ID or name. {/ min-version: 2.1.203 /}As of v2.1.203, the lookup reaches background agents spawned by another agent in the same session, not only those spawned by the calling conversation. If the supplied id or name does not match a running task, the error lists the currently running agents by id and description so the caller can correct the id | No |

Update the matching TaskOutput row in the same way, preserving the deprecation note but adding the v2.1.203 cross-agent and error-contract clarifications:

Before:

TaskOutput | (Deprecated) Retrieves output from a background task. Prefer Read on the task's output file path | No |

After:

TaskOutput | (Deprecated) Retrieves output from a background task. Prefer Read on the task's output file path. {/ min-version: 2.1.203 /}As of v2.1.203, the task_id lookup reaches background agents spawned by another agent in the same session. If the id does not match, the error lists the currently running agents by id and description | No |

Mirror the same change in the Agent SDK TypeScript reference at https://code.claude.com/docs/en/agent-sdk/typescript for both TaskStop (### TaskStop) and TaskOutput (### TaskOutput), including the agent-id resolution note and the new error-message format in the prose paragraph after each type definition.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/tools-reference | TaskOutput and TaskStop rows in the tools table |
| https://code.claude.com/docs/en/agent-sdk/typescript | ### TaskOutput and ### TaskStop tool descriptions |

Total scope: 2 pages affected.

The v2.1.203 changelog notes the change as a fix, not a feature, so the docs should treat it as a correction to existing TaskStop/TaskOutput descriptions rather than a new tool surface. The agent-sdk/python reference does not currently document TaskStop or TaskOutput as standalone tools, but it does mention TaskStop in passing (# Run for the lifetime of the session; stop with TaskStop); if that reference grows tool entries in the future, the same prose should be mirrored there.

View original on GitHub ↗