# Persona Hot-Swap Example [NOT YET IMPLEMENTED]

> **Status:** This document describes a planned feature. `ctl_switch_persona` is **not yet implemented**.
> Persona is currently fixed at agent start and cannot be changed at runtime.

This document describes the planned behavior for `ctl_switch_persona`, which will allow an agent to change its persona mid-session while preserving conversation history.

## Overview (Planned)

When implemented, persona hot-swap will allow a running agent to adapt its capabilities without restarting. This will be useful when:

- Switching from a "coder" persona to a "reviewer" persona for code review
- Adapting to different task phases within a single session
- Dynamically adjusting tool access or model parameters based on context

## Prerequisites (When Implemented)

- anima CLI installed and configured
- Two or more PersonaSpec JSON files

## Planned Walkthrough

### Step 1: Create Persona A (Coder)

Create `personas/coder.json`:

```json
{
  "id": "coder",
  "description": "A coding assistant that writes and edits code",
  "prompt": "You are an expert software engineer. Your task is to write clean, well-documented code. You have access to file system tools for reading and writing code. After completing your task, call ctl_finish with a summary of what you created.",
  "model": "claude-sonnet-4-20250514",
  "tools": {
    "filesystem": "read_write",
    "shell": "read_only"
  },
  "spec_version": "0.1.0"
}
```

### Step 2: Create Persona B (Reviewer)

Create `personas/reviewer.json`:

```json
{
  "id": "reviewer",
  "description": "A code reviewer that provides feedback on code quality",
  "prompt": "You are a senior code reviewer. Your task is to review code for correctness, style, and potential improvements. You have read-only access to the filesystem. After completing your review, call ctl_finish with your findings.",
  "model": "claude-sonnet-4-20250514",
  "tools": {
    "filesystem": "read_only"
  },
  "spec_version": "0.1.0"
}
```

### Step 3: Start a Daemon with Persona A

Spawn a daemon agent with the coder persona:

```bash
anima spawn \
  --persona-file personas/coder.json \
  --lifecycle daemon \
  "Create a Python script that calculates fibonacci numbers"
```

Note the instance ID (e.g., `inst_abc123`).

### Step 4: Interact and Switch Persona (Planned)

When `ctl_switch_persona` is implemented, you would attach to the running agent:

```bash
anima talk inst_abc123
```

And then request a persona switch within the same session:

```
[You] Please switch to the reviewer persona and review the code you just wrote.

[Agent] I'll switch to the reviewer persona now.

>>> Calling ctl_switch_persona with {"persona_ref": "personas/reviewer.json"}
<<< Result: "Persona switched to: reviewer. Will take effect at next turn."

[Agent - now as reviewer] Reviewing the fibonacci script...

The code is functional but has a few issues:
1. No input validation for negative numbers
2. Could benefit from memoization for performance
3. Missing docstrings and type hints
...
```

## Planned Behaviors

### Turn Boundary Semantics

When implemented, the persona switch would be **cooperative**, not immediate:

1. `ctl_switch_persona` would be called and return immediately
2. The switch would be queued for the next turn boundary
3. Ongoing tool calls in the current turn would complete normally
4. At the next turn, the agent would be rebuilt with the new persona
5. `message_history` would be preserved; only the agent object would be replaced

### State Preservation

When implemented, the following state would be preserved across a persona switch:

- ✅ Conversation history (`message_history`)
- ✅ Turn counters
- ✅ Token accounting
- ✅ MCP server connections
- ✅ Control channel state

The following would be updated:

- 🔄 Agent object (rebuilt with new persona)
- 🔄 Persona-derived fields in `AgentStateData`:
  - `persona_name`
  - `persona_ref`
  - `spec_id`
  - `spec_digest`

### Single-Pending Constraint

When implemented, only one persona switch would be allowed to be pending at a time:

```python
# First switch request - would succeed
result1 = await ctl_switch_persona("personas/reviewer.json")
# Would return: "Persona switched to: reviewer. Will take effect at next turn."

# Second switch request while first is pending - would fail
result2 = await ctl_switch_persona("personas/architect.json")
# Would return: "Error: A persona switch is already pending"
```

## Planned API Reference

### ctl_switch_persona(persona_ref) [NOT YET IMPLEMENTED]

**Parameters:**
- `persona_ref` (string, required): Path to a PersonaSpec JSON file

**Returns (when implemented):**
- Success: `"Persona switched to: <persona_name>. Will take effect at next turn."`
- Failure: `"Error: <message>"`

**Error Conditions (when implemented):**
- Persona file not found or invalid JSON
- Another persona switch is already pending
- PersonaSpec validation fails

## See Also

- [INTERFACES.md Section D.5](../INTERFACES.md#d5-ctl_switch_personapersona_ref) - Planned API documentation
- [DESIGN.md Section 8](../DESIGN.md#8-persona-runtime-switchability) - Architecture planning
