docs(subagents): default to background-first execution to avoid blocking the main chat

[cristim]

Summary

• CLAUDE.md: Replaced the short "Parallel vs background" bullet under ### 2. Subagent Strategy with a "Background-first" policy that sets background execution as the default for any long-running or independent work, explains when foreground is appropriate, and keeps the parallel-calls and lock-patterns guidance.
• subagent-strategy.md: Added a new ## Background-first execution section (placed between the PR-shipping tier split section and the model rubric), covering: background-by-default for builds/suites/watchers/sweeps/research, the never-poll rule, parallelizing independent work, handing control back while work runs, and keeping post-implementation verification honest.

Rationale

Blocking the main (interactive) session on work that could run detached costs the user time and keeps the session context busy on waiting rather than on useful work. Making background-first the explicit default - rather than an implied option - closes the gap where agents default to foreground for convenience and stall the conversation.

Test plan

• Read CLAUDE.md section 2 to confirm the new bullet replaces "Parallel vs background" cleanly and no em-dashes were introduced
• Read subagent-strategy.md to confirm the new section appears between the tier-split section and the model rubric, and integrates without duplicating existing guidance
• Verify git diff --stat origin/main reports exactly CLAUDE.md + subagent-strategy.md (2 files, 11 insertions, 1 deletion)
• Confirm security/ directory is not staged or included in the commit

Summary by CodeRabbit

Documentation

• Refined internal guidance for optimizing task execution to maintain system responsiveness and performance.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 05f70b1a-3f49-49e1-8e4b-2c22a9467b91

📥 Commits

Reviewing files that changed from the base of the PR and between d836f5c and 700f491.

📒 Files selected for processing (2)

• CLAUDE.md
• subagent-strategy.md

---

📝 Walkthrough

Walkthrough

Documentation updated to establish background-first execution as the default strategy for subagent work: run_in_background: true for independent or long-running tasks to keep the main chat responsive, with results collected via completion notifications rather than polling, combined with criteria for foreground-only work and post-implementation verification requirements.

Changes

Background-first subagent execution strategy

Layer / File(s)	Summary
Background-first execution guidance subagent-strategy.md, CLAUDE.md	New rubric subsection added to define background execution defaults, parallel dispatch for independent tasks, foreground-only criteria, and verification requirements; existing CLAUDE.md guidance updated to emphasize run_in_background: true for independent/long-running work with completion notifications instead of polling.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• LeanerCloud/dotclaude#5: Both PRs modify the same documentation section in CLAUDE.md ("Subagent Strategy"), specifically the subagent delegation rules (one adds run_in_background/background-first execution guidance, the other adjusts tier-based delegation with Claude↔OpenAI mappings), making the changes conceptually and textually overlapping in the subagent strategy logic.
• LeanerCloud/dotclaude#2: Both PRs update CLAUDE.md "Subagent Strategy" to change how subagent work should be delegated (main PR adds background-first non-blocking run_in_background: true, while retrieved PR mandates delegating down to cheaper tiers before using the main session), so they are directly connected to the same delegation policy.
• LeanerCloud/dotclaude#9: Both PRs update the CLAUDE.md "Subagent Strategy" guidance section, adding/expanding rules for how subagent work should be delegated (background-first execution vs. explicit model/labeling procedural rules).

Suggested labels

triaged, type/docs, effort/s, impact/internal, severity/low, urgency/eventually, priority/p3

Poem

🐰 Hopping toward responsive chats so bright,
Let background tasks run out of sight,
Main chat keeps moving, never delayed,
Results arrive when their work is weighed,
A carrot-earned efficiency, perfectly played! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: updating documentation to establish background-first execution as the default approach for subagents to avoid blocking the main chat.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/background-first-execution

Warning

Tools execution failed with the following error:

Failed to run tools: Stream initialization permanently failed: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

---

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