# Phase 4: Agent Identity & Coloring — Implementation Plan

**Priority:** P3 · **Effort:** 0.5 days

---

## Step 1: Types

### 1.1. Modify `src/types.ts`

```typescript
export type AgentColorName = "blue" | "green" | "yellow" | "magenta" | "cyan" | "red" | "white" | "dim";

export const AGENT_COLORS: AgentColorName[] = [
  "blue", "green", "yellow", "magenta", "cyan", "red", "white", "dim",
];
```

Add to `AgentConfig`:
```typescript
color?: AgentColorName;
```

### 1.2. Modify `src/ui/agent-widget.ts`

Add color to `AgentDetails`:
```typescript
export interface AgentDetails {
  // ...existing...
  color?: AgentColorName;
}
```

---

## Step 2: Create `src/agent-color.ts`

New module for color management:

```typescript
import { AGENT_COLORS, type AgentColorName } from "./types.js";

/**
 * Deterministic color assignment from agent ID.
 * Same agent ID always gets the same color.
 */
export function assignAgentColor(id: string, preferred?: AgentColorName): AgentColorName {
  if (preferred && AGENT_COLORS.includes(preferred)) return preferred;
  // Simple hash of the ID to pick a color
  let hash = 0;
  for (let i = 0; i < id.length; i++) {
    hash = ((hash << 5) - hash + id.charCodeAt(i)) | 0;
  }
  return AGENT_COLORS[Math.abs(hash) % AGENT_COLORS.length];
}
```

---

## Step 3: Wire Through the System

### 3.1. In `src/index.ts` — Agent Tool Execute

When building `detailBase`, include the color:

```typescript
const color = assignAgentColor(
  id,
  customConfig?.color as AgentColorName | undefined,
);

const detailBase = {
  displayName,
  description: params.description,
  subagentType,
  modelName: agentModelName,
  tags: agentTags.length > 0 ? agentTags : undefined,
  color,
};
```

### 3.2. In `src/ui/agent-widget.ts` — Rendering

Use the color in the widget's status line. The `pi-tui` `theme.fg()` function accepts color names:

```typescript
// In the widget render:
const colorName = details.color ?? "blue";
const indicator = theme.fg(colorName, "●");
```

### 3.3. In `src/custom-agents.ts` — Frontmatter Parsing

```typescript
// Extract color from frontmatter
const color = frontmatter.color;
if (color && AGENT_COLORS.includes(color as AgentColorName)) {
  config.color = color as AgentColorName;
}
```

---

## Step 4: Tests — `test/agent-color.test.ts`

| # | Test | Expected |
|---|---|---|
| 1 | Deterministic assignment | Same ID → same color |
| 2 | Preferred color respected | `assignAgentColor("id", "green")` → `"green"` |
| 3 | Invalid preferred falls back | `assignAgentColor("id", "purple")` → some valid color |
| 4 | Distribution | 100 random IDs cover most of the palette |
| 5 | Frontmatter parsing | `.md` with `color: cyan` parses correctly |

---

## File Change Summary

| Action | File |
|---|---|
| **MODIFY** | `src/types.ts` — add `AgentColorName`, `AGENT_COLORS`, `color` on `AgentConfig` |
| **CREATE** | `src/agent-color.ts` (~30 lines) |
| **MODIFY** | `src/index.ts` — assign color in detailBase |
| **MODIFY** | `src/ui/agent-widget.ts` — render color indicator |
| **MODIFY** | `src/custom-agents.ts` — parse color from frontmatter |
| **CREATE** | `test/agent-color.test.ts` (~50 lines) |