Issue: Architectural Conflict between runSubagent Tool Schema and System Instructions
Summary:
The runSubagent tool defines the agentName parameter as optional in its JSON schema. This configuration fundamentally conflicts with specialized "Manager/Orchestrator" system prompts that require explicit subagent selection. The model's internal priority for tool schema definitions overrides "Strict Instruction" prompts, leading to recursive self-invocations where the Manager agent calls itself instead of a specialized subagent (e.g., Coder, Advisor).
Root Cause Analysis:
- Schema Slack: In the
runSubagent tool definition, agentName is not listed in the required array.
- Model Bias: When a parameter is optional in the schema, the LLM often takes the path of least resistance (minimal JSON payload), even if the System Prompt explicitly forbids omitting it.
- Recursive Failure: Because the
agentName is omitted, the system defaults to the current agent (Manager). The Manager agent, which lacks file-editing tools by design, then "executes" the task within its own context and frequently hallucinates the outcome because it cannot perform the required actions (like edit_file).
Impact:
- Hallucinations: Managers claim to have fixed files they cannot touch.
- Context Pollution: Large research tasks are executed in the main orchestrator context instead of being isolated in a subagent session.
- Workflow Breaking: The "Clean Architecture" of the agentic team is compromised by recursive loops.
Observed Behavior:
Manager Prompt: "You MUST provide the EXACT agent name."
Tool Call: runSubagent({ prompt: "Fix config", description: "Fixing..." }) (omitting agentName)
Result: Manager invokes Manager. Task fails or results are fabricated.
Proposed Solution:
Update the runSubagent tool's JSON schema to make agentName a Required Property.
Enforcing this at the schema level (hard constraint) is the only way to ensure the model correctly routes tasks to specialized subagents and prevents the "Manager-calling-Manager" failure mode.
Technical Note for Developers:
Instruction-based enforcement (System Prompt) is insufficient when the tool's API surface allows for ambiguity. Hardening the schema to required: ["agentName", "prompt", "description"] will stabilize the multi-agent orchestration pattern. Otherwise, they will continue to call themselves, and hallucinate that they are successfully solving the problem.
Issue: Architectural Conflict between
runSubagentTool Schema and System InstructionsSummary:
The
runSubagenttool defines theagentNameparameter as optional in its JSON schema. This configuration fundamentally conflicts with specialized "Manager/Orchestrator" system prompts that require explicit subagent selection. The model's internal priority for tool schema definitions overrides "Strict Instruction" prompts, leading to recursive self-invocations where the Manager agent calls itself instead of a specialized subagent (e.g., Coder, Advisor).Root Cause Analysis:
runSubagenttool definition,agentNameis not listed in therequiredarray.agentNameis omitted, the system defaults to the current agent (Manager). The Manager agent, which lacks file-editing tools by design, then "executes" the task within its own context and frequently hallucinates the outcome because it cannot perform the required actions (likeedit_file).Impact:
Observed Behavior:
Proposed Solution:
Update the
runSubagenttool's JSON schema to makeagentNamea Required Property.Enforcing this at the schema level (hard constraint) is the only way to ensure the model correctly routes tasks to specialized subagents and prevents the "Manager-calling-Manager" failure mode.
Technical Note for Developers:
Instruction-based enforcement (System Prompt) is insufficient when the tool's API surface allows for ambiguity. Hardening the schema to
required: ["agentName", "prompt", "description"]will stabilize the multi-agent orchestration pattern. Otherwise, they will continue to call themselves, and hallucinate that they are successfully solving the problem.