AGENTS.md@packages/senpi-task/src/tools/task git:20261010.03c01fbA

Immutable. This exact content never changes and is served at /api/v1/blob/3b12edd305d3c8d7.

# tools/task - The `task` Tool

Single or `tasks:[...]` batch spawn of child tasks routed by category or agent. Tool contracts, plan-gated agents, and batch semantics live in the package AGENTS.md; this file maps the modules and the validation rules. 54 files, the largest tool subtree.

## Anatomy

| Path | Purpose |
|------|---------|
| `tool.ts` | `createTaskTool` / `TASK_TOOL_NAME` (`"task"`). |
| `params.ts` | TypeBox `TaskToolParams`; batches have no per-call size cap - items beyond the run limit queue in `TaskConcurrency`. Prompts MUST be English; `prompt` XOR `tasks`. |
| `argument-normalization.ts` | Batch item inheritance from top-level params; empty provider padding normalized before validation; item-level `run_in_background` mirrors survive. |
| `validation.ts` | `validateTaskTarget`, `resolveSpawnItems`, `validateBatchShape`, `resolveRunInBackground`; codes `both_targets` / `no_target` / `category_with_model` / `run_in_background_conflict`. |
| `categories.ts` / `description.ts` | Category/agent discovery and prompt description builders (plan-gated names get their own line). |
| `execute.ts` | Entry: shape validation -> item resolution -> single/batch dispatch. |
| `execute-single.ts` / `execute-batch.ts` / `execute-spec.ts` | Single spawn, batch aggregation (start/error/background/foreground), start-spec construction. |
| `batch-item-details.ts` / `batch-progress.ts` | Per-item result details for batches; throttled per-child progress partials for a foreground batch (one status row per child). |
| `foreground-wait.ts` | Foreground wait surface. |
| `invocation-gate.ts` / `plan-review-contract.ts` | plan-consultant/plan-reviewer plan-gate consult before `manager.start` (single: `denied`; batch item: `plan_unresolved` / `invalid_target`). |
| `spawn-policy.ts` | `evaluateSpawnPolicy` verdicts. |
| `skills.ts` / `skill-result.ts` | Skill loading/prepend + task skill summaries. |
| `renderers.ts` / `call-renderer.ts` / `start-presentation.ts` / `result-details.ts` | Result rendering and details; package subpath `./task-renderers` points at `renderers.ts`. |
| `types.ts` | Contract hub: `TaskToolContext`, `TaskAncestry`, `TaskToolDeps`, `ResolvedSpawnItem`, `TaskToolDetails`. |

## Conventions

- Pure-ish `run*` functions + `create*Tool` adapters; runtime seams injected via `TaskToolDeps` / `TaskToolContext` (tests use `__fixtures__/task-tool-fakes.ts`).
- Every effective spawn has exactly one target after batch inheritance; an effective category item carries no own or inherited model.
- `run_in_background` is batch-wide: the top-level value and every item-level mirror must agree (`resolveRunInBackground`); agreement is hoisted, disagreement is `invalid_arguments`.
- Validation hard-fails invalid targets with the fix named in the message; fields are never silently ignored.

## Anti-patterns

- NEVER combine `category` with `subagent_type`; NEVER combine category routing with `model` (a call-site override would bypass `categories.<name>.models` routing).
- Batches are uncapped per call: admission is governed only by `TaskConcurrency` lane/global limits, with items beyond the limit queued. Never reintroduce a per-call size cap in the schema or the execution path.
- New spawn paths must consult the invocation gate; both single and batch routes do.

## QA

```sh
bun test packages/senpi-task/src/tools/task
```

Parent: [`../../../AGENTS.md`](../../../AGENTS.md).