Subagents
Common Scenarios
Use a subagent boundary mainly in these cases:
- A shell command is slow or noisy, and you want its output isolated from the parent loop.
- The work is still multi-step, but you want the inner execution to operate with a narrower tool set.
- You want one compact final result instead of leaking raw intermediate output back to the parent.
- The child work should run in the local Codex, Claude Code or Antigravity (
agy) CLI.
Choose the entry like this:
- Use
bash.run_in_subtask=truefor one concrete shell command. - Use
spawnwhen the inner execution still needs agent-style tool use such asread_file,url_fetch, orbash. - Use
coderwhen the inner execution should be delegated to local Codex, Claude Code or the Antigravity CLI. - Do not add an isolated layer for trivial one-step work the parent can finish directly.
Overview
Mistermorph currently exposes three isolated-task entries:
| Entry | Starts another LLM loop | Best for | Returns |
|---|---|---|---|
spawn | Yes | an inner agent that still needs tools and reasoning | SubtaskResult JSON envelope |
coder | No local inner Mister Morph loop; starts Codex, Claude Code or Antigravity CLI | coding subtasks handled by local coding-agent CLIs | SubtaskResult JSON envelope |
bash.run_in_subtask=true | No | one shell command with isolated execution/output | SubtaskResult JSON envelope |
Shared behavior:
- All three are synchronous. The parent waits until the inner run finishes.
- All three share the same depth limit.
- All three return the same top-level envelope shape.
- These paths do not send the raw inner transcript back into the parent loop by default.
This feature is about isolation and result collection. It is not a background job system yet.
Current Implementation
spawn
spawn is an engine-scoped tool. It appears only after an agent engine is assembled for a run.
Parameters:
task: required prompt for the inner agent.tools: required non-empty tool-name array.model: optional model override for the inner agent.output_schema: optional structured-output label.observe_profile: optional observer hint. Supported values aredefault,long_shell, andweb_extract.
Current behavior:
- The inner registry is built from the tool names passed in
tools. - Unknown or unavailable tool names are ignored.
- If no usable tool remains, the call fails.
spawnis never re-exposed inside the inner agent, even if listed intools.
coder
coder is also an engine-scoped tool.
Parameters:
coder: required backend,codex,claudeoragy(the Antigravity CLI)task: required prompt for the coding CLIcwd: optional working-directory override
Current behavior:
- each CLI runs as a session over stdio, the same way in every runtime:
codexoncodex app-server,claudeonclaude -p --input-format stream-json --output-format stream-json --verbose --include-partial-messages --permission-prompt-tool stdio --session-id <uuid>,agyonagy acp - a session is one CLI process that takes one task after another: it lasts for a Console conversation, or for one run anywhere else
- only a Console conversation's sessions ask the user to approve actions and show the CLI's own questions; every other run has approvals bypassed (Claude Code:
--dangerously-skip-permissions), and a question the CLI asks there fails the task with the question as its error - what the CLI reports while it works is emitted as tool-output events; no terminal is involved and no CLI screen is read
- the final result is normalized into the same
SubtaskResultenvelope used byspawn coderis never re-exposed inside isolated child runs
bash.run_in_subtask=true
This is the lighter isolated-execution path.
- It uses the direct isolated path behind
bash. - It does not start a second LLM loop.
- Its
output_schemais fixed tosubtask.bash.result.v1. - Its observer profile is fixed to
long_shell.
Use it when the inner work is already one concrete shell step and does not need more tool decisions.
Depth Limit
The current depth limit is 1.
- A root run can enter one isolated extra layer.
- A run that is already inside that layer cannot enter another one.
output_schema
output_schema is only a contract label. It is not a built-in JSON Schema registry.
If you set it for spawn:
- the inner agent is told to produce JSON final output;
- the runtime requires the final output to be JSON or JSON-parsable text;
- the same identifier is echoed back in the result envelope.
Mistermorph does not validate the returned object against a real schema definition.
Result Envelope
All three entries return JSON in this shape:
{
"task_id": "sub_123",
"status": "done",
"summary": "subtask completed",
"output_kind": "text",
"output_schema": "",
"output": "child result",
"error": ""
}Meaning of the fields:
status: currentlydoneorfailed.summary: short status text for the isolated run.output_kind:textorjson.output_schema: empty for plain text output, or the identifier you passed in.output: the result payload.error: set only when the run fails.
For bash.run_in_subtask=true, output is structured JSON with exit_code, truncation flags, stdout, and stderr.
Test Prompts
These are good smoke tests when spawn and bash are enabled.
Prompt 1: spawn + bash, return one line
You must call the spawn tool. Do not answer directly. Allow the inner agent to use only bash. Have it run `printf 'alpha\nbeta\ngamma\n' | sed -n '2p'`. Return only the second line.Expected result: beta
Prompt 2: spawn + bash, return structured JSON
You must call the spawn tool and set output_schema to `subagent.demo.echo.v1`. Allow the inner agent to use only bash. Have it run `echo '{"ok":true,"value":42}'`. Return structured JSON only, with no explanation.Expected result:
{"ok":true,"value":42}Prompt 3: bash.run_in_subtask=true
Call the bash tool and set `run_in_subtask` to true. Run `printf 'one\ntwo\nthree\n' | tail -n 1`. Do not explain anything. Return only the last line.Expected result: three
Prompt 4: longer isolated shell run
Call the bash tool and set `run_in_subtask` to true. Run `sleep 1; echo SUBAGENT_BASH_OK`. Reply with stdout only.Expected result: SUBAGENT_BASH_OK
Config and Embedding
tools.spawn.enabledcontrols only the explicitspawntool entry.tools.coder.enabledcontrols whether the explicitcodertool entry is exposed by default. It defaults to false because the child Codex / Claude Code / Antigravity CLI process runs with approval and permission prompts bypassed.$codercan still expose it for one task.coderstartscodex,claudeandagyin thebashtool's environment (thepowershelltool's on Windows), not in the service's: the allowlisted variables (HOME,LANG,TERM,USER, ...), the variables oftools.bash.injected_env_vars(tools.powershell.injected_env_varson Windows), and nothing else. Proxy variables (HTTPS_PROXY,HTTP_PROXY,NO_PROXY,ALL_PROXY),CODEX_HOME,CLAUDE_CONFIG_DIRand provider keys such asOPENAI_API_KEYorANTHROPIC_API_KEYreach the CLIs only when listed there. A subscription sign-in under the home directory needs nothing.- The CLIs' PATH, in order:
tools.coder.path_extra,tools.bash.path_extra, the service's PATH, and, only whiletools.coder.path_extrais empty, the default install locations that exist:~/.local/bin,/opt/homebrew/bin,/usr/local/bin,/home/linuxbrew/.linuxbrew/bin; on Windows%USERPROFILE%\.local\bin,%LOCALAPPDATA%\Programs\OpenAI\Codex\binand%LOCALAPPDATA%\agy\bin. They come last, so they never replace a CLI the PATH already finds. tools.coder.path_extraprepends directories to that PATH for the coder only. Set it when the CLIs are somewhere else, such as an npm global directory under a version manager; setting it turns the default install locations off.tools.coder.bypass_approvals.codex,tools.coder.bypass_approvals.claudeandtools.coder.bypass_approvals.agy(default false) apply to the Console, where the coders' sessions ask the user to approve actions. Set one to true to start that CLI without approval prompts or sandbox: Codex with approval policyneverand sandboxdanger-full-access, Claude Code and the Antigravity CLI with--dangerously-skip-permissions. A running session is reopened with the new setting before its next task. A question the CLI itself asks is still shown. Only turn this on where the CLI may run anything the service user can.- Direct isolated runs such as
bash.run_in_subtask=truestill work even iftools.spawn.enabled=false. integration.Config.BuiltinToolNamescan include or omitspawnandcoder.- If you build an engine directly with
agent.New(...),spawnis enabled by default, whilecoderis disabled by default. Override them withagent.WithSpawnToolEnabled(...)andagent.WithCoderToolEnabled(...).
Example:
cfg := integration.DefaultConfig()
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn", "coder"}
cfg.Set("tools.spawn.enabled", true)
cfg.Set("tools.coder.enabled", true)See also: