Skip to content

feat(tools): add SpawnStatusTool for reporting subagent statuses#1540

Merged
lxowalle merged 17 commits intosipeed:mainfrom
SHINE-six:main
Mar 17, 2026
Merged

feat(tools): add SpawnStatusTool for reporting subagent statuses#1540
lxowalle merged 17 commits intosipeed:mainfrom
SHINE-six:main

Conversation

@SHINE-six
Copy link
Contributor

@SHINE-six SHINE-six commented Mar 14, 2026

📝 Description

add SpawnStatusTool for reporting subagent statuses

🗣️ Type of Change

  • ✨ New feature (non-breaking change which adds functionality)

🤖 AI Code Generation

  • 🤖 Fully AI-generated (100% AI, 0% Human)

🔗 Related Issue

Close #1539

🧪 Test Environment

  • Model/Provider: stepfun/step-3.5-flash

Usage

Click to view interaction

new-feat.log

☑️ Checklist

  • My code/docs follow the style of this project.
  • I have performed a self-review of my own changes.
  • I have updated the documentation accordingly.

Copilot AI review requested due to automatic review settings March 14, 2026 08:50
@CLAassistant
Copy link

CLAassistant commented Mar 14, 2026

CLA assistant check
All committers have signed the CLA.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new spawn_status tool to expose runtime status for subagents spawned via the existing spawn tool, addressing issue #1539.

Changes:

  • Introduces SpawnStatusTool to query a specific subagent by task_id or list all known subagent tasks with status counts.
  • Registers the new tool alongside spawn when subagents are enabled.
  • Adds unit tests covering tool metadata, empty state, listing, lookup-by-id, status counts, and result truncation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File Description
