How AgentDefinition & Persona Merge
Deconstructing Agent definitions, Persona overrides, and the merge order of final session behavior
THE QUESTION THIS PAGE ANSWERS
ANSWER FIRSTHow AgentDefinition & Persona Merge?
Deconstructing Agent definitions, Persona overrides, and the merge order of final session behavior
Make the claim earn its place. Use this page as a decision aid, not a definition to memorize. Connect the idea to one real task, one observable result, and one failure that would change your mind.
Write one question you could answer with evidence after trying this idea.
A conclusion that sounds complete but leaves the key assumption untested.
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.
Why “Definition Resolution and Runtime Overrides Are Two Input Streams” depends on the operation
“Distinguish between AgentDefinition , SubagentRole , SubagentPersona , and EffectiveRuntimeConfig , and accurately determine the merge priority for each field” makes the structure concrete. The useful comparison is not which name sounds more advanced, but how the data is arranged and how far the most common operation has to travel.
Read a structure through access and change
“Type and function names in the diagram come from source code;” exposes a trade-off that is easy to miss: reading by position, looking up by key, adding at either end, inserting in the middle, and traversing relationships do not favor the same organization. A structure that is fast for one operation is not automatically fast for all of them.
Count scale and update frequency together
Use “spawn specifies reasoning_effort=high and Persona reviewer;” as a boundary check. Write down the data size, the dominant operation, and the latency you can accept before deciding whether an AI-generated structure actually fits.
From “Definition Resolution and Runtime Overrides Are Two Input Streams” to “AgentDefinition: The Versionable Agent Contract”
“Definition Resolution and Runtime Overrides Are Two Input Streams” grounds the problem in “Type and function names in the diagram come from source code; arrows illustrate data convergence”. “AgentDefinition: The Versionable Agent Contract” then moves it toward “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 priori…”. Together, they show that the lesson is not just a conclusion to remember, but a claim with conditions.
Carry the judgment into the next situation
When you meet a new data structure, do not begin by memorizing its definition. Write down the most frequent operation, estimate scale and update behavior, and check whether the structure satisfies all three conditions.
- “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 priori…
- “The closing point”: 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 P…
The final “The closing point” brings the discussion to “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 P…”. The useful thing to carry forward is knowing which judgments must be revisited when input, scale, or risk changes.
I turned one judgment from this article into a small experiment I could run today. Knowing what to observe next is more useful than simply remembering the conclusion.
After reading this, I first looked for the conditions behind the idea instead of copying the method into a project. That order made the later trade-offs much clearer.
When this judgment reaches real work, which constraint should be added first? I am curious which step matters most between reading and the first practical attempt.
No discussion on this article yet.