feat: add model-specific instructions

Author: ammar-agent

docs/instruction-files.md

@@ -62,6 +62,32 @@ 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
+Anthropic's Claude Sonnet family tends to wax poetic—answer in two sentences max and focus on code changes.
+
+## Model: /openai:.*codex/i
+OpenAI's GPT-5.1 Codex models already respond tersely, so no additional instruction is required.
+```
+
+The second section documents that OpenAI models (as of `openai:gpt-5.1-codex`) don't need extra prompting, while Sonnet benefits from an explicit "be terse" reminder.
+
+
 ## 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,73 @@ 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";
 
@@ -71,14 +71,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,6 +103,15 @@ 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)}`;
 
@@ -113,6 +124,13 @@ export async function buildSystemMessage(
     systemMessage += `\n\n<${tag}>\n${modeContent}\n</${tag}>`;
   }
 
+  if (modelContent && modelString) {
+    const sanitizedModelValue =
+      modelString.toLowerCase().replace(/[^a-z0-9_-]/gi, "-") || "model";
+    const modelTag = `model-${sanitizedModelValue}`;
+    systemMessage += `\n\n<${modelTag}>\n${modelContent}\n</${modelTag}>`;
+  }
+
   if (additionalSystemInstructions) {
     systemMessage += `\n\n<additional-instructions>\n${additionalSystemInstructions}\n</additional-instructions>`;
   }

src/node/utils/main/markdown.ts

@@ -49,3 +49,75 @@ export function extractModeSection(markdown: string, mode: string): string | nul
 
   return null;
 }
+
+/**
+ * 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 md = new MarkdownIt({ html: false, linkify: false, typographer: false });
+  const tokens = md.parse(markdown, {});
+  const lines = markdown.split(/\r?\n/);
+  const headingPattern = /^model:\s*(.+)$/i;
+
+  const compileRegex = (pattern: string): RegExp | null => {
+    const trimmed = pattern.trim();
+    if (!trimmed) return null;
+
+    // Allow optional /pattern/flags syntax; default to case-insensitive matching otherwise
+    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;
+    }
+  };
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.type !== "heading_open") continue;
+
+    const level = Number(token.tag?.replace(/^h/, "")) || 1;
+    const inline = tokens[i + 1];
+    if (inline?.type !== "inline") continue;
+
+    const match = headingPattern.exec((inline.content || "").trim());
+    if (!match) continue;
+
+    const regex = compileRegex(match[1] ?? "");
+    if (!regex) continue;
+    if (!regex.test(modelId)) continue;
+
+    const headingEndLine = inline.map?.[1] ?? token.map?.[1] ?? (token.map?.[0] ?? 0) + 1;
+
+    let endLine = lines.length;
+    for (let j = i + 1; j < tokens.length; j++) {
+      const nextToken = tokens[j];
+      if (nextToken.type === "heading_open") {
+        const nextLevel = Number(nextToken.tag?.replace(/^h/, "")) || 1;
+        if (nextLevel <= level) {
+          endLine = nextToken.map?.[0] ?? endLine;
+          break;
+        }
+      }
+    }
+
+    const slice = lines.slice(headingEndLine, endLine).join("\n").trim();
+    return slice.length > 0 ? slice : null;
+  }
+
+  return null;
+}