Multi-Agent Communication

Based on two core tools, sessions_spawn and sessions_send, to help users build, manage, and optimize distributed Agent systems, enabling task decomposition,...

Security Scan

The skill's instructions are coherent with a multi-agent orchestration purpose, but they include several risky behaviors and permissive defaults (attachment snapshotting, workspace inheritance, invisible child runs, and a default allow-all policy) that could lead to unintended data persistence or broad agent-to-agent access.

Purpose & Capability

The name and description align with the provided instructions: the skill documents two APIs (sessions_spawn and sessions_send) for creating and messaging Agents. However, the SKILL.md assumes platform-level features (Gateway RPC, SubagentRegistry, Sweeper, thread binding to Discord/Slack) without declaring required credentials or environment hooks — this is plausible for an instruction-only skill that expects runtime platform support, but the reliance on external channels and RPC mechanisms should be confirmed with the platform implementer.

Instruction Scope

The instructions instruct copying attachments into child Agents (‘Snapshots over References’) and inheriting working directories for same-type child Agents. These behaviors cause data duplication and persistence (child retains access even if the parent deletes the data). The skill also supports invisible, background child runs (mode="run" that are 'not visible to the user by default') and automatic push-back via a Sweeper — both increase the chance of unnoticed data movement. The SKILL.md also references binding to Discord/Slack threads and pushing final results to user channels, which could expose data externally. Overall, the guidance goes beyond simple orchestration into actions that can persist or forward user data without explicit per-item consent.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest disk/write risk. Nothing is downloaded or installed by the skill itself.

Credentials

The skill requests no environment variables or external credentials, which is proportionate for an instruction-only policy document. That said, it references external systems (Slack/Discord threads, Gateway RPC) and a default configuration example that sets session.agentToAgent.allow to ["*"]. The combination of no declared credential requirements and references to external channels means the real platform will need credentials; confirm who supplies them and whether the skill expects implicit access.

Persistence & Privilege

The skill describes persistent child sessions (mode="session"), snapshotting attachments (child retains copies), and invisible one-shot runs (mode="run" not visible to users). While 'always' is false and it doesn't change other skills' config, these capabilities grant substantial persistence and stealthy behavior if the runtime allows it. The provided defaults (max spawn depth, children per agent) are limiting, but examples show those can be relaxed; also the example allow: ["*"] is permissive and increases blast radius. Because the skill can be invoked autonomously (platform default), these persistence features amplify risk.

What to consider before installing

This skill is conceptually coherent for orchestrating multiple Agents, but before installing or enabling it verify the runtime controls and defaults: - Confirm how attachments/snapshots are stored and for how long. If child Agents receive copies of attachments, those copies may persist even after the parent deletes them. - Ask the platform: when sessions inherit a working directory, what files are accessible to child Agents? Are secrets or credentials excluded by policy? - Verify visibility and audit logs for mode="run" background tasks (since they can run 'invisible' by default). Ensure you can audit spawned sessions and their outputs. - Do not accept a global allow-all cross-agent policy (allow: ["*"]) in production. Configure whitelists for which agent types can be spawned and which labels can communicate. - Confirm what external endpoints (Discord/Slack threads, other channels) the skill will post to and where the credentials for those integrations are stored and audited. - Test the patterns in an isolated environment with strict maxSpawnDepth and maxChildrenPerAgent limits, then increase permissions only if you can monitor behavior and revoke sessions. If you need help formulating the specific questions to ask your platform/owner (e.g., where Sweeper writes results, how long snapshots persist, how to restrict agent-to-agent allow lists), I can draft them for you.

Core tools: sessions_spawn (launch child Agents) and sessions_send (send messages to existing Agents).

Use Cases

• Launching child Agents for background tasks
• Multi-Agent collaboration and negotiation
• Configuring Agent permissions and concurrency limits
• Choosing the appropriate communication mode (run/session/send)
• Designing Agent team workflows

Two Core Tools

sessions_spawn — Create a new Agent instance

sessions_spawn({
  task: "Review PR #123",
  agent: "code-reviewer",     // Agent ID (not SOUL name)
  mode: "run",                // run=one-shot, session=persistent
  thread: false,              // Whether to bind to a message thread
  runTimeoutSeconds: 300      // Optional, timeout duration
})

