feat: add /btw background session command

[Svtter]

Issue for this PR

Closes #16992
Supersedes #17198

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

This rebases the original /btw implementation from #17198 onto current dev.

I resolved the merge conflict in packages/opencode/src/session/llm.ts and fixed /btw after rebase by awaiting SessionStatus.get(), which is now async on current dev.

There are no intended behavior changes beyond making the branch mergeable and keeping the original /btw behavior working on current dev.

Credit to @brendandebeasi for the original implementation in #17198.

How did you verify your code works?

• cd packages/opencode && bun typecheck
• cd packages/opencode && bun test test/session/btw.test.ts test/session/message-v2.test.ts

Screenshots / recordings

N/A - backend/CLI command, no UI changes.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Related PR Found:

• feat: add /btw background session command #17198 - feat: add /btw background session command
  • This is the original implementation that PR feat: add /btw background session command #18635 supersedes. PR feat: add /btw background session command #18635 is a rebase of feat: add /btw background session command #17198 onto the current dev branch that resolves merge conflicts and compatibility issues.

No other duplicate PRs found. PR #18635 is explicitly intended to replace #17198 with the same feature rebased for current compatibility.

[github-actions]

Thanks for updating your PR! It now meets our contributing guidelines. 👍

[atharvau]

This PR adds a comprehensive background task command system (/btw) with todo management and child session support, plus tool count limiting and synthetic message filtering improvements.

Strengths ✅

• Comprehensive test coverage: Excellent test suite with realistic scenarios
• Well-architected: Clean separation between ask, todo, and status functionality
• Good error handling: Proper async error catching and reporting
• Type safety: Strong TypeScript usage throughout

Concerns 🚨

1. Large Feature Scope

• 7 files modified - this is a substantial feature addition
• Multiple concerns mixed: Tool limiting, synthetic messages, background tasks
• Consider splitting: This could be broken into smaller, focused PRs

2. Tool Limiting Logic

const TOOL_LIMITS: Record<string, number> = { xai: 200 }

• Hardcoded limits: Should be configurable or from provider metadata
• Silent truncation: Dropping tools without user awareness could cause confusion
• Missing documentation: Users won't know why their tools aren't available

3. Synthetic Message Filtering

• Breaking change potential: Changes how synthetic messages are handled
• Unclear rationale: Why filter synthetic assistant parts but not user parts?
• Missing tests: No specific tests for this behavior change

4. Session Management Complexity

• Parent-child relationships: Complex async coordination between sessions
• Memory usage: Background sessions persist indefinitely?
• Error propagation: What happens when child sessions fail?

Recommendations

1. Split the PR: Separate tool limits, synthetic filtering, and /btw command
2. Tool limits: Make configurable or document the reasoning
3. Add documentation: Command needs user-facing docs
4. Session cleanup: Consider lifecycle management for background sessions
5. Test synthetic filtering: Add specific tests for message filtering changes

Recommendation: Consider splitting into focused PRs for safer integration.

[atharvau]

Code Review Summary

Overall Assessment: ⚠️ APPROVE with Recommendations

Substantial feature addition that adds background task capability. Well-implemented but has some areas for improvement.

✅ Strengths:

• Comprehensive Feature: Adds ask, todo, and status subcommands
• Good Architecture: Proper session management and child session creation
• Extensive Testing: 269 lines of thorough test coverage
• Tool Limiting: Smart tool count limiting for providers with restrictions
• Async Handling: Proper background task execution and result posting

🟡 Areas for Improvement:

Code Quality:

• Naming Convention Violation: Multiple camelCase variables (assistantMessage, toolExecutor) should be single words per style guide
• Function Length: commandBtw function is quite long (~200 lines) - consider breaking into smaller functions
• Duplication: Helper functions (post, update) could be extracted to reusable utilities

Potential Bugs:

• Double Length Check: Line 759 has redundant if (assistantMessage.parts.length > 0) check
• Synthetic Text Filtering: The synthetic text filtering logic may be too broad and could affect other features

Security/Performance:

• Tool Limiting: Hard-coded TOOL_LIMITS for xai (200) - consider making this configurable
• Memory Usage: Background tasks could accumulate without cleanup mechanism

Documentation:

• ✅ Good command documentation in .opencode/command/btw.md
• 🟡 Complex features could use more inline code comments

Breaking Changes:

• Message Filtering: Changes to synthetic text part handling in toModelMessages
• Tool Limits: New tool limiting may affect existing workflows

Recommendations:

1. Refactor: Break down commandBtw into smaller, focused functions
2. Fix Naming: Use single-word variable names per style guide
3. Remove Duplication: Extract common patterns
4. Add Cleanup: Consider background task cleanup/timeout mechanisms

Overall: Good feature, ready to merge with follow-up refactoring

[Svtter]

@atharvau Thanks for the review. I'm going to split this work into two smaller PRs instead of keeping the current scope bundled together.

Planned split:

1. /btw PR

• command implementation and docs
• child-session execution / status reporting
• todo append flow
• session cleanup/archive behavior after background completion
• the /btw-specific message filtering needed so the synthetic status/result messages don't leak back into future model turns

2. Tool-limit PR

• limit.tools model/provider support
• xAI fallback tool cap
• runtime tool capping
• user-facing warning when tools are capped

I've already reworked the code locally along those lines and will follow up by separating them into those two reviewable changes.

[Svtter]

Follow-up: the split PRs are now up.

• feat: add /btw background session command #18917 /btw command work
• fix: cap active tools for providers with tool count limits #18916 tool-limit work

I'll keep further review on those split PRs.

[brendandebeasi]

Yeah, sorry about that. Good call.

…

On Mar 24, 2026 at 3:24 AM -0700, 修昊 ***@***.***>, wrote: Svtter left a comment (anomalyco/opencode#18635) Follow-up: the split PRs are now up. • #18917 /btw command work • #18916 tool-limit work I'll keep further review on those split PRs. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>