@gramatr/client 0.5.1

package/core/installer-cli.ts

@@ -0,0 +1,122 @@
+import type { StaleArtifact } from './migration.ts';
+import type { IntegrationTargetId } from './targets.ts';
+
+export interface DetectionDisplayTarget {
+  id: IntegrationTargetId;
+  label: string;
+  kind: 'local' | 'remote';
+  description: string;
+  detection: {
+    detected: boolean;
+    details?: string;
+  };
+}
+
+export function formatDetectionLines(detections: DetectionDisplayTarget[]): string[] {
+  const locals = detections.filter((target) => target.kind === 'local');
+  const remotes = detections.filter((target) => target.kind === 'remote');
+  const lines: string[] = [];
+
+  lines.push('Detected local integration targets:');
+  for (const target of locals) {
+    const status = target.detection.detected ? 'detected' : 'not found';
+    const suffix = target.detection.details ? ` (${target.detection.details})` : '';
+    lines.push(`- ${target.id}: ${status}${suffix}`);
+  }
+
+  lines.push('');
+  lines.push('Remote / hosted integration targets:');
+  for (const target of remotes) {
+    const suffix = target.detection.details ? ` (${target.detection.details})` : '';
+    lines.push(`- ${target.id}: ${target.description}${suffix}`);
+  }
+
+  return lines;
+}
+
+export function formatRemoteGuidanceLines(detections: DetectionDisplayTarget[]): string[] {
+  const remotes = detections.filter((target) => target.kind === 'remote');
+  const lines: string[] = [];
+  lines.push('');
+  lines.push('Hosted / remote targets are configured differently:');
+  for (const target of remotes) {
+    lines.push(`- ${target.id}: ${target.description}`);
+  }
+  lines.push("Use 'gramatr install remote-mcp' for remote setup guidance.");
+  return lines;
+}
+
+export function formatInstallMenuLines(
+  detections: DetectionDisplayTarget[],
+): { lines: string[]; targetIds: IntegrationTargetId[] } {
+  const targets = detections.filter((target) => target.kind === 'local');
+  const lines = ['Available local install targets:'];
+  for (const [index, target] of targets.entries()) {
+    const status = target.detection.detected ? 'detected' : 'not found';
+    lines.push(`${index + 1}. ${target.label} (${target.id}) - ${status}`);
+  }
+  lines.push(`${targets.length + 1}. all detected local targets`);
+  return { lines, targetIds: targets.map((target) => target.id) };
+}
+
+export function resolveInteractiveSelection(
+  answer: string,
+  targetIds: IntegrationTargetId[],
+  detectedLocalTargets: IntegrationTargetId[],
+  resolveTarget: (id: string) => { id: IntegrationTargetId; kind: 'local' | 'remote' } | undefined,
+): IntegrationTargetId[] {
+  if (!answer) return [];
+  if (answer === 'all') return detectedLocalTargets;
+
+  const parts = answer.split(',').map((part) => part.trim()).filter(Boolean);
+  const selected = new Set<IntegrationTargetId>();
+
+  for (const part of parts) {
+    const numeric = Number(part);
+    if (!Number.isNaN(numeric) && Number.isInteger(numeric)) {
+      if (numeric === targetIds.length + 1) {
+        for (const target of detectedLocalTargets) selected.add(target);
+        continue;
+      }
+      const indexed = targetIds[numeric - 1];
+      if (indexed) {
+        selected.add(indexed);
+        continue;
+      }
+    }
+
+    const target = resolveTarget(part);
+    if (target?.kind === 'local') {
+      selected.add(target.id);
+      continue;
+    }
+
+    throw new Error(`Unknown install target selection: ${part}`);
+  }
+
+  return Array.from(selected);
+}
+
+export function formatDoctorLines(
+  detections: DetectionDisplayTarget[],
+  payloadDir: string,
+  payloadPresent: boolean,
+  staleArtifacts: StaleArtifact[],
+): string[] {
+  const lines = formatDetectionLines(detections);
+  lines.push('');
+  lines.push(`Payload dir: ${payloadDir} ${payloadPresent ? '(present)' : '(missing)'}`);
+
+  if (staleArtifacts.length === 0) {
+    lines.push('Stale legacy artifacts: none detected');
+    return lines;
+  }
+
+  lines.push('Stale legacy artifacts:');
+  for (const artifact of staleArtifacts) {
+    lines.push(`- ${artifact.path} (${artifact.reason})`);
+  }
+  lines.push('Run `gramatr upgrade` after cleanup to re-sync installed targets.');
+  return lines;
+}
+

