agent-gauntlet 0.13.1 → 0.14.0

package/dist/index.js

@@ -7,9 +7,9 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "agent-gauntlet",
-  version: "0.13.1",
+  version: "0.14.0",
   description: "A CLI tool for testing AI coding agents",
-  license: "Apache-2.0",
+  license: "MIT",
   author: "Paul Caplan",
   repository: {
     type: "git",
@@ -70,6 +70,7 @@ var package_default = {
     typescript: "^5"
   },
   dependencies: {
+    "@inquirer/prompts": "^8.2.1",
     "@logtape/logtape": "^2.0.2",
     chalk: "^5.6.2",
     commander: "^14.0.2",
@@ -946,11 +947,14 @@ class ClaudeStopHookAdapter {
     const stopReason = result.shouldBlock && blockReason ? blockReason : result.message;
     const response = {
       decision: result.shouldBlock ? "block" : "approve",
-      stopReason,
-      systemMessage: result.message,
-      status: result.status,
-      message: result.message
+      status: result.status
     };
+    if (stopReason)
+      response.stopReason = stopReason;
+    if (result.message) {
+      response.systemMessage = result.message;
+      response.message = result.message;
+    }
     if (result.shouldBlock && blockReason) {
       response.reason = blockReason;
     }
@@ -995,7 +999,7 @@ class CursorStopHookAdapter {
       return JSON.stringify(response2);
     }
     const response = {
-      systemMessage: result.message
+      ...result.message ? { systemMessage: result.message } : {}
     };
     return JSON.stringify(response);
   }
@@ -1305,6 +1309,9 @@ class DebugLogger {
   async logStopHook(decision, reason) {
     await this.write(`STOP_HOOK decision=${decision} reason=${reason}`);
   }
+  async logStartHook(adapter) {
+    await this.write(`START_HOOK adapter=${adapter}`);
+  }
   async logStopHookDiagnostics(diagnostics) {
     const parts = [
       "STOP_HOOK_DIAG",
@@ -1567,6 +1574,27 @@ async function isCommitInBranch(commit, branch) {
 function getExecutionStateFilename() {
   return EXECUTION_STATE_FILENAME;
 }
+async function hasWorkingTreeChanges() {
+  return new Promise((resolve) => {
+    const child = spawn("git", ["status", "--porcelain"], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    child.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve(stdout.trim().length > 0);
+      } else {
+        resolve(true);
+      }
+    });
+    child.on("error", () => {
+      resolve(true);
+    });
+  });
+}
 async function gitObjectExists(sha) {
   return new Promise((resolve) => {
     const child = spawn("git", ["cat-file", "-t", sha], {
@@ -1818,7 +1846,7 @@ var STATUS_MESSAGES = {
   no_config: "○ Not a gauntlet project — no .gauntlet/config.yml found.",
   stop_hook_active: "↺ Stop hook cycle detected — allowing stop to prevent infinite loop.",
   loop_detected: "↺ Loop detected — stop hook blocked 3 times within 60s. Allowing stop to prevent infinite loop.",
-  stop_hook_disabled: "○ Stop hook is disabled via configuration.",
+  stop_hook_disabled: "",
   invalid_input: "⚠ Invalid hook input — could not parse JSON, allowing stop."
 };
 function getStatusMessage(status, context) {
@@ -2528,6 +2556,9 @@ class ClaudeAdapter {
   transformCommand(markdownContent) {
     return markdownContent;
   }
+  supportsHooks() {
+    return true;
+  }
   async execute(opts) {
     const fullContent = `${opts.prompt}
 
@@ -2727,6 +2758,9 @@ class CodexAdapter {
   transformCommand(markdownContent) {
     return markdownContent;
   }
+  supportsHooks() {
+    return false;
+  }
   buildArgs(allowToolUse, thinkingBudget) {
     const args = [
       "exec",
@@ -2837,6 +2871,9 @@ class CursorAdapter {
   transformCommand(markdownContent) {
     return markdownContent;
   }
+  supportsHooks() {
+    return true;
+  }
   async execute(opts) {
     const fullContent = `${opts.prompt}
 
@@ -3080,6 +3117,9 @@ class GeminiAdapter {
   canUseSymlink() {
     return false;
   }
+  supportsHooks() {
+    return false;
+  }
   transformCommand(markdownContent) {
     const fmMatch = markdownContent.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
     let description = "Run the gauntlet verification suite";
@@ -3279,6 +3319,9 @@ class GitHubCopilotAdapter {
   transformCommand(markdownContent) {
     return markdownContent;
   }
+  supportsHooks() {
+    return false;
+  }
   async execute(opts) {
     const fullContent = `${opts.prompt}
 
@@ -5468,7 +5511,8 @@ async function shouldAutoClean(logDir, baseBranch) {
   } catch {
     return { clean: false };
   }
-  if (!state.working_tree_ref || state.working_tree_ref === state.commit) {
+  const hasChanges = await hasWorkingTreeChanges();
+  if (!hasChanges) {
     try {
       const isMerged = await isCommitInBranch(state.commit, baseBranch);
       if (isMerged) {
@@ -6720,13 +6764,141 @@ function registerHelpCommand(program) {
 }
 // src/commands/init.ts
 import { readFileSync } from "node:fs";
+import fs26 from "node:fs/promises";
+import path25 from "node:path";
+import { fileURLToPath } from "node:url";
+import chalk10 from "chalk";
+
+// src/commands/init-checksums.ts
+import { createHash } from "node:crypto";
 import fs25 from "node:fs/promises";
 import path24 from "node:path";
-import { fileURLToPath } from "node:url";
+async function computeSkillChecksum(skillDir) {
+  const files = await collectFiles(skillDir);
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const hash = createHash("sha256");
+  for (const file of files) {
+    hash.update(file.relativePath);
+    hash.update(file.content);
+  }
+  return hash.digest("hex");
+}
+function computeExpectedSkillChecksum(content, references) {
+  const entries = [
+    { relativePath: "SKILL.md", content }
+  ];
+  if (references) {
+    for (const [name, refContent] of Object.entries(references)) {
+      entries.push({
+        relativePath: path24.join("references", name),
+        content: refContent
+      });
+    }
+  }
+  entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const hash = createHash("sha256");
+  for (const entry of entries) {
+    hash.update(entry.relativePath);
+    hash.update(entry.content);
+  }
+  return hash.digest("hex");
+}
+function computeHookChecksum(entries) {
+  const gauntletEntries = entries.filter((entry) => isGauntletHookEntry(entry));
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify(gauntletEntries));
+  return hash.digest("hex");
+}
+function computeExpectedHookChecksum(hookEntries) {
+  return computeHookChecksum(hookEntries);
+}
+function isGauntletHookEntry(entry) {
+  if (typeof entry.command === "string" && entry.command.startsWith("agent-gauntlet")) {
+    return true;
+  }
+  const nested = entry.hooks;
+  if (Array.isArray(nested)) {
+    return nested.some((h) => typeof h.command === "string" && h.command.startsWith("agent-gauntlet"));
+  }
+  return false;
+}
+async function collectFiles(dir, baseDir) {
+  const base = baseDir ?? dir;
+  const results = [];
+  const entries = await fs25.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path24.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...await collectFiles(fullPath, base));
+    } else if (entry.isFile()) {
+      const content = await fs25.readFile(fullPath, "utf-8");
+      results.push({ relativePath: path24.relative(base, fullPath), content });
+    }
+  }
+  return results;
+}
+
+// src/commands/init-prompts.ts
+import { checkbox, confirm, number } from "@inquirer/prompts";
 import chalk9 from "chalk";
-var __dirname2 = path24.dirname(fileURLToPath(import.meta.url));
+async function promptDevCLIs(detectedNames, skipPrompts) {
+  if (skipPrompts)
+    return detectedNames;
+  console.log();
+  console.log(chalk9.bold("Select your development CLI(s). These are the main tools you work in."));
+  const selected = await checkbox({
+    message: "Development CLIs:",
+    choices: detectedNames.map((name) => ({ name, value: name })),
+    required: true
+  });
+  return selected;
+}
+async function promptReviewCLIs(detectedNames, skipPrompts) {
+  if (skipPrompts)
+    return detectedNames;
+  console.log();
+  console.log(chalk9.bold("Select your reviewer CLI(s). These are the CLIs that will be used for AI code reviews."));
+  const selected = await checkbox({
+    message: "Review CLIs:",
+    choices: detectedNames.map((name) => ({ name, value: name })),
+    required: true
+  });
+  return selected;
+}
+async function promptNumReviews(reviewCliCount, skipPrompts) {
+  if (reviewCliCount === 1)
+    return 1;
+  if (skipPrompts)
+    return reviewCliCount;
+  const result = await number({
+    message: "How many of these CLIs would you like to run on every review?",
+    min: 1,
+    max: reviewCliCount,
+    default: 1
+  });
+  return result ?? 1;
+}
+async function promptFileOverwrite(name, skipPrompts) {
+  if (skipPrompts)
+    return true;
+  return confirm({
+    message: `Skill \`${name}\` has changed, update it?`,
+    default: true
+  });
+}
+async function promptHookOverwrite(hookFile, skipPrompts) {
+  if (skipPrompts)
+    return true;
+  return confirm({
+    message: `Hook configuration in ${hookFile} has changed, update it?`,
+    default: true
+  });
+}
+
+// src/commands/init.ts
+var __dirname2 = path25.dirname(fileURLToPath(import.meta.url));
 function readSkillTemplate(filename) {
-  const templatePath = path24.join(__dirname2, "skill-templates", filename);
+  const templatePath = path25.join(__dirname2, "skill-templates", filename);
   return readFileSync(templatePath, "utf-8");
 }
 var CLI_PREFERENCE_ORDER = [
@@ -6744,13 +6916,15 @@ var ADAPTER_CONFIG = {
 function buildGauntletSkillContent(mode) {
   const isRun = mode === "run";
   const name = isRun ? "run" : "check";
-  const description = isRun ? "Run the full verification gauntlet" : "Run checks only (no reviews)";
+  const description = isRun ? "Run the full verification gauntlet. Use this as the final step after completing a coding task — verifies quality, runs checks, and ensures all gates pass. Must be run before committing, pushing, or creating PRs." : "Run checks only (no reviews)";
   const command = isRun ? "agent-gauntlet run" : "agent-gauntlet check";
   const heading = isRun ? "Execute the autonomous verification suite." : "Run the gauntlet checks only — no AI reviews.";
+  const disableModelInvocation = isRun ? "false" : "true";
   const frontmatter = `---
 name: gauntlet-${name}
-description: ${description}
-disable-model-invocation: true
+description: >-
+  ${description}
+disable-model-invocation: ${disableModelInvocation}
 allowed-tools: Bash
 ---`;
   const steps = [
@@ -6839,16 +7013,37 @@ var SETUP_SKILL_CONTENT = readSkillTemplate("setup-skill.md");
 var CHECK_CATALOG_REFERENCE = readSkillTemplate("check-catalog.md");
 var PROJECT_STRUCTURE_REFERENCE = readSkillTemplate("setup-ref-project-structure.md");
 var SKILL_DEFINITIONS = [
-  { action: "run", content: GAUNTLET_RUN_SKILL_CONTENT },
-  { action: "check", content: GAUNTLET_CHECK_SKILL_CONTENT },
-  { action: "push-pr", content: PUSH_PR_SKILL_CONTENT },
-  { action: "fix-pr", content: FIX_PR_SKILL_CONTENT },
-  { action: "status", content: GAUNTLET_STATUS_SKILL_CONTENT },
+  {
+    action: "run",
+    content: GAUNTLET_RUN_SKILL_CONTENT,
+    description: "Run the verification suite"
+  },
+  {
+    action: "check",
+    content: GAUNTLET_CHECK_SKILL_CONTENT,
+    description: "Run a single check gate"
+  },
+  {
+    action: "push-pr",
+    content: PUSH_PR_SKILL_CONTENT,
+    description: "Commit, push, and create a PR"
+  },
+  {
+    action: "fix-pr",
+    content: FIX_PR_SKILL_CONTENT,
+    description: "Fix PR review comments and CI failures"
+  },
+  {
+    action: "status",
+    content: GAUNTLET_STATUS_SKILL_CONTENT,
+    description: "Show gauntlet status"
+  },
   {
     action: "help",
     content: HELP_SKILL_BUNDLE.content,
     references: HELP_SKILL_BUNDLE.references,
-    skillsOnly: true
+    skillsOnly: true,
+    description: "Diagnose and explain gauntlet behavior"
   },
   {
     action: "setup",
@@ -6857,82 +7052,192 @@ var SKILL_DEFINITIONS = [
       "check-catalog.md": CHECK_CATALOG_REFERENCE,
       "project-structure.md": PROJECT_STRUCTURE_REFERENCE
     },
-    skillsOnly: true
+    skillsOnly: true,
+    description: "Configure checks and reviews interactively"
   }
 ];
+var NATIVE_CLIS = new Set(["claude", "cursor"]);
 function registerInitCommand(program) {
   program.command("init").description("Initialize .gauntlet configuration").option("-y, --yes", "Skip prompts and use defaults").action(async (options) => {
     const projectRoot = process.cwd();
-    const targetDir = path24.join(projectRoot, ".gauntlet");
-    if (await exists(targetDir)) {
-      console.log(chalk9.yellow(".gauntlet directory already exists."));
-      return;
-    }
+    const targetDir = path25.join(projectRoot, ".gauntlet");
+    const skipPrompts = options.yes ?? false;
     console.log("Detecting available CLI agents...");
     const availableAdapters = await detectAvailableCLIs();
     if (availableAdapters.length === 0) {
       printNoCLIsMessage();
       return;
     }
-    await scaffoldProject({
-      projectRoot,
-      targetDir,
-      availableAdapters,
-      skipPrompts: options.yes ?? false
-    });
-    if (availableAdapters.some((a) => a.name === "claude")) {
-      await installStopHook(projectRoot);
-    }
-    if (availableAdapters.some((a) => a.name === "cursor")) {
-      await installCursorStopHook(projectRoot);
+    const detectedNames = availableAdapters.map((a) => a.name);
+    const gauntletExists = await exists(targetDir);
+    let hookAdapters;
+    let instructionCLINames;
+    if (gauntletExists) {
+      console.log(chalk10.dim(".gauntlet/ already exists, skipping scaffolding"));
+      hookAdapters = availableAdapters;
+      instructionCLINames = detectedNames;
+    } else {
+      const devCLINames = await promptDevCLIs(detectedNames, skipPrompts);
+      hookAdapters = availableAdapters.filter((a) => devCLINames.includes(a.name));
+      for (const adapter of hookAdapters) {
+        if (!adapter.supportsHooks()) {
+          console.log(chalk10.yellow(`  ${adapter.name} doesn't support hooks yet, skipping hook installation`));
+        }
+      }
+      const reviewCLINames = await promptReviewCLIs(detectedNames, skipPrompts);
+      const numReviews = await promptNumReviews(reviewCLINames.length, skipPrompts);
+      console.log(chalk10.cyan("Agent Gauntlet's built-in code quality reviewer will be installed."));
+      await scaffoldGauntletDir(projectRoot, targetDir, reviewCLINames, numReviews);
+      instructionCLINames = devCLINames;
     }
+    await installExternalFiles(projectRoot, hookAdapters, skipPrompts);
     await addToGitignore(projectRoot, "gauntlet_logs");
-    console.log();
-    console.log(chalk9.bold("Run /gauntlet-setup to configure your checks and reviews"));
+    printPostInitInstructions(instructionCLINames);
   });
 }
 function printNoCLIsMessage() {
   console.log();
-  console.log(chalk9.red("Error: No CLI agents found. Install at least one:"));
+  console.log(chalk10.red("Error: No CLI agents found. Install at least one:"));
   console.log("  - Claude: https://docs.anthropic.com/en/docs/claude-code");
   console.log("  - Gemini: https://github.com/google-gemini/gemini-cli");
   console.log("  - Codex: https://github.com/openai/codex");
   console.log();
 }
-async function scaffoldProject(options) {
-  const { projectRoot, targetDir, availableAdapters, skipPrompts } = options;
-  await fs25.mkdir(targetDir);
-  await fs25.mkdir(path24.join(targetDir, "checks"));
-  await fs25.mkdir(path24.join(targetDir, "reviews"));
-  const commands = SKILL_DEFINITIONS.map((skill) => ({
-    action: skill.action,
-    content: skill.content,
-    ..."references" in skill ? { references: skill.references } : {},
-    ..."skillsOnly" in skill ? { skillsOnly: skill.skillsOnly } : {}
-  }));
-  if (skipPrompts) {
-    await installCommands({
-      level: "project",
-      agentNames: ["claude"],
-      projectRoot,
-      commands
-    });
-  } else {
-    await promptAndInstallCommands({ projectRoot, commands });
+async function scaffoldGauntletDir(_projectRoot, targetDir, reviewCLINames, numReviews) {
+  if (await exists(targetDir)) {
+    console.log(chalk10.dim(".gauntlet/ already exists, skipping scaffolding"));
+    return;
+  }
+  await fs26.mkdir(targetDir);
+  await fs26.mkdir(path25.join(targetDir, "checks"));
+  await fs26.mkdir(path25.join(targetDir, "reviews"));
+  await writeConfigYml(targetDir, reviewCLINames);
+  await fs26.writeFile(path25.join(targetDir, "reviews", "code-quality.yml"), `builtin: code-quality
+num_reviews: ${numReviews}
+`);
+  console.log(chalk10.green("Created .gauntlet/reviews/code-quality.yml"));
+}
+async function writeSkillFiles(actionDir, content, references) {
+  await fs26.mkdir(actionDir, { recursive: true });
+  await fs26.writeFile(path25.join(actionDir, "SKILL.md"), content);
+  if (references) {
+    const refsDir = path25.join(actionDir, "references");
+    await fs26.mkdir(refsDir, { recursive: true });
+    for (const [fileName, fileContent] of Object.entries(references)) {
+      await fs26.writeFile(path25.join(refsDir, fileName), fileContent);
+    }
+  }
+}
+async function installSkillsWithChecksums(projectRoot, skipPrompts) {
+  const skillsDir = path25.join(projectRoot, ".claude", "skills");
+  for (const skill of SKILL_DEFINITIONS) {
+    const actionDir = path25.join(skillsDir, `gauntlet-${skill.action}`);
+    const skillPath = path25.join(actionDir, "SKILL.md");
+    const references = "references" in skill ? skill.references : undefined;
+    if (!await exists(actionDir)) {
+      await writeSkillFiles(actionDir, skill.content, references);
+      console.log(chalk10.green(`Created ${path25.relative(projectRoot, skillPath)}`));
+      continue;
+    }
+    const expectedChecksum = computeExpectedSkillChecksum(skill.content, references);
+    const actualChecksum = await computeSkillChecksum(actionDir);
+    if (expectedChecksum === actualChecksum)
+      continue;
+    const shouldOverwrite = await promptFileOverwrite(`gauntlet-${skill.action}`, skipPrompts);
+    if (!shouldOverwrite)
+      continue;
+    await fs26.rm(actionDir, { recursive: true, force: true });
+    await writeSkillFiles(actionDir, skill.content, references);
+    console.log(chalk10.green(`Updated ${path25.relative(projectRoot, skillPath)}`));
+  }
+}
+async function installHookWithChecksums(target, skipPrompts) {
+  const spec = buildHookSpec(target);
+  let existingConfig = {};
+  if (await exists(spec.config.filePath)) {
+    try {
+      existingConfig = JSON.parse(await fs26.readFile(spec.config.filePath, "utf-8"));
+    } catch {
+      existingConfig = {};
+    }
+  }
+  const existingHooks = existingConfig.hooks || {};
+  const existingEntries = Array.isArray(existingHooks[spec.config.hookKey]) ? existingHooks[spec.config.hookKey] : [];
+  const gauntletEntries = existingEntries.filter((e) => isGauntletHookEntry(e));
+  if (gauntletEntries.length === 0) {
+    await installHookWithLog(spec.config, spec.installedMsg, spec.existsMsg);
+    return;
   }
-  await writeConfigYml(targetDir, availableAdapters);
-  await fs25.writeFile(path24.join(targetDir, "reviews", "code-quality.yml"), `builtin: code-quality
-num_reviews: 1
+  const expectedEntry = spec.config.wrapInHooksArray ? { hooks: [spec.config.hookEntry] } : spec.config.hookEntry;
+  const expectedChecksum = computeExpectedHookChecksum([
+    expectedEntry
+  ]);
+  const actualChecksum = computeHookChecksum(existingEntries);
+  if (expectedChecksum === actualChecksum) {
+    console.log(chalk10.dim(spec.existsMsg));
+    return;
+  }
+  const shouldOverwrite = await promptHookOverwrite(spec.config.filePath, skipPrompts);
+  if (!shouldOverwrite) {
+    console.log(chalk10.dim(spec.existsMsg));
+    return;
+  }
+  const nonGauntletEntries = existingEntries.filter((e) => !isGauntletHookEntry(e));
+  const entryToAdd = spec.config.wrapInHooksArray ? { hooks: [spec.config.hookEntry] } : spec.config.hookEntry;
+  const newEntries = [...nonGauntletEntries, entryToAdd];
+  const merged = {
+    ...spec.config.baseConfig ?? {},
+    ...existingConfig,
+    hooks: {
+      ...existingHooks,
+      [spec.config.hookKey]: newEntries
+    }
+  };
+  await fs26.mkdir(path25.dirname(spec.config.filePath), { recursive: true });
+  await fs26.writeFile(spec.config.filePath, `${JSON.stringify(merged, null, 2)}
 `);
-  console.log(chalk9.green("Created .gauntlet/reviews/code-quality.yml"));
-  await copyStatusScript(targetDir);
+  console.log(chalk10.green(spec.installedMsg));
+}
+async function installExternalFiles(projectRoot, devAdapters, skipPrompts) {
+  await installSkillsWithChecksums(projectRoot, skipPrompts);
+  await copyStatusScript(path25.join(projectRoot, ".gauntlet"));
+  for (const adapter of devAdapters) {
+    if (!adapter.supportsHooks())
+      continue;
+    if (adapter.name !== "claude" && adapter.name !== "cursor")
+      continue;
+    for (const kind of ["stop", "start"]) {
+      const target = {
+        projectRoot,
+        variant: adapter.name,
+        kind
+      };
+      await installHookWithChecksums(target, skipPrompts);
+    }
+  }
+}
+function printPostInitInstructions(devCLINames) {
+  const hasNative = devCLINames.some((name) => NATIVE_CLIS.has(name));
+  const nonNativeNames = devCLINames.filter((name) => !NATIVE_CLIS.has(name));
+  const hasNonNative = nonNativeNames.length > 0;
+  console.log();
+  if (hasNative) {
+    console.log(chalk10.bold("To complete setup, run /gauntlet-setup in your CLI. This will guide you through configuring the static checks (unit tests, linters, etc.) that Agent Gauntlet will run."));
+  }
+  if (hasNonNative) {
+    console.log(chalk10.bold("To complete setup, reference the setup skill in your CLI: @.claude/skills/gauntlet-setup/SKILL.md. This will guide you through configuring the static checks (unit tests, linters, etc.) that Agent Gauntlet will run."));
+    console.log();
+    console.log("Available skills:");
+    for (const s of SKILL_DEFINITIONS) {
+      console.log(`  @.claude/skills/gauntlet-${s.action}/SKILL.md — ${s.description}`);
+    }
+  }
 }
-async function writeConfigYml(targetDir, adapters3) {
+async function writeConfigYml(targetDir, reviewCLINames) {
   const baseBranch = await detectBaseBranch();
-  const sortedAdapters = [...adapters3].sort((a, b) => CLI_PREFERENCE_ORDER.indexOf(a.name) - CLI_PREFERENCE_ORDER.indexOf(b.name));
-  const cliList = sortedAdapters.map((a) => `    - ${a.name}`).join(`
+  const cliList = reviewCLINames.map((name) => `    - ${name}`).join(`
 `);
-  const adapterSettings = buildAdapterSettingsBlock(adapters3);
+  const adapterSettings = buildAdapterSettingsBlock(reviewCLINames);
   const content = `# Ordered list of CLI agents to try for reviews
 cli:
   default_preference:
@@ -6989,14 +7294,14 @@ entry_points: []
 #     enabled: true
 #     format: text                # Options: text, json
 `;
-  await fs25.writeFile(path24.join(targetDir, "config.yml"), content);
-  console.log(chalk9.green("Created .gauntlet/config.yml"));
+  await fs26.writeFile(path25.join(targetDir, "config.yml"), content);
+  console.log(chalk10.green("Created .gauntlet/config.yml"));
 }
 async function addToGitignore(projectRoot, entry) {
-  const gitignorePath = path24.join(projectRoot, ".gitignore");
+  const gitignorePath = path25.join(projectRoot, ".gitignore");
   let content = "";
   if (await exists(gitignorePath)) {
-    content = await fs25.readFile(gitignorePath, "utf-8");
+    content = await fs26.readFile(gitignorePath, "utf-8");
     const lines = content.split(`
 `).map((l) => l.trim());
     if (lines.includes(entry)) {
@@ -7006,9 +7311,9 @@ async function addToGitignore(projectRoot, entry) {
   const suffix = content.length > 0 && !content.endsWith(`
 `) ? `
 ` : "";
-  await fs25.appendFile(gitignorePath, `${suffix}${entry}
+  await fs26.appendFile(gitignorePath, `${suffix}${entry}
 `);
-  console.log(chalk9.green(`Added ${entry} to .gitignore`));
+  console.log(chalk10.green(`Added ${entry} to .gitignore`));
 }
 function gitSilent(args, opts) {
   const { execFileSync } = __require("node:child_process");
@@ -7035,13 +7340,13 @@ async function detectBaseBranch() {
   }
   return "origin/main";
 }
-function buildAdapterSettingsBlock(adapters3) {
-  const items = adapters3.filter((a) => ADAPTER_CONFIG[a.name]);
+function buildAdapterSettingsBlock(adapterNames) {
+  const items = adapterNames.filter((name) => ADAPTER_CONFIG[name]);
   if (items.length === 0)
     return "";
-  const lines = items.map((a) => {
-    const c = ADAPTER_CONFIG[a.name];
-    return `    ${a.name}:
+  const lines = items.map((name) => {
+    const c = ADAPTER_CONFIG[name];
+    return `    ${name}:
       allow_tool_use: ${c?.allow_tool_use}
       thinking_budget: ${c?.thinking_budget}`;
   });
@@ -7057,233 +7362,171 @@ async function detectAvailableCLIs() {
   for (const adapter of allAdapters) {
     const isAvailable = await adapter.isAvailable();
     if (isAvailable) {
-      console.log(chalk9.green(`  ✓ ${adapter.name}`));
+      console.log(chalk10.green(`  ✓ ${adapter.name}`));
       available.push(adapter);
     } else {
-      console.log(chalk9.dim(`  ✗ ${adapter.name} (not installed)`));
+      console.log(chalk10.dim(`  ✗ ${adapter.name} (not installed)`));
     }
   }
   return available;
 }
 async function copyStatusScript(targetDir) {
-  const statusScriptDir = path24.join(targetDir, "skills", "gauntlet", "status", "scripts");
-  const statusScriptPath = path24.join(statusScriptDir, "status.ts");
-  await fs25.mkdir(statusScriptDir, { recursive: true });
+  const statusScriptDir = path25.join(targetDir, "scripts");
+  const statusScriptPath = path25.join(statusScriptDir, "status.ts");
+  await fs26.mkdir(statusScriptDir, { recursive: true });
   if (await exists(statusScriptPath))
     return;
-  const bundledScript = path24.join(path24.dirname(new URL(import.meta.url).pathname), "..", "scripts", "status.ts");
+  const bundledScript = path25.join(path25.dirname(new URL(import.meta.url).pathname), "..", "scripts", "status.ts");
   if (await exists(bundledScript)) {
-    await fs25.copyFile(bundledScript, statusScriptPath);
-    console.log(chalk9.green("Created .gauntlet/skills/gauntlet/status/scripts/status.ts"));
+    await fs26.copyFile(bundledScript, statusScriptPath);
+    console.log(chalk10.green("Created .gauntlet/scripts/status.ts"));
   } else {
-    console.log(chalk9.yellow("Warning: bundled status script not found; /gauntlet-status may fail."));
+    console.log(chalk10.yellow("Warning: bundled status script not found; /gauntlet-status may fail."));
   }
 }
-async function promptAndInstallCommands(options) {
-  const { projectRoot, commands } = options;
-  await installCommands({
-    level: "project",
-    agentNames: ["claude"],
-    projectRoot,
-    commands
+function hookHasCommand(entries, cmd) {
+  return entries.some((hook) => {
+    if (hook.command === cmd)
+      return true;
+    const nested = hook.hooks;
+    return Array.isArray(nested) && nested.some((h) => h.command === cmd);
   });
 }
-async function installSkill(skillDir, ctx, command) {
-  const actionDir = path24.join(skillDir, `gauntlet-${command.action}`);
-  const skillPath = path24.join(actionDir, "SKILL.md");
-  await fs25.mkdir(actionDir, { recursive: true });
-  if (await exists(skillPath)) {
-    const relPath2 = ctx.isUserLevel ? skillPath : path24.relative(ctx.projectRoot, skillPath);
-    console.log(chalk9.dim(`  claude: ${relPath2} already exists, skipping`));
-    return;
-  }
-  await fs25.writeFile(skillPath, command.content);
-  const relPath = ctx.isUserLevel ? skillPath : path24.relative(ctx.projectRoot, skillPath);
-  console.log(chalk9.green(`Created ${relPath}`));
-  if (command.references) {
-    const refsDir = path24.join(actionDir, "references");
-    await fs25.mkdir(refsDir, { recursive: true });
-    for (const [fileName, fileContent] of Object.entries(command.references)) {
-      const refPath = path24.join(refsDir, fileName);
-      if (await exists(refPath))
-        continue;
-      await fs25.writeFile(refPath, fileContent);
-      const refRelPath = ctx.isUserLevel ? refPath : path24.relative(ctx.projectRoot, refPath);
-      console.log(chalk9.green(`Created ${refRelPath}`));
-    }
-  }
-}
-async function installFlatCommand(adapter, commandDir, ctx, command) {
-  const name = command.action === "run" ? "gauntlet" : command.action;
-  const fileName = `${name}${adapter.getCommandExtension()}`;
-  const filePath = path24.join(commandDir, fileName);
+async function mergeHookConfig(opts) {
+  const {
+    filePath,
+    hookKey,
+    hookEntry,
+    deduplicateCmd,
+    wrapInHooksArray,
+    baseConfig
+  } = opts;
+  await fs26.mkdir(path25.dirname(filePath), { recursive: true });
+  let existing = {};
   if (await exists(filePath)) {
-    const relPath2 = ctx.isUserLevel ? filePath : path24.relative(ctx.projectRoot, filePath);
-    console.log(chalk9.dim(`  ${adapter.name}: ${relPath2} already exists, skipping`));
-    return;
-  }
-  const transformedContent = adapter.transformCommand(command.content);
-  await fs25.writeFile(filePath, transformedContent);
-  const relPath = ctx.isUserLevel ? filePath : path24.relative(ctx.projectRoot, filePath);
-  console.log(chalk9.green(`Created ${relPath}`));
-}
-async function installSkillsForAdapter(adapter, skillDir, ctx, commands) {
-  const resolvedSkillDir = ctx.isUserLevel ? skillDir : path24.join(ctx.projectRoot, skillDir);
-  try {
-    for (const command of commands) {
-      await installSkill(resolvedSkillDir, ctx, command);
-    }
-  } catch (error) {
-    const err = error;
-    console.log(chalk9.yellow(`  ${adapter.name}: Could not create skill - ${err.message}`));
-  }
-}
-async function installFlatCommandsForAdapter(adapter, commandDir, ctx, commands) {
-  const resolvedCommandDir = ctx.isUserLevel ? commandDir : path24.join(ctx.projectRoot, commandDir);
-  try {
-    await fs25.mkdir(resolvedCommandDir, { recursive: true });
-    const flatCommands = commands.filter((c) => c.action !== "check" && c.action !== "status" && !c.skillsOnly);
-    for (const command of flatCommands) {
-      await installFlatCommand(adapter, resolvedCommandDir, ctx, command);
-    }
-  } catch (error) {
-    const err = error;
-    console.log(chalk9.yellow(`  ${adapter.name}: Could not create command - ${err.message}`));
-  }
-}
-async function installCommands(options) {
-  const { level, agentNames, projectRoot, commands } = options;
-  if (level === "none" || agentNames.length === 0)
-    return;
-  console.log();
-  const allAdapters = getAllAdapters();
-  const isUserLevel = level === "user";
-  const ctx = { isUserLevel, projectRoot };
-  for (const agentName of agentNames) {
-    const adapter = allAdapters.find((a) => a.name === agentName);
-    if (!adapter)
-      continue;
-    const skillDir = isUserLevel ? adapter.getUserSkillDir() : adapter.getProjectSkillDir();
-    if (skillDir) {
-      await installSkillsForAdapter(adapter, skillDir, ctx, commands);
-      continue;
-    }
-    const commandDir = isUserLevel ? adapter.getUserCommandDir() : adapter.getProjectCommandDir();
-    if (!commandDir)
-      continue;
-    await installFlatCommandsForAdapter(adapter, commandDir, ctx, commands);
-  }
-}
-var STOP_HOOK_CONFIG = {
-  hooks: {
-    Stop: [
-      {
-        hooks: [
-          {
-            type: "command",
-            command: "agent-gauntlet stop-hook",
-            timeout: 300
-          }
-        ]
-      }
-    ]
-  }
-};
-var CURSOR_STOP_HOOK_CONFIG = {
-  version: 1,
-  hooks: {
-    stop: [
-      {
-        command: "agent-gauntlet stop-hook",
-        loop_limit: 10
-      }
-    ]
-  }
-};
-async function installStopHook(projectRoot) {
-  const claudeDir = path24.join(projectRoot, ".claude");
-  const settingsPath = path24.join(claudeDir, "settings.local.json");
-  await fs25.mkdir(claudeDir, { recursive: true });
-  let existingSettings = {};
-  if (await exists(settingsPath)) {
     try {
-      const content = await fs25.readFile(settingsPath, "utf-8");
-      existingSettings = JSON.parse(content);
+      existing = JSON.parse(await fs26.readFile(filePath, "utf-8"));
     } catch {
-      existingSettings = {};
+      existing = {};
     }
   }
-  const existingHooks = existingSettings.hooks || {};
-  const existingStopHooks = Array.isArray(existingHooks.Stop) ? existingHooks.Stop : [];
-  const hookExists = existingStopHooks.some((hook) => hook?.hooks?.some?.((h) => h?.command === "agent-gauntlet stop-hook"));
-  if (hookExists) {
-    console.log(chalk9.dim("Stop hook already installed"));
-    return;
+  const existingHooks = existing.hooks || {};
+  const existingEntries = Array.isArray(existingHooks[hookKey]) ? existingHooks[hookKey] : [];
+  if (hookHasCommand(existingEntries, deduplicateCmd)) {
+    return false;
   }
-  const newStopHooks = [...existingStopHooks, ...STOP_HOOK_CONFIG.hooks.Stop];
-  const mergedSettings = {
-    ...existingSettings,
+  const entryToAdd = wrapInHooksArray ? { hooks: [hookEntry] } : hookEntry;
+  const newEntries = [...existingEntries, entryToAdd];
+  const merged = {
+    ...baseConfig ?? {},
+    ...existing,
     hooks: {
       ...existingHooks,
-      Stop: newStopHooks
+      [hookKey]: newEntries
     }
   };
-  await fs25.writeFile(settingsPath, `${JSON.stringify(mergedSettings, null, 2)}
+  await fs26.writeFile(filePath, `${JSON.stringify(merged, null, 2)}
 `);
-  console.log(chalk9.green("Stop hook installed - gauntlet will run automatically when agent stops"));
+  return true;
 }
-async function installCursorStopHook(projectRoot) {
-  const cursorDir = path24.join(projectRoot, ".cursor");
-  const hooksPath = path24.join(cursorDir, "hooks.json");
-  await fs25.mkdir(cursorDir, { recursive: true });
-  let existingConfig = {};
-  if (await exists(hooksPath)) {
-    try {
-      const content = await fs25.readFile(hooksPath, "utf-8");
-      existingConfig = JSON.parse(content);
-    } catch {
-      existingConfig = {};
+var START_HOOK_ENTRY = {
+  matcher: "startup|resume|clear|compact",
+  hooks: [
+    {
+      type: "command",
+      command: "agent-gauntlet start-hook",
+      async: false
     }
-  }
-  const existingHooks = existingConfig.hooks || {};
-  const existingStopHooks = Array.isArray(existingHooks.stop) ? existingHooks.stop : [];
-  const hookExists = existingStopHooks.some((hook) => hook?.command === "agent-gauntlet stop-hook");
-  if (hookExists) {
-    console.log(chalk9.dim("Cursor stop hook already installed"));
-    return;
-  }
-  const newStopHooks = [
-    ...existingStopHooks,
-    ...CURSOR_STOP_HOOK_CONFIG.hooks.stop
-  ];
-  const mergedConfig = {
-    ...existingConfig,
-    version: existingConfig.version ?? CURSOR_STOP_HOOK_CONFIG.version,
-    hooks: {
-      ...existingHooks,
-      stop: newStopHooks
+  ]
+};
+var CURSOR_START_HOOK_ENTRY = {
+  command: "agent-gauntlet start-hook --adapter cursor"
+};
+var STOP_HOOK_ENTRY = {
+  type: "command",
+  command: "agent-gauntlet stop-hook",
+  timeout: 300
+};
+var CURSOR_STOP_HOOK_ENTRY = {
+  command: "agent-gauntlet stop-hook",
+  loop_limit: 10
+};
+async function installHookWithLog(config, installedMsg, existsMsg) {
+  const added = await mergeHookConfig(config);
+  console.log(added ? chalk10.green(installedMsg) : chalk10.dim(existsMsg));
+}
+function buildHookSpec(target) {
+  const { projectRoot, variant, kind } = target;
+  const isCursor = variant === "cursor";
+  const isStop = kind === "stop";
+  const hookConfigs = {
+    "claude-stop": {
+      dir: ".claude",
+      file: "settings.local.json",
+      hookKey: "Stop",
+      entry: STOP_HOOK_ENTRY,
+      cmd: "agent-gauntlet stop-hook",
+      wrap: true
+    },
+    "cursor-stop": {
+      dir: ".cursor",
+      file: "hooks.json",
+      hookKey: "stop",
+      entry: CURSOR_STOP_HOOK_ENTRY,
+      cmd: "agent-gauntlet stop-hook",
+      wrap: false
+    },
+    "claude-start": {
+      dir: ".claude",
+      file: "settings.local.json",
+      hookKey: "SessionStart",
+      entry: START_HOOK_ENTRY,
+      cmd: "agent-gauntlet start-hook",
+      wrap: false
+    },
+    "cursor-start": {
+      dir: ".cursor",
+      file: "hooks.json",
+      hookKey: "sessionStart",
+      entry: CURSOR_START_HOOK_ENTRY,
+      cmd: "agent-gauntlet start-hook --adapter cursor",
+      wrap: false
     }
   };
-  await fs25.writeFile(hooksPath, `${JSON.stringify(mergedConfig, null, 2)}
-`);
-  console.log(chalk9.green("Cursor stop hook installed - gauntlet will run automatically when agent stops"));
+  const key = `${variant}-${kind}`;
+  const cfg = hookConfigs[key];
+  const prefix = isCursor ? "Cursor " : "";
+  const kindLabel = isCursor ? kind : isStop ? "Stop" : "Start";
+  const purpose = isStop ? "gauntlet will run automatically when agent stops" : "agent will be primed with gauntlet instructions at session start";
+  return {
+    config: {
+      filePath: path25.join(projectRoot, cfg.dir, cfg.file),
+      hookKey: cfg.hookKey,
+      hookEntry: cfg.entry,
+      deduplicateCmd: cfg.cmd,
+      wrapInHooksArray: cfg.wrap,
+      ...isCursor ? { baseConfig: { version: 1 } } : {}
+    },
+    installedMsg: `${prefix}${kindLabel} hook installed - ${purpose}`,
+    existsMsg: `${prefix}${kindLabel} hook already installed`
+  };
 }
 // src/commands/list.ts
-import chalk10 from "chalk";
+import chalk11 from "chalk";
 function registerListCommand(program) {
   program.command("list").description("List configured gates").action(async () => {
     try {
       const config = await loadConfig();
-      console.log(chalk10.bold("Check Gates:"));
+      console.log(chalk11.bold("Check Gates:"));
       Object.values(config.checks).forEach((c) => {
         console.log(` - ${c.name}`);
       });
-      console.log(chalk10.bold(`
+      console.log(chalk11.bold(`
 Review Gates:`));
       Object.values(config.reviews).forEach((r) => {
         console.log(` - ${r.name} (Tools: ${r.cli_preference?.join(", ")})`);
       });
-      console.log(chalk10.bold(`
+      console.log(chalk11.bold(`
 Entry Points:`));
       config.project.entry_points.forEach((ep) => {
         console.log(` - ${ep.path}`);
@@ -7294,12 +7537,12 @@ Entry Points:`));
       });
     } catch (error) {
       const err = error;
-      console.error(chalk10.red("Error:"), err.message);
+      console.error(chalk11.red("Error:"), err.message);
     }
   });
 }
 // src/commands/review.ts
-import chalk11 from "chalk";
+import chalk12 from "chalk";
 function registerReviewCommand(program) {
   program.command("review").description("Run only applicable reviews for detected changes").option("-b, --base-branch <branch>", "Override base branch for change detection").option("-g, --gate <name>", "Run specific review gate only").option("-c, --commit <sha>", "Use diff for a specific commit").option("-u, --uncommitted", "Use diff for current uncommitted changes (staged and unstaged)").action(async (options) => {
     let config;
@@ -7321,7 +7564,7 @@ function registerReviewCommand(program) {
       const effectiveBaseBranch = options.baseBranch || (process.env.GITHUB_BASE_REF && (process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true") ? process.env.GITHUB_BASE_REF : null) || config.project.base_branch;
       const autoCleanResult = await shouldAutoClean(config.project.log_dir, effectiveBaseBranch);
       if (autoCleanResult.clean) {
-        console.log(chalk11.dim(`Auto-cleaning logs (${autoCleanResult.reason})...`));
+        console.log(chalk12.dim(`Auto-cleaning logs (${autoCleanResult.reason})...`));
         await debugLogger?.logClean("auto", autoCleanResult.reason || "unknown");
         await performAutoClean(config.project.log_dir, autoCleanResult);
       }
@@ -7337,7 +7580,7 @@ function registerReviewCommand(program) {
       let changeOptions;
       let passedSlotsMap;
       if (isRerun) {
-        console.log(chalk11.dim("Existing logs detected — running in verification mode..."));
+        console.log(chalk12.dim("Existing logs detected — running in verification mode..."));
         const { failures: previousFailures, passedSlots } = await findPreviousFailures(config.project.log_dir, options.gate, true);
         failuresMap = new Map;
         for (const gateFailure of previousFailures) {
@@ -7351,7 +7594,7 @@ function registerReviewCommand(program) {
         passedSlotsMap = passedSlots;
         if (previousFailures.length > 0) {
           const totalViolations = previousFailures.reduce((sum, gf) => sum + gf.adapterFailures.reduce((s, af) => s + af.violations.length, 0), 0);
-          console.log(chalk11.yellow(`Found ${previousFailures.length} gate(s) with ${totalViolations} previous violation(s)`));
+          console.log(chalk12.yellow(`Found ${previousFailures.length} gate(s) with ${totalViolations} previous violation(s)`));
         }
         changeOptions = { uncommitted: true };
         const executionState = await readExecutionState(config.project.log_dir);
@@ -7363,7 +7606,7 @@ function registerReviewCommand(program) {
         if (executionState) {
           const resolved = await resolveFixBase(executionState, effectiveBaseBranch);
           if (resolved.warning) {
-            console.log(chalk11.yellow(`Warning: ${resolved.warning}`));
+            console.log(chalk12.yellow(`Warning: ${resolved.warning}`));
           }
           if (resolved.fixBase) {
             changeOptions = { fixBase: resolved.fixBase };
@@ -7383,16 +7626,16 @@ function registerReviewCommand(program) {
       });
       const expander = new EntryPointExpander;
       const jobGen = new JobGenerator(config);
-      console.log(chalk11.dim("Detecting changes..."));
+      console.log(chalk12.dim("Detecting changes..."));
       const changes = await changeDetector.getChangedFiles();
       if (changes.length === 0) {
-        console.log(chalk11.green("No changes detected."));
+        console.log(chalk12.green("No changes detected."));
         await writeExecutionState(config.project.log_dir);
         await releaseLock(config.project.log_dir);
         restoreConsole?.restore();
         process.exit(0);
       }
-      console.log(chalk11.dim(`Found ${changes.length} changed files.`));
+      console.log(chalk12.dim(`Found ${changes.length} changed files.`));
       const entryPoints = await expander.expand(config.project.entry_points, changes);
       let jobs = jobGen.generateJobs(entryPoints);
       jobs = jobs.filter((j) => j.type === "review");
@@ -7400,13 +7643,13 @@ function registerReviewCommand(program) {
         jobs = jobs.filter((j) => j.name === options.gate);
       }
       if (jobs.length === 0) {
-        console.log(chalk11.yellow("No applicable reviews for these changes."));
+        console.log(chalk12.yellow("No applicable reviews for these changes."));
         await writeExecutionState(config.project.log_dir);
         await releaseLock(config.project.log_dir);
         restoreConsole?.restore();
         process.exit(0);
       }
-      console.log(chalk11.dim(`Running ${jobs.length} review(s)...`));
+      console.log(chalk12.dim(`Running ${jobs.length} review(s)...`));
       const runMode = isRerun ? "verification" : "full";
       await debugLogger?.logRunStart(runMode, changes.length, jobs.length);
       const reporter = new ConsoleReporter;
@@ -7429,15 +7672,15 @@ function registerReviewCommand(program) {
         await releaseLock(config.project.log_dir);
       }
       const err = error;
-      console.error(chalk11.red("Error:"), err.message);
+      console.error(chalk12.red("Error:"), err.message);
       restoreConsole?.restore();
       process.exit(1);
     }
   });
 }
 // src/core/run-executor.ts
-import fs26 from "node:fs/promises";
-import path25 from "node:path";
+import fs27 from "node:fs/promises";
+import path26 from "node:path";
 
 // src/core/diff-stats.ts
 import { execFile as execFile2 } from "node:child_process";
@@ -7746,25 +7989,25 @@ function isProcessAlive(pid) {
   }
 }
 async function tryAcquireLock(logDir) {
-  await fs26.mkdir(logDir, { recursive: true });
-  const lockPath = path25.resolve(logDir, LOCK_FILENAME2);
+  await fs27.mkdir(logDir, { recursive: true });
+  const lockPath = path26.resolve(logDir, LOCK_FILENAME2);
   try {
-    await fs26.writeFile(lockPath, String(process.pid), { flag: "wx" });
+    await fs27.writeFile(lockPath, String(process.pid), { flag: "wx" });
     return true;
   } catch (err) {
     if (typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST") {
       try {
-        const lockContent = await fs26.readFile(lockPath, "utf-8");
+        const lockContent = await fs27.readFile(lockPath, "utf-8");
         const lockPid = parseInt(lockContent.trim(), 10);
-        const lockStat = await fs26.stat(lockPath);
+        const lockStat = await fs27.stat(lockPath);
         const lockAgeMs = Date.now() - lockStat.mtimeMs;
         const pidValid = !Number.isNaN(lockPid);
         const pidDead = pidValid && !isProcessAlive(lockPid);
         const lockStale = !pidValid && lockAgeMs > STALE_LOCK_MS;
         if (pidDead || lockStale) {
-          await fs26.rm(lockPath, { force: true });
+          await fs27.rm(lockPath, { force: true });
           try {
-            await fs26.writeFile(lockPath, String(process.pid), {
+            await fs27.writeFile(lockPath, String(process.pid), {
               flag: "wx"
             });
             return true;
@@ -7780,7 +8023,7 @@ async function tryAcquireLock(logDir) {
 }
 async function findLatestConsoleLog(logDir) {
   try {
-    const files = await fs26.readdir(logDir);
+    const files = await fs27.readdir(logDir);
     let maxNum = -1;
     let latestFile = null;
     for (const file of files) {
@@ -7796,7 +8039,7 @@ async function findLatestConsoleLog(logDir) {
         }
       }
     }
-    return latestFile ? path25.join(logDir, latestFile) : null;
+    return latestFile ? path26.join(logDir, latestFile) : null;
   } catch {
     return null;
   }
@@ -7828,7 +8071,7 @@ var statusMessages = {
   loop_detected: "Loop detected — rapid blocks overridden.",
   interval_not_elapsed: "Run interval not elapsed.",
   invalid_input: "Invalid input.",
-  stop_hook_disabled: "Stop hook is disabled via configuration.",
+  stop_hook_disabled: "",
   pr_push_required: "Gates passed — PR needs to be created/updated.",
   ci_pending: "CI checks still running.",
   ci_failed: "CI checks failed or review changes requested.",
@@ -8076,17 +8319,90 @@ function registerRunCommand(program) {
     process.exit(isSuccessStatus(result.status) ? 0 : 1);
   });
 }
+// src/commands/start-hook.ts
+import fs28 from "node:fs/promises";
+import path27 from "node:path";
+import YAML7 from "yaml";
+var START_HOOK_MESSAGE = `<IMPORTANT>
+This project uses Agent Gauntlet for automated quality verification.
+
+BEFORE reporting any coding task as complete, you MUST run /gauntlet-run
+to verify your changes pass all quality gates.
+
+Run /gauntlet-run when ALL of these are true:
+  1. You completed a coding task (implemented a feature, fixed a bug,
+     refactored code, or made other substantive code changes)
+  2. You are about to report the work as done, complete, or fixed
+
+Do NOT run /gauntlet-run when:
+  - You only answered questions, explored code, or ran read-only commands
+  - You are in the middle of a multi-step task (run it at the end, not
+    after every individual change)
+  - The user explicitly asked to skip verification
+
+If you are unsure whether to run it, run it. False positives (running
+unnecessarily) are far less costly than false negatives (skipping
+verification on code that needed it).
+</IMPORTANT>`;
+function formatClaudeOutput(message) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: message
+    }
+  });
+}
+function formatCursorOutput(message) {
+  return message;
+}
+function isValidConfig(content) {
+  const trimmed = content.trim();
+  if (!trimmed) {
+    return false;
+  }
+  try {
+    const parsed = YAML7.parse(trimmed);
+    return parsed != null && typeof parsed === "object";
+  } catch {
+    return false;
+  }
+}
+function registerStartHookCommand(program) {
+  program.command("start-hook").description("Session start hook - primes agent with gauntlet verification instructions").option("--adapter <adapter>", "Output format: claude or cursor", "claude").action(async (options) => {
+    const configPath = path27.join(process.cwd(), ".gauntlet", "config.yml");
+    try {
+      const content = await fs28.readFile(configPath, "utf-8");
+      if (!isValidConfig(content)) {
+        return;
+      }
+    } catch {
+      return;
+    }
+    const adapter = options.adapter;
+    try {
+      const cwd = process.cwd();
+      const logDir = path27.join(cwd, await getLogDir(cwd));
+      const globalConfig = await loadGlobalConfig();
+      const projectDebugLogConfig = await getDebugLogConfig(cwd);
+      const debugLogConfig = mergeDebugLogConfig(projectDebugLogConfig, globalConfig.debug_log);
+      const debugLogger = new DebugLogger(logDir, debugLogConfig);
+      await debugLogger.logStartHook(adapter);
+    } catch {}
+    const output = adapter === "cursor" ? formatCursorOutput(START_HOOK_MESSAGE) : formatClaudeOutput(START_HOOK_MESSAGE);
+    console.log(output);
+  });
+}
 // src/commands/validate.ts
-import chalk12 from "chalk";
+import chalk13 from "chalk";
 function registerValidateCommand(program) {
   program.command("validate").description("Validate .gauntlet/ config files against schemas").action(async () => {
     try {
       await loadConfig();
-      console.log(chalk12.green("All config files are valid."));
+      console.log(chalk13.green("All config files are valid."));
       process.exitCode = 0;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      console.error(chalk12.red("Validation failed:"), message);
+      console.error(chalk13.red("Validation failed:"), message);
       process.exitCode = 1;
     }
   });
@@ -8369,6 +8685,7 @@ registerListCommand(program);
 registerHealthCommand(program);
 registerInitCommand(program);
 registerValidateCommand(program);
+registerStartHookCommand(program);
 registerStopHookCommand(program);
 registerWaitCICommand(program);
 registerHelpCommand(program);
@@ -8377,4 +8694,4 @@ if (process.argv.length < 3) {
 }
 program.parse(process.argv);
 
-//# debugId=61E76D84AB3F58F264756E2164756E21
+//# debugId=27272999504866CC64756E2164756E21