[DOCS] Document the Agent tool for local subagents

[inference-gateway-maintainer]

Summary

The CLI shipped a new first-class Agent tool that lets the main agent (chat or headless) spawn one or
more local subagents to run work in parallel and fold their results back into the main context, without
standing up an A2A agent server. A subagent is just an infer agent subprocess with its own isolated
session, so it is cheap, isolated, and session-persisted.

This is the lightweight, local complement to the existing A2A trio (A2A_SubmitTask / A2A_QueryTask /
A2A_QueryAgent), which targets external A2A servers.

• Implemented in CLI: [FEATURE] Local subagents via an Agent tool - parallel headless + interactive tmux panes cli#653 (PR feat(tools): add Agent tool for local subagents cli#658).
• This ticket tracks the user-facing documentation for it.

What needs documenting (user-facing)

1. The Agent tool

A config-gated tool (enabled by default) that fans out local subagents. Document:

• What it is and when to reach for it vs. the A2A tools (local short-lived helpers vs. external A2A servers).
• The tool parameters the model sees:
  • tasks: an array of subagent tasks run in parallel, each with:
    • description (required) - the task for the subagent
    • label (optional) - short label shown in progress output / tmux panes
    • model (optional) - per-subagent model override
    • system_prompt (optional) - gives that subagent a specialized role/persona
  • description (optional) - shorthand for a single-task call (alternative to tasks)
  • system_prompt (optional) - system prompt for the single-description form
• Each subagent runs in its own isolated session id of the form subagent-<parentSession>-<uuid>.
• Parallel fan-out is capped by max_parallel (default 4) concurrent subagents per call.

2. Result modes (async by default, plus blocking wait-all)

• Async (default): the call returns immediately with subagent ids; when each subagent finishes, its final
  result is injected back into the main conversation (mirrors A2A_SubmitTask notify behavior). In chat,
  running/completed status is surfaced in the sticky progress area.
• Wait-all (wait: true): the call blocks until every spawned subagent reaches a terminal state, then
  returns the aggregated results in one tool result. This is the default in the shipped config.

3. Execution surfaces: headless vs. interactive (tmux)

• headless: subagents run in the background; results aggregate back into the main context.
• interactive: each subagent runs in a live tmux pane/window you can watch while it works; the result
  still aggregates back exactly as in headless mode (interactive is "headless plus a tmux pane attached to
  the live process").
• tmux is an optional runtime dependency, required only for interactive mode (not for headless). Document
  that interactive mode must be run from inside tmux ($TMUX set).
• Graceful degradation when not inside tmux (or tmux not installed) is configurable: fallback: headless
  (warn and run headless) or fallback: error.

4. Configuration block: tools.agent.*

Document the new config block with the shipped defaults (note: the default mode shipped as
interactive):

tools:
  agent:
    enabled: true
    require_approval: true     # spawning work that can edit files is a mutating action
    mode: interactive          # headless | interactive (default when a call omits it)
    wait: true                 # block and return aggregated results by default
    max_parallel: 4            # cap on concurrent subagents per call
    max_depth: 1               # recursion guard; a subagent is itself an `infer agent`
    model: ""                  # default subagent model (inherits parent if blank)
    interactive:
      multiplexer: tmux        # tmux only
      layout: vertical         # vertical | horizontal | window
      fallback: headless       # headless | error (when not inside tmux)

Also document the corresponding env-var overrides (INFER_TOOLS_AGENT_*) consistent with the rest of the
config, and that this block is regenerated by infer init.

5. New flag: infer agent --result-file <path>

infer agent gained a --result-file flag that atomically writes the final assistant message and the
run outcome as JSON to the given path on exit. It is used by the Agent tool to harvest the result of a
detached (tmux pane) subagent. Worth a short mention in the infer agent command reference.

6. Approval and security behavior

• Subagents run in standard bash mode (the restricted allow-list), exactly like every other headless run.
• The Agent tool is in the approval policy and requires approval by default (require_approval: true),
  with a per-tool override - consistent with A2A_SubmitTask.
• Subagents honor the existing approval-delivery resolution (prompt / ipc / block), so they remain
  secure by default: an off-list or mutating action is blocked in CI/heartbeat (no approver reachable) and
  sent for IPC approval under a channel (e.g. Telegram).
• A depth guard (max_depth, default 1) prevents subagent fork-bombs: a subagent cannot itself spawn
  further subagents at the default cap.

7. Note on the dangling "Task tool" references

prompts.yaml previously referenced a non-existent "Task tool"; those references now point at the real
Agent tool. If the docs mirror any of those prompt descriptions, they should be updated to "Agent" too.

Suggested affected docs pages

• The CLI tools reference (the page that documents the built-in tools alongside the A2A tools).
• The CLI configuration reference (add the tools.agent.* block and its env-var overrides).
• The infer agent command reference (the --result-file flag).
• Any "delegation / multi-agent" or A2A overview page, to contrast local subagents with A2A servers and to
  mention tmux as an optional dependency for interactive mode.

Out of scope (matches the v1 implementation)

• Nested subagents (depth capped at 1 for v1).
• Routing a subagent's tool-approval prompt back to the main chat TUI.
• Non-tmux multiplexers (screen, zellij) and a /agent chat shortcut.

References

• CLI feature issue: [FEATURE] Local subagents via an Agent tool - parallel headless + interactive tmux panes cli#653
• CLI implementation PR: feat(tools): add Agent tool for local subagents cli#658

[edenreich]

@claude Can you document it?

[inference-gateway-maintainer]

Claude finished @edenreich's task in 8m 50s —— View job • docs/issue-283-20260627-0228 • Create PR ➔

---

Documenting the Agent tool for local subagents

Done. Opened PR #284 with the docs.

• Read the issue and gather repo context
• Map the affected docs pages and their conventions
• Document the Agent tool in the CLI tools reference (cli.md)
• Add the tools.agent.* config block + env-var overrides (cli.md)
• Document infer agent --result-file in the command reference
• Contrast local subagents vs. A2A on the A2A page (a2a.md)
• Lint + format + build, then commit and open a PR

What changed

cli.md

• New Local Subagents (Agent tool) section: what it is and when to use it vs. the A2A tools, the tasks / description / label / model / system_prompt parameters, the subagent-<parentSession>-<uuid> session ids, and the max_parallel cap.
• Both result modes (async injection vs. the shipped wait: true blocking aggregation).
• Headless vs. interactive (tmux) execution surfaces, the $TMUX requirement, and fallback: headless | error.
• The full tools.agent.* config block with shipped defaults, the INFER_TOOLS_AGENT_* env-var override table, and the infer init regen note.
• Approval and security (standard bash mode, require_approval: true, IPC/block delivery, max_depth fork-bomb guard) plus a v1-scope note.
• A infer agent --result-file <path> subsection under Headless Agent Stream Output.
• Added a Local Subagents row to the Tool Categories table.

a2a.md

• New Local Subagents vs. A2A Agents section contrasting local subprocess subagents with external A2A servers, noting tmux as an optional dependency, cross-linked to the CLI section.

Notes

• The CLI's own config is documented inline in cli.md; configuration.md is the gateway/server reference, so tools.agent.* correctly lives in cli.md, not there.
• No "Task tool" references exist in the docs, so item 7 needed no changes.
• Verified locally: lint:md, format:check, and the VitePress build all pass; the new heading anchors and the a2a.md -> /cli/#local-subagents-agent-tool cross-link resolve in the generated HTML.

| Branch: docs/issue-283-20260627-0228