Essence: Fork a new process. Creates an independent session and execution environment, automatically pushing results back to the parent Agent upon completion. In mode="run", the child Agent's execution process is not visible to the user by default.

sessions_send — Send a message to an existing Agent

sessions_send({
  sessionKey: "agent:main:subagent:abc",
  label: "security",          // Use sessionKey or label
  message: "Check security",
  timeoutSeconds: 30          // Synchronous wait; 0=asynchronous delivery
})

Essence: Inter-Process Communication (IPC). Sends messages to an existing session, supporting multi-round A2A negotiation (up to 5 rounds of ping-pong).

Core Decision: Which One to Choose?

Scenario	Tool	Mode
Background data processing, one-shot analysis	sessions_spawn	mode: "run"
Parallel task decomposition (multiple spawns)	sessions_spawn	mode: "run"
Multi-round code review (user-visible)	sessions_spawn	mode: "session", thread: true
Real-time collaborative Q&A between Agents	sessions_send	timeoutSeconds > 0
Asynchronous delivery, no reply needed	sessions_send	timeoutSeconds: 0

Quick Judgment:

• Need to create a new Agent → sessions_spawn
• Need to communicate with an existing Agent → sessions_send

Spawn Execution Flow (10 Stages)

User Request → Main Agent → sessions_spawn
  ↓
[1. Permission Check]  → Verify depth, concurrency, whitelist
  ↓
[2. Session Creation]  → Generate unique sessionKey
  ↓
[3. Thread Binding]    → (Optional) Bind to Discord/Slack thread
  ↓
[4. Attachment Handling] → Snapshot transfer (independent lifecycle)
  ↓
[5. System Prompt]     → Inject task context
  ↓
[6. Working Directory] → Inherit parent Agent or use target Agent config
  ↓
[7. Agent Launch]      → Via Gateway RPC
  ↓
[8. Runtime Registration] → Record in SubagentRegistry
  ↓
[9. Hook Trigger]      → Notify plugins
  ↓
[10. Result Return]    → Return childSessionKey

Results are automatically pushed back to the parent Agent via Sweeper (checks every 1-8 seconds), no manual polling required.

Session Key Design

Main Agent:    agent:main:main
Child Agent:   agent:main:subagent:<uuid>
Grandchild:    agent:main:subagent:<uuid>:subagent:<uuid>

UUID ensures global uniqueness; the hierarchical structure facilitates routing and traceability.

mode="run" vs. mode="session"

Feature	run	session
Lifecycle	One-shot, deleted upon completion	Persistent, awaits subsequent messages
Thread Binding	Not supported	Required (thread=true)
User Visibility	❌ Completely invisible	✅ Visible in thread
Applicable Scenarios	Background data processing	Multi-turn conversations, code reviews

⚠️ Note: mode="session" must also have thread=true set, otherwise subsequent messages cannot be routed correctly.

Three-Tier Security Protection

Constraint	Default Value	Purpose
Max Recursion Depth	1	Prevent infinite recursion
Max Child Processes	5/session	Prevent resource exhaustion
Whitelist Mechanism	Configurable	Cross-Agent permission control

A2A Multi-Round Negotiation (sessions_send)

Agent A ──"Format this code"──→ Agent B
         ←─"Which style do you prefer?"
Agent A ──"Use Prettier"─────→ Agent B
         ←─"Done"
Agent A ──REPLY_SKIP──────────→ Agent B

• Maximum 5 rounds (configurable)
• Either party replies with REPLY_SKIP_TOKEN to end
• Final result delivered to the user channel

Key Design Decisions

• Snapshots over References: Attachments are copied to the child Agent; the child can still access them even after the parent deletes them.
• Push over Polling: Zero polling cost; a 30-second task saves approximately 15,000 tokens.
• Cross-Agent Workspace Isolation: Same-type child Agents inherit the parent directory; cross-type ones use the target Agent's configuration.

Configuration Suggestions

See references/config.md for details.

Design Patterns

See references/patterns.md for details.