Multi-agent (the task tool)

The model can call task({ description, prompt }) to spin up a fresh sub-agent with its own tool registry and its own conversation. The sub-agent runs to completion and reports a summary back - only that summary re-enters the parent’s context, not the sub-agent’s full transcript.

This is useful for work that would otherwise bloat the main context: “search the codebase for every place X is configured and summarize”, “read these five files and tell me which one has the bug”.

For a sub-agent you define and name yourself - with its own system prompt, tool allowlist, and model - see Agent definitions. Those run on the same machinery described here.

Sub-agent model

By default a sub-agent runs on the same model as the parent. Set subAgentModel in settings.json (or POLYGLOT_SUB_AGENT_MODEL) to a model id/label - matched against models[] the same way /model <query> is - and every task sub-agent runs on that instead. Delegated work is usually mechanical (grep the repo, read files, summarise), so a smaller, cheaper model handles it fine:

{ "model": "claude-sonnet-5", "subAgentModel": "claude-haiku-4-5" }

The sub-agent’s token usage still rolls up into the session totals, so /cost and the -p --output-format json envelope show it as its own per-model row.

Bounds

• Off by default for weak models - task is only offered when the active model has reliable native tool-calling: on for anthropic, off for openai-compatible. A small local model that delegates to itself mostly just burns turns. Force it either way with "subAgents": true / false in settings or POLYGLOT_SUB_AGENTS.
• Spawn cap per turn - at most 3 sub-agents are spawned per user turn (across all steps). Once the budget is spent, further task calls return an error telling the model to do the work directly. This bounds cost even for a capable model that over-delegates.
• Depth limit - sub-agents can themselves call task, up to a hard depth of 3 by default. At the limit, the task tool simply isn’t offered to that sub-agent, so recursion can’t run away.
• Concurrency - multiple task calls emitted in a single model turn run concurrently.
• Permissions - sub-agents share the parent’s permission gate; a sub-agent can’t do anything the parent couldn’t. Hooks and secret scanning apply to a sub-agent’s tool calls too.
• Persistence - sub-agent conversations are in-memory only; they’re never written to ~/.polyglot/sessions/.