fix(server): bound Claude subagent usage

[Ivorisnoob]

What Changed

• Limit Claude Code to five concurrent subagents and one level of subagent spawning by default.
• Allow provider environment variables to override either limit.
• Stop known background tasks before closing, replacing, or interrupting a Claude session.
• Reconcile live tasks using the SDK's background-task snapshots so missed lifecycle events do not leave work running.
• Upgrade the Claude Agent SDK from 0.3.170 to 0.3.235 and handle its updated message and permission contracts.
• Add regression tests and document the limits and overrides.

Why

Claude sessions could delegate into a large tree of concurrent subagents, while some background tasks could survive session shutdown paths and continue consuming subscription usage.

This adds conservative default bounds and makes task cleanup consistent across shutdown paths. It preserves the existing streaming and session-resume architecture so the change does not intentionally disrupt prompt caching or steering.

Checklist

• This PR is small and focused
• I explained what changed and why
• Screenshots are not applicable because this PR has no UI changes
• Video is not applicable because this PR has no animation or interaction changes

Note

Bound Claude subagent spawn depth and concurrency with default guardrails

• Adds withClaudeSubagentGuardrails in ClaudeAdapter.ts to inject default env vars (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=5) unless already set by the process environment.
• Tracks live background task IDs from background_tasks_changed SDK messages and stops all live tasks via stopLiveTasks before closing a session or replacing a turn.
• Adds handling for informational and model_refusal_no_fallback SDK system subtypes, emitting runtime warnings instead of silently ignoring them.
• Documents the new defaults and override mechanism in providers-claude.md.
• Behavioral Change: stopSession now stops background tasks before closing the SDK transport and emits task.completed (status: stopped) events for each stopped task.

^{Macroscope summarized de22df2.}

---

Note

Medium Risk
Touches Claude session lifecycle, background task teardown, and SDK integration paths that affect token usage and shutdown behavior; changes are bounded by tests but affect production agent orchestration.

Overview
Claude sessions get default subagent guardrails (max depth 1, max 5 concurrent) via withClaudeSubagentGuardrails, with provider env vars overriding when set. User docs describe the defaults and overrides.

Background task cleanup is unified: stopLiveTasks runs before closing the SDK query on stopSession (and is shared with interruptTurn). Live task IDs are reconciled from background_tasks_changed snapshots so missed lifecycle events do not leave agents running.

Claude Agent SDK bumps from 0.3.170 to 0.3.235; tests pass requestId into canUseTool mocks. New system subtypes (informational, model_refusal_no_fallback, etc.) are handled or surfaced as warnings instead of unknown-subtype noise.

^{Reviewed by Cursor Bugbot for commit de22df2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f1b089fd-22c1-4766-b3f8-7da92301a855

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces runtime behavior changes affecting resource usage control (subagent spawn limits with explicit subscription/billing implications) and task lifecycle management. The scope of behavioral changes warrants human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

Thanks for the PR. We're not taking changes to the orchestration and provider layers right now: that part of the server is being rewritten for V2, and merging into the current code would either conflict with or be thrown away by that work.

Closing for now. If this is still an issue once V2 lands, please reopen (or open a fresh PR against the new code) and we'll take a proper look.