feat(guardrails): enforce _max_prompt_tokens; adhoc engines match the ladder

Both found by executing the field guide's user stories against the CLI:

_max_prompt_tokens was declared in types and recommended by docs but
enforced nowhere. It now blocks execution before any engine turn when the
fully resolved prompt exceeds the limit, with a PROMPT_TOKEN_LIMIT error
pointing at --_context.

Ad-hoc md.COMMAND aliases were limited to a stale v2 list (no pi,
cursor-agent, agy, and no custom engines). Detection now accepts any
registered adapter or PATH binary, mirroring the filename rung, and the
name pattern allows hyphens (md.cursor-agent).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: johnlindquist

src/adhoc-command.ts

@@ -12,18 +12,36 @@
  */
 
 import { basename } from "path";
+import { hasAdapter } from "./adapters";
 
-/** Supported command aliases */
+/**
+ * Built-in engines always accepted as md.COMMAND aliases. Beyond this list,
+ * any registered adapter or PATH binary works, mirroring the filename rung
+ * of the engine ladder (md.echo, md.pi, md.agy all resolve).
+ */
 export const SUPPORTED_COMMANDS = [
   "claude",
   "codex",
   "gemini",
   "copilot",
   "droid",
   "opencode",
+  "pi",
+  "cursor-agent",
+  "agy",
 ] as const;
 
-export type SupportedCommand = typeof SUPPORTED_COMMANDS[number];
+export type SupportedCommand = string;
+
+function isRunnableEngine(cmd: string): boolean {
+  if ((SUPPORTED_COMMANDS as readonly string[]).includes(cmd)) return true;
+  if (hasAdapter(cmd)) return true;
+  try {
+    return Bun.which(cmd) !== null;
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Result of parsing an ad-hoc command invocation
@@ -85,19 +103,19 @@ function parseAdhocFromName(name: string): { isAdhoc: boolean; command?: Support
   const cleanName = name.replace(/\.(ts|js|mjs|cjs)$/, "");
 
   // Pattern: md.i.COMMAND (interactive mode)
-  const interactiveMatch = cleanName.match(/^md\.i\.([a-z]+)$/i);
+  const interactiveMatch = cleanName.match(/^md\.i\.([a-z][a-z0-9-]*)$/i);
   if (interactiveMatch) {
-    const cmd = interactiveMatch[1]?.toLowerCase() as SupportedCommand;
-    if (SUPPORTED_COMMANDS.includes(cmd)) {
+    const cmd = interactiveMatch[1]!.toLowerCase();
+    if (isRunnableEngine(cmd)) {
       return { isAdhoc: true, command: cmd, interactive: true };
     }
   }
 
   // Pattern: md.COMMAND
-  const match = cleanName.match(/^md\.([a-z]+)$/i);
+  const match = cleanName.match(/^md\.([a-z][a-z0-9-]*)$/i);
   if (match) {
-    const cmd = match[1]?.toLowerCase() as SupportedCommand;
-    if (SUPPORTED_COMMANDS.includes(cmd)) {
+    const cmd = match[1]!.toLowerCase();
+    if (isRunnableEngine(cmd)) {
       return { isAdhoc: true, command: cmd, interactive: false };
     }
   }

src/cli-runner.ts

@@ -696,6 +696,20 @@ export class CliRunner {
     }
 
     // Edit before execute
+    // Hard prompt budget: _max_prompt_tokens blocks execution BEFORE any
+    // engine turn is spent when the fully resolved prompt exceeds the limit.
+    const maxPromptTokens = frontmatter._max_prompt_tokens;
+    if (typeof maxPromptTokens === "number" && maxPromptTokens > 0) {
+      const promptTokens = await countTokensAsync(finalBody);
+      if (promptTokens > maxPromptTokens) {
+        throw new MarkdownAgentError(
+          `Prompt is ~${promptTokens.toLocaleString()} tokens, over the _max_prompt_tokens limit of ${maxPromptTokens.toLocaleString()}. ` +
+            `Narrow the imports, raise the limit, or inspect with --_context.`,
+          { errorCode: "PROMPT_TOKEN_LIMIT", exitCode: 1 }
+        );
+      }
+    }
+
     let promptToRun = finalBody;
     if (parsed.editFlag && !parsed.jsonMode) {
       const editResult = await editPrompt(finalBody);
@@ -982,6 +996,20 @@ export class CliRunner {
     }
 
     // Edit before execute
+    // Hard prompt budget: _max_prompt_tokens blocks execution BEFORE any
+    // engine turn is spent when the fully resolved prompt exceeds the limit.
+    const maxPromptTokens = frontmatter._max_prompt_tokens;
+    if (typeof maxPromptTokens === "number" && maxPromptTokens > 0) {
+      const promptTokens = await countTokensAsync(finalBody);
+      if (promptTokens > maxPromptTokens) {
+        throw new MarkdownAgentError(
+          `Prompt is ~${promptTokens.toLocaleString()} tokens, over the _max_prompt_tokens limit of ${maxPromptTokens.toLocaleString()}. ` +
+            `Narrow the imports, raise the limit, or inspect with --_context.`,
+          { errorCode: "PROMPT_TOKEN_LIMIT", exitCode: 1 }
+        );
+      }
+    }
+
     let promptToRun = finalBody;
     if (parsed.editFlag && !parsed.jsonMode) {
       const editResult = await editPrompt(finalBody);