package/core/migration.ts

@@ -0,0 +1,479 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { buildClaudeHooksFile } from './install.ts';
+
+// ── Deep clean: PAI / Fabric / aios artifact removal ─────────────────────────
+//
+// `gramatr migrate --deep` detects and removes PAI, Fabric, and aios
+// leftovers from ~/.claude/{commands,skills} and from MCP server registries.
+// Always dry-run unless --apply. Always backs up to ~/.claude/backups/
+// before deleting. Conservative: deny-list only, never blanket-deletes.
+
+/**
+ * Slash command + skill name patterns that identify PAI/Fabric/aios artifacts.
+ * Match is case-insensitive against the basename (without .md extension).
+ */
+export const DEEP_CLEAN_DENY_PATTERNS: RegExp[] = [
+  /^pai[-_]/i,
+  /^pai$/i,
+  /^fabric[-_]/i,
+  /^fabric$/i,
+  /^aios[-_]/i,
+  /^aios$/i,
+  /^extract[-_]?wisdom/i,
+  /^extract[-_]/i,
+  /^analyze[-_]/i,
+  /^summarize[-_]/i,
+  /^create[-_]?prompt/i,
+  /^write[-_]?essay/i,
+  /^write[-_]?story/i,
+  /^get[-_]?wow/i,
+  /^improve[-_]?prompt/i,
+  /^official[-_]?pattern/i,
+  /^pattern[-_]/i,
+  /^council$/i,
+  /^prompting$/i,
+  /^becreative$/i,
+  /^beexpert$/i,
+];
+
+/**
+ * MCP server keys that are PAI/Fabric/aios remnants (case-insensitive).
+ * The legacy migration already strips `aios`. This adds the rest.
+ */
+export const DEEP_CLEAN_MCP_DENY_KEYS: RegExp[] = [
+  /^aios/i,
+  /^pai$/i,
+  /^pai[-_]/i,
+  /^fabric/i,
+];
+
+/**
+ * Slash commands gramatr itself ships. Always preserved by deep-clean.
+ * Both legacy `gmtr-*` / `GMTR-*` and the new lowercase `gramatr-*` per #500.
+ */
+export const GRAMATR_OWNED_COMMANDS: Set<string> = new Set([
+  'gramatr-algorithm.md',
+  'gramatr-init.md',
+  'gramatr-login.md',
+  'gramatr-query.md',
+  'gramatr-recall.md',
+  'gramatr-remember.md',
+  'GMTR-ALGORITHM.md',
+  'gmtr-init.md',
+  'gmtr-login.md',
+  'gmtr-query.md',
+  'gmtr-recall.md',
+  'gmtr-remember.md',
+]);
+
+export interface DeepCleanArtifact {
+  kind: 'command-file' | 'skill-dir' | 'mcp-server-entry';
+  path: string;
+  reason: string;
+  // For mcp-server-entry: which file the entry lives in + the key.
+  mcpFile?: string;
+  mcpKey?: string;
+}
+
+export interface DeepCleanResult {
+  artifacts: DeepCleanArtifact[];
+  backupDir?: string;
+}
+
+function matchesDenyPattern(name: string): boolean {
+  const stem = name.replace(/\.md$/i, '');
+  return DEEP_CLEAN_DENY_PATTERNS.some((rx) => rx.test(stem));
+}
+
+function matchesMcpDenyKey(key: string): boolean {
+  return DEEP_CLEAN_MCP_DENY_KEYS.some((rx) => rx.test(key));
+}
+
+/**
+ * Detect PAI/Fabric/aios cruft. Read-only — never modifies the filesystem.
+ */
+export function findDeepCleanArtifacts(homeDir: string): DeepCleanArtifact[] {
+  const out: DeepCleanArtifact[] = [];
+
+  // 1. ~/.claude/commands/*.md — flag any matching deny pattern OR (when not
+  //    in the gramatr allowlist AND matching a known PAI prefix). User's own
+  //    custom commands are NEVER touched unless they match a deny pattern.
+  const commandsDir = join(homeDir, '.claude', 'commands');
+  if (existsSync(commandsDir) && statSync(commandsDir).isDirectory()) {
+    for (const entry of readdirSync(commandsDir)) {
+      if (!entry.endsWith('.md')) continue;
+      if (GRAMATR_OWNED_COMMANDS.has(entry)) continue;
+      if (matchesDenyPattern(entry)) {
+        out.push({
+          kind: 'command-file',
+          path: join(commandsDir, entry),
+          reason: 'PAI/Fabric/aios slash command (matches deny pattern)',
+        });
+      }
+    }
+  }
+
+  // 2. ~/.claude/skills/*/ — flag any directory matching deny pattern.
+  //    gramatr ships zero skills today; anything matching the deny patterns
+  //    is definitely cruft. We do NOT blanket-delete the whole skills/ dir.
+  const skillsDir = join(homeDir, '.claude', 'skills');
+  if (existsSync(skillsDir) && statSync(skillsDir).isDirectory()) {
+    for (const entry of readdirSync(skillsDir)) {
+      const path = join(skillsDir, entry);
+      if (!statSync(path).isDirectory()) continue;
+      if (matchesDenyPattern(entry)) {
+        out.push({
+          kind: 'skill-dir',
+          path,
+          reason: 'PAI/Fabric skill directory (matches deny pattern)',
+        });
+      }
+    }
+  }
+
+  // 3. ~/.claude.json mcpServers + ~/.claude/mcp.json — flag deny-key entries.
+  for (const mcpFile of [join(homeDir, '.claude.json'), join(homeDir, '.claude', 'mcp.json')]) {
+    if (!existsSync(mcpFile)) continue;
+    let parsed: JsonObject;
+    try {
+      parsed = JSON.parse(readFileSync(mcpFile, 'utf8')) as JsonObject;
+    } catch {
+      continue;
+    }
+    const servers = isRecord(parsed.mcpServers) ? parsed.mcpServers : null;
+    if (!servers) continue;
+    for (const key of Object.keys(servers)) {
+      if (matchesMcpDenyKey(key)) {
+        out.push({
+          kind: 'mcp-server-entry',
+          path: `${mcpFile}#mcpServers.${key}`,
+          reason: `PAI/Fabric/aios MCP server entry "${key}"`,
+          mcpFile,
+          mcpKey: key,
+        });
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Run a deep-clean. Dry-run unless apply=true. When applying, backs up every
+ * removed artifact to ~/.claude/backups/gramatr-deep-clean-<timestamp>/ before
+ * deletion (full reversibility).
+ */
+export function runDeepClean(opts: {
+  homeDir: string;
+  apply: boolean;
+  log?: (message: string) => void;
+}): DeepCleanResult {
+  const { homeDir, apply, log } = opts;
+  const artifacts = findDeepCleanArtifacts(homeDir);
+
+  log?.('gramatr deep clean (PAI / Fabric / aios)');
+  log?.(`Mode: ${apply ? 'apply' : 'dry-run'}`);
+  log?.(`Found ${artifacts.length} artifact(s)`);
+
+  if (artifacts.length === 0) {
+    log?.('Nothing to clean. Already gramatr-only.');
+    return { artifacts };
+  }
+
+  // Group + display
+  const byKind = new Map<string, DeepCleanArtifact[]>();
+  for (const a of artifacts) {
+    const arr = byKind.get(a.kind) ?? [];
+    arr.push(a);
+    byKind.set(a.kind, arr);
+  }
+  for (const [kind, list] of byKind) {
+    log?.(`\n${kind} (${list.length}):`);
+    for (const a of list) log?.(`  ${a.path}  — ${a.reason}`);
+  }
+
+  if (!apply) {
+    log?.('\nDry-run only. Re-run with --apply to remove these (with backup).');
+    return { artifacts };
+  }
+
+  // ─── APPLY MODE ───
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = join(homeDir, '.claude', 'backups', `gramatr-deep-clean-${ts}`);
+  mkdirSync(backupDir, { recursive: true });
+  log?.(`\nBacking up to ${backupDir}`);
+
+  for (const artifact of artifacts) {
+    if (artifact.kind === 'command-file') {
+      const dest = join(backupDir, 'commands', artifact.path.split('/').pop() ?? 'unknown');
+      mkdirSync(join(backupDir, 'commands'), { recursive: true });
+      cpSync(artifact.path, dest);
+      rmSync(artifact.path, { force: true });
+      log?.(`  removed ${artifact.path}`);
+    } else if (artifact.kind === 'skill-dir') {
+      const dest = join(backupDir, 'skills', artifact.path.split('/').pop() ?? 'unknown');
+      mkdirSync(join(backupDir, 'skills'), { recursive: true });
+      cpSync(artifact.path, dest, { recursive: true });
+      rmSync(artifact.path, { recursive: true, force: true });
+      log?.(`  removed ${artifact.path}`);
+    } else if (artifact.kind === 'mcp-server-entry') {
+      // Strip the entry from the JSON file. Backup the original file once.
+      if (!artifact.mcpFile || !artifact.mcpKey) continue;
+      const fileBackup = join(backupDir, artifact.mcpFile.split('/').pop() ?? 'mcp.json');
+      if (!existsSync(fileBackup)) cpSync(artifact.mcpFile, fileBackup);
+      const parsed = JSON.parse(readFileSync(artifact.mcpFile, 'utf8')) as JsonObject;
+      if (isRecord(parsed.mcpServers)) {
+        const next = { ...parsed.mcpServers };
+        delete next[artifact.mcpKey];
+        parsed.mcpServers = next;
+        writeFileSync(artifact.mcpFile, `${JSON.stringify(parsed, null, 2)}\n`);
+      }
+      log?.(`  stripped ${artifact.path}`);
+    }
+  }
+
+  log?.(`\nDone. ${artifacts.length} artifact(s) removed. Backup: ${backupDir}`);
+  return { artifacts, backupDir };
+}
+
+const MANAGED_EVENTS = [
+  'PreToolUse',
+  'PostToolUse',
+  'UserPromptSubmit',
+  'SessionStart',
+  'SessionEnd',
+  'Stop',
+] as const;
+
+const LEGACY_HOOK_BASENAMES = [
+  'LoadContext.hook.ts',
+  'SecurityValidator.hook.ts',
+  'RatingCapture.hook.ts',
+  'VoiceGate.hook.ts',
+  'AutoWorkCreation.hook.ts',
+  'WorkCompletionLearning.hook.ts',
+  'RelationshipMemory.hook.ts',
+  'SessionSummary.hook.ts',
+  'UpdateCounts.hook.ts',
+  'IntegrityCheck.hook.ts',
+];
+
+export const LEGACY_CLIENT_DIRS = ['aios-v2-client'];
+export const LEGACY_REMOVE_DIRS = ['.claude/hooks'];
+export const LEGACY_REMOVE_HOOK_FILES = LEGACY_HOOK_BASENAMES;
+
+export interface StaleArtifact {
+  kind: 'directory' | 'hook-file';
+  path: string;
+  reason: string;
+}
+
+export interface MigrationOptions {
+  homeDir: string;
+  clientDir: string;
+  includeOptionalUx?: boolean;
+  apply: boolean;
+  log?: (message: string) => void;
+}
+
+interface JsonObject {
+  [key: string]: unknown;
+}
+
+function isRecord(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function commandLooksLegacy(command: string): boolean {
+  if (command.includes('/.claude/hooks/')) return true;
+  if (command.includes('/aios-v2-client/')) return true;
+  return LEGACY_HOOK_BASENAMES.some((basename) => command.includes(`/${basename}`));
+}
+
+function stripLegacyEntriesFromHookEvent(value: unknown): unknown {
+  if (!Array.isArray(value)) return value;
+
+  return value
+    .map((entry) => {
+      if (!isRecord(entry) || !Array.isArray(entry.hooks)) return entry;
+      const hooks = entry.hooks.filter((hook) => {
+        if (!isRecord(hook) || typeof hook.command !== 'string') return true;
+        return !commandLooksLegacy(hook.command);
+      });
+
+      if (hooks.length === 0) return null;
+      return { ...entry, hooks };
+    })
+    .filter(Boolean);
+}
+
+export function sanitizeClaudeSettings(
+  settings: JsonObject,
+  clientDir: string,
+  _includeOptionalUx: boolean = false, // deprecated — thin client has no optional hooks
+): JsonObject {
+  const next = { ...settings };
+  const hooks = isRecord(next.hooks) ? { ...next.hooks } : {};
+
+  for (const [eventName, eventValue] of Object.entries(hooks)) {
+    hooks[eventName] = stripLegacyEntriesFromHookEvent(eventValue);
+  }
+
+  const managed = buildClaudeHooksFile(clientDir).hooks;
+  for (const eventName of MANAGED_EVENTS) {
+    hooks[eventName] = managed[eventName];
+  }
+
+  next.hooks = hooks;
+  return next;
+}
+
+export function sanitizeClaudeJson(claudeJson: JsonObject): JsonObject {
+  if (!isRecord(claudeJson.mcpServers)) return claudeJson;
+  const mcpServers = { ...claudeJson.mcpServers };
+  delete mcpServers.aios;
+  return { ...claudeJson, mcpServers };
+}
+
+export function findStaleArtifacts(
+  homeDir: string,
+  clientDir: string,
+  exists: (path: string) => boolean,
+): StaleArtifact[] {
+  const artifacts: StaleArtifact[] = [];
+
+  for (const dir of LEGACY_CLIENT_DIRS) {
+    const path = `${homeDir}/${dir}`;
+    if (exists(path)) {
+      artifacts.push({
+        kind: 'directory',
+        path,
+        reason: 'Legacy client payload directory',
+      });
+    }
+  }
+
+  for (const dir of LEGACY_REMOVE_DIRS) {
+    const path = `${homeDir}/${dir}`;
+    if (exists(path)) {
+      artifacts.push({
+        kind: 'directory',
+        path,
+        reason: 'Legacy Claude hook directory',
+      });
+    }
+  }
+
+  for (const basename of LEGACY_REMOVE_HOOK_FILES) {
+    const path = `${clientDir}/hooks/${basename}`;
+    if (exists(path)) {
+      artifacts.push({
+        kind: 'hook-file',
+        path,
+        reason: 'Deprecated legacy hook file',
+      });
+    }
+  }
+
+  return artifacts;
+}
+
+function backupFile(path: string, log?: (message: string) => void): void {
+  if (!existsSync(path)) return;
+  const backup = `${path}.backup-${Date.now()}`;
+  cpSync(path, backup);
+  log?.(`OK Backed up ${path} -> ${backup}`);
+}
+
+function readJson(path: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+}
+
+function writeJson(path: string, value: Record<string, unknown>): void {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function removeIfExists(path: string, log?: (message: string) => void): void {
+  if (!existsSync(path)) return;
+  rmSync(path, { recursive: true, force: true });
+  log?.(`OK Removed ${path}`);
+}
+
+function removeLegacyHookFiles(clientDir: string, log?: (message: string) => void): void {
+  const hooksDir = join(clientDir, 'hooks');
+  if (!existsSync(hooksDir)) return;
+
+  for (const basename of LEGACY_REMOVE_HOOK_FILES) {
+    const path = join(hooksDir, basename);
+    if (existsSync(path)) {
+      rmSync(path, { force: true });
+      log?.(`OK Removed stale hook ${path}`);
+    }
+  }
+
+  for (const entry of readdirSync(hooksDir)) {
+    if (!entry.endsWith('.sh')) continue;
+    const path = join(hooksDir, entry);
+    if (statSync(path).isFile()) {
+      rmSync(path, { force: true });
+      log?.(`OK Removed stale shell hook ${path}`);
+    }
+  }
+}
+
+export function runLegacyMigration(options: MigrationOptions): void {
+  const { homeDir, clientDir, includeOptionalUx = false, apply, log } = options;
+  const claudeSettingsPath = join(homeDir, '.claude', 'settings.json');
+  const claudeJsonPath = join(homeDir, '.claude.json');
+
+  log?.('grāmatr legacy install cleanup');
+  log?.(`Mode: ${apply ? 'apply' : 'dry-run'}`);
+  log?.(`Client dir: ${clientDir}`);
+
+  if (existsSync(claudeSettingsPath)) {
+    const sanitized = sanitizeClaudeSettings(readJson(claudeSettingsPath), clientDir, includeOptionalUx);
+    if (apply) {
+      backupFile(claudeSettingsPath, log);
+      writeJson(claudeSettingsPath, sanitized);
+      log?.(`OK Sanitized ${claudeSettingsPath}`);
+    } else {
+      log?.(`Would sanitize ${claudeSettingsPath}`);
+    }
+  }
+
+  if (existsSync(claudeJsonPath)) {
+    const sanitized = sanitizeClaudeJson(readJson(claudeJsonPath));
+    if (apply) {
+      backupFile(claudeJsonPath, log);
+      writeJson(claudeJsonPath, sanitized);
+      log?.(`OK Sanitized ${claudeJsonPath}`);
+    } else {
+      log?.(`Would sanitize ${claudeJsonPath}`);
+    }
+  }
+
+  for (const dir of LEGACY_CLIENT_DIRS) {
+    const path = join(homeDir, dir);
+    if (apply) {
+      removeIfExists(path, log);
+    } else if (existsSync(path)) {
+      log?.(`Would remove ${path}`);
+    }
+  }
+
+  for (const dir of LEGACY_REMOVE_DIRS) {
+    const path = join(homeDir, dir);
+    if (apply) {
+      removeIfExists(path, log);
+    } else if (existsSync(path)) {
+      log?.(`Would remove ${path}`);
+    }
+  }
+
+  if (apply) {
+    removeLegacyHookFiles(clientDir, log);
+  } else if (existsSync(join(clientDir, 'hooks'))) {
+    log?.(`Would remove stale hook files from ${join(clientDir, 'hooks')}`);
+  }
+}

package/core/routing.ts

@@ -0,0 +1,108 @@
+import {
+  callMcpToolDetailed,
+  resolveMcpUrl,
+  saveLastClassification,
+  type MctToolCallError,
+} from '../hooks/lib/gmtr-hook-utils.ts';
+import type { RouteResponse } from './types.ts';
+
+export const MIN_PROMPT_LENGTH = 10;
+export const TRIVIAL_PATTERNS =
+  /^(hi|hey|hello|yo|ok|yes|no|thanks|thank you|sure|yep|nope|k|bye|quit|exit)\b/i;
+
+export function shouldSkipPromptRouting(prompt: string): boolean {
+  const trimmed = prompt.trim();
+  return trimmed.length < MIN_PROMPT_LENGTH || TRIVIAL_PATTERNS.test(trimmed);
+}
+
+export async function routePrompt(options: {
+  prompt: string;
+  projectId?: string;
+  sessionId?: string;
+  timeoutMs?: number;
+  /**
+   * Cross-tool statusline injection (#496). When true, the server attaches a
+   * composed [GMTR Status] markdown block to the route response. Hooks for
+   * Codex and Gemini set this; the Claude Code path leaves it false because
+   * Claude Code has its own native terminal statusline.
+   */
+  includeStatusline?: boolean;
+  statuslineSize?: 'small' | 'medium' | 'large';
+}): Promise<{ route: RouteResponse | null; error: MctToolCallError | null }> {
+  const result = await callMcpToolDetailed<RouteResponse>(
+    'gmtr_route_request',
+    {
+      prompt: options.prompt,
+      ...(options.projectId ? { project_id: options.projectId } : {}),
+      ...(options.sessionId ? { session_id: options.sessionId } : {}),
+      ...(options.includeStatusline ? { include_statusline: true } : {}),
+      ...(options.statuslineSize ? { statusline_size: options.statuslineSize } : {}),
+    },
+    options.timeoutMs ?? 15000,
+  );
+
+  return {
+    route: result.data,
+    error: result.error,
+  };
+}
+
+export function describeRoutingFailure(error: MctToolCallError): {
+  title: string;
+  detail: string;
+  action: string;
+} {
+  switch (error.reason) {
+    case 'auth':
+      return {
+        title: 'Routing request failed due to authentication.',
+        detail: error.detail,
+        action: 'Check the configured GMTR token for the hook runtime.',
+      };
+    case 'timeout':
+      return {
+        title: 'Routing request timed out.',
+        detail: error.detail,
+        action: 'Check gramatr server latency or increase the hook timeout.',
+      };
+    case 'network_error':
+      return {
+        title: 'Routing request could not reach the gramatr MCP endpoint.',
+        detail: error.detail,
+        action: `Verify connectivity to ${resolveMcpUrl()}.`,
+      };
+    case 'http_error':
+    case 'mcp_error':
+    case 'parse_error':
+    case 'unknown':
+    default:
+      return {
+        title: 'Routing request failed before intelligence could be injected.',
+        detail: error.detail,
+        action: `Inspect the response from ${resolveMcpUrl()} and the gmtr_route_request handler.`,
+      };
+  }
+}
+
+export function persistClassificationResult(options: {
+  rootDir: string;
+  prompt: string;
+  route: RouteResponse | null;
+  downstreamModel: string | null;
+  clientType: string;
+  agentName: string;
+}): void {
+  saveLastClassification(options.rootDir, {
+    timestamp: new Date().toISOString(),
+    original_prompt: options.prompt,
+    effort_level: options.route?.classification?.effort_level || null,
+    intent_type: options.route?.classification?.intent_type || null,
+    confidence: options.route?.classification?.confidence ?? null,
+    classifier_model: options.route?.execution_summary?.classifier_model || null,  // previously: qwen_model
+    downstream_model: options.downstreamModel || null,
+    client_type: options.clientType,
+    agent_name: options.agentName,
+    pending_feedback: true,
+    feedback_submitted_at: null,
+  });
+}