🤖 feat: add model-specific instructions (#639)

## Summary
- add model-scoped section extraction that mirrors the existing
mode-specific behavior
- thread the active model id through system message construction so
matching content is emitted
- document the Model: heading convention and cover it with unit tests

## Testing
- bun test v1.3.1 (89fa0f34)
- Generated version.ts: v0.5.1-90-gfe3b2519 (fe3b251) at
2025-11-16T21:43:17Z
[0] bun run node_modules/@typescript/native-preview/bin/tsgo.js --noEmit
exited with code 0
[1] bun run node_modules/@typescript/native-preview/bin/tsgo.js --noEmit
-p tsconfig.main.json exited with code 0

_Generated with _

---------

Co-authored-by: root <root@ovh-1.tailc2a514.ts.net>
Co-authored-by: Ammar Bandukwala <ammar@ammar.io>

Author: 3 people

docs/instruction-files.md

@@ -62,6 +62,31 @@ When compacting conversation history:
 
 Customizing the `compact` mode is particularly useful for controlling what information is preserved during automatic history compaction.
 
+## Model Prompts
+
+Similar to modes, mux reads headings titled `Model: <regex>` to scope instructions to specific models or families. The `<regex>` is matched against the full model identifier (for example, `openai:gpt-5.1-codex`).
+
+Rules:
+
+- Workspace instructions are evaluated before global instructions; the first matching section wins.
+- Regexes are case-insensitive by default. Use `/pattern/flags` syntax to opt into custom flags (e.g., `/openai:.*codex/i`).
+- Invalid regex patterns are ignored instead of breaking the parse.
+- Only the content under the first matching heading is injected.
+
+<!-- Developers: See extractModelSection in src/node/utils/main/markdown.ts for the implementation. -->
+
+Example:
+
+```markdown
+## Model: sonnet
+
+Be terse and to the point.
+
+## Model: openai:.\*codex
+
+Use status reporting tools every few minutes.
+```
+
 ## Practical layout
 
 ```

src/node/services/aiService.ts

@@ -655,7 +655,8 @@ export class AIService extends EventEmitter {
         runtime,
         workspacePath,
         mode,
-        additionalSystemInstructions
+        additionalSystemInstructions,
+        modelString
       );
 
       // Count system message tokens for cost tracking

src/node/services/systemMessage.test.ts

@@ -203,4 +203,74 @@ Special mode instructions.
     expect(systemMessage).toContain("Special mode instructions");
     expect(systemMessage).toContain("</my-special_mode->");
   });
+
+  test("includes model-specific section when regex matches active model", async () => {
+    await fs.writeFile(
+      path.join(projectDir, "AGENTS.md"),
+      `# Instructions
+## Model: sonnet
+Respond to Sonnet tickets in two sentences max.
+`
+    );
+
+    const metadata: WorkspaceMetadata = {
+      id: "test-workspace",
+      name: "test-workspace",
+      projectName: "test-project",
+      projectPath: projectDir,
+      runtimeConfig: DEFAULT_RUNTIME_CONFIG,
+    };
+
+    const systemMessage = await buildSystemMessage(
+      metadata,
+      runtime,
+      workspaceDir,
+      undefined,
+      undefined,
+      "anthropic:claude-3.5-sonnet"
+    );
+
+    expect(systemMessage).toContain("<model-anthropic-claude-3-5-sonnet>");
+    expect(systemMessage).toContain("Respond to Sonnet tickets in two sentences max.");
+    expect(systemMessage).toContain("</model-anthropic-claude-3-5-sonnet>");
+  });
+
+  test("falls back to global model section when project lacks a match", async () => {
+    await fs.writeFile(
+      path.join(globalDir, "AGENTS.md"),
+      `# Global Instructions
+## Model: /openai:.*codex/i
+OpenAI's GPT-5.1 Codex models already default to terse replies.
+`
+    );
+
+    await fs.writeFile(
+      path.join(projectDir, "AGENTS.md"),
+      `# Project Instructions
+General details only.
+`
+    );
+
+    const metadata: WorkspaceMetadata = {
+      id: "test-workspace",
+      name: "test-workspace",
+      projectName: "test-project",
+      projectPath: projectDir,
+      runtimeConfig: DEFAULT_RUNTIME_CONFIG,
+    };
+
+    const systemMessage = await buildSystemMessage(
+      metadata,
+      runtime,
+      workspaceDir,
+      undefined,
+      undefined,
+      "openai:gpt-5.1-codex"
+    );
+
+    expect(systemMessage).toContain("<model-openai-gpt-5-1-codex>");
+    expect(systemMessage).toContain(
+      "OpenAI's GPT-5.1 Codex models already default to terse replies."
+    );
+  });
 });

src/node/services/systemMessage.ts

@@ -3,7 +3,7 @@ import {
   readInstructionSet,
   readInstructionSetFromRuntime,
 } from "@/node/utils/main/instructionFiles";
-import { extractModeSection } from "@/node/utils/main/markdown";
+import { extractModeSection, extractModelSection } from "@/node/utils/main/markdown";
 import type { Runtime } from "@/node/runtime/Runtime";
 import { getMuxHome } from "@/common/constants/paths";
 
@@ -12,6 +12,24 @@ import { getMuxHome } from "@/common/constants/paths";
 // The PRELUDE is intentionally minimal to not conflict with the user's instructions.
 // mux is designed to be model agnostic, and models have shown large inconsistency in how they
 // follow instructions.
+
+function sanitizeSectionTag(value: string | undefined, fallback: string): string {
+  const normalized = (value ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/gi, "-")
+    .replace(/-+/g, "-");
+  return normalized.length > 0 ? normalized : fallback;
+}
+
+function buildTaggedSection(
+  content: string | null,
+  rawTagValue: string | undefined,
+  fallback: string
+): string {
+  if (!content) return "";
+  const tag = sanitizeSectionTag(rawTagValue, fallback);
+  return `\n\n<${tag}>\n${content}\n</${tag}>`;
+}
 const PRELUDE = ` 
 <prelude>
 You are a coding agent.
@@ -71,14 +89,16 @@ function getSystemDirectory(): string {
  * @param workspacePath - Workspace directory path
  * @param mode - Optional mode name (e.g., "plan", "exec")
  * @param additionalSystemInstructions - Optional instructions appended last
+ * @param modelString - Active model identifier used for Model-specific sections
  * @throws Error if metadata or workspacePath invalid
  */
 export async function buildSystemMessage(
   metadata: WorkspaceMetadata,
   runtime: Runtime,
   workspacePath: string,
   mode?: string,
-  additionalSystemInstructions?: string
+  additionalSystemInstructions?: string,
+  modelString?: string
 ): Promise<string> {
   if (!metadata) throw new Error("Invalid workspace metadata: metadata is required");
   if (!workspacePath) throw new Error("Invalid workspace path: workspacePath is required");
@@ -101,16 +121,32 @@ export async function buildSystemMessage(
       null;
   }
 
+  // Extract model-specific section based on active model identifier (context first)
+  let modelContent: string | null = null;
+  if (modelString) {
+    modelContent =
+      (contextInstructions && extractModelSection(contextInstructions, modelString)) ??
+      (globalInstructions && extractModelSection(globalInstructions, modelString)) ??
+      null;
+  }
+
   // Build system message
   let systemMessage = `${PRELUDE.trim()}\n\n${buildEnvironmentContext(workspacePath)}`;
 
   if (customInstructions) {
     systemMessage += `\n<custom-instructions>\n${customInstructions}\n</custom-instructions>`;
   }
 
-  if (modeContent) {
-    const tag = (mode ?? "mode").toLowerCase().replace(/[^a-z0-9_-]/gi, "-");
-    systemMessage += `\n\n<${tag}>\n${modeContent}\n</${tag}>`;
+  const modeSection = buildTaggedSection(modeContent, mode, "mode");
+  if (modeSection) {
+    systemMessage += modeSection;
+  }
+
+  if (modelContent && modelString) {
+    const modelSection = buildTaggedSection(modelContent, `model-${modelString}`, "model");
+    if (modelSection) {
+      systemMessage += modelSection;
+    }
   }
 
   if (additionalSystemInstructions) {

src/node/utils/main/markdown.ts

@@ -1,43 +1,34 @@
 import MarkdownIt from "markdown-it";
 
-/**
- * Extract the content under a heading titled "Mode: <mode>" (case-insensitive).
- * - Matches any heading level (#..######)
- * - Returns raw markdown content between this heading and the next heading
- *   of the same or higher level in the same document
- * - If multiple sections match, the first one wins
- * - The heading line itself is excluded from the returned content
- */
-export function extractModeSection(markdown: string, mode: string): string | null {
-  if (!markdown || !mode) return null;
+type HeadingMatcher = (headingText: string, level: number) => boolean;
+
+function extractSectionByHeading(markdown: string, headingMatcher: HeadingMatcher): string | null {
+  if (!markdown) return null;
 
   const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
   const tokens = md.parse(markdown, {});
   const lines = markdown.split(/\r?\n/);
-  const target = `mode: ${mode}`.toLowerCase();
 
   for (let i = 0; i < tokens.length; i++) {
-    const t = tokens[i];
-    if (t.type !== "heading_open") continue;
+    const token = tokens[i];
+    if (token.type !== "heading_open") continue;
 
-    const level = Number(t.tag?.replace(/^h/, "")) || 1;
+    const level = Number(token.tag?.replace(/^h/, "")) || 1;
     const inline = tokens[i + 1];
     if (inline?.type !== "inline") continue;
 
-    const text = (inline.content || "").trim().toLowerCase();
-    if (text !== target) continue;
+    const headingText = (inline.content || "").trim();
+    if (!headingMatcher(headingText, level)) continue;
 
-    // Start content after the heading block ends
-    const headingEndLine = inline.map?.[1] ?? t.map?.[1] ?? (t.map?.[0] ?? 0) + 1;
+    const headingEndLine = inline.map?.[1] ?? token.map?.[1] ?? (token.map?.[0] ?? 0) + 1;
 
-    // Find the next heading of same or higher level to bound the section
-    let endLine = lines.length; // exclusive
+    let endLine = lines.length;
     for (let j = i + 1; j < tokens.length; j++) {
-      const tt = tokens[j];
-      if (tt.type === "heading_open") {
-        const nextLevel = Number(tt.tag?.replace(/^h/, "")) || 1;
+      const nextToken = tokens[j];
+      if (nextToken.type === "heading_open") {
+        const nextLevel = Number(nextToken.tag?.replace(/^h/, "")) || 1;
         if (nextLevel <= level) {
-          endLine = tt.map?.[0] ?? endLine;
+          endLine = nextToken.map?.[0] ?? endLine;
           break;
         }
       }
@@ -49,3 +40,56 @@ export function extractModeSection(markdown: string, mode: string): string | nul
 
   return null;
 }
+
+/**
+ * Extract the content under a heading titled "Mode: <mode>" (case-insensitive).
+ */
+export function extractModeSection(markdown: string, mode: string): string | null {
+  if (!markdown || !mode) return null;
+
+  const expectedHeading = `mode: ${mode}`.toLowerCase();
+  return extractSectionByHeading(
+    markdown,
+    (headingText) => headingText.toLowerCase() === expectedHeading
+  );
+}
+
+/**
+ * Extract the first section whose heading matches "Model: <regex>" and whose regex matches
+ * the provided model identifier. Matching is case-insensitive by default unless the regex
+ * heading explicitly specifies flags via /pattern/flags syntax.
+ */
+export function extractModelSection(markdown: string, modelId: string): string | null {
+  if (!markdown || !modelId) return null;
+
+  const headingPattern = /^model:\s*(.+)$/i;
+
+  const compileRegex = (pattern: string): RegExp | null => {
+    const trimmed = pattern.trim();
+    if (!trimmed) return null;
+
+    if (trimmed.startsWith("/") && trimmed.lastIndexOf("/") > 0) {
+      const lastSlash = trimmed.lastIndexOf("/");
+      const source = trimmed.slice(1, lastSlash);
+      const flags = trimmed.slice(lastSlash + 1);
+      try {
+        return new RegExp(source, flags || undefined);
+      } catch {
+        return null;
+      }
+    }
+
+    try {
+      return new RegExp(trimmed, "i");
+    } catch {
+      return null;
+    }
+  };
+
+  return extractSectionByHeading(markdown, (headingText) => {
+    const match = headingPattern.exec(headingText);
+    if (!match) return false;
+    const regex = compileRegex(match[1] ?? "");
+    return Boolean(regex?.test(modelId));
+  });
+}