pkg/tools/spawn_status.go Implements the spawn_status tool and formats status reports for subagent tasks.
pkg/tools/spawn_status_test.go Adds unit tests for SpawnStatusTool behaviors and output formatting.
pkg/agent/loop.go Registers spawn_status tool when spawn + subagent tooling is enabled.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings March 14, 2026 09:08
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new spawn_status tool to expose subagent/task status reporting to agents, addressing the need for observability of background subagent work (Issue #1539).

Changes:

  • Introduce SpawnStatusTool that lists subagent tasks or fetches a task by task_id, including per-status summary counts.
  • Add comprehensive unit tests for formatting, filtering (per channel/chat), and result truncation.
  • Register the new tool alongside the existing spawn tool when subagents are enabled.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File Description
pkg/tools/spawn_status.go Implements the new spawn_status tool, including per-conversation filtering and human-readable formatting.
pkg/tools/spawn_status_test.go Adds test coverage for listing, lookup by ID, truncation behavior, and channel/chat filtering.
pkg/agent/loop.go Registers spawn_status tool for agents when spawn + subagent are enabled.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings March 14, 2026 09:13
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new spawn_status tool to expose subagent task status reporting (per issue #1539), along with unit tests and tool registration in the agent loop so it becomes available when spawn/subagent tooling is enabled.

Changes:

  • Introduce SpawnStatusTool (spawn_status) to list all subagent tasks or query a specific task by task_id, including basic status aggregation and output formatting.
  • Add comprehensive unit tests covering empty state, listing, lookup-by-id, truncation, and channel/chat scoping behavior.
  • Register spawn_status alongside spawn in the shared tool registration path.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File Description
pkg/tools/spawn_status.go Implements the new spawn_status tool (listing/querying, filtering, formatting).
pkg/tools/spawn_status_test.go Adds test coverage for the new tool’s behaviors (including filtering and truncation).
pkg/agent/loop.go Registers the new tool when subagent/spawn tooling is enabled.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@SHINE-six SHINE-six requested a review from Copilot March 14, 2026 09:37
@sipeed-bot sipeed-bot bot added type: enhancement New feature or request domain: tool domain: agent go Pull requests that update go code labels Mar 14, 2026
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new spawn_status tool to expose spawned subagent task status (list and per-task lookup), intended to improve observability of background subagent work.

Changes:

  • Register a new SpawnStatusTool alongside the existing spawn tool.
  • Add race-free snapshot helpers on SubagentManager (GetTaskCopy, ListTaskCopies) and use them from the new tool.
  • Add comprehensive unit tests for formatting, filtering, sorting, and truncation behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File Description
pkg/tools/subagent.go Adds snapshot APIs and tweaks task status initialization to support race-free status reporting.
pkg/tools/spawn_status.go Implements the new spawn_status tool (list + by-id) with conversation scoping and output formatting.
pkg/tools/spawn_status_test.go Adds tests covering tool schema, filtering, sorting, and result truncation.
pkg/agent/loop.go Registers spawn_status when spawn + subagent tools are enabled.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@SHINE-six
Copy link
Contributor Author

STATUS:
Ready to be reviewed and merge

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new spawn_status tool to expose subagent task status reporting (requested in #1539), along with concurrency-safe task snapshot helpers and test coverage.

Changes:

  • Add SpawnStatusTool (spawn_status) to list subagent tasks or query a specific task by ID with per-conversation scoping.
  • Add GetTaskCopy / ListTaskCopies to SubagentManager to provide race-free task snapshots for status reporting.
  • Register the new tool alongside spawn and add a comprehensive test suite.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File Description
pkg/tools/subagent.go Add snapshot/copy APIs on SubagentManager for race-free status inspection.
pkg/tools/spawn_status.go Implement spawn_status tool output formatting, filtering, sorting, and truncation.
pkg/tools/spawn_status_test.go Add tests for listing, filtering, sorting, truncation, and error cases.
pkg/agent/loop.go Register spawn_status tool when spawn + subagent are enabled.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

return registry.CanSpawnSubagent(currentAgentID, targetAgentID)
})
agent.Tools.Register(spawnTool)
agent.Tools.Register(tools.NewSpawnStatusTool(subagentManager))
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say this is a deliberate design choice, not a bug. spawn_status is a read-only companion to spawn — it has no independent purpose without the spawn tool. The pattern of
registering a status/query tool alongside its parent tool is reasonable. Other examples in the codebase show similar patterns (e.g., find_skills is tightly coupled to skills).

Adding a separate config toggle for spawn_status would be over-engineering — no user would want spawn enabled but spawn_status disabled. The current behavior
(implicitly enabled with spawn) is the correct default.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @SHINE-six , this tool is not necessary for all users. Please add a configuration option to enable whether this tool should be used and default is false.

Copy link
Contributor Author

@SHINE-six SHINE-six Mar 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lxowalle Since spawn and subagent is default to true, I think for this to default to true will be better? Often time usage with spawn (async), user/agents would need to check on it for task status progress

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hope tool list can be kept as small as possible, retaining only the necessary tools. I believe that in most cases, retrieving the status of subagents is only necessary when encountering issues. @SHINE-six

@SHINE-six
Copy link
Contributor Author

@lxowalle PTAL

Copy link
Collaborator

@lxowalle lxowalle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @SHINE-six, this tool is not necessary for all users. Please add a configuration option to enable whether this tool should be used and default to false

Copilot AI review requested due to automatic review settings March 15, 2026 10:33
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new spawn_status tool to report the status of asynchronously spawned subagents, with backend config/UI exposure and agent-loop registration.

Changes:

  • Added SpawnStatusTool to list subagent tasks or query a specific task by ID, including per-conversation scoping and output formatting.
  • Extended SubagentManager with snapshot APIs (GetTaskCopy, ListTaskCopies) to avoid races when reading task state.
  • Added config + web backend wiring so spawn_status can be enabled/disabled and shown in the tools catalog, plus unit tests for the new tool.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
web/backend/api/tools.go Adds spawn_status to the tools catalog and tool-state handling.
pkg/tools/subagent.go Adds task snapshot helpers to read subagent task state safely.
pkg/tools/spawn_status.go Implements the new spawn_status tool (list/query + formatting + scoping).
pkg/tools/spawn_status_test.go Adds test coverage for spawn_status behavior (filtering, sorting, truncation, errors).
pkg/config/defaults.go Enables spawn_status by default in the generated default config.
pkg/config/config.go Adds spawn_status to ToolsConfig and IsToolEnabled.
pkg/agent/loop.go Registers SpawnStatusTool when enabled (alongside spawn/subagent).
Comments suppressed due to low confidence (1)

web/backend/api/tools.go:222

  • In buildToolSupport, spawn_status is treated like spawn and only checks subagent as a dependency. This can report spawn_status as enabled even when spawn is disabled, but the tool is only registered inside the spawn block in the agent loop—so it won’t actually be available. Consider either (a) making spawn_status support status depend on both spawn_status and spawn being enabled (and surface a clear reason code), or (b) adjusting tool registration/config loading so enabling spawn_status also guarantees spawn is enabled in all paths (not just via applyToolState).
		case "spawn", "spawn_status":
			if cfg.Tools.IsToolEnabled(entry.ConfigKey) {
				if cfg.Tools.IsToolEnabled("subagent") {
					status = "enabled"
				} else {
					status = "blocked"
					reasonCode = "requires_subagent"
				}
			}

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +225 to +238
agent.Tools.Register(spawnTool)
if cfg.Tools.IsToolEnabled("spawn_status") {
agent.Tools.Register(tools.NewSpawnStatusTool(subagentManager))
}
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings March 15, 2026 10:37
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new spawn_status tool to let agents/users query the status of background subagent tasks managed by SubagentManager, addressing issue #1539.

Changes:

  • Introduces SpawnStatusTool (with conversation scoping, sorting, and result truncation) plus comprehensive unit tests.
  • Extends SubagentManager with race-free snapshot helpers (GetTaskCopy, ListTaskCopies) to support safe status reporting.
  • Wires the tool into config/defaults, agent tool registration, and the web backend tool catalog/state endpoints.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
web/backend/api/tools.go Adds spawn_status to the tool catalog and tool state update logic.
pkg/tools/subagent.go Adds snapshot-copy accessors for tasks to avoid data races when reporting status.
pkg/tools/spawn_status.go Implements the new status-reporting tool (list + per-task lookup).
pkg/tools/spawn_status_test.go Adds unit tests covering formatting, filtering, sorting, and truncation.
pkg/config/defaults.go Enables spawn_status by default in the generated config.
pkg/config/config.go Adds spawn_status to ToolsConfig and IsToolEnabled.
pkg/agent/loop.go Registers spawn_status alongside spawn when enabled.
Comments suppressed due to low confidence (1)

web/backend/api/tools.go:222

  • buildToolSupport treats spawn_status the same as spawn and only checks subagent, but the runtime registration in pkg/agent/loop.go only registers spawn_status inside the spawn-enabled block. With a config like spawn=false + spawn_status=true, the API/UI will report spawn_status as enabled even though it will never be registered/usable. Consider marking spawn_status as blocked when spawn is disabled (e.g., add a requires_spawn reason), or adjust registration so spawn_status availability matches what the API reports.
		case "spawn", "spawn_status":
			if cfg.Tools.IsToolEnabled(entry.ConfigKey) {
				if cfg.Tools.IsToolEnabled("subagent") {
					status = "enabled"
				} else {
					status = "blocked"
					reasonCode = "requires_subagent"
				}
			}

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

SHINE-six and others added 2 commits March 15, 2026 18:43
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings March 15, 2026 10:43
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new spawn_status tool to expose status reporting for spawned subagents, wiring it into configuration and the web tool catalog so agents/users can query subagent progress/state.

Changes:

  • Introduce SpawnStatusTool with per-conversation scoping, formatting, and result truncation.
  • Add concurrency-safe snapshot accessors (GetTaskCopy, ListTaskCopies) to SubagentManager.
  • Register/configure spawn_status across config defaults, tool enablement checks, agent tool registration, and the web backend tools API.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
web/backend/api/tools.go Adds spawn_status to the web tool catalog and tool enable/disable handling.
pkg/tools/subagent.go Adds task snapshot copy helpers for race-free status reporting.
pkg/tools/spawn_status.go Implements the new spawn_status tool and its output formatting/scoping logic.
pkg/tools/spawn_status_test.go Adds unit tests covering listing, lookup, scoping, sorting, and truncation behavior.
pkg/config/defaults.go Enables spawn_status by default in the generated default config.
pkg/config/config.go Adds spawn_status to ToolsConfig and IsToolEnabled.
pkg/agent/loop.go Registers spawn_status alongside subagent/spawn tooling based on config.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings March 15, 2026 11:51
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

Copy link
Collaborator

@lxowalle lxowalle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@lxowalle
Copy link
Collaborator

@SHINE-six I made some modifications, please fix the PR check.

@lxowalle lxowalle merged commit b402888 into sipeed:main Mar 17, 2026
4 checks passed
alexhoshina pushed a commit to alexhoshina/picoclaw that referenced this pull request Mar 17, 2026
…eed#1540)

* feat(tools): add SpawnStatusTool for reporting subagent statuses

* feat(tools): enhance SpawnStatusTool to restrict task visibility by conversation context

* feat(tests): add Unicode result truncation and channel filtering tests for SpawnStatusTool

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* feat(tools): enhance SpawnStatusTool with task ID validation and sorting by creation timestamp

* feat(tools): update SpawnStatusTool description and parameter documentation for clarity

* refactor(tests): improve comments for clarity in ChannelFiltering test case

* fix(tools): update no subagents message for clarity and remove unnecessary locking in runTask

* fix(tools): improve description clarity for SpawnStatusTool regarding task context

* feat(tools): add spawn_status tool configuration and registration

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix(agent): improve subagent management for spawn and spawn_status tools

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix(tests): update ResultTruncation_Unicode test to use valid CJK character

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: lxowalle <83055338+lxowalle@users.noreply.github.com>
@Orgmar
Copy link
Contributor

Orgmar commented Mar 18, 2026

@SHINE-six The SpawnStatusTool is a solid addition for subagent visibility. Being able to track what each subagent is doing makes debugging multi-agent flows way more manageable. Clean implementation too, closing out #1539 nicely.

By the way, we have a PicoClaw Dev Group on Discord where contributors share ideas and collaborate. If you want in, just email support@sipeed.com with the subject [Join PicoClaw Dev Group] SHINE-six and we'll send you the invite link!

j0904 pushed a commit to j0904/picoclaw that referenced this pull request Mar 22, 2026
…eed#1540)

* feat(tools): add SpawnStatusTool for reporting subagent statuses

* feat(tools): enhance SpawnStatusTool to restrict task visibility by conversation context

* feat(tests): add Unicode result truncation and channel filtering tests for SpawnStatusTool

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* feat(tools): enhance SpawnStatusTool with task ID validation and sorting by creation timestamp

* feat(tools): update SpawnStatusTool description and parameter documentation for clarity

* refactor(tests): improve comments for clarity in ChannelFiltering test case

* fix(tools): update no subagents message for clarity and remove unnecessary locking in runTask

* fix(tools): improve description clarity for SpawnStatusTool regarding task context

* feat(tools): add spawn_status tool configuration and registration

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix(agent): improve subagent management for spawn and spawn_status tools

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix(tests): update ResultTruncation_Unicode test to use valid CJK character

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: lxowalle <83055338+lxowalle@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

domain: agent domain: tool go Pull requests that update go code type: enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEAT] Expose subagent status reporting via tool/API

5 participants