Understanding the spawn-session Tool in Craft Agents: How to Enable Agent-to-Agent Communication

The spawn_session tool is a session-scoped utility that enables a running Craft Agent to create independent, parallel agent sessions with isolated contexts, facilitating multi-agent collaboration through a sandboxed, fire-and-forget architecture.

The spawn-session tool in the craft-ai-agents/craft-agents-oss repository provides the foundation for dynamic session orchestration within the Craft Agents ecosystem. This tool allows agents to delegate work to separate sessions that run concurrently, establishing a clean separation of concerns while maintaining the ability to share results through the workspace filesystem.

What Is the spawn-session Tool?

The spawn_session tool is defined in packages/shared/src/agent/spawn-session-tool.ts and built using the Claude SDK's tool() helper with Zod schema validation. It functions as a session-scoped utility that allows an existing agent to instantiate a brand-new, independent agent session from within its own execution context.

Unlike standard tool invocations that return immediate results to the caller, this tool operates on a fire-and-forget principle. When invoked, it delegates the creation of a new session to a registered callback, which then issues an HTTP request to the internal /spawn-session endpoint. The original agent continues execution immediately while the spawned session initializes and runs in parallel.

How spawn-session Facilitates Agent-to-Agent Communication

The tool enables agent-to-agent communication by creating isolated execution environments that can exchange information through shared storage. Each spawned session receives its own prompt, LLM model, connection configuration, source settings, and working directory, ensuring complete state isolation from the parent agent.

Communication between agents occurs through the workspace filesystem. For example, a parent agent might spawn a session to analyze a document, which writes its findings to a specific file path. The parent can then read those results by invoking file-reading tools, creating a clean, sandboxed channel for multi-agent collaboration without direct memory sharing or state leakage.

Operating Modes: Help vs. Spawn

The tool supports two distinct operational modes depending on the arguments provided:

Help mode (help=true) – Returns a discovery payload containing available LLM connections, models, and source slugs. This allows agents to introspect what resources are available before attempting to spawn a session with specific configurations.

Spawn mode – Requires a mandatory prompt argument and optional parameters such as name, llmConnection, model, and attachments. In this mode, the tool retrieves the spawnSessionFn from the session-scoped callback registry and executes it to create the new session.

Implementation Architecture

Tool Definition and Validation

The core implementation resides in packages/shared/src/agent/spawn-session-tool.ts. The tool definition uses Zod to validate arguments, ensuring that either help is set to true or a valid prompt string is provided. The tool is registered with the Claude SDK through packages/shared/src/agent/session-scoped-tools.ts, making it available as a callable function within agent contexts.

Session-Scoped Callback Registry

The actual execution logic relies on a per-session callback system defined in packages/shared/src/agent/session-scoped-tool-callback-registry.ts. When the tool runs, it calls getSpawnSessionFn() to retrieve the lazy-resolved callback registered for the current session. If no callback is available, the tool returns an error. Developers register the callback using registerSessionScopedToolCallbacks(sessionId, { spawnSessionFn: async (args) => { ... } }).

Server-Side Session Creation

The callback ultimately forwards the request to the internal MCP server. In packages/server/src/index.ts, the implementation sends an HTTP POST request to http://127.0.0.1:${config.callbackPort}/spawn-session. The server—likely routed through packages/messaging-gateway/src/router.ts—creates a new session directory, persists the supplied prompt, and initiates the session process. The new session immediately appears in the workspace's session list and operates independently.

Practical Code Examples

Querying Available Resources

Use help mode to discover what LLM connections and models are available before spawning:

// Discovery invocation
await tool('spawn_session', {
  help: true,
});
// Returns: { connections: [...], models: [...], sources: [...] }

Spawning a Parallel Session

Create an independent session to handle a specific task while the parent continues execution:

// Spawn mode invocation
await tool('spawn_session', {
  prompt: 'Write a concise executive summary of the attached PDF.',
  name: 'summary-session',
  llmConnection: 'anthropic-api',
  model: 'claude-2.1',
  attachments: [{ path: '/workspace/reports/annual.pdf' }],
});
// Returns immediately; new session runs in parallel

Registering the Spawn Callback

Per-session registration is required to connect the tool to the server implementation:

import { registerSessionScopedToolCallbacks } from '@craft-agent/shared/src/agent/session-scoped-tool-callback-registry';

registerSessionScopedToolCallbacks(sessionId, {
  spawnSessionFn: async (args) => {
    // Forward to internal /spawn-session endpoint
    const resp = await fetch(
      `http://127.0.0.1:${config.callbackPort}/spawn-session`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(args),
      }
    );
    return await resp.json(); // { sessionId, ... }
  },
});

Summary

• The spawn_session tool is a session-scoped utility defined in packages/shared/src/agent/spawn-session-tool.ts that enables dynamic agent creation.
• It operates in two modes: Help mode for resource discovery and Spawn mode for creating new sessions.
• The tool uses a fire-and-forget pattern where the parent agent continues execution immediately after delegating to a new session.
• Agent-to-agent communication occurs through shared workspace files, providing a sandboxed collaboration channel.
• Implementation relies on a callback registry (packages/shared/src/agent/session-scoped-tool-callback-registry.ts) and an internal HTTP endpoint (/spawn-session) handled by the server package.

Frequently Asked Questions

What is the spawn-session tool used for?

The spawn-session tool enables a running Craft Agent to create additional, independent agent sessions for parallel task execution. According to the source code in craft-ai-agents/craft-agents-oss, this is useful for workflows that require isolated contexts, such as concurrent research, drafting, or analysis tasks that should not interfere with the parent agent's state.

How do spawned sessions communicate with the parent agent?

Spawned sessions communicate indirectly through the shared workspace filesystem. As implemented in the architecture, a child session can write results to specific file paths that the parent agent later reads using standard file tools. This design provides a clean, sandboxed channel that prevents state leakage between sessions while enabling rich collaboration.

What parameters are required to spawn a new session?

The tool requires either help: true to enter discovery mode or a prompt string to enter spawn mode. Optional parameters include name for the session identifier, llmConnection to specify the API endpoint, model to select the LLM, and attachments to include file references. The implementation in packages/shared/src/agent/spawn-session-tool.ts validates these inputs using Zod schemas.

Where is the spawn-session callback registered?

The callback is registered per-session in packages/shared/src/agent/session-scoped-tool-callback-registry.ts using the registerSessionScopedToolCallbacks function. This registry stores the spawnSessionFn that the tool invokes when creating new sessions, which ultimately forwards the request to the internal /spawn-session endpoint defined in the server package.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}