Add spawn_identical_subagents tool to the AI framework

[luisorofino]

What does this PR do?

Adds a new spawn_identical_subagents tool to the ddev AI framework. It runs the same subagent — identical system prompt and tool set — over many different assignments in parallel, sending the shared system prompt and tools once instead of repeating them per child.

• New SpawnIdenticalSubagentsTool (ai/tools/agents/spawn_identical_subagents.py): validates assignments (non-empty, unique names, a cap on fan-out) and the requested tool subset, fans out under an asyncio.Semaphore, and aggregates per-child results in assignment order. One child failing (or hitting max_tokens) never affects its siblings; the call succeeds on partial results and only fails when validation fails or every child errors.
• Each child is given a concise-output directive appended to the shared system prompt, so aggregated results stay small and don't overflow the parent's context.
• Extracts the machinery shared with spawn_subagent into an abstract BaseSpawnTool[TInput] (child config/scope construction, tool-subset validation, max_tokens handling). SpawnSubagentTool is refactored onto it with no external behavior change. Neither spawn tool is ever offered to a child.
• Registers the tool in the manifest (reusing the existing spawn factory — no ToolContext changes). Flows opt in by listing spawn_identical_subagents in an agent's tools.
• Tests: a shared conftest.py provides fake-agent and fake-process-factory fixtures; base-class restriction logic is tested once in test_base.py; per-tool behavior (aggregation/order, partial and total failure, max_tokens notice, concurrency cap, config inheritance) is covered in the respective files.

Motivation

spawn_subagent delegates one subtask to one child, re-inlining the full system_prompt on every call. Running the same worker over N input slices therefore cost N×(system_prompt + prompt) of output tokens — enough to push a worker turn past max_tokens and truncate it mid tool_use. This tool makes "same agent, many assignments" first-class, so output scales as 1×system_prompt + N×(tiny assignment prompt).

Review checklist (to be filled by reviewers)

• Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
• Add qa/required if this PR needs QA validation, or qa/skip-qa if it does not. Exactly one of the two is required.
• If you need to backport this PR to another branch, you can add the backport/<branch-name> label to the PR and it will automatically open a backport PR once this one is merged

[datadog-datadog-prod-us1-2]

 

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 96.34%
• Overall Coverage: 88.47%

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 4415607 | Docs | Datadog PR Page | Give us feedback!}

[luisorofino]

@codex

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 00631c1c18

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[AAraKKe]

Thanks! Some questions and a simple request.

My Feedback Legend

Here's a quick guide to the prefixes I use in my comments:

praise: no action needed, just celebrate!
note: just a comment/information, no need to take any action.
question: I need clarification or I'm seeking to understand your approach.
nit: A minor, non-blocking issue (e.g., style, typo). Feel free to ignore.
suggestion: I'm proposing an improvement. This is optional but recommended.
request: A change I believe is necessary before this can be merged.

The only blocking comments are request, any other type of comment can be applied at discretion of the developer.

[dd-octo-sts]

Validation Report

All 21 validations passed.

Show details

Validation	Description	Status
agent-reqs	Verify check versions match the Agent requirements file	✅
ci	Validate CI configuration and code coverage settings	✅
codeowners	Validate every integration has a CODEOWNERS entry	✅
config	Validate default configuration files against spec.yaml	✅
dep	Verify dependency pins are consistent and Agent-compatible	✅
http	Validate integrations use the HTTP wrapper correctly	✅
imports	Validate check imports do not use deprecated modules	✅
integration-style	Validate check code style conventions	✅
jmx-metrics	Validate JMX metrics definition files and config	✅
labeler	Validate PR labeler config matches integration directories	✅
legacy-signature	Validate no integration uses the legacy Agent check signature	✅
license-headers	Validate Python files have proper license headers	✅
licenses	Validate third-party license attribution list	✅
metadata	Validate metadata.csv metric definitions	✅
models	Validate configuration data models match spec.yaml	✅
openmetrics	Validate OpenMetrics integrations disable the metric limit	✅
package	Validate Python package metadata and naming	✅
qa-label	Validate the pull request declares whether it needs QA for the next Agent release	✅
readmes	Validate README files have required sections	✅
saved-views	Validate saved view JSON file structure and fields	✅
version	Validate version consistency between package and changelog	✅

View full run

[AAraKKe]

Thanks!