Cap agent tool-call recursion depth
Agents that can spawn agents, or call a tool that re-enters the loop, grow exponentially until the budget dies. Bound the depth at a small number and refuse delegations past it.
Procedure
- Declare a maximum depth before the run — a flat fan-out, depth 2 (parent plus children), is usually enough.
- Pass the current depth in every delegation call:
run_subagent(brief=..., depth=2, max_depth=3).
- Refuse any call that would exceed
max_depth, returning a clear depth_exceeded error the parent must handle.
- Cap total descendants as well as depth: depth 3 with branching 10 is 1000 agents; cap the count at, say, 20.
- Require each child to be strictly narrower than its parent — a child that re-delegates the same brief is a loop.
- Track a delegation tree in the run state so depth and count are measured, not assumed.
- Treat a tool that "calls the agent again" the same as spawning: carry depth through it too.
- When depth is hit, do the work inline instead of delegating — a leaf that cannot spawn is still an agent.
MAX_DEPTH, MAX_DESC = 3, 20
def spawn(brief, depth, spawned):
if depth >= MAX_DEPTH or spawned >= MAX_DESC:
raise RuntimeError(f"delegation refused depth={depth} spawned={spawned}")
return run_subagent(brief, depth + 1, spawned + 1)
Pitfalls
- Letting a child spawn a grandchild with the same brief, doubling work at every level.
- Capping depth but not total count, so a wide fan-out still exhausts the budget.
- Passing depth in a global variable that a child cannot see, so every child thinks it is depth 0.
- Allowing a re-entrant tool call to reset depth, so recursion never terminates.
- Setting max depth so high ("just in case") that it provides no bound at all.
- Counting only successful spawns, ignoring refused ones that still consumed a model turn.
Verification
grep -oE 'depth=[0-9]+' notes/action.log | sort -u | tail -1 # largest depth <= declared max_depth
Report the declared max depth and count, the deepest delegation used, and any refusal.
1---2name: cap-agent-tool-call-recursion-depth3description: Use when an agent can call a tool that may invoke the agent again, or spawn subagents. Bound the depth and total descendants so delegation cannot run away.4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/cap-agent-tool-call-recursion-depth6---78# Cap agent tool-call recursion depth910Agents that can spawn agents, or call a tool that re-enters the loop, grow exponentially until the budget dies. Bound the depth at a small number and refuse delegations past it.1112## Procedure13141. Declare a maximum depth before the run — a flat fan-out, depth 2 (parent plus children), is usually enough.152. Pass the current depth in every delegation call: `run_subagent(brief=..., depth=2, max_depth=3)`.163. Refuse any call that would exceed `max_depth`, returning a clear `depth_exceeded` error the parent must handle.174. Cap total descendants as well as depth: depth 3 with branching 10 is 1000 agents; cap the count at, say, 20.185. Require each child to be strictly narrower than its parent — a child that re-delegates the same brief is a loop.196. Track a delegation tree in the run state so depth and count are measured, not assumed.207. Treat a tool that "calls the agent again" the same as spawning: carry depth through it too.218. When depth is hit, do the work inline instead of delegating — a leaf that cannot spawn is still an agent.2223```python24MAX_DEPTH, MAX_DESC = 3, 2025def spawn(brief, depth, spawned):26 if depth >= MAX_DEPTH or spawned >= MAX_DESC:27 raise RuntimeError(f"delegation refused depth={depth} spawned={spawned}")28 return run_subagent(brief, depth + 1, spawned + 1)29```3031## Pitfalls3233- Letting a child spawn a grandchild with the same brief, doubling work at every level.34- Capping depth but not total count, so a wide fan-out still exhausts the budget.35- Passing depth in a global variable that a child cannot see, so every child thinks it is depth 0.36- Allowing a re-entrant tool call to reset depth, so recursion never terminates.37- Setting max depth so high ("just in case") that it provides no bound at all.38- Counting only successful spawns, ignoring refused ones that still consumed a model turn.3940## Verification4142 grep -oE 'depth=[0-9]+' notes/action.log | sort -u | tail -1 # largest depth <= declared max_depth4344Report the declared max depth and count, the deepest delegation used, and any refusal.