feat: Base multi-agent collaboration framework

[edouard-claude]

📝 Description

Add the foundation for multi-agent collaboration as described in #294. This introduces a new pkg/agent/multi package with:

• Agent interface — standard contract with Name, Role, SystemPrompt, Capabilities, Tools, and Execute
• BaseAgent struct — embeddable implementation for concrete agent types
• SharedContext — thread-safe blackboard pattern for inter-agent data sharing with append-only event log
• AgentRegistry — agent lifecycle management with capability-based routing
• HandoffRequest/HandoffResult — task delegation protocol between agents

This is a non-invasive addition: no existing files were modified. The new package creates abstractions that the existing SubagentManager and AgentLoop can be gradually migrated to use.

🗣️ Type of Change

• 🐞 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 📖 Documentation update
• ⚡ Code refactoring (no functional changes, no api changes)

🤖 AI Code Generation

• 🤖 Fully AI-generated (100% AI, 0% Human)
• 🛠️ Mostly AI-generated (AI draft, Human verified/modified)
• 👨‍💻 Mostly Human-written (Human lead, AI assisted or none)

🔗 Related Issue

Closes #294

📚 Technical Context (Skip for Docs)

• Reference URL: Feature: Base Multi-agent Collaboration Framework & Shared Context #294, Introducing Swarm Mode: Multi-instance Collaboration for PicoClaw #119
• Reasoning: The current architecture uses a monolithic AgentLoop with SubagentManager that runs goroutine-based subagents with hardcoded system prompts and no shared context. Issue Feature: Base Multi-agent Collaboration Framework & Shared Context #294 requires: (1) Agent interface/struct, (2) Shared context pool, (3) Basic hand-off mechanism, (4) Agent lifecycle management. This PR implements all four requirements as new abstractions in pkg/agent/multi/ without modifying existing code, allowing gradual migration.

🧪 Test Environment

• Hardware: MacBook (Apple Silicon)
• OS: macOS Darwin 25.2.0
• Model/Provider: N/A (unit tests only, no LLM required)
• Channels: N/A

📸 Evidence (Optional)

Click to view test results

=== RUN   TestSharedContext_SetGet          --- PASS
=== RUN   TestSharedContext_GetString       --- PASS
=== RUN   TestSharedContext_Delete          --- PASS
=== RUN   TestSharedContext_Keys            --- PASS
=== RUN   TestSharedContext_Events          --- PASS
=== RUN   TestSharedContext_EventsByAgent   --- PASS
=== RUN   TestSharedContext_EventsByType    --- PASS
=== RUN   TestSharedContext_Snapshot        --- PASS
=== RUN   TestSharedContext_ConcurrentAccess --- PASS
=== RUN   TestBaseAgent_Fields             --- PASS
=== RUN   TestBaseAgent_NilRegistry        --- PASS
=== RUN   TestAgentRegistry_Register       --- PASS
=== RUN   TestAgentRegistry_Unregister     --- PASS
=== RUN   TestAgentRegistry_Get            --- PASS
=== RUN   TestAgentRegistry_List           --- PASS
=== RUN   TestAgentRegistry_FindByCapability --- PASS
=== RUN   TestAgentRegistry_SharedContext   --- PASS
=== RUN   TestAgentRegistry_Handoff_DirectRouting      --- PASS
=== RUN   TestAgentRegistry_Handoff_CapabilityRouting  --- PASS
=== RUN   TestAgentRegistry_Handoff_NotFound           --- PASS
=== RUN   TestAgentRegistry_Handoff_ExecutionError     --- PASS
=== RUN   TestAgentRegistry_Handoff_ContextPassing     --- PASS
=== RUN   TestAgentRegistry_Handoff_AgentStateTransition --- PASS
=== RUN   TestAgentRegistry_Handoff_ContextCancellation  --- PASS
=== RUN   TestMultiAgent_Integration       --- PASS
PASS
ok  github.com/sipeed/picoclaw/pkg/agent/multi  0.827s

☑️ 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.

[Zepan]

Thanks for your contribution! We are forming the PicoClaw Dev Group to accelerate the evolution of the project.

Would you like to join the PicoClaw Dev Group? If so, please send an email to support@sipeed.com with the subject line: [Join PicoClaw Dev Group] + Your GitHub account. We will send the Discord invite link to your inbox.

[edouard-claude]

Closing in favor of #423

After a discussion with @Leeaandrob on the PicoClaw Dev Group Discord, we agreed to consolidate our efforts on a single implementation. Here's why #423 is the better foundation:

• LLM-callable tools (blackboard, handoff, list_agents) — agents can autonomously decide when to delegate tasks, which is fundamentally more powerful than the programmatic-only handoff in this PR
• Smaller, more idiomatic Go interface — AgentResolver (2 methods) follows Go's "accept interfaces, return structs" principle better than my 6-method Agent interface
• Real integration — modifies AgentLoop to inject blackboard snapshots into system prompts and registers multi-agent tools only when >1 agent is configured (zero overhead for single-agent setups)
• Builds on merged work — extends PRs Refactor providers by protocol family (discussion #122) #213 (provider protocol refactor) and feat: model fallback chain + multi-agent routing #131 (model fallback + routing), already part of main
• Architecture documentation — full C4 diagrams (system context, container, component, code level)

Looking forward to contributing directly on #423.