Sub-agents
Named workers with their own prompt, toolset and model - and the switch that decides whether one starts from the conversation
Foxl can hand a piece of work to a sub-agent - an independent session that runs while the main conversation carries on. Up to 5 run concurrently, and they are always asynchronous.
A sub-agent is not one fixed kind of worker. It is a definition you write:
| Part | What it decides |
|---|---|
| Prompt | The instructions this worker runs under. |
| Tools | Exactly which tools it may use - never more than the app allows. |
| Model | Optionally pin a model, instead of following the conversation's. |
| Inherit conversation context | Whether it starts already knowing the conversation, or from a clean slate. |
You manage them on the Agents screen, under the Subagents tab. The run history that used to be this whole screen is on the second tab, and the screen remembers which one you were on.
The three that ship
| Definition | Inherits context | For |
|---|---|---|
| general-purpose | Yes | Anything. This is what a delegation that names no type runs. |
| researcher | No | Reading and searching, with nothing that writes. |
| code-reviewer | No | Reading code and reporting on it, with no shell. |
Edit them, duplicate them, or write your own. A restore button brings back any starter you deleted without touching the ones you changed.
There is only one kind of sub-agent run. A spawn that names no type resolves
to general-purpose, so the prompt, the toolset and the model you set there
are the ones that actually run - editing it changes the case that comes up
most.
Inherit conversation context
This is the switch that decides where a sub-agent starts.
On - it starts already knowing the conversation and shares the main agent's cached prompt, so handing it work is much cheaper and you do not have to brief it from scratch. The main agent is told which sub-agents already have the context, so it stops re-explaining.
Off - it starts fresh from the task alone, and uses its own prompt, its own narrower toolset and its own model.
A sub-agent cannot both inherit the conversation and hold a reduced toolset.
Sharing the cache means running on the same tools and the same model, so
turning inheritance on gives up tools, model and the prompt replacement -
its prompt is delivered as part of the task instead. The editor says so
wherever it applies.
general-purpose ships with inheritance on, which is exactly how untyped
delegation already behaved, so nothing gets more expensive. The read-only
researcher and code-reviewer ship with it off, so their restrictions
still bite. An existing install keeps whatever you have chosen.
A definition can only ever narrow
The per-tool switches on the Tools page stay the final word. A definition narrows what an agent may do and can never widen it, so turning a tool off there switches it off for every sub-agent regardless of what any definition asks for. The same is true of the approval rules: a definition cannot grant a sub-agent a tool you have denied.
A definition that names a tool which is currently unavailable - switched off, or waiting on a skill or a dependency - says so in the editor and keeps the setting rather than quietly dropping it. That matters because "unknown right now" is a normal state: some tools are gated on a connected account, and custom tools come and go.
The editor prints the count as "2 of 3", never "3", for the same reason - the number of tools it actually gets, not the number it asked for.
Where definitions live
One JSON file per definition:
~/.foxl/agents/<name>.jsonThe filename is the name, so they can be hand-edited, diffed, and sent to someone else. The name is fixed once created - to rename one, duplicate it and delete the original.
The tools the agent uses
| Tool | Description |
|---|---|
| sessions_spawn | Start a sub-agent. Takes agentType to pick a definition by name; omit it and general-purpose runs. |
| sessions_status | Check progress of running sub-agents. |
| sessions_stop | Terminate a running sub-agent. |
| sessions_message | Send a running sub-agent a message - extra context or a correction - without stopping it. |
The main agent sees the roster with your description of each one, and picks by name when it delegates. When every sub-agent has finished, Foxl automatically continues the conversation to synthesise what came back.
What a delegation costs
A chat's usage now includes the sub-agents it spawned. The status HUD's This chat panel has a Delegated line naming those tokens and how many sub-agents produced them, while the context bar keeps showing only the chat's own fill - a sub-agent's prompt is not sitting in your window, which is the point of delegating.
Use cases
Parallel research
"Research these 3 competitors and compile a comparison"
Three researcher sub-agents, one per competitor, none of which can write
anything.
Review without a shell
"Review the changes on this branch"
code-reviewer reads the code and reports. Giving it no shell means the review
cannot become an edit.
Multi-file code changes
"Refactor the authentication module"
general-purpose workers on different files, each already knowing what the
conversation decided.
Limitations
- Maximum 5 concurrent sub-agents.
- Sub-agents cannot spawn their own sub-agents.
- A sub-agent that does not inherit context has its own context window, separate from the main conversation.
- Definitions and runs live on the desktop, so the Subagents screen needs a reachable desktop - it works from a phone or the web app over the desktop relay.