feat: add automatic subagent parallelization

Prepare v3.1.0 release with automatic subagent delegation, native .a3s/agents loading, SDK API alignment, release version updates, and expanded unit/integration coverage.

Author: claude

CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2026-05-23
+
+### Added
+
+- Added Claude Code-style automatic subagent delegation. When a request matches
+  multiple independent specialists, the runtime can pre-run those child agents
+  through one bounded `parallel_task` call and feed the gathered context back
+  into the main turn.
+- Added `auto_delegation` configuration and session overrides, including the
+  global `auto_parallel` kill switch. Setting `auto_parallel = false` disables
+  automatic parallel child-agent fan-out while keeping manual `parallel_task`
+  available.
+- Added `max_parallel_tasks` as the shared sibling fan-out limit for
+  `parallel_task`, delegated plan waves, and safe parallel write batches.
+- Added a reusable ordered parallel executor so concurrent child results remain
+  deterministic and individual task failures are isolated.
+- Added native `.a3s/agents` and `~/.a3s/agents` subagent discovery with
+  recursive loading. `.claude/agents` remains a compatibility source, but
+  `.a3s/agents` wins when the same agent name appears in both locations.
+- Added Claude-style markdown agent compatibility for `tools`,
+  `allowedTools`, and `disallowedTools` frontmatter. `tools` behaves as an
+  allowlist and `disallowedTools` is a denylist that takes precedence.
+- Added direct worker/subagent APIs across Rust, Node.js, and Python:
+  `WorkerAgentSpec`, `AgentDefinition`, `session_for_worker`, live worker
+  registration, and `task` / `parallel_task` helpers.
+- Added real-provider smoke coverage for automatic parallel delegation and
+  built-in subagent execution using `.a3s/config.acl`.
+
+### Changed
+
+- Aligned built-in subagent names and aliases with Claude Code conventions:
+  `general-purpose` aliases to `general`; `verify` / `verifier` alias to
+  `verification`; `code-review` / `reviewer` alias to `review`.
+- Tightened built-in subagent permission boundaries. Read-only and review-style
+  agents now default-deny undeclared tools, and all built-ins deny recursive
+  `task` / `parallel_task` delegation to prevent unbounded nesting.
+- Collapsed independent delegated plan waves into a single `parallel_task`
+  operation where possible, rather than launching serial sibling `task` calls.
+- Updated Node and Python SDK documentation to prefer the single delegation
+  surface backed by the core `task` and `parallel_task` tools.
+
+### Fixed
+
+- Fixed release helper version checks so they no longer reference the removed
+  `cli/` package.
+- Fixed explicit subagent trigger parsing so normal phrases such as "use the
+  plan" are not mistaken for a `plan` subagent request.
+
 ## [3.0.0] - 2026-05-20
 
 ### Added (Phase 8 — typed-error SDK alignment)

Cargo.lock

@@ -75,6 +75,8 @@ Create `agent.acl`:
 
 ```acl
 default_model = "anthropic/claude-sonnet-4-20250514"
+max_parallel_tasks = 8
+auto_parallel = false
 
 providers "anthropic" {
   apiKey = env("ANTHROPIC_API_KEY")
@@ -1113,6 +1115,43 @@ Core delegation primitives:
 - `task` — run one focused delegated child run
 - `parallel_task` — run independent delegated child runs concurrently
 
+Built-in subagents are available through these primitives and through automatic
+delegation:
+
+- `explore` — read-only codebase search and inspection
+- `plan` — read-only implementation planning
+- `general` / `general-purpose` — multi-step implementation work
+- `verification` — adversarial checks and regression validation
+- `review` — code review findings
+
+Automatic delegation can trigger from high-confidence task descriptions, from
+Claude Code-style proactive agent descriptions, or explicitly with mentions such
+as `@general-purpose`, `@agent-plan`, `use the review subagent`, `delegate to
+verification`, or `ask docs-auditor`.
+
+Custom agents are loaded recursively from configured `agent_dirs`, from
+`./.a3s/agents`, and from `~/.a3s/agents`. The Claude-compatible
+`./.claude/agents` and `~/.claude/agents` paths are still read as migration
+sources, but `.a3s/agents` is the native A3S location and wins for same-name
+agents. Markdown agent files support Claude-style frontmatter:
+
+```markdown
+---
+name: docs-auditor
+description: Use proactively after documentation changes
+tools: Read, Grep, Glob
+disallowedTools:
+  - Write
+  - Bash(rm:*)
+---
+
+Audit docs for drift, broken examples, and unclear migration notes.
+```
+
+The `tools` field is treated as an allowlist. `disallowedTools` is applied as a
+denylist and wins over allowed tools. Model routing fields are intentionally not
+part of this compatibility layer.
+
 The older model-visible team shortcut and duplicate lifecycle control-plane API
 are no longer part of the public surface. Multi-agent work enters through the
 delegation core.
@@ -1271,6 +1310,8 @@ blocks such as `providers "anthropic" { ... }`.
 
 ```acl
 default_model = "anthropic/claude-sonnet-4-20250514"
