fix: add error handling to critical tools

README.md

@@ -72,6 +72,66 @@ The pattern is always the same: vague prompt → Claude guesses → wrong output
      → 4,000 tokens, done right the first time
 ```
 
+### What Tool Output Looks Like
+
+When you run `preflight_check` on a real prompt, here's what you get back:
+
+**Ambiguous prompt** — `"update the user model"`:
+
+```
+┌─ preflight_check ────────────────────────────────────────────┐
+│ Classification: ⚠️ AMBIGUOUS                                 │
+│ Confidence: 0.85                                             │
+│                                                              │
+│ Issues:                                                      │
+│  • "user model" matches 3 files: User (prisma/schema.prisma),│
+│    UserProfile (src/types/user.ts), UserDTO (src/api/types.ts)│
+│  • No indication of what fields to update or why             │
+│                                                              │
+│ Suggested clarification:                                     │
+│  "Which user model? What fields are changing?                │
+│   e.g. 'Add emailVerified boolean to the User model          │
+│   in prisma/schema.prisma and regenerate the client'"        │
+│                                                              │
+│ Correction history: You've had 2 past corrections on         │
+│ schema changes — both were missing migration steps.          │
+│ Consider including 'and create a migration' in your prompt.  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Well-specified prompt** — `"add a retryCount integer field to the Job model in prisma/schema.prisma, default 0, and create a migration"`:
+
+```
+┌─ preflight_check ────────────────────────────────────────────┐
+│ Classification: ✅ CLEAR                                     │
+│ Confidence: 0.95                                             │
+│                                                              │
+│ Scope: 1 file (prisma/schema.prisma) + migration             │
+│ Estimated tokens: ~2,000                                     │
+│ Proceeding without intervention.                             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Cross-service prompt** — `"change the webhook payload format"`:
+
+```
+┌─ preflight_check ────────────────────────────────────────────┐
+│ Classification: 🔗 CROSS-SERVICE                             │
+│                                                              │
+│ Contracts found:                                             │
+│  • WebhookPayload (src/events/types.ts)                      │
+│  • WebhookPayload consumer (auth-service/src/handlers/       │
+│    webhook.ts:42)                                            │
+│  • WebhookPayload consumer (billing-api/src/lib/events.ts:18)│
+│                                                              │
+│ ⚠️ 2 downstream consumers depend on this type.               │
+│ Changing the payload shape will break auth-service and        │
+│ billing-api unless they're updated too.                      │
+└──────────────────────────────────────────────────────────────┘
+```
+
+These outputs appear inline in your Claude Code session — no extra windows or dashboards.
+
 ---
 
 ## Quick Start

src/index.ts

@@ -49,6 +49,7 @@
 import { registerGenerateScorecard } from "./tools/generate-scorecard.js";
 import { registerSearchContracts } from "./tools/search-contracts.js";
 import { registerEstimateCost } from "./tools/estimate-cost.js";
+import { registerExportTimeline } from "./tools/export-timeline.js";
 
 // Validate related projects from config
 function validateRelatedProjects(): void {
@@ -73,7 +74,7 @@
 }
 
 // Load config and validate related projects on startup
 const config = getConfig();
 validateRelatedProjects();
 
 const profile = getProfile();
@@ -110,6 +111,7 @@
   ["generate_scorecard", registerGenerateScorecard],
   ["estimate_cost", registerEstimateCost],
   ["search_contracts", registerSearchContracts],
+  ["export_timeline", registerExportTimeline],
 ];
 
 let registered = 0;

src/tools/audit-workspace.ts

@@ -35,6 +35,7 @@ export function registerAuditWorkspace(server: McpServer): void {
     `Audit workspace documentation freshness vs actual project state. Compares .claude/ workspace docs against recent git commits to find stale or missing documentation. Call after completing a batch of work or at session end.`,
     {},
     async () => {
+      try {
       const docs = findWorkspaceDocs();
       const recentFiles = run("git diff --name-only HEAD~10 2>/dev/null || echo ''").split("\n").filter(Boolean);
       const sections: string[] = [];
@@ -92,6 +93,15 @@ export function registerAuditWorkspace(server: McpServer): void {
       sections.push(`## Recommendation\n${recs.join("\n")}`);
 
       return { content: [{ type: "text" as const, text: sections.join("\n\n") }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{
+            type: "text" as const,
+            text: `## Workspace Audit — Error ❌\n\n**Error**: ${message}\n\nCould not audit workspace. Ensure you're in a git repository with a .claude/ directory.`,
+          }],
+        };
+      }
     }
   );
 }

src/tools/checkpoint.ts

@@ -17,6 +17,7 @@ export function registerCheckpoint(server: McpServer): void {
       commit_mode: z.enum(["staged", "tracked", "all"]).optional().describe("What to commit: 'staged' (only staged files), 'tracked' (modified tracked files), 'all' (git add -A). Default: 'tracked'"),
     },
     async ({ summary, next_steps, current_blockers, commit_mode }) => {
+      try {
       const mode = commit_mode || "tracked";
       const branch = getBranch();
       const dirty = getStatus();
@@ -114,6 +115,15 @@ ${current_blockers ? "- Current blockers\n" : ""}- Working tree state at checkpo
 Tell the next session/continuation: "Read .claude/last-checkpoint.md for where I left off"`,
         }],
       };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{
+            type: "text" as const,
+            text: `## Checkpoint Failed ❌\n\n**Error**: ${message}\n\n**What to do**: Your work is NOT lost — files are still on disk. Try:\n1. Manually commit: \`git add -u && git commit -m "manual checkpoint"\`\n2. Check git status: \`git status\`\n3. Re-run checkpoint after fixing the issue`,
+          }],
+        };
+      }
     }
   );
 }