feat: support local team composition from external files

[Sayt-0]

Summary

• compose a primary agent manifest with one or more local YAML, YML, or HCL teams
• support both declarative sub_agents imports and the repeatable CLI form --team "Team name=path"
• keep nested team members private to their lead while allowing synchronous nested delegation
• group the existing TUI agent cards under human-readable team section titles

Usage

docker agent run ./examples/local-team/primary-cli.yaml \
  --team "Research team=./secondary-team.yaml"

The first positional argument remains the primary manifest, and subsequent positional arguments remain user messages. Additional teams use repeated --team flags.

TUI preview

Idle state:

 Primary team ────────────────────────────

 ▶ root                                 ^1
   openai/gpt-4o

 Research team ───────────────────────────

   root                                 ^2
   openai/gpt-4o

   researcher
   openai/gpt-4o

   writer
   openai/gpt-4o

While a private team member is active:

 Primary team ────────────────────────────

   root                                 ^1
   openai/gpt-4o

 Research team ───────────────────────────

   root                                 ^2
   openai/gpt-4o

 ▶ researcher
   openai/gpt-4o

   writer
   openai/gpt-4o

Only public leads receive shortcuts and click targets. Private members are visible for progress feedback but remain unavailable as direct switch targets.

Design notes

• Primary team is the default title for the primary manifest.
• The text before = is presentation-only. A distinct routing ID is generated internally, so imported leads retain their manifest-local display name.
• transfer_task is blocking: control returns to the parent lead only after the delegated lead finishes.
• Relative team paths resolve from the importing manifest.
• Circular local imports and exposed-ID collisions are rejected.
• Imported manifests with top-level permissions, budget, budgets, or runtime.safety are rejected instead of silently dropping policy. Those policies belong in the primary manifest.
• --team is currently local-only and is incompatible with --remote and --sandbox.

Validation

Check	Result
task build	pass
focused Go packages	pass
golangci-lint run	pass
repository linter	pass
go mod tidy --diff	pass
race tests for nested delegation and team sidebar	pass
real gateway smoke test	pass

The real smoke test used DOCKER_AGENT_MODELS_GATEWAY=https://ai-backend-service-stage.docker.com/proxy with direct provider API keys removed. It completed root -> research-team -> researcher -> research-team -> root with no runtime error events.

Known CI environment note

The full local suite is affected by existing SSRF tests when the host proxy replaces http.DefaultTransport; focused changed packages, build, lint, race checks, example loading, and the real gateway flow pass.

Issue mapping

No linked issue was identified for this change.

[aheritier]

Where does the idea comes from ? I am not against but while its adding some value it will add a lot of complexity