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

> Discover the spawn-session tool in Craft Agents for seamless agent-to-agent communication. Enable parallel sessions with isolated contexts for effective multi-agent collaboration.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-06

---

**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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```typescript
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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.