review mode can recursively spawn claude subagents and exhaust usage limits

[iatsiuk]

ralphex: 1.6.1, claude code: 2.1.224
review model: sonnet, worker model: opus

internal review started multiple general-purpose agents that delegated recursively. a single run proudced more than three dozen subagent contexts with well over thousand model responses. root session also launched short placeholder agent while trying to wait for reviwers that CC had automatically moved to the background.

this looks like compatibility gap because ralphex requests foreground agent calls, while CC may execute them asynchronously.

mitigations were:

• created dedicated ralphex-reviewer agent with disallowedTools: Agent, Edit, Write
• configured all ralphex review roles to use that agent
• added the instruction "Perform the entire review in this agent context without delegating any part of it to other subagents."
• disabled experimental agent teams and background tasks for ralphex-launched claude sessions:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

dedicated reviewer stopped recursive delegation, and the next run had only the expected reviewer contexts with no nested agent calls. background-task overrides were added afterward to prevent the remaining async wait behavior and still need verification on the next full run.

this message is for anyone who runs into a similiar problem.

[umputun]

the recursive delegation half is real and it is ralphex's, fixed in #428.

{{agent:name}} expands to a general-purpose agent, which holds the agent tool itself, and the shared reviewer contract in reviewContextInstruction never told it not to use it. So a reviewer handed a five-section checklist fans out, and each child can do the same.

worth knowing why your disallowedTools workaround was needed rather than a prompt tweak: the "do NOT use run_in_background" line in review_first.txt only reaches the root session. A spawned agent's whole prompt is the lead-in plus its agent body, so nothing in the prompt files can reach the agent that recursed. #428 puts the line in the lead-in, which is prepended before the claude/codex branch, so it covers spawn_agent reviewers and custom agents too.

the other half is not fixed. CC moving foreground Task calls to the background, and the placeholder agent while waiting on them, is its own scheduling and a prompt cannot bind it. Your two env vars are the right lever there and need no change on our side, ralphex passes the environment through to the child claude untouched apart from CLAUDECODE and ANTHROPIC_API_KEY. If the next full run confirms they hold, say so here.

your dedicated ralphex-reviewer agent stays useful regardless: disallowedTools is a hard block where #428 is a prompt instruction, and agent: frontmatter has always been supported for pointing roles at it.

[iatsiuk]

i pass both variables via claude_args using --settings, not through the ralphex process environment:

claude_args = ... --settings '{"env":{"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS":"0","CLAUDE_CODE_DISABLE_BACKGROUND_TASKS":"1"}}'