feat: Add agent forking with letta fork subcommand

[cpfiffer]

Summary

Adds agent forking capability - agents can clone themselves to spawn subagents for parallel work.

Very speculative, mostly made for experimentation purposes.

Usage

From within an agent (via Bash tool):

# Basic fork - shares memory with parent
letta fork -p "analyze src/ directory"

# Isolated fork - cloned memory blocks
letta fork -p "experiment with refactor" --isolated

# Fresh conversation fork
letta fork -p "start from scratch" --fresh-conversation

# Persistent fork (don't auto-delete)
letta fork -p "long-running task" --keep

How It Works

1. Agent Cloning

• Uses agent export/import API to clone configuration
• Copies: model, tools, memory blocks, settings
• By default, shares memory blocks with parent (changes visible to both)
• --isolated flag creates new blocks with copied content

2. Fork Bomb Prevention

Requires LETTA_SELF_AGENT_ID environment variable:

• Only available when called from within an agent (via Bash tool)
• Set via global agent context when session starts
• Prevents external users from spawning forks

Maximum fork depth: 3 levels

• Tracks depth via agent tags: fork-depth:0, fork-depth:1, etc.
• Prevents recursive fork bombs
• Error if depth limit reached

Tagging:

• origin:letta-code-fork - Identifies as fork
• parent: - Links to parent agent
• fork-depth: - Tracks recursion depth
• ephemeral:true - Marks for auto-cleanup (unless --keep)

3. Ephemeral Agent Cleanup

By default, forks are ephemeral:

• Registered in cleanup registry
• Deleted when headless mode exits (normal or error)
• Use --keep flag to persist permanently

Cleanup triggers:

• After fork completes its task
• On parent agent error/exit
• Prevents orphaned agents accumulating

Implementation

Files Added

• src/agent/context.ts - Global agent ID context for tool execution
• src/agent/fork.ts - Fork logic with export/import/cleanup

Files Modified

• src/cli/App.tsx - Set agent context on session start
• src/headless.ts - Set agent context + cleanup ephemeral agents
• src/index.ts - Add fork subcommand detection + flags
• README.md - Document fork usage

Options

• --isolated - Clone memory blocks instead of sharing
• --fresh-conversation - Clear conversation history
• --keep - Persist forked agent (don't auto-delete)
• -p "prompt" - Execute prompt in forked agent

Example Workflow

# Agent delegates subtask to fork
Bash(letta fork -p "Run all tests and fix any failures" --keep)

# Parent continues working on main task
# Fork results come back in Bash tool output

# Fork auto-deleted after completion (unless --keep)

Testing

✅ Lint passes
✅ Type check passes
✅ Build succeeds
✅ Fork command fails gracefully without LETTA_SELF_AGENT_ID

Manual testing needed:

• Test fork from within live agent session
• Verify memory block sharing vs isolation
• Verify ephemeral cleanup works
• Test fork depth limit enforcement

Future Enhancements

• Permission-based fork gating (settings.json allowFork flag)
• Fork cleanup on parent deletion (not just exit)
• Fork monitoring/listing command (letta forks)
• Interactive fork support (currently headless only)

👾 Generated with Letta Code