+max_parallel_tasks = 8
+auto_parallel = false
 
 providers "anthropic" {
   apiKey = env("ANTHROPIC_API_KEY")
@@ -1286,6 +1327,13 @@ providers "anthropic" {
 skill_dirs = ["./skills"]
 mcp_servers = []
 
+auto_delegation {
+  enabled        = false
+  auto_parallel  = false
+  min_confidence = 0.72
+  max_tasks      = 4
+}
+
 ahp = {
   enabled = true
   url     = "http://harness:8080/ahp"
@@ -1297,6 +1345,12 @@ Model token limits use the `limit = { context = ..., output = ... }` object as t
 The flat `maxTokens` and `contextTokens` fields are accepted only as deprecated
 migration aliases and emit warnings.
 
+`max_parallel_tasks` bounds sibling fan-out for `parallel_task`, plan waves, and
+safe parallel write batches.
+`auto_delegation.enabled` controls Claude Code-style automatic subagent
+delegation. `auto_parallel = false` is a global kill switch for automatic
+parallel child-agent fan-out; manual `parallel_task` remains available.
+
 ---
 
 ## Development

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-core"
-version = "3.0.0"
+version = "3.1.0"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

core/Cargo.toml

@@ -20,13 +20,15 @@ use crate::planning::{AgentGoal, ExecutionPlan, TaskStatus};
 use crate::prompts::{PlanningMode, SystemPromptSlots};
 use crate::queue::{SessionCommand, SessionQueueConfig};
 use crate::session_lane_queue::SessionLaneQueue;
+use crate::subagent::AgentRegistry;
 use crate::tools::{ToolContext, ToolExecutor};
 use anyhow::Result;
 use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use std::sync::Arc;
 
+mod auto_delegation;
 mod completion_runtime;
 mod context_perception;
 mod execution_entry;
@@ -54,6 +56,7 @@ mod turn_context;
 
 /// Maximum number of tool execution rounds before stopping
 pub(crate) const MAX_TOOL_ROUNDS: usize = 50;
+pub(crate) const DEFAULT_MAX_PARALLEL_TASKS: usize = 8;
 
 /// Internal agent loop configuration.
 #[derive(Clone)]
@@ -100,6 +103,13 @@ pub(crate) struct AgentConfig {
     /// A timeout produces an error result sent back to the LLM rather than
     /// crashing the session.
     pub tool_timeout_ms: Option<u64>,
+    /// Maximum number of sibling branches/tools to run concurrently in bounded
+    /// parallel fan-out paths.
+    pub max_parallel_tasks: usize,
+    /// Runtime-driven automatic child-agent delegation.
+    pub auto_delegation: crate::config::AutoDelegationConfig,
+    /// Available child agents for automatic delegation.
+    pub agent_registry: Option<Arc<AgentRegistry>>,
     /// Circuit-breaker threshold: max consecutive LLM API failures before
     /// aborting (default: 3).
     ///
@@ -165,6 +175,12 @@ impl std::fmt::Debug for AgentConfig {
             )
             .field("max_parse_retries", &self.max_parse_retries)
             .field("tool_timeout_ms", &self.tool_timeout_ms)
+            .field("max_parallel_tasks", &self.max_parallel_tasks)
+            .field("auto_delegation", &self.auto_delegation)
+            .field(
+                "agent_registry",
+                &self.agent_registry.as_ref().map(|registry| registry.len()),
+            )
             .field("circuit_breaker_threshold", &self.circuit_breaker_threshold)
             .field(
                 "duplicate_tool_call_threshold",
@@ -199,6 +215,9 @@ impl Default for AgentConfig {
             skill_registry: Some(Arc::new(crate::skills::SkillRegistry::with_builtins())),
             max_parse_retries: 2,
             tool_timeout_ms: None,
+            max_parallel_tasks: DEFAULT_MAX_PARALLEL_TASKS,
+            auto_delegation: crate::config::AutoDelegationConfig::default(),
+            agent_registry: None,
             circuit_breaker_threshold: 3,
             duplicate_tool_call_threshold: 3,
             auto_compact: false,