┌──────────────────────────────────────────────────────────────────┐
│                        Claude Code Session                       │
│                                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
│  │  Agent 1  │    │  Agent 2  │    │  Agent 3  │    │  Agent N  │  │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘  │
│       │               │               │               │          │
│       └───────────────┼───────────────┼───────────────┘          │
│                       ▼                                          │
│              ┌────────────────┐                                  │
│              │  Stop Hook     │ ← Intercepts every agent stop    │
│              │  (pre-command) │                                   │
│              └───────┬────────┘                                  │
│                      ▼                                           │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │              Autopilot Coordinator                         │  │
│  │                                                           │  │
│  │  1. Discover tasks from 3 sources                         │  │
│  │  2. Check completion: all done?                           │  │
│  │     YES → Allow stop, record success episode              │  │
│  │     NO  → Build re-engagement context                     │  │
│  │           → Re-inject remaining tasks + learned patterns  │  │
│  │           → Increment iteration counter                   │  │
│  │           → Continue execution                            │  │
│  │                                                           │  │
│  │  Safety: max iterations (50), timeout (4hr), manual kill  │  │
│  └────────────────────┬──────────────────────────────────────┘  │
│                       ▼                                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │              AutopilotLearning (AgentDB)                   │  │
│  │                                                           │  │
│  │  • Record completion/failure episodes                     │  │
│  │  • SONA trajectory tracking                               │  │
│  │  • Pattern discovery from past completions                │  │
│  │  • Predict optimal next action                            │  │
│  │  • Build re-engagement context with recommendations       │  │
│  └───────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

interface ReEngagementContext {
  // From AutopilotLearning (AgentDB)
  pastFailures: Array<{ task: string; critique?: string; reward: number }>;
  pastSuccesses: Array<{ task: string; reward: number }>;
  patterns: Array<{ pattern: string; frequency: number; avgReward: number }>;
  recommendations: string[];
  confidence: number;  // 0-1, based on episode count

  // From task discovery
  remainingTasks: Array<{ id: string; subject: string; status: string; source: string }>;
  completedTasks: number;
  totalTasks: number;
  progressPercent: number;
}

AUTOPILOT: {completedTasks}/{totalTasks} tasks complete ({progressPercent}%).
Remaining: {remainingTasks as bullet list}
{if learning available: Past patterns suggest: {recommendations}}
Continue working on the remaining tasks. Do not stop until all are complete.

// Pseudocode for the stop hook
async function autopilotStopHook(context: StopHookContext): Promise<StopHookResult> {
  // 1. Check if autopilot is enabled
  const config = loadAutopilotConfig();
  if (!config.enabled) return { allowStop: true };

  // 2. Check safety limits
  const state = loadAutopilotState();
  if (state.iterations >= config.maxIterations) {
    logEvent('max-iterations-reached', state);
    return { allowStop: true, reason: `Max iterations (${config.maxIterations}) reached` };
  }
  if (Date.now() - state.startTime > config.timeoutMinutes * 60000) {
    logEvent('timeout-reached', state);
    return { allowStop: true, reason: `Timeout (${config.timeoutMinutes}min) reached` };
  }

  // 3. Discover tasks from all sources
  const tasks = await discoverTasks(config.taskSources);
  const incomplete = tasks.filter(t => !isTerminal(t.status));

  if (incomplete.length === 0) {
    // All done — record success and allow stop
    await learning.recordTaskCompletion({
      taskId: state.sessionId,
      subject: `Session completion: ${tasks.length} tasks`,
      status: 'completed',
      iterations: state.iterations,
      durationMs: Date.now() - state.startTime,
    });
    await learning.endSwarmTrajectory({ completed: tasks.length, total: tasks.length });
    logEvent('all-tasks-complete', { total: tasks.length, iterations: state.iterations });
    return { allowStop: true };
  }

  // 4. Tasks remain — build re-engagement context
  state.iterations++;
  saveAutopilotState(state);

  const reEngagement = await learning.getReEngagementContext(
    incomplete.map(t => ({ subject: t.subject, status: t.status }))
  );

  await learning.recordIterationStep(
    { completed: tasks.length - incomplete.length, total: tasks.length, iterations: state.iterations, progress: (tasks.length - incomplete.length) / tasks.length },
    []  // drift signals
  );

  logEvent('re-engaging', {
    iteration: state.iterations,
    completed: tasks.length - incomplete.length,
    remaining: incomplete.length,
    confidence: reEngagement.confidence,
  });

  // 5. Build continuation prompt
  const prompt = buildReEngagementPrompt(incomplete, reEngagement, state);

  return {
    allowStop: false,
    continueWith: prompt,
    reason: `${incomplete.length}/${tasks.length} tasks remaining (iteration ${state.iterations}/${config.maxIterations})`,
  };
}

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx claude-flow@latest hooks autopilot-check"
          }
        ]
      }
    ]
  }
}

