@vibescope/mcp-server 0.5.0 → 0.5.1

package/src/handlers/session.ts

@@ -1,1105 +1,1105 @@
-/**
- * Session Handlers
- *
- * Handles agent session lifecycle:
- * - start_work_session
- * - heartbeat
- * - end_work_session
- * - get_help
- * - get_token_usage
- */
-
-import os from 'os';
-import crypto from 'crypto';
-import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
-import { parseArgs, createEnumValidator } from '../validators.js';
-import { getApiClient } from '../api-client.js';
-import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
-import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
-import { normalizeGitUrl } from '../utils.js';
-import { autoPostActivity } from './chat.js';
-
-/**
- * Simple hash for content change detection.
- */
-function simpleHash(content: string): string {
-	return crypto.createHash('md5').update(content).digest('hex').slice(0, 12);
-}
-
-/**
- * Build the full CLAUDE.md content from dynamic rules + project instructions.
- * This is what gets persisted to .claude/CLAUDE.md by the agent.
- */
-function buildPersistContent(
-	agentRules: string[],
-	workflow: Record<string, unknown>,
-	project: Record<string, unknown> | undefined,
-	agentInstructions: string
-): string {
-	const lines: string[] = [];
-
-	lines.push('<!-- hash:{{HASH}} -->');
-	lines.push('<!-- AUTO-GENERATED by Vibescope MCP. Do not edit manually — changes will be overwritten on next start_work_session. -->');
-	lines.push('');
-	lines.push('# Vibescope Agent Guidelines');
-	lines.push('');
-
-	// Quick start
-	lines.push('## Quick Start');
-	lines.push('');
-	lines.push('```');
-	lines.push('start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus", agent_type: "claude", agent_name: "YOUR_NAME")');
-	lines.push('```');
-	lines.push('');
-
-	// Mandatory rules
-	lines.push('## MANDATORY Workflow Rules (NON-NEGOTIABLE)');
-	lines.push('');
-	for (const rule of agentRules) {
-		lines.push(`- ${rule}`);
-	}
-	lines.push('');
-
-	// Session ID reminder
-	lines.push('### Session ID');
-	lines.push('');
-	lines.push('Save the `session_id` from `start_work_session` and pass it on EVERY `update_task`, `complete_task`, and `get_next_task` call. Without it, task claiming fails and your name won\'t show on completed tasks.');
-	lines.push('');
-
-	// Workflow
-	const workflowContinuous = workflow.continuous_work as { steps?: string[]; rule?: string } | undefined;
-	if (workflowContinuous) {
-		lines.push('## Continuous Work Loop');
-		lines.push('');
-		if (workflowContinuous.steps) {
-			for (const step of workflowContinuous.steps) {
-				lines.push(`1. ${step}`);
-			}
-		}
-		if (workflowContinuous.rule) {
-			lines.push('');
-			lines.push(`**${workflowContinuous.rule}**`);
-		}
-		lines.push('');
-	}
-
-	const workflowValidation = workflow.validation as { steps?: string[] } | undefined;
-	if (workflowValidation?.steps) {
-		lines.push('## Validation Workflow');
-		lines.push('');
-		for (const step of workflowValidation.steps) {
-			lines.push(`1. ${step}`);
-		}
-		lines.push('');
-	}
-
-	// Context management
-	lines.push('## Context Management');
-	lines.push('');
-	lines.push('When context grows large or responses slow:');
-	lines.push('1. Run `/clear`');
-	lines.push('2. Call `start_work_session(...)` again immediately');
-	lines.push('3. Continue with `next_task` — do NOT ask permission');
-	lines.push('');
-
-	// MCP connection
-	lines.push('## MCP Connection Required');
-	lines.push('');
-	lines.push('**If MCP connection fails, end session immediately.** Never work without task tracking.');
-	lines.push('');
-
-	// Project-specific instructions from template
-	if (agentInstructions.trim()) {
-		lines.push('## Project-Specific Instructions');
-		lines.push('');
-		lines.push(agentInstructions.trim());
-		lines.push('');
-	}
-
-	// Help topics
-	lines.push('## Help Topics');
-	lines.push('');
-	lines.push('`get_help(topic)` for: `getting_started`, `tasks`, `validation`, `deployment`, `git`, `blockers`, `milestones`, `fallback`, `session`, `topics`');
-
-	const content = lines.join('\n');
-	// Replace hash placeholder with actual hash
-	const hash = simpleHash(content.replace('<!-- hash:{{HASH}} -->', ''));
-	return content.replace('{{HASH}}', hash);
-}
-
-// Auto-detect machine hostname for worktree tracking
-const MACHINE_HOSTNAME = os.hostname();
-
-const VALID_MODES = ['lite', 'full'] as const;
-// Model, role, and agent_type are now open-ended - any string is accepted
-
-type SessionMode = typeof VALID_MODES[number];
-type SessionModel = string; // Open-ended - any model name accepted
-type SessionRole = string; // Open-ended - any role name accepted
-type AgentType = string; // Open-ended - any agent type accepted
-
-// Argument schemas for type-safe parsing
-const startWorkSessionSchema = {
-	project_id: { type: 'string' as const },
-	git_url: { type: 'string' as const },
-	mode: { type: 'string' as const, default: 'lite', validate: createEnumValidator(VALID_MODES) },
-	model: { type: 'string' as const }, // Open-ended - any model name accepted
-	role: { type: 'string' as const, default: 'developer' }, // Open-ended - any role name accepted
-	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
-	agent_type: { type: 'string' as const }, // Open-ended - any agent type accepted
-	agent_name: { type: 'string' as const }, // Explicit agent name for cloud/remote agents (skips persona pool)
-};
-
-const heartbeatSchema = {
-	session_id: { type: 'string' as const },
-	current_worktree_path: { type: 'string' as const },
-	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
-};
-
-const endWorkSessionSchema = {
-	session_id: { type: 'string' as const },
-};
-
-const getHelpSchema = {
-	topic: { type: 'string' as const, required: true as const },
-};
-
-export const startWorkSession: Handler = async (args, ctx) => {
-	const { project_id, git_url, mode, model, role, hostname: providedHostname, agent_type, agent_name } = parseArgs(args, startWorkSessionSchema);
-
-	// Use auto-detected hostname if not provided - enables machine-aware worktree filtering
-	const hostname = providedHostname || MACHINE_HOSTNAME;
-
-	// Normalize git_url and track if it was changed - helps agents understand URL matching
-	const normalizedGitUrl = git_url ? normalizeGitUrl(git_url) : null;
-	const gitUrlWasNormalized = git_url && normalizedGitUrl && git_url !== normalizedGitUrl;
-
-	const { session, updateSession } = ctx;
-
-	// Reset token tracking for new session with model info
-	// Model is now open-ended - use as-is (normalize Claude model names for consistency)
-	const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
-
-	updateSession({
-		tokenUsage: {
-			callCount: 0,
-			totalTokens: 0,
-			byTool: {},
-			byModel: {},
-			currentModel: normalizedModel,
-		},
-	});
-
-	// Require project_id or git_url
-	if (!project_id && !git_url) {
-		return {
-			result: {
-				error: 'Please provide project_id or git_url to start a session',
-				session_termination_required: true,
-				reason: 'Cannot start work without identifying a project',
-				action: 'END_SESSION_NOW - Do not proceed with any work until MCP is properly configured.',
-			},
-		};
-	}
-
-	const apiClient = getApiClient();
-	const response = await apiClient.startSession({
-		project_id,
-		git_url,
-		mode: mode as SessionMode,
-		model: model as SessionModel | undefined,
-		role: role as SessionRole,
-		hostname, // Machine hostname for worktree tracking
-		agent_type: agent_type as AgentType | undefined, // Agent type for onboarding
-		agent_name: agent_name as string | undefined, // Explicit name for cloud/remote agents
-	});
-
-	if (!response.ok) {
-		// Include additional error details if available
-		const errorData = response.data as { detail?: string; code?: string } | undefined;
-		return {
-			result: {
-				error: response.error || 'Failed to start session',
-				...(errorData?.detail && { detail: errorData.detail }),
-				...(errorData?.code && { code: errorData.code }),
-				session_termination_required: true,
-				reason: 'MCP server connection failed - cannot track work',
-				action: 'END_SESSION_NOW - Do not proceed with any work.',
-				troubleshooting: [
-					'1. Check if MCP server is configured: claude mcp list',
-					'2. Verify VIBESCOPE_API_KEY is set correctly',
-					'3. Check network connectivity to vibescope.dev',
-					'4. Restart Claude Code after fixing configuration',
-				],
-				user_message: 'MCP connection to Vibescope failed. I cannot proceed without task tracking. Please fix the configuration and restart.',
-			},
-		};
-	}
-
-	const data = response.data;
-
-	// Handle project not found - include agent guidelines for new project setup
-	if (!data?.session_started) {
-		// If project_not_found, include agent guidelines template for CLAUDE.md setup
-		if (data?.project_not_found) {
-			return {
-				result: {
-					...data,
-					agent_guidelines: {
-						message: 'IMPORTANT: After creating the project, add these guidelines to your .claude/CLAUDE.md file.',
-						summary: getAgentGuidelinesSummary(),
-						full_template: getAgentGuidelinesTemplate(),
-						setup_instructions: [
-							'1. Create the project using create_project()',
-							'2. Create .claude/CLAUDE.md in your project root',
-							'3. Copy the full_template content into CLAUDE.md',
-							'4. Call start_work_session again to begin work',
-						],
-					},
-				},
-			};
-		}
-		return { result: data };
-	}
-
-	// Store session ID and persona in local state
-	if (data.session_id) {
-		updateSession({
-			currentSessionId: data.session_id,
-			currentPersona: data.persona || null,
-		});
-	}
-
-	// Check for urgent questions - these MUST be handled first
-	const hasUrgentQuestions = data.URGENT_QUESTIONS || (data.pending_requests && data.pending_requests.length > 0);
-
-	// Build result - URGENT_QUESTIONS at absolute top for maximum visibility
-	const result: Record<string, unknown> = {
-		session_started: true,
-	};
-
-	// URGENT_QUESTIONS must be the FIRST thing the agent sees
-	if (data.URGENT_QUESTIONS) {
-		result.URGENT_QUESTIONS = data.URGENT_QUESTIONS;
-	}
-
-	// Directive comes right after urgent questions
-	result.directive = data.directive || 'ACTION_REQUIRED: Start working immediately.';
-	result.auto_continue = true;
-
-	// Session info
-	result.session_id = data.session_id;
-	result.IMPORTANT_session_id_reminder = `Save this session_id ("${data.session_id}") and pass it on EVERY update_task and complete_task call. Without it, the dashboard shows "Agent" instead of your name.`;
-	result.persona = data.persona;
-	result.role = data.role;
-	result.project = data.project;
-
-	// For cloud agents: include workspace setup instructions if repo not yet cloned
-	// Cloud agents pass git_url; check if workspace needs setup
-	if (git_url && data.project?.git_url) {
-		result.workspace_setup = {
-			message: 'If the project repo is NOT already cloned to your workspace, follow these steps:',
-			steps: [
-				`git clone ${data.project.git_url} ~/workspace/project`,
-				'cd ~/workspace/project',
-				...(data.project.git_workflow === 'git-flow'
-					? [`git checkout ${data.project.git_develop_branch || 'develop'}`]
-					: []),
-				'Install dependencies (check for pnpm-lock.yaml, package-lock.json, etc.)',
-				'If using SvelteKit: run `pnpm exec svelte-kit sync` or equivalent',
-			],
-			note: 'Skip these steps if ~/workspace/project already exists and has the repo.',
-		};
-	}
-
-	// Inform agent if git_url was normalized (helps explain URL matching behavior)
-	if (gitUrlWasNormalized) {
-		result.git_url_normalized = {
-			message: 'Your git URL was normalized for project lookup. All URL formats for the same repository resolve to the same project.',
-			original: git_url,
-			normalized: normalizedGitUrl,
-			examples: [
-				'git@github.com:owner/repo.git → https://github.com/owner/repo',
-				'https://GITHUB.COM/Owner/Repo/ → https://github.com/owner/repo',
-				'http://github.com/owner/repo.git → https://github.com/owner/repo',
-			],
-		};
-	}
-
-	// Add task data
-	if (data.next_task) {
-		result.next_task = data.next_task;
-	}
-
-	// Add pending requests (questions from user) - these take priority
-	if (data.pending_requests && data.pending_requests.length > 0) {
-		result.pending_requests = data.pending_requests;
-		result.pending_requests_count = data.pending_requests.length;
-	}
-
-	// Add active tasks for full mode
-	if (data.active_tasks) {
-		result.active_tasks = data.active_tasks;
-	}
-
-	// Add blockers
-	if (data.blockers) {
-		result.open_blockers = data.blockers;
-	}
-	if (data.blockers_count !== undefined && data.blockers_count > 0) {
-		result.blockers_count = data.blockers_count;
-	}
-
-	// Add validation tasks when present - agents should validate before starting new work
-	if (data.validation_count !== undefined && data.validation_count > 0) {
-		result.validation_count = data.validation_count;
-	}
-	if (data.awaiting_validation && data.awaiting_validation.length > 0) {
-		result.awaiting_validation = data.awaiting_validation;
-		result.validation_priority = data.validation_priority;
-	}
-
-	// Add stale worktrees warning if any exist
-	if (data.stale_worktrees && data.stale_worktrees.length > 0) {
-		result.stale_worktrees = data.stale_worktrees;
-		result.stale_worktrees_count = data.stale_worktrees_count;
-		result.cleanup_action = data.cleanup_action;
-	}
-
-	// Add git workflow info if available in project
-	if (data.project?.git_workflow && data.project.git_workflow !== 'none') {
-		// Branching workflows (git-flow, github-flow) require worktrees
-		// Trunk-based development commits directly to main, no worktree needed
-		const isBranchingWorkflow = data.project.git_workflow === 'git-flow' || data.project.git_workflow === 'github-flow';
-		const baseBranch = data.project.git_workflow === 'git-flow'
-			? (data.project.git_develop_branch || 'develop')
-			: (data.project.git_main_branch || 'main');
-
-		result.git_workflow = {
-			workflow: data.project.git_workflow,
-			auto_branch: data.project.git_auto_branch ?? false,
-			main_branch: data.project.git_main_branch || 'main',
-			...(data.project.git_workflow === 'git-flow' && data.project.git_develop_branch
-				? { develop_branch: data.project.git_develop_branch }
-				: {}),
-			worktree_required: isBranchingWorkflow,
-		};
-
-		// Only show worktree reminder for branching workflows (git-flow, github-flow)
-		if (isBranchingWorkflow) {
-			result.WORKTREE_REMINDER = {
-				message: 'CRITICAL: Create worktree BEFORE making ANY file edits',
-				wrong_order: 'DO NOT: Edit files → stash → create worktree → pop stash',
-				right_order: 'DO: Create worktree → cd into it → THEN edit files',
-				command: `git worktree add ../<project>-<persona>-<task> -b feature/<task-id> ${baseBranch}`,
-				help: 'Run get_help("git") for full instructions',
-			};
-
-			// Add FIRST_TIME_CONNECTION guidance for git-flow
-			if (data.project.git_workflow === 'git-flow') {
-				result.FIRST_TIME_CONNECTION = {
-					workflow: 'git-flow',
-					steps: [
-						`1. git checkout ${data.project.git_develop_branch || 'develop'}`,
-						`2. git pull origin ${data.project.git_develop_branch || 'develop'}`,
-						'3. All feature branches must be created from develop',
-					],
-					warning: 'Working from main or stale branches causes merge conflicts.',
-					base_branch: data.project.git_develop_branch || 'develop',
-				};
-			} else if (data.project.git_workflow === 'github-flow') {
-				result.FIRST_TIME_CONNECTION = {
-					workflow: 'github-flow',
-					steps: [
-						`1. git checkout ${data.project.git_main_branch || 'main'}`,
-						`2. git pull origin ${data.project.git_main_branch || 'main'}`,
-						'3. All feature branches must be created from main',
-					],
-					warning: 'Working from stale branches causes merge conflicts.',
-					base_branch: data.project.git_main_branch || 'main',
-				};
-			}
-		}
-	}
-
-	// Add agent setup instructions if this is a new agent type for the project
-	if (data.agent_setup) {
-		result.agent_setup = data.agent_setup;
-		// If setup is required, update directive to prioritize setup
-		if (data.agent_setup.setup_required) {
-			result.directive = `SETUP REQUIRED: This is your first time connecting as a ${data.agent_setup.agent_type} agent. Follow the agent_setup instructions before starting work.`;
-		}
-	}
-
-	// Build dynamic AGENT_RULES from project settings
-	const agentRules: string[] = [];
-	const projectWorkflow = data.project?.git_workflow;
-	const isBranching = projectWorkflow === 'git-flow' || projectWorkflow === 'github-flow';
-	const ruleBaseBranch = projectWorkflow === 'git-flow'
-		? (data.project?.git_develop_branch || 'develop')
-		: (data.project?.git_main_branch || 'main');
-
-	// Git workflow rules (dynamic based on project settings)
-	if (isBranching) {
-		agentRules.push(`WORKTREE REQUIRED: Create a git worktree BEFORE making ANY file edits. Command: git worktree add ../PROJECT-PERSONA-task -b feature/TASKID-desc ${ruleBaseBranch}`);
-		agentRules.push(`REBASE BEFORE PR: Always rebase onto ${ruleBaseBranch} before creating a PR. Run: git fetch origin && git rebase origin/${ruleBaseBranch} && git push --force-with-lease. This prevents overwriting other agents' work.`);
-	}
-	if (projectWorkflow && projectWorkflow !== 'none') {
-		agentRules.push(`GIT WORKFLOW: This project uses ${projectWorkflow}. Branch from ${ruleBaseBranch}. Do NOT commit directly to main or develop.`);
-	}
-
-	// Task lifecycle rules
-	agentRules.push('COMPLETE TASKS: Always call complete_task(task_id, summary, session_id) immediately after creating a PR. This is mandatory — it updates the dashboard and triggers validation.');
-	agentRules.push('SESSION ID: Pass session_id on EVERY update_task and complete_task call. Without it, the dashboard shows "Agent" instead of your name.');
-	agentRules.push(`STATUS UPDATES: Call update_agent_status(status_message: "Working on: TASK_TITLE", project_id: "${data.project?.id || ''}", agent_name: "${result.persona || ''}") whenever you start or finish a task.`);
-	agentRules.push('TRACK PROGRESS: Call update_task with progress_percentage (0-100) every 15-20% of task completion.');
-
-	// Validation rules (dynamic based on project settings)
-	if (data.project?.validation_required !== false) {
-		agentRules.push('REVIEW REQUIRED: All completed tasks must be reviewed/validated by another agent before merging.');
-	}
-	if (data.project?.auto_merge_on_approval !== false) {
-		agentRules.push('AUTO-MERGE: After approving a PR during validation, merge it immediately with `gh pr merge --squash`.');
-	}
-
-	// Autonomy rules
-	agentRules.push('BE AUTONOMOUS: Pick up tasks without asking permission. Never ask "Should I continue?" — just continue to the next task.');
-	agentRules.push('BREAK DOWN COMPLEX TASKS: If a task is too large, create subtasks with add_subtask() and start on the first one immediately.');
-
-	result.AGENT_RULES = agentRules;
-
-	// Build WORKFLOW section — dynamic step-by-step instructions
-	// This replaces the hardcoded workflow in CLAUDE.md
-	const workflow: Record<string, unknown> = {};
-
-	// Continuous work loop
-	workflow.continuous_work = {
-		description: 'After completing a task, immediately continue to the next one.',
-		steps: [
-			'complete_task(task_id, summary, session_id) — returns next_task if available',
-			'If no next_task returned: call get_next_task(project_id)',
-			'If no tasks available: call get_pending_requests(project_id) and handle any',
-			'If still nothing: call signal_idle() then start_fallback_activity(project_id, activity: "code_review")',
-		],
-		rule: 'Never ask permission. Never stop working while tasks exist.',
-	};
-
-	// Validation workflow (only if validation is enabled)
-	if (data.project?.validation_required !== false) {
-		workflow.validation = {
-			description: 'How to validate/review completed tasks. Review PRs in FIFO order (lowest PR number first).',
-			steps: [
-				'claim_validation(task_id) — returns worktree setup commands and PR info',
-				`Set up worktree from existing branch: git fetch origin feature/xxx && git worktree add ../PROJECT-PERSONA-validation feature/xxx`,
-				'Review code, run tests if applicable',
-				'Verify PR checks: gh pr view <PR> --json statusCheckRollup,mergeable',
-				'Approve: validate_task(task_id, approved: true, pr_checks_passing: true, validation_notes: "...")',
-				data.project?.auto_merge_on_approval !== false
-					? 'Merge immediately: gh pr merge <PR> --squash'
-					: 'Do NOT merge — wait for project owner to merge.',
-				'Reject: validate_task(task_id, approved: false, validation_notes: "...", create_fix_task: true)',
-				'Clean up worktree after validation',
-			],
-			handle_failures: {
-				tests_fail: 'Use create_fix_task: true in validate_task() to create a follow-up task',
-				merge_conflicts: 'Create a task: add_task(project_id, title: "Resolve merge conflicts in PR #XXX")',
-				minor_issues: 'Fix directly in the branch, push, and re-validate',
-				closed_pr: 'cancel_task(task_id, cancelled_reason: "pr_closed")',
-			},
-			rule: 'Every PR review MUST end with a clear action. Never leave PRs unmerged or unresolved.',
-		};
-
-		// Post-merge branch sync (git-flow only)
-		if (projectWorkflow === 'git-flow' && data.project) {
-			const devBranch = data.project.git_develop_branch || 'develop';
-			workflow.post_merge_sync = {
-				description: `After merging to main, sync main back to ${devBranch} to prevent divergence.`,
-				commands: [
-					`git checkout ${devBranch} && git pull origin ${devBranch}`,
-					'git merge origin/main',
-					`git push origin ${devBranch}`,
-				],
-			};
-		}
-	}
-
-	// Deployment resolution workflow
-	workflow.deployment_resolution = {
-		description: 'When a fix already exists but just needs deployment',
-		steps: [
-			'add_finding(project_id, title: "Fix exists - needs deployment", category: "other", severity: "info")',
-			'complete_task(task_id, summary: "Fix exists in [branch/commit], pending deployment", session_id)',
-			'check_deployment_status(project_id) then request_deployment(project_id) if needed',
-		],
-		rule: 'Don\'t block tasks waiting for deployment — investigation is complete when you identify the resolution.',
-	};
-
-	result.WORKFLOW = workflow;
-
-	// Build PERSIST_INSTRUCTIONS — tells the agent to write rules to .claude/CLAUDE.md
-	// This ensures instructions survive context clears and persist across the whole session.
-	// Content comes from: admin templates + project settings (fully customizable from dashboard).
-	const agentInstructions = data.project?.agent_instructions || '';
-	const persistContent = buildPersistContent(agentRules, workflow, data.project as Record<string, unknown> | undefined, agentInstructions);
-	// Extract hash from the generated content (it's embedded in the first line)
-	const hashMatch = persistContent.match(/<!-- hash:(\w+) -->/);
-	const contentHash = hashMatch?.[1] || simpleHash(persistContent);
-
-	result.PERSIST_INSTRUCTIONS = {
-		action: 'Write the content below to .claude/CLAUDE.md (overwrite existing). This ensures your instructions persist across context clears.',
-		path: '.claude/CLAUDE.md',
-		content: persistContent,
-		hash: contentHash,
-		skip_if_hash_matches: `Only write if the file doesn't exist or its content has changed. Check for "<!-- hash:${contentHash} -->" at the top.`,
-	};
-
-	// Add next action at end - pending requests take priority over validation, then regular tasks
-	if (hasUrgentQuestions) {
-		const firstQuestion = data.URGENT_QUESTIONS?.requests?.[0] || data.pending_requests?.[0];
-		result.next_action = firstQuestion
-			? `answer_question(request_id: "${firstQuestion.id}", answer: "...")`
-			: 'Check pending_requests and respond using answer_question(request_id, answer)';
-	} else if (data.awaiting_validation && data.awaiting_validation.length > 0) {
-		// Validation tasks take priority over new work - use next_action from API if available
-		result.next_action = data.next_action || `claim_validation(task_id: "${data.awaiting_validation[0].id}")`;
-	} else if (data.next_task) {
-		result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress", session_id: "${result.session_id}")`;
-	} else if (data.project) {
-		result.next_action = data.project.fallback_activities_enabled !== false
-			? `start_fallback_activity(project_id: "${data.project.id}", activity: "code_review")`
-			: 'signal_idle() — no tasks available and fallback activities are disabled.';
-	}
-
-	// Auto-post boot activity to project chat
-	if (data.project?.id) {
-		const persona = data.persona || 'Agent';
-		const nextTaskInfo = data.next_task ? ` Next task: **${data.next_task.title}**` : '';
-		void autoPostActivity(
-			data.project.id,
-			`🤖 **${persona}** started a work session.${nextTaskInfo}`,
-			data.session_id
-		);
-	}
-
-	return { result };
-};
-
-export const heartbeat: Handler = async (args, ctx) => {
-	const { session_id, current_worktree_path, hostname: providedHostname } = parseArgs(args, heartbeatSchema);
-	const { session } = ctx;
-	const targetSession = session_id || session.currentSessionId;
-
-	// Use auto-detected hostname if not provided
-	const hostname = providedHostname || MACHINE_HOSTNAME;
-
-	if (!targetSession) {
-		return {
-			result: {
-				error: 'No active session. Call start_work_session first.',
-			},
-		};
-	}
-
-	const apiClient = getApiClient();
-
-	// Send heartbeat with optional worktree path and hostname
-	const heartbeatResponse = await apiClient.heartbeat(targetSession, {
-		current_worktree_path,
-		hostname,
-	});
-
-	if (!heartbeatResponse.ok) {
-		return {
-			result: {
-				error: heartbeatResponse.error || 'Failed to send heartbeat',
-			},
-		};
-	}
-
-	// Sync token usage to session
-	await apiClient.syncSession(targetSession, {
-		total_tokens: session.tokenUsage.totalTokens,
-		token_breakdown: session.tokenUsage.byTool,
-		model_usage: session.tokenUsage.byModel,
-	});
-
-	return {
-		result: {
-			success: true,
-			session_id: targetSession,
-			timestamp: heartbeatResponse.data?.timestamp || new Date().toISOString(),
-		},
-	};
-};
-
-export const endWorkSession: Handler = async (args, ctx) => {
-	const { session_id } = parseArgs(args, endWorkSessionSchema);
-	const { session, updateSession } = ctx;
-	const targetSession = session_id || session.currentSessionId;
-
-	if (!targetSession) {
-		return {
-			result: {
-				success: true,
-				message: 'No active session to end',
-			},
-		};
-	}
-
-	const apiClient = getApiClient();
-
-	// Sync final token usage before ending
-	await apiClient.syncSession(targetSession, {
-		total_tokens: session.tokenUsage.totalTokens,
-		token_breakdown: session.tokenUsage.byTool,
-		model_usage: session.tokenUsage.byModel,
-	});
-
-	// End the session
-	const response = await apiClient.endSession(targetSession);
-
-	if (!response.ok) {
-		return {
-			result: {
-				error: response.error || 'Failed to end session',
-			},
-		};
-	}
-
-	const endedSessionId = targetSession;
-
-	// Clear local session state if this was the current session
-	if (session.currentSessionId === targetSession) {
-		updateSession({ currentSessionId: null });
-	}
-
-	const data = response.data;
-
-	return {
-		result: {
-			success: true,
-			ended_session_id: endedSessionId,
-			session_summary: {
-				agent_name: data?.session_summary?.agent_name || 'Agent',
-				tasks_completed_this_session: data?.session_summary?.tasks_completed_this_session || 0,
-				tasks_awaiting_validation: data?.session_summary?.tasks_awaiting_validation || 0,
-				tasks_released: data?.session_summary?.tasks_released || 0,
-				token_usage: {
-					total_calls: session.tokenUsage.callCount,
-					total_tokens: session.tokenUsage.totalTokens,
-					avg_per_call: session.tokenUsage.callCount > 0
-						? Math.round(session.tokenUsage.totalTokens / session.tokenUsage.callCount)
-						: 0,
-				},
-			},
-			reminders: data?.reminders || ['Session ended cleanly. Good work!'],
-		},
-	};
-};
-
-export const getHelp: Handler = async (args, _ctx) => {
-	const { topic } = parseArgs(args, getHelpSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.getHelpTopic(topic);
-
-	// Try database content first
-	if (response.ok && response.data?.content) {
-		return { result: { topic, content: response.data.content } };
-	}
-
-	// Fall back to local content if database is empty or unavailable
-	const fallback = getFallbackHelpContent(topic);
-	if (fallback) {
-		return { result: { topic, content: fallback.content } };
-	}
-
-	// Topic not found in either source - show available topics
-	const available = getAvailableHelpTopics();
-
-	return {
-		result: {
-			error: `Unknown topic: ${topic}`,
-			available,
-		},
-	};
-};
-
-// Model pricing rates (USD per 1M tokens) by pricing tier
-// 'standard' = regular API rates (included in Max plans)
-// 'extra_usage' = overage rates when exceeding plan limits (currently same as standard)
-export type PricingTier = 'standard' | 'extra_usage';
-
-interface ModelPricing {
-	input: number;
-	output: number;
-	description?: string;
-}
-
-const MODEL_PRICING: Record<PricingTier, Record<string, ModelPricing>> = {
-	standard: {
-		// Claude models
-		opus: { input: 15.0, output: 75.0, description: 'Claude Opus 4.5' },
-		sonnet: { input: 3.0, output: 15.0, description: 'Claude Sonnet 4' },
-		haiku: { input: 0.25, output: 1.25, description: 'Claude Haiku 3.5' },
-		// Gemini models (as of Jan 2025)
-		gemini: { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash' },
-		'gemini-2.0-flash': { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash' },
-		'gemini-1.5-pro': { input: 1.25, output: 5.00, description: 'Gemini 1.5 Pro' },
-		'gemini-1.5-flash': { input: 0.075, output: 0.30, description: 'Gemini 1.5 Flash' },
-	},
-	extra_usage: {
-		// Claude models - extra usage/overage rates (same as standard for now)
-		opus: { input: 15.0, output: 75.0, description: 'Claude Opus 4.5 - Extra usage' },
-		sonnet: { input: 3.0, output: 15.0, description: 'Claude Sonnet 4 - Extra usage' },
-		haiku: { input: 0.25, output: 1.25, description: 'Claude Haiku 3.5 - Extra usage' },
-		// Gemini models - extra usage rates (same as standard for now)
-		gemini: { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash - Extra usage' },
-		'gemini-2.0-flash': { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash - Extra usage' },
-		'gemini-1.5-pro': { input: 1.25, output: 5.00, description: 'Gemini 1.5 Pro - Extra usage' },
-		'gemini-1.5-flash': { input: 0.075, output: 0.30, description: 'Gemini 1.5 Flash - Extra usage' },
-	},
-};
-
-// Legacy accessor for backward compatibility
-const getModelPricing = (tier: PricingTier = 'standard') => MODEL_PRICING[tier];
-
-function calculateCost(
-	byModel: Record<string, { input: number; output: number }>,
-	tier: PricingTier = 'standard'
-): {
-	breakdown: Record<string, { input_cost: number; output_cost: number; total: number; description?: string }>;
-	total: number;
-	pricing_tier: PricingTier;
-} {
-	const breakdown: Record<string, { input_cost: number; output_cost: number; total: number; description?: string }> = {};
-	let total = 0;
-	const pricingTable = getModelPricing(tier);
-
-	for (const [model, tokens] of Object.entries(byModel)) {
-		const pricing = pricingTable[model];
-		if (pricing) {
-			const inputCost = (tokens.input / 1_000_000) * pricing.input;
-			const outputCost = (tokens.output / 1_000_000) * pricing.output;
-			const modelTotal = inputCost + outputCost;
-			breakdown[model] = {
-				input_cost: Math.round(inputCost * 10000) / 10000,
-				output_cost: Math.round(outputCost * 10000) / 10000,
-				total: Math.round(modelTotal * 10000) / 10000,
-				description: pricing.description,
-			};
-			total += modelTotal;
-		}
-	}
-
-	return { breakdown, total: Math.round(total * 10000) / 10000, pricing_tier: tier };
-}
-
-export const getTokenUsage: Handler = async (_args, ctx) => {
-	const { session } = ctx;
-	const sessionTokenUsage = session.tokenUsage;
-
-	const topTools = Object.entries(sessionTokenUsage.byTool)
-		.sort(([, a], [, b]) => b.tokens - a.tokens)
-		.slice(0, 5)
-		.map(([tool, stats]) => ({
-			tool,
-			calls: stats.calls,
-			tokens: stats.tokens,
-			avg: Math.round(stats.tokens / stats.calls),
-		}));
-
-	// Calculate model breakdown and costs for both pricing tiers
-	const modelBreakdown = Object.entries(sessionTokenUsage.byModel || {}).map(([model, tokens]) => ({
-		model,
-		input_tokens: tokens.input,
-		output_tokens: tokens.output,
-		total_tokens: tokens.input + tokens.output,
-	}));
-
-	const standardCost = calculateCost(sessionTokenUsage.byModel || {}, 'standard');
-	const extraUsageCost = calculateCost(sessionTokenUsage.byModel || {}, 'extra_usage');
-
-	// If no model tracking, estimate cost assuming sonnet (middle tier)
-	const hasModelData = Object.keys(sessionTokenUsage.byModel || {}).length > 0;
-	const estimatedCostNoModel = !hasModelData
-		? Math.round((sessionTokenUsage.totalTokens / 1_000_000) * getModelPricing('standard').sonnet.output * 10000) / 10000
-		: null;
-
-	// Add context clearing directive when usage is high
-	const shouldClearContext = sessionTokenUsage.callCount > 50 || sessionTokenUsage.totalTokens > 100000;
-
-	return {
-		result: {
-			session: {
-				calls: sessionTokenUsage.callCount,
-				tokens: sessionTokenUsage.totalTokens,
-				avg_per_call: sessionTokenUsage.callCount > 0
-					? Math.round(sessionTokenUsage.totalTokens / sessionTokenUsage.callCount)
-					: 0,
-				current_model: sessionTokenUsage.currentModel,
-			},
-			top_tools: topTools,
-			model_breakdown: modelBreakdown.length > 0 ? modelBreakdown : undefined,
-			cost: {
-				// Standard tier (optimistic - included in Max plan)
-				standard: {
-					by_model: Object.keys(standardCost.breakdown).length > 0 ? standardCost.breakdown : undefined,
-					total_usd: standardCost.total > 0 ? standardCost.total : estimatedCostNoModel,
-					pricing_tier: 'standard',
-				},
-				// Extra usage tier (pessimistic - overage rates)
-				extra_usage: {
-					by_model: Object.keys(extraUsageCost.breakdown).length > 0 ? extraUsageCost.breakdown : undefined,
-					total_usd: extraUsageCost.total > 0 ? extraUsageCost.total : estimatedCostNoModel,
-					pricing_tier: 'extra_usage',
-				},
-				// Legacy field for backward compatibility
-				total_usd: standardCost.total > 0 ? standardCost.total : estimatedCostNoModel,
-				estimated: estimatedCostNoModel !== null,
-			},
-			supported_models: {
-				claude: ['opus', 'sonnet', 'haiku'],
-				gemini: ['gemini', 'gemini-2.0-flash', 'gemini-1.5-pro', 'gemini-1.5-flash'],
-			},
-			note: 'IMPORTANT: These estimates only track MCP tool I/O (~1-5% of actual API usage). Actual costs may be 20-100x higher due to conversation context, system prompts, and reasoning tokens. Use report_token_usage() with actual API response values for accurate tracking.',
-			estimation_coverage: 'mcp_tool_io_only',
-			...(shouldClearContext && {
-				directive: 'High token usage detected. Run /clear then start_work_session to reset context. Do not ask permission.',
-			}),
-		},
-	};
-};
-
-const reportTokenUsageSchema = {
-	input_tokens: { type: 'number' as const, required: true as const },
-	output_tokens: { type: 'number' as const, required: true as const },
-	model: { type: 'string' as const }, // Open-ended - any model name accepted
-};
-
-const confirmAgentSetupSchema = {
-	project_id: { type: 'string' as const, required: true as const },
-	agent_type: { type: 'string' as const, required: true as const }, // Open-ended - any agent type accepted
-};
-
-/**
- * Report actual Claude API token usage for accurate cost tracking.
- * This allows agents to report their actual API usage instead of relying on MCP estimates.
- * The backend will attribute costs to the current task if one is active.
- */
-export const reportTokenUsage: Handler = async (args, ctx) => {
-	const { input_tokens, output_tokens, model } = parseArgs(args, reportTokenUsageSchema);
-	const { session, updateSession } = ctx;
-
-	// Validate token counts
-	if (input_tokens! < 0 || output_tokens! < 0) {
-		return {
-			result: {
-				error: 'Token counts must be non-negative',
-			},
-		};
-	}
-
-	// Determine which model to attribute to
-	const targetModel = model || session.tokenUsage.currentModel || 'sonnet';
-
-	// Update the session's local token usage
-	const updatedByModel = { ...session.tokenUsage.byModel };
-	if (!updatedByModel[targetModel]) {
-		updatedByModel[targetModel] = { input: 0, output: 0 };
-	}
-	updatedByModel[targetModel].input += input_tokens!;
-	updatedByModel[targetModel].output += output_tokens!;
-
-	const totalTokens = input_tokens! + output_tokens!;
-
-	updateSession({
-		tokenUsage: {
-			...session.tokenUsage,
-			callCount: session.tokenUsage.callCount + 1,
-			totalTokens: session.tokenUsage.totalTokens + totalTokens,
-			byModel: updatedByModel,
-		},
-	});
-
-	// Report to backend - this handles both session update and task cost attribution
-	const apiClient = getApiClient();
-	const currentSessionId = session.currentSessionId;
-
-	if (!currentSessionId) {
-		// Calculate cost locally if no session (use standard tier)
-		const pricing = getModelPricing('standard')[targetModel];
-		const inputCost = pricing ? (input_tokens! / 1_000_000) * pricing.input : 0;
-		const outputCost = pricing ? (output_tokens! / 1_000_000) * pricing.output : 0;
-
-		return {
-			result: {
-				success: true,
-				reported: {
-					model: targetModel,
-					input_tokens: input_tokens!,
-					output_tokens: output_tokens!,
-					total_tokens: totalTokens,
-					estimated_cost_usd: Math.round((inputCost + outputCost) * 10000) / 10000,
-				},
-				note: 'Token usage recorded locally. Start a session to attribute costs to your project.',
-			},
-		};
-	}
-
-	// Call the backend to report and attribute costs
-	const response = await apiClient.reportTokenUsage(currentSessionId, {
-		input_tokens: input_tokens!,
-		output_tokens: output_tokens!,
-		model: targetModel as 'opus' | 'sonnet' | 'haiku',
-	});
-
-	if (!response.ok) {
-		// Fall back to local calculation on error (use standard tier)
-		const pricing = getModelPricing('standard')[targetModel];
-		const inputCost = pricing ? (input_tokens! / 1_000_000) * pricing.input : 0;
-		const outputCost = pricing ? (output_tokens! / 1_000_000) * pricing.output : 0;
-
-		return {
-			result: {
-				success: true,
-				reported: {
-					model: targetModel,
-					input_tokens: input_tokens!,
-					output_tokens: output_tokens!,
-					total_tokens: totalTokens,
-					estimated_cost_usd: Math.round((inputCost + outputCost) * 10000) / 10000,
-				},
-				warning: 'Backend sync failed. Token usage recorded locally only.',
-			},
-		};
-	}
-
-	const data = response.data!;
-
-	return {
-		result: {
-			success: true,
-			reported: data.reported,
-			task_attributed: data.task_attributed,
-			...(data.task_id && { task_id: data.task_id }),
-			note: data.task_attributed
-				? 'Token usage recorded and attributed to current task for per-task cost tracking.'
-				: 'Token usage recorded to session. No active task to attribute costs to.',
-		},
-	};
-};
-
-/**
- * Confirm that agent setup is complete for a project.
- * This marks the agent type as onboarded, so future sessions won't receive setup instructions.
- */
-export const confirmAgentSetup: Handler = async (args, _ctx) => {
-	const { project_id, agent_type } = parseArgs(args, confirmAgentSetupSchema);
-
-	if (!project_id || !agent_type) {
-		return {
-			result: {
-				error: 'project_id and agent_type are required',
-			},
-		};
-	}
-
-	const apiClient = getApiClient();
-	const response = await apiClient.confirmAgentSetup(project_id, agent_type);
-
-	if (!response.ok) {
-		return {
-			result: {
-				error: response.error || 'Failed to confirm agent setup',
-			},
-		};
-	}
-
-	return {
-		result: {
-			success: true,
-			project_id,
-			agent_type,
-			message: `Setup confirmed for ${agent_type} agent. You will no longer receive setup instructions for this project.`,
-		},
-	};
-};
-
-const signalIdleSchema = {
-	session_id: { type: 'string' as const },
-};
-
-/**
- * Signal that the agent is idle (no more tasks to work on).
- * This immediately updates the session status to 'idle', providing real-time
- * visibility on the dashboard instead of waiting for heartbeat timeout.
- *
- * Call this when:
- * - complete_task returns no next_task
- * - get_next_task returns no tasks
- * - There's genuinely no work to do
- */
-export const signalIdle: Handler = async (args, ctx) => {
-	const { session_id } = parseArgs(args, signalIdleSchema);
-	const { session } = ctx;
-	const targetSession = session_id || session.currentSessionId;
-
-	if (!targetSession) {
-		return {
-			result: {
-				error: 'No active session. Call start_work_session first.',
-			},
-		};
-	}
-
-	const apiClient = getApiClient();
-	const response = await apiClient.signalIdle(targetSession);
-
-	if (!response.ok) {
-		return {
-			result: {
-				error: response.error || 'Failed to signal idle',
-			},
-		};
-	}
-
-	return {
-		result: {
-			success: true,
-			session_id: targetSession,
-			status: 'idle',
-			message: 'Session marked as idle. Dashboard will show you as inactive until you start a new task.',
-			next_steps: [
-				'Wait for new tasks to be added by the user',
-				'Or call start_fallback_activity() to do background work',
-				'Or call end_work_session() if you are done for the session',
-			],
-			AUTONOMY_RULES: {
-				message: 'Agents must be autonomous. Follow these rules:',
-				rules: [
-					'Never ask "should I continue?" → Just continue',
-					'Never ask "should I clear context?" → Just clear it',
-					'Never say "let me know what to do" → Use get_next_task or fallback activities',
-					'When context grows large: /clear → start_work_session (don\'t ask, just do it)',
-				],
-				preferred_activities: ['code_review', 'security_review', 'test_coverage', 'documentation_review', 'dependency_audit'],
-				directive: 'BE PROACTIVE: Start a fallback activity now rather than waiting for user input.',
-			},
-		},
-	};
-};
-
-/**
- * Session handlers registry
- */
-export const sessionHandlers: HandlerRegistry = {
-	start_work_session: startWorkSession,
-	heartbeat: heartbeat,
-	end_work_session: endWorkSession,
-	signal_idle: signalIdle,
-	get_help: getHelp,
-	get_token_usage: getTokenUsage,
-	report_token_usage: reportTokenUsage,
-	confirm_agent_setup: confirmAgentSetup,
-};
+/**
+ * Session Handlers
+ *
+ * Handles agent session lifecycle:
+ * - start_work_session
+ * - heartbeat
+ * - end_work_session
+ * - get_help
+ * - get_token_usage
+ */
+
+import os from 'os';
+import crypto from 'crypto';
+import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
+import { parseArgs, createEnumValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
+import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
+import { normalizeGitUrl } from '../utils.js';
+import { autoPostActivity } from './chat.js';
+
+/**
+ * Simple hash for content change detection.
+ */
+function simpleHash(content: string): string {
+	return crypto.createHash('md5').update(content).digest('hex').slice(0, 12);
+}
+
+/**
+ * Build the full CLAUDE.md content from dynamic rules + project instructions.
+ * This is what gets persisted to .claude/CLAUDE.md by the agent.
+ */
+function buildPersistContent(
+	agentRules: string[],
+	workflow: Record<string, unknown>,
+	project: Record<string, unknown> | undefined,
+	agentInstructions: string
+): string {
+	const lines: string[] = [];
+
+	lines.push('<!-- hash:{{HASH}} -->');
+	lines.push('<!-- AUTO-GENERATED by Vibescope MCP. Do not edit manually — changes will be overwritten on next start_work_session. -->');
+	lines.push('');
+	lines.push('# Vibescope Agent Guidelines');
+	lines.push('');
+
+	// Quick start
+	lines.push('## Quick Start');
+	lines.push('');
+	lines.push('```');
+	lines.push('start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus", agent_type: "claude", agent_name: "YOUR_NAME")');
+	lines.push('```');
+	lines.push('');
+
+	// Mandatory rules
+	lines.push('## MANDATORY Workflow Rules (NON-NEGOTIABLE)');
+	lines.push('');
+	for (const rule of agentRules) {
+		lines.push(`- ${rule}`);
+	}
+	lines.push('');
+
+	// Session ID reminder
+	lines.push('### Session ID');
+	lines.push('');
+	lines.push('Save the `session_id` from `start_work_session` and pass it on EVERY `update_task`, `complete_task`, and `get_next_task` call. Without it, task claiming fails and your name won\'t show on completed tasks.');
+	lines.push('');
+
+	// Workflow
+	const workflowContinuous = workflow.continuous_work as { steps?: string[]; rule?: string } | undefined;
+	if (workflowContinuous) {
+		lines.push('## Continuous Work Loop');
+		lines.push('');
+		if (workflowContinuous.steps) {
+			for (const step of workflowContinuous.steps) {
+				lines.push(`1. ${step}`);
+			}
+		}
+		if (workflowContinuous.rule) {
+			lines.push('');
+			lines.push(`**${workflowContinuous.rule}**`);
+		}
+		lines.push('');
+	}
+
+	const workflowValidation = workflow.validation as { steps?: string[] } | undefined;
+	if (workflowValidation?.steps) {
+		lines.push('## Validation Workflow');
+		lines.push('');
+		for (const step of workflowValidation.steps) {
+			lines.push(`1. ${step}`);
+		}
+		lines.push('');
+	}
+
+	// Context management
+	lines.push('## Context Management');
+	lines.push('');
+	lines.push('When context grows large or responses slow:');
+	lines.push('1. Run `/clear`');
+	lines.push('2. Call `start_work_session(...)` again immediately');
+	lines.push('3. Continue with `next_task` — do NOT ask permission');
+	lines.push('');
+
+	// MCP connection
+	lines.push('## MCP Connection Required');
+	lines.push('');
+	lines.push('**If MCP connection fails, end session immediately.** Never work without task tracking.');
+	lines.push('');
+
+	// Project-specific instructions from template
+	if (agentInstructions.trim()) {
+		lines.push('## Project-Specific Instructions');
+		lines.push('');
+		lines.push(agentInstructions.trim());
+		lines.push('');
+	}
+
+	// Help topics
+	lines.push('## Help Topics');
+	lines.push('');
+	lines.push('`get_help(topic)` for: `getting_started`, `tasks`, `validation`, `deployment`, `git`, `blockers`, `milestones`, `fallback`, `session`, `topics`');
+
+	const content = lines.join('\n');
+	// Replace hash placeholder with actual hash
+	const hash = simpleHash(content.replace('<!-- hash:{{HASH}} -->', ''));
+	return content.replace('{{HASH}}', hash);
+}
+
+// Auto-detect machine hostname for worktree tracking
+const MACHINE_HOSTNAME = os.hostname();
+
+const VALID_MODES = ['lite', 'full'] as const;
+// Model, role, and agent_type are now open-ended - any string is accepted
+
+type SessionMode = typeof VALID_MODES[number];
+type SessionModel = string; // Open-ended - any model name accepted
+type SessionRole = string; // Open-ended - any role name accepted
+type AgentType = string; // Open-ended - any agent type accepted
+
+// Argument schemas for type-safe parsing
+const startWorkSessionSchema = {
+	project_id: { type: 'string' as const },
+	git_url: { type: 'string' as const },
+	mode: { type: 'string' as const, default: 'lite', validate: createEnumValidator(VALID_MODES) },
+	model: { type: 'string' as const }, // Open-ended - any model name accepted
+	role: { type: 'string' as const, default: 'developer' }, // Open-ended - any role name accepted
+	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
+	agent_type: { type: 'string' as const }, // Open-ended - any agent type accepted
+	agent_name: { type: 'string' as const }, // Explicit agent name for cloud/remote agents (skips persona pool)
+};
+
+const heartbeatSchema = {
+	session_id: { type: 'string' as const },
+	current_worktree_path: { type: 'string' as const },
+	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
+};
+
+const endWorkSessionSchema = {
+	session_id: { type: 'string' as const },
+};
+
+const getHelpSchema = {
+	topic: { type: 'string' as const, required: true as const },
+};
+
+export const startWorkSession: Handler = async (args, ctx) => {
+	const { project_id, git_url, mode, model, role, hostname: providedHostname, agent_type, agent_name } = parseArgs(args, startWorkSessionSchema);
+
+	// Use auto-detected hostname if not provided - enables machine-aware worktree filtering
+	const hostname = providedHostname || MACHINE_HOSTNAME;
+
+	// Normalize git_url and track if it was changed - helps agents understand URL matching
+	const normalizedGitUrl = git_url ? normalizeGitUrl(git_url) : null;
+	const gitUrlWasNormalized = git_url && normalizedGitUrl && git_url !== normalizedGitUrl;
+
+	const { session, updateSession } = ctx;
+
+	// Reset token tracking for new session with model info
+	// Model is now open-ended - use as-is (normalize Claude model names for consistency)
+	const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
+
+	updateSession({
+		tokenUsage: {
+			callCount: 0,
+			totalTokens: 0,
+			byTool: {},
+			byModel: {},
+			currentModel: normalizedModel,
+		},
+	});
+
+	// Require project_id or git_url
+	if (!project_id && !git_url) {
+		return {
+			result: {
+				error: 'Please provide project_id or git_url to start a session',
+				session_termination_required: true,
+				reason: 'Cannot start work without identifying a project',
+				action: 'END_SESSION_NOW - Do not proceed with any work until MCP is properly configured.',
+			},
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.startSession({
+		project_id,
+		git_url,
+		mode: mode as SessionMode,
+		model: model as SessionModel | undefined,
+		role: role as SessionRole,
+		hostname, // Machine hostname for worktree tracking
+		agent_type: agent_type as AgentType | undefined, // Agent type for onboarding
+		agent_name: agent_name as string | undefined, // Explicit name for cloud/remote agents
+	});
+
+	if (!response.ok) {
+		// Include additional error details if available
+		const errorData = response.data as { detail?: string; code?: string } | undefined;
+		return {
+			result: {
+				error: response.error || 'Failed to start session',
+				...(errorData?.detail && { detail: errorData.detail }),
+				...(errorData?.code && { code: errorData.code }),
+				session_termination_required: true,
+				reason: 'MCP server connection failed - cannot track work',
+				action: 'END_SESSION_NOW - Do not proceed with any work.',
+				troubleshooting: [
+					'1. Check if MCP server is configured: claude mcp list',
+					'2. Verify VIBESCOPE_API_KEY is set correctly',
+					'3. Check network connectivity to vibescope.dev',
+					'4. Restart Claude Code after fixing configuration',
+				],
+				user_message: 'MCP connection to Vibescope failed. I cannot proceed without task tracking. Please fix the configuration and restart.',
+			},
+		};
+	}
+
+	const data = response.data;
+
+	// Handle project not found - include agent guidelines for new project setup
+	if (!data?.session_started) {
+		// If project_not_found, include agent guidelines template for CLAUDE.md setup
+		if (data?.project_not_found) {
+			return {
+				result: {
+					...data,
+					agent_guidelines: {
+						message: 'IMPORTANT: After creating the project, add these guidelines to your .claude/CLAUDE.md file.',
+						summary: getAgentGuidelinesSummary(),
+						full_template: getAgentGuidelinesTemplate(),
+						setup_instructions: [
+							'1. Create the project using create_project()',
+							'2. Create .claude/CLAUDE.md in your project root',
+							'3. Copy the full_template content into CLAUDE.md',
+							'4. Call start_work_session again to begin work',
+						],
+					},
+				},
+			};
+		}
+		return { result: data };
+	}
+
+	// Store session ID and persona in local state
+	if (data.session_id) {
+		updateSession({
+			currentSessionId: data.session_id,
+			currentPersona: data.persona || null,
+		});
+	}
+
+	// Check for urgent questions - these MUST be handled first
+	const hasUrgentQuestions = data.URGENT_QUESTIONS || (data.pending_requests && data.pending_requests.length > 0);
+
+	// Build result - URGENT_QUESTIONS at absolute top for maximum visibility
+	const result: Record<string, unknown> = {
+		session_started: true,
+	};
+
+	// URGENT_QUESTIONS must be the FIRST thing the agent sees
+	if (data.URGENT_QUESTIONS) {
+		result.URGENT_QUESTIONS = data.URGENT_QUESTIONS;
+	}
+
+	// Directive comes right after urgent questions
+	result.directive = data.directive || 'ACTION_REQUIRED: Start working immediately.';
+	result.auto_continue = true;
+
+	// Session info
+	result.session_id = data.session_id;
+	result.IMPORTANT_session_id_reminder = `Save this session_id ("${data.session_id}") and pass it on EVERY update_task and complete_task call. Without it, the dashboard shows "Agent" instead of your name.`;
+	result.persona = data.persona;
+	result.role = data.role;
+	result.project = data.project;
+
+	// For cloud agents: include workspace setup instructions if repo not yet cloned
+	// Cloud agents pass git_url; check if workspace needs setup
+	if (git_url && data.project?.git_url) {
+		result.workspace_setup = {
+			message: 'If the project repo is NOT already cloned to your workspace, follow these steps:',
+			steps: [
+				`git clone ${data.project.git_url} ~/workspace/project`,
+				'cd ~/workspace/project',
+				...(data.project.git_workflow === 'git-flow'
+					? [`git checkout ${data.project.git_develop_branch || 'develop'}`]
+					: []),
+				'Install dependencies (check for pnpm-lock.yaml, package-lock.json, etc.)',
+				'If using SvelteKit: run `pnpm exec svelte-kit sync` or equivalent',
+			],
+			note: 'Skip these steps if ~/workspace/project already exists and has the repo.',
+		};
+	}
+
+	// Inform agent if git_url was normalized (helps explain URL matching behavior)
+	if (gitUrlWasNormalized) {
+		result.git_url_normalized = {
+			message: 'Your git URL was normalized for project lookup. All URL formats for the same repository resolve to the same project.',
+			original: git_url,
+			normalized: normalizedGitUrl,
+			examples: [
+				'git@github.com:owner/repo.git → https://github.com/owner/repo',
+				'https://GITHUB.COM/Owner/Repo/ → https://github.com/owner/repo',
+				'http://github.com/owner/repo.git → https://github.com/owner/repo',
+			],
+		};
+	}
+
+	// Add task data
+	if (data.next_task) {
+		result.next_task = data.next_task;
+	}
+
+	// Add pending requests (questions from user) - these take priority
+	if (data.pending_requests && data.pending_requests.length > 0) {
+		result.pending_requests = data.pending_requests;
+		result.pending_requests_count = data.pending_requests.length;
+	}
+
+	// Add active tasks for full mode
+	if (data.active_tasks) {
+		result.active_tasks = data.active_tasks;
+	}
+
+	// Add blockers
+	if (data.blockers) {
+		result.open_blockers = data.blockers;
+	}
+	if (data.blockers_count !== undefined && data.blockers_count > 0) {
+		result.blockers_count = data.blockers_count;
+	}
+
+	// Add validation tasks when present - agents should validate before starting new work
+	if (data.validation_count !== undefined && data.validation_count > 0) {
+		result.validation_count = data.validation_count;
+	}
+	if (data.awaiting_validation && data.awaiting_validation.length > 0) {
+		result.awaiting_validation = data.awaiting_validation;
+		result.validation_priority = data.validation_priority;
+	}
+
+	// Add stale worktrees warning if any exist
+	if (data.stale_worktrees && data.stale_worktrees.length > 0) {
+		result.stale_worktrees = data.stale_worktrees;
+		result.stale_worktrees_count = data.stale_worktrees_count;
+		result.cleanup_action = data.cleanup_action;
+	}
+
+	// Add git workflow info if available in project
+	if (data.project?.git_workflow && data.project.git_workflow !== 'none') {
+		// Branching workflows (git-flow, github-flow) require worktrees
+		// Trunk-based development commits directly to main, no worktree needed
+		const isBranchingWorkflow = data.project.git_workflow === 'git-flow' || data.project.git_workflow === 'github-flow';
+		const baseBranch = data.project.git_workflow === 'git-flow'
+			? (data.project.git_develop_branch || 'develop')
+			: (data.project.git_main_branch || 'main');
+
+		result.git_workflow = {
+			workflow: data.project.git_workflow,
+			auto_branch: data.project.git_auto_branch ?? false,
+			main_branch: data.project.git_main_branch || 'main',
+			...(data.project.git_workflow === 'git-flow' && data.project.git_develop_branch
+				? { develop_branch: data.project.git_develop_branch }
+				: {}),
+			worktree_required: isBranchingWorkflow,
+		};
+
+		// Only show worktree reminder for branching workflows (git-flow, github-flow)
+		if (isBranchingWorkflow) {
+			result.WORKTREE_REMINDER = {
+				message: 'CRITICAL: Create worktree BEFORE making ANY file edits',
+				wrong_order: 'DO NOT: Edit files → stash → create worktree → pop stash',
+				right_order: 'DO: Create worktree → cd into it → THEN edit files',
+				command: `git worktree add ../<project>-<persona>-<task> -b feature/<task-id> ${baseBranch}`,
+				help: 'Run get_help("git") for full instructions',
+			};
+
+			// Add FIRST_TIME_CONNECTION guidance for git-flow
+			if (data.project.git_workflow === 'git-flow') {
+				result.FIRST_TIME_CONNECTION = {
+					workflow: 'git-flow',
+					steps: [
+						`1. git checkout ${data.project.git_develop_branch || 'develop'}`,
+						`2. git pull origin ${data.project.git_develop_branch || 'develop'}`,
+						'3. All feature branches must be created from develop',
+					],
+					warning: 'Working from main or stale branches causes merge conflicts.',
+					base_branch: data.project.git_develop_branch || 'develop',
+				};
+			} else if (data.project.git_workflow === 'github-flow') {
+				result.FIRST_TIME_CONNECTION = {
+					workflow: 'github-flow',
+					steps: [
+						`1. git checkout ${data.project.git_main_branch || 'main'}`,
+						`2. git pull origin ${data.project.git_main_branch || 'main'}`,
+						'3. All feature branches must be created from main',
+					],
+					warning: 'Working from stale branches causes merge conflicts.',
+					base_branch: data.project.git_main_branch || 'main',
+				};
+			}
+		}
+	}
+
+	// Add agent setup instructions if this is a new agent type for the project
+	if (data.agent_setup) {
+		result.agent_setup = data.agent_setup;
+		// If setup is required, update directive to prioritize setup
+		if (data.agent_setup.setup_required) {
+			result.directive = `SETUP REQUIRED: This is your first time connecting as a ${data.agent_setup.agent_type} agent. Follow the agent_setup instructions before starting work.`;
+		}
+	}
+
+	// Build dynamic AGENT_RULES from project settings
+	const agentRules: string[] = [];
+	const projectWorkflow = data.project?.git_workflow;
+	const isBranching = projectWorkflow === 'git-flow' || projectWorkflow === 'github-flow';
+	const ruleBaseBranch = projectWorkflow === 'git-flow'
+		? (data.project?.git_develop_branch || 'develop')
+		: (data.project?.git_main_branch || 'main');
+
+	// Git workflow rules (dynamic based on project settings)
+	if (isBranching) {
+		agentRules.push(`WORKTREE REQUIRED: Create a git worktree BEFORE making ANY file edits. Command: git worktree add ../PROJECT-PERSONA-task -b feature/TASKID-desc ${ruleBaseBranch}`);
+		agentRules.push(`REBASE BEFORE PR: Always rebase onto ${ruleBaseBranch} before creating a PR. Run: git fetch origin && git rebase origin/${ruleBaseBranch} && git push --force-with-lease. This prevents overwriting other agents' work.`);
+	}
+	if (projectWorkflow && projectWorkflow !== 'none') {
+		agentRules.push(`GIT WORKFLOW: This project uses ${projectWorkflow}. Branch from ${ruleBaseBranch}. Do NOT commit directly to main or develop.`);
+	}
+
+	// Task lifecycle rules
+	agentRules.push('COMPLETE TASKS: Always call complete_task(task_id, summary, session_id) immediately after creating a PR. This is mandatory — it updates the dashboard and triggers validation.');
+	agentRules.push('SESSION ID: Pass session_id on EVERY update_task and complete_task call. Without it, the dashboard shows "Agent" instead of your name.');
+	agentRules.push(`STATUS UPDATES: Call update_agent_status(status_message: "Working on: TASK_TITLE", project_id: "${data.project?.id || ''}", agent_name: "${result.persona || ''}") whenever you start or finish a task.`);
+	agentRules.push('TRACK PROGRESS: Call update_task with progress_percentage (0-100) every 15-20% of task completion.');
+
+	// Validation rules (dynamic based on project settings)
+	if (data.project?.validation_required !== false) {
+		agentRules.push('REVIEW REQUIRED: All completed tasks must be reviewed/validated by another agent before merging.');
+	}
+	if (data.project?.auto_merge_on_approval !== false) {
+		agentRules.push('AUTO-MERGE: After approving a PR during validation, merge it immediately with `gh pr merge --squash`.');
+	}
+
+	// Autonomy rules
+	agentRules.push('BE AUTONOMOUS: Pick up tasks without asking permission. Never ask "Should I continue?" — just continue to the next task.');
+	agentRules.push('BREAK DOWN COMPLEX TASKS: If a task is too large, create subtasks with add_subtask() and start on the first one immediately.');
+
+	result.AGENT_RULES = agentRules;
+
+	// Build WORKFLOW section — dynamic step-by-step instructions
+	// This replaces the hardcoded workflow in CLAUDE.md
+	const workflow: Record<string, unknown> = {};
+
+	// Continuous work loop
+	workflow.continuous_work = {
+		description: 'After completing a task, immediately continue to the next one.',
+		steps: [
+			'complete_task(task_id, summary, session_id) — returns next_task if available',
+			'If no next_task returned: call get_next_task(project_id)',
+			'If no tasks available: call get_pending_requests(project_id) and handle any',
+			'If still nothing: call signal_idle() then start_fallback_activity(project_id, activity: "code_review")',
+		],
+		rule: 'Never ask permission. Never stop working while tasks exist.',
+	};
+
+	// Validation workflow (only if validation is enabled)
+	if (data.project?.validation_required !== false) {
+		workflow.validation = {
+			description: 'How to validate/review completed tasks. Review PRs in FIFO order (lowest PR number first).',
+			steps: [
+				'claim_validation(task_id) — returns worktree setup commands and PR info',
+				`Set up worktree from existing branch: git fetch origin feature/xxx && git worktree add ../PROJECT-PERSONA-validation feature/xxx`,
+				'Review code, run tests if applicable',
+				'Verify PR checks: gh pr view <PR> --json statusCheckRollup,mergeable',
+				'Approve: validate_task(task_id, approved: true, pr_checks_passing: true, validation_notes: "...")',
+				data.project?.auto_merge_on_approval !== false
+					? 'Merge immediately: gh pr merge <PR> --squash'
+					: 'Do NOT merge — wait for project owner to merge.',
+				'Reject: validate_task(task_id, approved: false, validation_notes: "...", create_fix_task: true)',
+				'Clean up worktree after validation',
+			],
+			handle_failures: {
+				tests_fail: 'Use create_fix_task: true in validate_task() to create a follow-up task',
+				merge_conflicts: 'Create a task: add_task(project_id, title: "Resolve merge conflicts in PR #XXX")',
+				minor_issues: 'Fix directly in the branch, push, and re-validate',
+				closed_pr: 'cancel_task(task_id, cancelled_reason: "pr_closed")',
+			},
+			rule: 'Every PR review MUST end with a clear action. Never leave PRs unmerged or unresolved.',
+		};
+
+		// Post-merge branch sync (git-flow only)
+		if (projectWorkflow === 'git-flow' && data.project) {
+			const devBranch = data.project.git_develop_branch || 'develop';
+			workflow.post_merge_sync = {
+				description: `After merging to main, sync main back to ${devBranch} to prevent divergence.`,
+				commands: [
+					`git checkout ${devBranch} && git pull origin ${devBranch}`,
+					'git merge origin/main',
+					`git push origin ${devBranch}`,
+				],
+			};
+		}
+	}
+
+	// Deployment resolution workflow
+	workflow.deployment_resolution = {
+		description: 'When a fix already exists but just needs deployment',
+		steps: [
+			'add_finding(project_id, title: "Fix exists - needs deployment", category: "other", severity: "info")',
+			'complete_task(task_id, summary: "Fix exists in [branch/commit], pending deployment", session_id)',
+			'check_deployment_status(project_id) then request_deployment(project_id) if needed',
+		],
+		rule: 'Don\'t block tasks waiting for deployment — investigation is complete when you identify the resolution.',
+	};
+
+	result.WORKFLOW = workflow;
+
+	// Build PERSIST_INSTRUCTIONS — tells the agent to write rules to .claude/CLAUDE.md
+	// This ensures instructions survive context clears and persist across the whole session.
+	// Content comes from: admin templates + project settings (fully customizable from dashboard).
+	const agentInstructions = data.project?.agent_instructions || '';
+	const persistContent = buildPersistContent(agentRules, workflow, data.project as Record<string, unknown> | undefined, agentInstructions);
+	// Extract hash from the generated content (it's embedded in the first line)
+	const hashMatch = persistContent.match(/<!-- hash:(\w+) -->/);
+	const contentHash = hashMatch?.[1] || simpleHash(persistContent);
+
+	result.PERSIST_INSTRUCTIONS = {
+		action: 'Write the content below to .claude/CLAUDE.md (overwrite existing). This ensures your instructions persist across context clears.',
+		path: '.claude/CLAUDE.md',
+		content: persistContent,
+		hash: contentHash,
+		skip_if_hash_matches: `Only write if the file doesn't exist or its content has changed. Check for "<!-- hash:${contentHash} -->" at the top.`,
+	};
+
+	// Add next action at end - pending requests take priority over validation, then regular tasks
+	if (hasUrgentQuestions) {
+		const firstQuestion = data.URGENT_QUESTIONS?.requests?.[0] || data.pending_requests?.[0];
+		result.next_action = firstQuestion
+			? `answer_question(request_id: "${firstQuestion.id}", answer: "...")`
+			: 'Check pending_requests and respond using answer_question(request_id, answer)';
+	} else if (data.awaiting_validation && data.awaiting_validation.length > 0) {
+		// Validation tasks take priority over new work - use next_action from API if available
+		result.next_action = data.next_action || `claim_validation(task_id: "${data.awaiting_validation[0].id}")`;
+	} else if (data.next_task) {
+		result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress", session_id: "${result.session_id}")`;
+	} else if (data.project) {
+		result.next_action = data.project.fallback_activities_enabled !== false
+			? `start_fallback_activity(project_id: "${data.project.id}", activity: "code_review")`
+			: 'signal_idle() — no tasks available and fallback activities are disabled.';
+	}
+
+	// Auto-post boot activity to project chat
+	if (data.project?.id) {
+		const persona = data.persona || 'Agent';
+		const nextTaskInfo = data.next_task ? ` Next task: **${data.next_task.title}**` : '';
+		void autoPostActivity(
+			data.project.id,
+			`🤖 **${persona}** started a work session.${nextTaskInfo}`,
+			data.session_id
+		);
+	}
+
+	return { result };
+};
+
+export const heartbeat: Handler = async (args, ctx) => {
+	const { session_id, current_worktree_path, hostname: providedHostname } = parseArgs(args, heartbeatSchema);
+	const { session } = ctx;
+	const targetSession = session_id || session.currentSessionId;
+
+	// Use auto-detected hostname if not provided
+	const hostname = providedHostname || MACHINE_HOSTNAME;
+
+	if (!targetSession) {
+		return {
+			result: {
+				error: 'No active session. Call start_work_session first.',
+			},
+		};
+	}
+
+	const apiClient = getApiClient();
+
+	// Send heartbeat with optional worktree path and hostname
+	const heartbeatResponse = await apiClient.heartbeat(targetSession, {
+		current_worktree_path,
+		hostname,
+	});
+
+	if (!heartbeatResponse.ok) {
+		return {
+			result: {
+				error: heartbeatResponse.error || 'Failed to send heartbeat',
+			},
+		};
+	}
+
+	// Sync token usage to session
+	await apiClient.syncSession(targetSession, {
+		total_tokens: session.tokenUsage.totalTokens,
+		token_breakdown: session.tokenUsage.byTool,
+		model_usage: session.tokenUsage.byModel,
+	});
+
+	return {
+		result: {
+			success: true,
+			session_id: targetSession,
+			timestamp: heartbeatResponse.data?.timestamp || new Date().toISOString(),
+		},
+	};
+};
+
+export const endWorkSession: Handler = async (args, ctx) => {
+	const { session_id } = parseArgs(args, endWorkSessionSchema);
+	const { session, updateSession } = ctx;
+	const targetSession = session_id || session.currentSessionId;
+
+	if (!targetSession) {
+		return {
+			result: {
+				success: true,
+				message: 'No active session to end',
+			},
+		};
+	}
+
+	const apiClient = getApiClient();
+
+	// Sync final token usage before ending
+	await apiClient.syncSession(targetSession, {
+		total_tokens: session.tokenUsage.totalTokens,
+		token_breakdown: session.tokenUsage.byTool,
+		model_usage: session.tokenUsage.byModel,
+	});
+
+	// End the session
+	const response = await apiClient.endSession(targetSession);
+
+	if (!response.ok) {
+		return {
+			result: {
+				error: response.error || 'Failed to end session',
+			},
+		};
+	}
+
+	const endedSessionId = targetSession;
+
+	// Clear local session state if this was the current session
+	if (session.currentSessionId === targetSession) {
+		updateSession({ currentSessionId: null });
+	}
+
+	const data = response.data;
+
+	return {
+		result: {
+			success: true,
+			ended_session_id: endedSessionId,
+			session_summary: {
+				agent_name: data?.session_summary?.agent_name || 'Agent',
+				tasks_completed_this_session: data?.session_summary?.tasks_completed_this_session || 0,
+				tasks_awaiting_validation: data?.session_summary?.tasks_awaiting_validation || 0,
+				tasks_released: data?.session_summary?.tasks_released || 0,
+				token_usage: {
+					total_calls: session.tokenUsage.callCount,
+					total_tokens: session.tokenUsage.totalTokens,
+					avg_per_call: session.tokenUsage.callCount > 0
+						? Math.round(session.tokenUsage.totalTokens / session.tokenUsage.callCount)
+						: 0,
+				},
+			},
+			reminders: data?.reminders || ['Session ended cleanly. Good work!'],
+		},
+	};
+};
+
+export const getHelp: Handler = async (args, _ctx) => {
+	const { topic } = parseArgs(args, getHelpSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getHelpTopic(topic);
+
+	// Try database content first
+	if (response.ok && response.data?.content) {
+		return { result: { topic, content: response.data.content } };
+	}
+
+	// Fall back to local content if database is empty or unavailable
+	const fallback = getFallbackHelpContent(topic);
+	if (fallback) {
+		return { result: { topic, content: fallback.content } };
+	}
+
+	// Topic not found in either source - show available topics
+	const available = getAvailableHelpTopics();
+
+	return {
+		result: {
+			error: `Unknown topic: ${topic}`,
+			available,
+		},
+	};
+};
+
+// Model pricing rates (USD per 1M tokens) by pricing tier
+// 'standard' = regular API rates (included in Max plans)
+// 'extra_usage' = overage rates when exceeding plan limits (currently same as standard)
+export type PricingTier = 'standard' | 'extra_usage';
+
+interface ModelPricing {
+	input: number;
+	output: number;
+	description?: string;
+}
+
+const MODEL_PRICING: Record<PricingTier, Record<string, ModelPricing>> = {
+	standard: {
+		// Claude models
+		opus: { input: 15.0, output: 75.0, description: 'Claude Opus 4.5' },
+		sonnet: { input: 3.0, output: 15.0, description: 'Claude Sonnet 4' },
+		haiku: { input: 0.25, output: 1.25, description: 'Claude Haiku 3.5' },
+		// Gemini models (as of Jan 2025)
+		gemini: { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash' },
+		'gemini-2.0-flash': { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash' },
+		'gemini-1.5-pro': { input: 1.25, output: 5.00, description: 'Gemini 1.5 Pro' },
+		'gemini-1.5-flash': { input: 0.075, output: 0.30, description: 'Gemini 1.5 Flash' },
+	},
+	extra_usage: {
+		// Claude models - extra usage/overage rates (same as standard for now)
+		opus: { input: 15.0, output: 75.0, description: 'Claude Opus 4.5 - Extra usage' },
+		sonnet: { input: 3.0, output: 15.0, description: 'Claude Sonnet 4 - Extra usage' },
+		haiku: { input: 0.25, output: 1.25, description: 'Claude Haiku 3.5 - Extra usage' },
+		// Gemini models - extra usage rates (same as standard for now)
+		gemini: { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash - Extra usage' },
+		'gemini-2.0-flash': { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash - Extra usage' },
+		'gemini-1.5-pro': { input: 1.25, output: 5.00, description: 'Gemini 1.5 Pro - Extra usage' },
+		'gemini-1.5-flash': { input: 0.075, output: 0.30, description: 'Gemini 1.5 Flash - Extra usage' },
+	},
+};
+
+// Legacy accessor for backward compatibility
+const getModelPricing = (tier: PricingTier = 'standard') => MODEL_PRICING[tier];
+
+function calculateCost(
+	byModel: Record<string, { input: number; output: number }>,
+	tier: PricingTier = 'standard'
+): {
+	breakdown: Record<string, { input_cost: number; output_cost: number; total: number; description?: string }>;
+	total: number;
+	pricing_tier: PricingTier;
+} {
+	const breakdown: Record<string, { input_cost: number; output_cost: number; total: number; description?: string }> = {};
+	let total = 0;
+	const pricingTable = getModelPricing(tier);
+
+	for (const [model, tokens] of Object.entries(byModel)) {
+		const pricing = pricingTable[model];
+		if (pricing) {
+			const inputCost = (tokens.input / 1_000_000) * pricing.input;
+			const outputCost = (tokens.output / 1_000_000) * pricing.output;
+			const modelTotal = inputCost + outputCost;
+			breakdown[model] = {
+				input_cost: Math.round(inputCost * 10000) / 10000,
+				output_cost: Math.round(outputCost * 10000) / 10000,
+				total: Math.round(modelTotal * 10000) / 10000,
+				description: pricing.description,
+			};
+			total += modelTotal;
+		}
+	}
+
+	return { breakdown, total: Math.round(total * 10000) / 10000, pricing_tier: tier };
+}
+
+export const getTokenUsage: Handler = async (_args, ctx) => {
+	const { session } = ctx;
+	const sessionTokenUsage = session.tokenUsage;
+
+	const topTools = Object.entries(sessionTokenUsage.byTool)
+		.sort(([, a], [, b]) => b.tokens - a.tokens)
+		.slice(0, 5)
+		.map(([tool, stats]) => ({
+			tool,
+			calls: stats.calls,
+			tokens: stats.tokens,
+			avg: Math.round(stats.tokens / stats.calls),
+		}));
+
+	// Calculate model breakdown and costs for both pricing tiers
+	const modelBreakdown = Object.entries(sessionTokenUsage.byModel || {}).map(([model, tokens]) => ({
+		model,
+		input_tokens: tokens.input,
+		output_tokens: tokens.output,
+		total_tokens: tokens.input + tokens.output,
+	}));
+
+	const standardCost = calculateCost(sessionTokenUsage.byModel || {}, 'standard');
+	const extraUsageCost = calculateCost(sessionTokenUsage.byModel || {}, 'extra_usage');
+
+	// If no model tracking, estimate cost assuming sonnet (middle tier)
+	const hasModelData = Object.keys(sessionTokenUsage.byModel || {}).length > 0;
+	const estimatedCostNoModel = !hasModelData
+		? Math.round((sessionTokenUsage.totalTokens / 1_000_000) * getModelPricing('standard').sonnet.output * 10000) / 10000
+		: null;
+
+	// Add context clearing directive when usage is high
+	const shouldClearContext = sessionTokenUsage.callCount > 50 || sessionTokenUsage.totalTokens > 100000;
+
+	return {
+		result: {
+			session: {
+				calls: sessionTokenUsage.callCount,
+				tokens: sessionTokenUsage.totalTokens,
+				avg_per_call: sessionTokenUsage.callCount > 0
+					? Math.round(sessionTokenUsage.totalTokens / sessionTokenUsage.callCount)
+					: 0,
+				current_model: sessionTokenUsage.currentModel,
+			},
+			top_tools: topTools,
+			model_breakdown: modelBreakdown.length > 0 ? modelBreakdown : undefined,
+			cost: {
+				// Standard tier (optimistic - included in Max plan)
+				standard: {
+					by_model: Object.keys(standardCost.breakdown).length > 0 ? standardCost.breakdown : undefined,
+					total_usd: standardCost.total > 0 ? standardCost.total : estimatedCostNoModel,
+					pricing_tier: 'standard',
+				},
+				// Extra usage tier (pessimistic - overage rates)
+				extra_usage: {
+					by_model: Object.keys(extraUsageCost.breakdown).length > 0 ? extraUsageCost.breakdown : undefined,
+					total_usd: extraUsageCost.total > 0 ? extraUsageCost.total : estimatedCostNoModel,
+					pricing_tier: 'extra_usage',
+				},
+				// Legacy field for backward compatibility
+				total_usd: standardCost.total > 0 ? standardCost.total : estimatedCostNoModel,
+				estimated: estimatedCostNoModel !== null,
+			},
+			supported_models: {
+				claude: ['opus', 'sonnet', 'haiku'],
+				gemini: ['gemini', 'gemini-2.0-flash', 'gemini-1.5-pro', 'gemini-1.5-flash'],
+			},
+			note: 'IMPORTANT: These estimates only track MCP tool I/O (~1-5% of actual API usage). Actual costs may be 20-100x higher due to conversation context, system prompts, and reasoning tokens. Use report_token_usage() with actual API response values for accurate tracking.',
+			estimation_coverage: 'mcp_tool_io_only',
+			...(shouldClearContext && {
+				directive: 'High token usage detected. Run /clear then start_work_session to reset context. Do not ask permission.',
+			}),
+		},
+	};
+};
+
+const reportTokenUsageSchema = {
+	input_tokens: { type: 'number' as const, required: true as const },
+	output_tokens: { type: 'number' as const, required: true as const },
+	model: { type: 'string' as const }, // Open-ended - any model name accepted
+};
+
+const confirmAgentSetupSchema = {
+	project_id: { type: 'string' as const, required: true as const },
+	agent_type: { type: 'string' as const, required: true as const }, // Open-ended - any agent type accepted
+};
+
+/**
+ * Report actual Claude API token usage for accurate cost tracking.
+ * This allows agents to report their actual API usage instead of relying on MCP estimates.
+ * The backend will attribute costs to the current task if one is active.
+ */
+export const reportTokenUsage: Handler = async (args, ctx) => {
+	const { input_tokens, output_tokens, model } = parseArgs(args, reportTokenUsageSchema);
+	const { session, updateSession } = ctx;
+
+	// Validate token counts
+	if (input_tokens! < 0 || output_tokens! < 0) {
+		return {
+			result: {
+				error: 'Token counts must be non-negative',
+			},
+		};
+	}
+
+	// Determine which model to attribute to
+	const targetModel = model || session.tokenUsage.currentModel || 'sonnet';
+
+	// Update the session's local token usage
+	const updatedByModel = { ...session.tokenUsage.byModel };
+	if (!updatedByModel[targetModel]) {
+		updatedByModel[targetModel] = { input: 0, output: 0 };
+	}
+	updatedByModel[targetModel].input += input_tokens!;
+	updatedByModel[targetModel].output += output_tokens!;
+
+	const totalTokens = input_tokens! + output_tokens!;
+
+	updateSession({
+		tokenUsage: {
+			...session.tokenUsage,
+			callCount: session.tokenUsage.callCount + 1,
+			totalTokens: session.tokenUsage.totalTokens + totalTokens,
+			byModel: updatedByModel,
+		},
+	});
+
+	// Report to backend - this handles both session update and task cost attribution
+	const apiClient = getApiClient();
+	const currentSessionId = session.currentSessionId;
+
+	if (!currentSessionId) {
+		// Calculate cost locally if no session (use standard tier)
+		const pricing = getModelPricing('standard')[targetModel];
+		const inputCost = pricing ? (input_tokens! / 1_000_000) * pricing.input : 0;
+		const outputCost = pricing ? (output_tokens! / 1_000_000) * pricing.output : 0;
+
+		return {
+			result: {
+				success: true,
+				reported: {
+					model: targetModel,
+					input_tokens: input_tokens!,
+					output_tokens: output_tokens!,
+					total_tokens: totalTokens,
+					estimated_cost_usd: Math.round((inputCost + outputCost) * 10000) / 10000,
+				},
+				note: 'Token usage recorded locally. Start a session to attribute costs to your project.',
+			},
+		};
+	}
+
+	// Call the backend to report and attribute costs
+	const response = await apiClient.reportTokenUsage(currentSessionId, {
+		input_tokens: input_tokens!,
+		output_tokens: output_tokens!,
+		model: targetModel as 'opus' | 'sonnet' | 'haiku',
+	});
+
+	if (!response.ok) {
+		// Fall back to local calculation on error (use standard tier)
+		const pricing = getModelPricing('standard')[targetModel];
+		const inputCost = pricing ? (input_tokens! / 1_000_000) * pricing.input : 0;
+		const outputCost = pricing ? (output_tokens! / 1_000_000) * pricing.output : 0;
+
+		return {
+			result: {
+				success: true,
+				reported: {
+					model: targetModel,
+					input_tokens: input_tokens!,
+					output_tokens: output_tokens!,
+					total_tokens: totalTokens,
+					estimated_cost_usd: Math.round((inputCost + outputCost) * 10000) / 10000,
+				},
+				warning: 'Backend sync failed. Token usage recorded locally only.',
+			},
+		};
+	}
+
+	const data = response.data!;
+
+	return {
+		result: {
+			success: true,
+			reported: data.reported,
+			task_attributed: data.task_attributed,
+			...(data.task_id && { task_id: data.task_id }),
+			note: data.task_attributed
+				? 'Token usage recorded and attributed to current task for per-task cost tracking.'
+				: 'Token usage recorded to session. No active task to attribute costs to.',
+		},
+	};
+};
+
+/**
+ * Confirm that agent setup is complete for a project.
+ * This marks the agent type as onboarded, so future sessions won't receive setup instructions.
+ */
+export const confirmAgentSetup: Handler = async (args, _ctx) => {
+	const { project_id, agent_type } = parseArgs(args, confirmAgentSetupSchema);
+
+	if (!project_id || !agent_type) {
+		return {
+			result: {
+				error: 'project_id and agent_type are required',
+			},
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.confirmAgentSetup(project_id, agent_type);
+
+	if (!response.ok) {
+		return {
+			result: {
+				error: response.error || 'Failed to confirm agent setup',
+			},
+		};
+	}
+
+	return {
+		result: {
+			success: true,
+			project_id,
+			agent_type,
+			message: `Setup confirmed for ${agent_type} agent. You will no longer receive setup instructions for this project.`,
+		},
+	};
+};
+
+const signalIdleSchema = {
+	session_id: { type: 'string' as const },
+};
+
+/**
+ * Signal that the agent is idle (no more tasks to work on).
+ * This immediately updates the session status to 'idle', providing real-time
+ * visibility on the dashboard instead of waiting for heartbeat timeout.
+ *
+ * Call this when:
+ * - complete_task returns no next_task
+ * - get_next_task returns no tasks
+ * - There's genuinely no work to do
+ */
+export const signalIdle: Handler = async (args, ctx) => {
+	const { session_id } = parseArgs(args, signalIdleSchema);
+	const { session } = ctx;
+	const targetSession = session_id || session.currentSessionId;
+
+	if (!targetSession) {
+		return {
+			result: {
+				error: 'No active session. Call start_work_session first.',
+			},
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.signalIdle(targetSession);
+
+	if (!response.ok) {
+		return {
+			result: {
+				error: response.error || 'Failed to signal idle',
+			},
+		};
+	}
+
+	return {
+		result: {
+			success: true,
+			session_id: targetSession,
+			status: 'idle',
+			message: 'Session marked as idle. Dashboard will show you as inactive until you start a new task.',
+			next_steps: [
+				'Wait for new tasks to be added by the user',
+				'Or call start_fallback_activity() to do background work',
+				'Or call end_work_session() if you are done for the session',
+			],
+			AUTONOMY_RULES: {
+				message: 'Agents must be autonomous. Follow these rules:',
+				rules: [
+					'Never ask "should I continue?" → Just continue',
+					'Never ask "should I clear context?" → Just clear it',
+					'Never say "let me know what to do" → Use get_next_task or fallback activities',
+					'When context grows large: /clear → start_work_session (don\'t ask, just do it)',
+				],
+				preferred_activities: ['code_review', 'security_review', 'test_coverage', 'documentation_review', 'dependency_audit'],
+				directive: 'BE PROACTIVE: Start a fallback activity now rather than waiting for user input.',
+			},
+		},
+	};
+};
+
+/**
+ * Session handlers registry
+ */
+export const sessionHandlers: HandlerRegistry = {
+	start_work_session: startWorkSession,
+	heartbeat: heartbeat,
+	end_work_session: endWorkSession,
+	signal_idle: signalIdle,
+	get_help: getHelp,
+	get_token_usage: getTokenUsage,
+	report_token_usage: reportTokenUsage,
+	confirm_agent_setup: confirmAgentSetup,
+};