proposal(runtime): let the root Agent create a bounded task-specific Sub Agent
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
## Problem
The root Agent can delegate work through `agent_spawn`, but every child must be selected from `agent_list` by `subagent_id` or from a legacy built-in profile. The root Agent can describe the task, but it cannot create a bounded task-specific child role when none of the configured presets fits.
This makes one-off delegation depend on configuration prepared before the task is understood. Users must either anticipate every specialization in Settings, accept an ill-fitting preset, interrupt the workflow to add one, or keep the work in the root Agent.
The missing capability is not unrestricted Agent creation. It is a narrow way for the root Agent to instantiate a temporary child whose task-specific instructions are chosen at delegation time while its authority remains inside a user-approved envelope.
## Desired outcome
Allow the root Agent to create a temporary, task-specific Sub Agent without requiring a matching named preset in advance.
- The user explicitly enables an ad hoc child policy and selects its maximum authority.
- The root Agent may provide a bounded display name, purpose, and task-specific instructions.
- Runtime, not the root Agent, chooses or validates the permitted model, tool profile, permission ceiling, workspace boundary, write-back modes, lifecycle, and nesting depth.
- The child remains a normal linked child Session/AgentRun with the existing lineage, event, inspection, cancellation, recovery, and artifact semantics.
- The root Agent cannot grant capabilities it does not have or widen the user's configured envelope.
- Existing configured presets remain the preferred path for repeatable roles and exact model selection.
- Disabling ad hoc creation removes the route from `agent_list`/`agent_spawn` rather than relying only on prompt instructions.
One possible model-facing shape is a Host-authorized synthetic catalog entry such as `temporary-bounded`, selected through the existing `subagent_id` flow, with a separate bounded role description. The exact protocol is less important than keeping policy authority out of model-provided fields.
## Acceptance criteria
1. With ad hoc creation disabled, current `agent_list` and `agent_spawn` behavior is unchanged.
2. With it enabled, the root Agent can spawn a task-specific child without first creating a named preset in Settings.
3. The child receives the delegated task and bounded role instructions, but its effective model, tools, permissions, workspace access, write-back policy, lifecycle, and nesting depth cannot exceed the user-approved envelope.
4. Invalid or over-broad requests fail before a child Session or AgentRun is created and explain which boundary was rejected.
5. The resulting child is visible and inspectable through the same linked-session and `agent_output` paths as configured children.
6. Parent cancellation, restart recovery, transcript isolation, and artifact lookup retain their current behavior.
7. Prompt injection in parent content cannot enable the feature, alter the authority envelope, or create nested children.
## Non-goals
- Background child execution, steering, or independent cancellation; those belong to #3540
- Letting the root Agent choose arbitrary credentials, providers, tools, permission modes, or filesystem access
- Replacing user-configured reusable Sub Agent presets
- Allowing Side Conversations or child Agents to create further children
- Adding a second Sub Agent runtime, ledger, or Session type
## Related
- #49 established child execution on the existing runtime spine and originally discussed an inline Agent specification.
- #3540 covers background lifecycle, steering, visibility, and stopping; this proposal is limited to how a foreground child role is selected and authorized.
Contributor guide
Research direction
Trace the existing agent_list and agent_spawn paths, then inspect how configured children use linked Session/AgentRun lineage and agent_output inspection. Define the host-authorized temporary role within the stated envelope, validate rejected boundaries before creation, and verify the acceptance criteria for visibility, cancellation, recovery, isolation, artifacts, and disabled or nested creation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- ai, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100