How AgentDefinition and Persona Merge
A sub-agent first resolves its executable skeleton, then folds spawn parameters, role defaults, and Persona defaults into a runtime configuration. The two structures take effect at different stages and together determine the child session.
Distinguish between AgentDefinition, SubagentRole, SubagentPersona, and EffectiveRuntimeConfig, and accurately determine the merge priority for each field.
Definition Resolution and Runtime Overrides Are Two Input Streams
Type and function names in the diagram come from source code; arrows illustrate data convergence.
AgentDefinition: The Versionable Agent Contract
Parsed from .grok/agents/*.md. Real fields include prompt_mode, tool_config, capability_mode, permission_mode, tools, isolation, model, hooks, and MCP inheritance. Project-defined discovery takes priority over user and bundled definitions.
SubagentRole: Runtime Preset Matched by Type
A role can provide capability, model, reasoning effort, prompt file, and default isolation. It is looked up by subagent_type and the role prompt is read at spawn time.
SubagentPersona: Behavior Layer Selected by Name
A Persona has inline instructions, an instructions file, inputs, outputs, model, reasoning effort, and default isolation. Inline text is merged before file content, then injected as a <persona> block into the prompt.
EffectiveRuntimeConfig: The Resolved Result
Real fields are model, reasoning_effort, capability_mode, persona, persona_instructions, role_prompt, role_prompt_warning, role_name, persona_error, and isolation. There are no temperature, max_tokens, or tools fields in the source code.
A Definition Fallback Follows EffectiveRuntimeConfig
After the shell receives the resolved result, if reasoning_effort is still empty, it reads AgentDefinition.effort. If runtime isolation is None but definition isolation is Worktree, it is upgraded to Worktree. In model resolution, the resolved runtime override takes precedence over per-agent pin, AgentDefinition.model, and parent model inheritance.
Fail-closed: Persona
If a Persona is requested but not found, has empty content, or fails to read its file, persona_error is written. File I/O failures return a defaulted result early; the spawn side aborts creation upon seeing a Persona error.
Soft Degradation: Role Prompt
A read failure for the role's prompt_file produces only role_prompt_warning; the remaining model, reasoning, capability, and isolation fields continue to be resolved.
pub struct EffectiveRuntimeConfig {
pub model: Option<String>,
pub reasoning_effort: Option<String>,
pub capability_mode: Option<SubagentCapabilityMode>,
pub persona: Option<String>,
pub persona_instructions: Option<String>,
pub role_prompt: Option<String>,
pub persona_error: Option<String>,
pub isolation: SubagentIsolationMode,
}Snapshot note: Field names and types come from the real struct; comments and two observational fields are omitted. The convergence diagram above is a teaching visualization and does not imply a monolithic pipeline class of that name exists in the source code.
Class Exercise: Manually Compute the Effective Configuration
spawn specifies reasoning_effort=high and Persona reviewer; role specifies model=A, capability=read-only, isolation=worktree; Persona specifies model=B, reasoning=low, isolation=none. Write out the final values for all four fields and explain why capability will not be read from the Persona.