Skip to content

feat(subagent): use report_back tool for announcing results#890

Closed
tyler6204 wants to merge 2 commits intoopenclaw:mainfrom
tyler6204:fix/subagent-announce
Closed

feat(subagent): use report_back tool for announcing results#890
tyler6204 wants to merge 2 commits intoopenclaw:mainfrom
tyler6204:fix/subagent-announce

Conversation

@tyler6204
Copy link
Copy Markdown
Member

@tyler6204 tyler6204 commented Jan 14, 2026 •
edited
Loading

Summary

Refactors subagent architecture to use a dedicated report_back tool instead of a secondary announce step. Subagents now have full control over when and how they report results.

Changes

  • New report_back tool - Subagents call this to send results back to main session
    • Injects into main session transcript (main agent has context)
    • Sends to messaging channels (Telegram, WhatsApp, etc.) if configured
    • internalOnly: true option for silent/internal tasks
  • Full subagent context - Subagents now receive same context as main agent:
    • All workspace files (SOUL.md, IDENTITY.md, USER.md, MEMORY.md, etc.)
    • Tool summaries and availability
    • Model aliases, user timezone, skills, runtime info
  • Simplified tool policy - Only 3 tools denied by default:
    • sessions_send (use report_back instead)
    • sessions_spawn (prevents infinite loops)
    • message (use report_back instead)
  • Read-only access - Subagents CAN use sessions_list and sessions_history
  • Removed announce step - No secondary agent call; subagent handles its own reporting
  • Updated docs - docs/tools/subagents.md reflects new architecture

Files

  • src/agents/tools/report-back-tool.ts - New tool for subagent reporting
  • src/agents/subagent-announce.ts - Expanded system prompt, added cleanup function
  • src/agents/subagent-registry.ts - Calls cleanup instead of announce flow
  • src/agents/tools/sessions-spawn-tool.ts - Loads full context for subagents
  • src/agents/clawdbot-tools.ts - Adds report_back tool for subagent sessions
  • src/agents/pi-tools.ts - Updated DEFAULT_SUBAGENT_TOOL_DENY
  • docs/tools/subagents.md - Updated documentation
  • Tests updated to match new architecture

Test plan

  • Build passes
  • Lint passes
  • All tests pass (2863)
  • Manual: spawn subagent, verify it calls report_back
  • Manual: verify internalOnly works (transcript only, no external send)

🤖 Generated with Claude Code

@tyler6204 @claude
fix(subagent): announce results to chat with SOUL.md persona
67de444 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@tyler6204 tyler6204 force-pushed the fix/subagent-announce branch 2 times, most recently from 02407db to 67de444 Compare January 14, 2026 08:13
@tyler6204 @claude
feat(subagent): use report_back tool for announcing results
b292fb0 
- Add report_back tool for subagents to send results to main session
- Subagents now get full context (workspace files, tools, skills, etc.)
- Remove secondary announce step - subagent handles its own reporting
- Update tool policy: deny sessions_send, sessions_spawn, message
- Allow sessions_list and sessions_history (read-only)
- Add internalOnly option to report_back for silent tasks
- Update docs to reflect new architecture

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@tyler6204 tyler6204 changed the title fix(subagent): announce results to chat with SOUL.md persona feat(subagent): use report_back tool for announcing results Jan 14, 2026
@steipete
Copy link
Copy Markdown
Contributor

steipete commented Jan 14, 2026

Each new tool adds complexity and needs more token - do we really need this?
subagents on purpose have no memory. We should discuss our idea what these are for - can you expand your reasoning?

@tyler6204
Copy link
Copy Markdown
Member Author

tyler6204 commented Jan 14, 2026

the announce tool wasn't working so this PR fixes that. but re the broader question of subagent purpose, my use case is parallel task execution without blocking main chat. yesterday i spun up 6 subagents (2 skill creations then 4 verification agents) simultaneously while continuing to chat.

the issue without context is subagents get stuck in loops trying to discover things like notion api quirks that are already in TOOLS.md. they burn more tokens searching my system for the 'right way' vs just having that context upfront. so counterintuitively, giving them SOUL.md + TOOLS.md actually saves tokens.

happy to discuss if subagents are meant for a different use case but for parallel non-blocking work, context is essential

@steipete
Copy link
Copy Markdown
Contributor

steipete commented Jan 15, 2026

I'm not sure subagents need a Soul or charcters, I see them as worker bees, they don't need to be sassy.
This needs more thinking.

@steipete steipete added the question Further information is requested label Jan 15, 2026
@tyler6204 tyler6204 closed this Jan 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

question Further information is requested

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@tyler6204 @steipete