## Autopilot: Persistent Task Completion

This project uses autopilot for persistent swarm completion. When enabled:

1. **Do not stop early**: Continue working until ALL tasks in the task list are complete
2. **Check task status**: Before finishing, verify every task is marked `completed`
3. **Re-engage on incomplete**: If tasks remain, continue working on them
4. **Report progress**: Periodically report completion percentage

### Autopilot Commands
- `npx claude-flow autopilot status` — Check current progress
- `npx claude-flow autopilot enable` — Enable persistent completion
- `npx claude-flow autopilot disable` — Disable (allow early stop)
- `npx claude-flow autopilot predict` — Get AI-recommended next action

// coordination/index.ts
export { AutopilotLearning } from './autopilot-learning.js';
export type { AutopilotEpisode, ReEngagementContext, LearningMetrics } from './autopilot-learning.js';

// mcp/fastmcp/tools/index.ts
export { registerAutopilotTools } from './autopilot-tools.js';

// cli/index.ts
export { handleAutopilotCommand } from './autopilot-cli.js';

{
  "exports": {
    "./autopilot": "./dist/coordination/autopilot-learning.js",
    "./autopilot/cli": "./dist/cli/autopilot-cli.js",
    "./autopilot/mcp": "./dist/mcp/fastmcp/tools/autopilot-tools.js"
  }
}

{
  "sessionId": "ulid-session-id",
  "enabled": true,
  "startTime": 1770837879989,
  "iterations": 0,
  "maxIterations": 50,
  "timeoutMinutes": 240,
  "taskSources": ["team-tasks", "swarm-tasks", "file-checklist"],
  "lastCheck": null,
  "history": []
}

[
  { "ts": 1770837880000, "event": "enabled", "config": { "maxIterations": 50 } },
  { "ts": 1770837890000, "event": "re-engaging", "iteration": 1, "completed": 3, "remaining": 5, "confidence": 0.72 },
  { "ts": 1770837990000, "event": "re-engaging", "iteration": 2, "completed": 6, "remaining": 2, "confidence": 0.85 },
  { "ts": 1770838090000, "event": "all-tasks-complete", "total": 8, "iterations": 3, "durationMs": 210000 }
]

{
  "claudeFlow": {
    "autopilot": {
      "enabled": true,
      "maxIterations": 50,
      "timeoutMinutes": 240,
      "taskSources": ["team-tasks", "swarm-tasks", "file-checklist"],
      "completionCriteria": "all-tasks-done",
      "logFile": ".claude-flow/data/autopilot-log.json"
    }
  }
}

await learning.recordTaskCompletion({
  taskId: sessionId,
  subject: `Completed: ${taskSummary}`,
  status: 'completed',
  iterations: state.iterations,
  durationMs: elapsed,
});

await learning.recordTaskFailure({
  taskId: sessionId,
  subject: `Incomplete: ${incompleteTasks.length} remaining`,
  status: 'timeout',
  iterations: state.iterations,
  durationMs: elapsed,
  critique: `Stopped at ${progressPercent}% — remaining: ${incompleteList}`,
});

reward = (1 - iterations/(iterations + 10)) * 0.6 + (1 - min(durationMs/3600000, 1)) * 0.4

WARNING: No progress in 5 iterations. Consider:
- Breaking remaining tasks into smaller subtasks
- Trying a different approach
- Checking if tasks are blocked on external dependencies