chapterhouse 0.5.2 → 0.7.0

package/dist/api/server.test.js

@@ -124,6 +124,22 @@ function readProjectRegistryRows(testRoot) {
         db.close();
     }
 }
+function getAgentFilePath(testRoot, slug) {
+    return join(testRoot, ".chapterhouse", "agents", `${slug}.agent.md`);
+}
+function writeAgentFile(testRoot, slug, content) {
+    mkdirSync(join(testRoot, ".chapterhouse", "agents"), { recursive: true });
+    writeFileSync(getAgentFilePath(testRoot, slug), content, "utf-8");
+}
+function markBundledAgent(testRoot, slug, hash = "bundled-hash") {
+    const db = new Database(getProjectDbPath(testRoot));
+    try {
+        db.prepare(`INSERT OR REPLACE INTO max_state (key, value) VALUES (?, ?)`).run(`bundled_agent_hash:${slug}.agent.md`, hash);
+    }
+    finally {
+        db.close();
+    }
+}
 function setMemoryActiveScope(testRoot, slug) {
     const db = new Database(getProjectDbPath(testRoot));
     try {
@@ -192,6 +208,15 @@ async function withStartedServer(run, extraEnv = {}, timeoutMs = DEFAULT_API_SER
         rmSync(testRoot, { recursive: true, force: true });
     }
 }
+test("agent edits require a team lead when Entra auth is enabled", async () => {
+    const accessModule = await import("./agent-edit-access.js");
+    assert.equal(typeof accessModule.assertAgentEditAccess, "function", "assertAgentEditAccess should be exported");
+    const assertAgentEditAccess = accessModule.assertAgentEditAccess;
+    assert.doesNotThrow(() => assertAgentEditAccess({ entraAuthEnabled: false }, { role: "engineer" }));
+    assert.throws(() => assertAgentEditAccess({ entraAuthEnabled: true }, { role: "engineer" }), /Admin access required/);
+    assert.throws(() => assertAgentEditAccess({ entraAuthEnabled: true }), /Admin access required/);
+    assert.doesNotThrow(() => assertAgentEditAccess({ entraAuthEnabled: true }, { role: "team-lead" }));
+});
 test("server routes expose bootstrap and public config without auth", async () => {
     await withStartedServer(async ({ baseUrl }) => {
         const bootstrap = await fetch(`${baseUrl}/api/bootstrap`);
@@ -222,6 +247,312 @@ test("server channels route returns chapterhouse plus persistent agents in chann
         ]);
     });
 });
+test("server agents routes return source-aware charter summaries and details", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader, testRoot }) => {
+        writeAgentFile(testRoot, "alpha-custom", [
+            "---",
+            "name: Alpha Custom",
+            "description: First custom charter",
+            "model: gpt-5.4",
+            "scope: frontend",
+            "skills:",
+            "  - ui-copy",
+            "  - wireframes",
+            "---",
+            "",
+            "You are Alpha Custom.",
+        ].join("\n"));
+        writeAgentFile(testRoot, "zulu-custom", [
+            "---",
+            "name: Zulu Custom",
+            "description: Last custom charter",
+            "model: claude-sonnet-4.6",
+            "persistent: true",
+            "---",
+            "",
+            "You are Zulu Custom.",
+        ].join("\n"));
+        markBundledAgent(testRoot, "designer");
+        const listResponse = await fetch(`${baseUrl}/api/agents`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(listResponse.status, 200);
+        const agents = await listResponse.json();
+        const firstCustomIndex = agents.findIndex((agent) => agent.type === "custom");
+        assert.notEqual(firstCustomIndex, -1);
+        assert.ok(agents.slice(0, firstCustomIndex).every((agent) => agent.type === "builtin"));
+        const customAgents = agents.filter((agent) => agent.type === "custom");
+        assert.deepEqual(customAgents.map((agent) => agent.name), ["Alpha Custom", "Zulu Custom"]);
+        const designer = agents.find((agent) => agent.slug === "designer");
+        assert.ok(designer);
+        assert.equal(designer.type, "builtin");
+        assert.equal(typeof designer.lastEdited, "string");
+        const alpha = agents.find((agent) => agent.slug === "alpha-custom");
+        assert.deepEqual(alpha, {
+            name: "Alpha Custom",
+            slug: "alpha-custom",
+            description: "First custom charter",
+            model: "gpt-5.4",
+            scope: "frontend",
+            type: "custom",
+            lastEdited: alpha?.lastEdited ?? null,
+        });
+        assert.equal(typeof alpha?.lastEdited, "string");
+        const detailResponse = await fetch(`${baseUrl}/api/agents/${encodeURIComponent("alpha-custom")}`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(detailResponse.status, 200);
+        assert.deepEqual(await detailResponse.json(), {
+            name: "Alpha Custom",
+            slug: "alpha-custom",
+            description: "First custom charter",
+            model: "gpt-5.4",
+            scope: "frontend",
+            persistent: false,
+            skills: ["ui-copy", "wireframes"],
+            type: "custom",
+            editable: true,
+            systemPrompt: "You are Alpha Custom.",
+        });
+        const builtinDetailResponse = await fetch(`${baseUrl}/api/agents/${encodeURIComponent("designer")}`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(builtinDetailResponse.status, 200);
+        const builtinDetail = await builtinDetailResponse.json();
+        assert.equal(builtinDetail.slug, "designer");
+        assert.equal(builtinDetail.type, "builtin");
+        assert.equal(builtinDetail.editable, false);
+        assert.equal(typeof builtinDetail.systemPrompt, "string");
+        assert.ok(builtinDetail.systemPrompt.length > 0);
+        const missingResponse = await fetch(`${baseUrl}/api/agents/${encodeURIComponent("missing-agent")}`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(missingResponse.status, 404);
+        assert.deepEqual(await missingResponse.json(), { error: "Agent 'missing-agent' not found" });
+    });
+});
+test("server rejects invalid agent slugs before reading agent files", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader, testRoot }) => {
+        writeFileSync(join(testRoot, "some-path.agent.md"), [
+            "---",
+            "name: Escaped Agent",
+            "description: Should never be readable",
+            "model: gpt-5.4",
+            "---",
+            "",
+            "You should not see this.",
+        ].join("\n"), "utf-8");
+        const response = await fetch(`${baseUrl}/api/agents/..%2F..%2Fsome-path`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(response.status, 400);
+        assert.deepEqual(await response.json(), { error: "Invalid slug" });
+    });
+});
+test("server patches a custom agent file and reloads the persistent agent registry", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader, testRoot }) => {
+        writeAgentFile(testRoot, "scribe", [
+            "---",
+            "name: Scribe",
+            "description: Drafts release notes",
+            "model: claude-sonnet-4.6",
+            "persistent: true",
+            "scope: docs",
+            "skills:",
+            "  - writing",
+            "tools:",
+            "  - bash",
+            "---",
+            "",
+            "Original system prompt.",
+        ].join("\n"));
+        const before = await fetch(`${baseUrl}/api/channels`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(before.status, 200);
+        const response = await fetch(`${baseUrl}/api/agents/scribe`, {
+            method: "PATCH",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                name: "Scribe Prime",
+                description: "Publishes saved agent edits",
+                systemPrompt: "# Updated Prompt\n\nShip it.",
+            }),
+        });
+        assert.equal(response.status, 200);
+        assert.deepEqual(await response.json(), {
+            name: "Scribe Prime",
+            slug: "scribe",
+            description: "Publishes saved agent edits",
+            model: "claude-sonnet-4.6",
+            scope: "docs",
+            persistent: true,
+            skills: ["writing"],
+            type: "custom",
+            editable: true,
+            systemPrompt: "# Updated Prompt\n\nShip it.",
+        });
+        const saved = readFileSync(getAgentFilePath(testRoot, "scribe"), "utf-8");
+        assert.match(saved, /^---\n[\s\S]*\n---\n\n# Updated Prompt\n\nShip it\.\n?$/);
+        assert.match(saved, /name: Scribe Prime/);
+        assert.match(saved, /description: Publishes saved agent edits/);
+        assert.match(saved, /model: claude-sonnet-4.6/);
+        assert.match(saved, /scope: docs/);
+        assert.match(saved, /tools:\n  - bash/);
+        assert.match(saved, /skills:\n  - writing/);
+        const after = await fetch(`${baseUrl}/api/channels`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(after.status, 200);
+        const channels = await after.json();
+        assert.deepEqual(channels.find((channel) => channel.slug === "scribe"), {
+            key: "agent:scribe",
+            label: "# scribe",
+            slug: "scribe",
+            name: "Scribe Prime",
+            description: "Publishes saved agent edits",
+            scope: "docs",
+        });
+    });
+});
+test("server rejects PATCH /api/agents/:slug when the request changes skills", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader, testRoot }) => {
+        writeAgentFile(testRoot, "scribe", [
+            "---",
+            "name: Scribe",
+            "description: Drafts release notes",
+            "model: claude-sonnet-4.6",
+            "skills:",
+            "  - writing",
+            "---",
+            "",
+            "Original system prompt.",
+        ].join("\n"));
+        const response = await fetch(`${baseUrl}/api/agents/scribe`, {
+            method: "PATCH",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ skills: ["editing", "review"] }),
+        });
+        assert.equal(response.status, 400);
+        assert.match((await response.json()).error, /skills/i);
+    });
+});
+test("server rejects PATCH /api/agents/:slug when the request changes read-only fields", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader, testRoot }) => {
+        writeAgentFile(testRoot, "scribe", [
+            "---",
+            "name: Scribe",
+            "description: Drafts release notes",
+            "model: claude-sonnet-4.6",
+            "---",
+            "",
+            "Original system prompt.",
+        ].join("\n"));
+        const response = await fetch(`${baseUrl}/api/agents/scribe`, {
+            method: "PATCH",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ slug: "other-scribe" }),
+        });
+        assert.equal(response.status, 400);
+        assert.match((await response.json()).error, /slug/i);
+    });
+});
+test("server rejects PATCH /api/agents/:slug for bundled agents", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const response = await fetch(`${baseUrl}/api/agents/designer`, {
+            method: "PATCH",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ description: "Should not save" }),
+        });
+        assert.equal(response.status, 403);
+        assert.deepEqual(await response.json(), { error: "Built-in agents are read-only" });
+    });
+});
+test("server rejects PATCH /api/agents/:slug for non-team-leads in team mode", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader, testRoot }) => {
+        writeAgentFile(testRoot, "scribe", [
+            "---",
+            "name: Scribe",
+            "description: Drafts release notes",
+            "model: claude-sonnet-4.6",
+            "---",
+            "",
+            "Original system prompt.",
+        ].join("\n"));
+        const response = await fetch(`${baseUrl}/api/agents/scribe`, {
+            method: "PATCH",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ description: "Should not save" }),
+        });
+        assert.equal(response.status, 403);
+        assert.deepEqual(await response.json(), { error: "Forbidden" });
+    }, {
+        CHAPTERHOUSE_MODE: "team",
+    });
+});
+test("server returns 404 when PATCH /api/agents/:slug targets a missing file", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const response = await fetch(`${baseUrl}/api/agents/missing-agent`, {
+            method: "PATCH",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ description: "Still missing" }),
+        });
+        assert.equal(response.status, 404);
+        assert.deepEqual(await response.json(), { error: "Agent not found" });
+    });
+});
+test("server returns 400 when PATCH /api/agents/:slug cannot parse malformed agent content", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader, testRoot }) => {
+        writeAgentFile(testRoot, "scribe", [
+            "---",
+            "name: Scribe",
+            "description: Drafts release notes",
+            "model: claude-sonnet-4.6",
+            "skills: [writing",
+            "---",
+            "",
+            "Original system prompt.",
+        ].join("\n"));
+        const response = await fetch(`${baseUrl}/api/agents/scribe`, {
+            method: "PATCH",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ description: "Broken input stays broken" }),
+        });
+        assert.equal(response.status, 400);
+        assert.match((await response.json()).error, /^Invalid content:/);
+    });
+});
+test("server returns 404 when confirming reload for an unknown agent", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const response = await fetch(`${baseUrl}/api/agents/missing/reload-confirm`, {
+            method: "POST",
+            headers: { authorization: authHeader },
+        });
+        assert.equal(response.status, 404);
+        assert.match(await response.text(), /Agent not found/i);
+    });
+});
 test("server runs in standalone mode without auth", async () => {
     await withStartedServer(async ({ baseUrl }) => {
         const bootstrap = await fetch(`${baseUrl}/api/bootstrap`);
@@ -916,17 +1247,17 @@ test("server caps concurrent SSE connections per IP", async () => {
         let secondResponse;
         try {
             firstResponse = await fetch(`${baseUrl}/stream`, {
-                headers: { authorization: authHeader },
+                headers: { authorization: authHeader, connection: "close" },
                 signal: firstController.signal,
             });
             secondResponse = await fetch(`${baseUrl}/stream`, {
-                headers: { authorization: authHeader },
+                headers: { authorization: authHeader, connection: "close" },
                 signal: secondController.signal,
             });
             assert.equal(firstResponse.status, 200);
             assert.equal(secondResponse.status, 200);
             const rejected = await fetch(`${baseUrl}/stream`, {
-                headers: { authorization: authHeader },
+                headers: { authorization: authHeader, connection: "close" },
             });
             assert.equal(rejected.status, 429);
             assert.equal(rejected.headers.get("retry-after"), "60");

package/dist/config.test.js

@@ -271,7 +271,19 @@ test("rejects invalid SSE replay settings", async () => {
         CHAPTERHOUSE_SSE_BUFFER_CAPACITY: "0",
     }), /CHAPTERHOUSE_SSE_BUFFER_CAPACITY must be a positive integer/);
 });
+test("personal mode starts cleanly without Entra env vars", async () => {
+    // Security: personal mode should boot in its intended unauthenticated configuration instead of requiring enterprise auth by accident.
+    const configModule = await import("./config.js");
+    assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
+    const parsed = configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "personal",
+    });
+    assert.equal(parsed.chapterhouseMode, "personal");
+    assert.equal(parsed.entraAuthEnabled, false);
+    assert.doesNotMatch(parsed.modeCompatibilityWarnings.join("\n"), /Entra/i);
+});
 test("personal mode rejects explicit Entra auth enablement with a clear fix suggestion", async () => {
+    // Security: personal deployments must fail fast instead of starting in a broken auth state that looks protected but is not.
     const configModule = await import("./config.js");
     assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
     assert.throws(() => configModule.parseRuntimeConfig({
@@ -281,7 +293,23 @@ test("personal mode rejects explicit Entra auth enablement with a clear fix sugg
         ENTRA_CLIENT_ID: "client-id",
     }), /Personal mode cannot be used with ENTRA_AUTH_ENABLED=true[\s\S]*CHAPTERHOUSE_MODE=team[\s\S]*unset ENTRA_AUTH_ENABLED/);
 });
+test("team mode accepts Entra auth when required settings are present", async () => {
+    // Security: team mode is the only safe place for Entra auth, so valid enterprise settings must remain supported there.
+    const configModule = await import("./config.js");
+    assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
+    const parsed = configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "team",
+        ENTRA_AUTH_ENABLED: "true",
+        ENTRA_TENANT_ID: "tenant-id",
+        ENTRA_CLIENT_ID: "client-id",
+    });
+    assert.equal(parsed.chapterhouseMode, "team");
+    assert.equal(parsed.entraAuthEnabled, true);
+    assert.equal(parsed.entraTenantId, "tenant-id");
+    assert.equal(parsed.entraClientId, "client-id");
+});
 test("personal mode still warns about leftover Entra settings when auth is not explicitly enabled", async () => {
+    // Security: leftover enterprise env vars should be called out so personal-mode operators know those settings are being ignored.
     const configModule = await import("./config.js");
     assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
     const parsed = configModule.parseRuntimeConfig({
@@ -293,6 +321,7 @@ test("personal mode still warns about leftover Entra settings when auth is not e
     assert.match(parsed.modeCompatibilityWarnings.join("\n"), /Entra/i);
 });
 test("personal mode warns and disables incomplete Teams notification settings instead of throwing", async () => {
+    // Security: personal mode should ignore team-only integrations without partially enabling cross-tenant notification flows.
     const configModule = await import("./config.js");
     assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
     const parsed = configModule.parseRuntimeConfig({

package/dist/copilot/agent-event-bus.js

@@ -11,6 +11,7 @@
  *   session:tool_call  — tool invoked           payload: { toolName, toolArgs, resultType?, _kind?, _seq?, _ts?, _summary? }
  *   session:destroyed  — subagent finished      payload: { agentName, reason: "complete" | "error" | "abort" }
  *   session:error      — subagent failed        payload: { agentName, error }
+ *   agent_saved        — custom agent saved     payload: { slug }
  *
  * @module copilot/agent-event-bus
  */

package/dist/copilot/agents.js

@@ -3,6 +3,7 @@ import { readdirSync, readFileSync, mkdirSync, writeFileSync, existsSync, rmSync
 import { createHash } from "crypto";
 import { join, dirname, sep } from "path";
 import { fileURLToPath } from "url";
+import { load as yamlLoad, dump as yamlDump } from "js-yaml";
 import { z } from "zod";
 import { approveAll } from "@github/copilot-sdk";
 import { AGENTS_DIR, SESSIONS_DIR } from "../paths.js";
@@ -34,48 +35,42 @@ const agentFrontmatterSchema = z.object({
 // Agent Registry
 // ---------------------------------------------------------------------------
 let agentRegistry = [];
+const defaultAgentSaveRuntimeHooks = {
+    getPersistentSessionState: () => "none",
+    reloadPersistentSession: async () => "none",
+    emitAgentReloadEvent: () => { },
+};
+let agentSaveRuntimeHooks = { ...defaultAgentSaveRuntimeHooks };
 /** Bundled agents shipped with the package */
 const BUNDLED_AGENTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
-const RESERVED_SLUGS = new Set(["chapterhouse", "designer", "coder", "general-purpose"]);
-const SLUG_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const RESERVED_SLUGS = new Set(["chapterhouse", "designer", "coder", "general-purpose"]);
+export const SLUG_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const BUILTIN_AGENT_SLUGS = new Set(RESERVED_SLUGS);
+if (existsSync(BUNDLED_AGENTS_DIR)) {
+    for (const file of readdirSync(BUNDLED_AGENTS_DIR)) {
+        if (file.endsWith(".agent.md")) {
+            BUILTIN_AGENT_SLUGS.add(file.replace(/\.agent\.md$/, ""));
+        }
+    }
+}
+export function isBuiltinAgent(slug) {
+    return BUILTIN_AGENT_SLUGS.has(slug);
+}
 /** Parse YAML frontmatter and markdown body from an .agent.md file. */
-export function parseAgentMd(content, slug) {
+export function parseAgentMdOrThrow(content, slug) {
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---\s*([\s\S]*)$/);
-    if (!fmMatch)
-        return null;
+    if (!fmMatch) {
+        throw new Error("Missing YAML frontmatter");
+    }
     const frontmatterRaw = fmMatch[1];
     const body = fmMatch[2].trim();
-    // Simple YAML parser for flat + array values
-    const parsed = {};
-    for (const line of frontmatterRaw.split("\n")) {
-        const idx = line.indexOf(": ");
-        if (idx <= 0)
-            continue;
-        const key = line.slice(0, idx).trim();
-        let value = line.slice(idx + 2).trim();
-        // Handle YAML quoted strings
-        if (typeof value === "string" && value.startsWith('"') && value.endsWith('"')) {
-            value = value.slice(1, -1);
-        }
-        parsed[key] = value;
+    const loaded = yamlLoad(frontmatterRaw);
+    if (loaded !== undefined && (loaded === null || typeof loaded !== "object" || Array.isArray(loaded))) {
+        throw new Error("Agent frontmatter must be a YAML object");
     }
-    // Parse arrays from YAML inline syntax: [a, b, c]
-    for (const key of ["skills", "tools", "mcpServers", "allowed_paths"]) {
-        const raw = parsed[key];
-        if (typeof raw === "string") {
-            const arrMatch = raw.match(/^\[(.*)\]$/);
-            if (arrMatch) {
-                parsed[key] = arrMatch[1]
-                    .split(",")
-                    .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
-                    .filter(Boolean);
-            }
-        }
-    }
-    const result = agentFrontmatterSchema.safeParse(parsed);
+    const result = agentFrontmatterSchema.safeParse(loaded ?? {});
     if (!result.success) {
-        log.warn({ slug, errors: result.error.format() }, "Invalid frontmatter in agent file");
-        return null;
+        throw new Error(z.prettifyError(result.error));
     }
     const fm = result.data;
     return {
@@ -92,6 +87,29 @@ export function parseAgentMd(content, slug) {
         systemMessage: body,
     };
 }
+export function parseAgentMd(content, slug) {
+    try {
+        return parseAgentMdOrThrow(content, slug);
+    }
+    catch (err) {
+        log.warn({ slug, err: err instanceof Error ? err.message : err }, "Invalid agent file");
+        return null;
+    }
+}
+export function serializeAgentMd(agent) {
+    const frontmatter = {
+        name: agent.name,
+        description: agent.description,
+        model: agent.model,
+        ...(agent.persistent !== undefined ? { persistent: agent.persistent } : {}),
+        ...(agent.scope !== undefined ? { scope: agent.scope } : {}),
+        ...(agent.skills !== undefined ? { skills: agent.skills } : {}),
+        ...(agent.tools !== undefined ? { tools: agent.tools } : {}),
+        ...(agent.mcpServers !== undefined ? { mcpServers: agent.mcpServers } : {}),
+        ...(agent.allowedPaths !== undefined ? { allowed_paths: agent.allowedPaths } : {}),
+    };
+    return `---\n${yamlDump(frontmatter, { lineWidth: -1 })}---\n\n${agent.systemMessage}`;
+}
 /** Scan ~/.chapterhouse/agents/ for .agent.md files and load configs. */
 export function loadAgents() {
     if (!existsSync(AGENTS_DIR)) {
@@ -132,6 +150,49 @@ export function getAgent(nameOrSlug) {
 export function getAgentRegistry() {
     return [...agentRegistry];
 }
+export function setAgentSaveRuntimeHooks(hooks) {
+    agentSaveRuntimeHooks = {
+        ...agentSaveRuntimeHooks,
+        ...hooks,
+    };
+}
+export function resetAgentSaveRuntimeHooks() {
+    agentSaveRuntimeHooks = { ...defaultAgentSaveRuntimeHooks };
+}
+export async function notifyAgentSaved(slug, savedConfig) {
+    const config = savedConfig ?? parseAgentMdOrThrow(readFileSync(join(AGENTS_DIR, `${slug}.agent.md`), "utf-8"), slug);
+    const existingIndex = agentRegistry.findIndex((entry) => entry.slug === slug);
+    if (existingIndex >= 0) {
+        agentRegistry[existingIndex] = config;
+    }
+    else {
+        agentRegistry.push(config);
+    }
+    void import("./orchestrator.js").then(({ enqueueForSse }) => {
+        enqueueForSse({ type: "agent_saved", slug });
+    }).catch((err) => {
+        log.warn({ slug, err: err instanceof Error ? err.message : err }, "Failed to emit agent_saved SSE event");
+    });
+    const emitReloaded = () => {
+        agentSaveRuntimeHooks.emitAgentReloadEvent({
+            type: "agent_reloaded",
+            slug,
+            reason: "session_restart",
+        });
+    };
+    const result = await agentSaveRuntimeHooks.reloadPersistentSession(slug, emitReloaded);
+    if (result === "scheduled") {
+        agentSaveRuntimeHooks.emitAgentReloadEvent({
+            type: "agent_reload_pending",
+            slug,
+            reason: "in_flight",
+        });
+        return;
+    }
+    if (result === "reloaded") {
+        emitReloaded();
+    }
+}
 /** Copy bundled agents to ~/.chapterhouse/agents/, updating stale copies when the bundled version changes.
  *  Respects user customizations: if the user edited the deployed file after our last sync, we skip it. */
 export function ensureDefaultAgents() {
@@ -186,16 +247,14 @@ export function createAgentFile(slug, name, description, model, systemPrompt, sk
     if (existsSync(filePath)) {
         return `Agent '${slug}' already exists. Edit it directly or remove it first.`;
     }
-    // YAML value escaping for safe frontmatter
-    const escapedName = name.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
-    const escapedDesc = description.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
-    let frontmatter = `---\nname: "${escapedName}"\ndescription: "${escapedDesc}"\nmodel: ${model}`;
-    if (skills?.length)
-        frontmatter += `\nskills:\n${skills.map((s) => `  - ${s}`).join("\n")}`;
-    if (tools?.length)
-        frontmatter += `\ntools:\n${tools.map((t) => `  - ${t}`).join("\n")}`;
-    frontmatter += "\n---\n\n";
-    writeFileSync(filePath, frontmatter + systemPrompt + "\n");
+    writeFileSync(filePath, serializeAgentMd({
+        name,
+        description,
+        model,
+        skills,
+        tools,
+        systemMessage: `${systemPrompt}\n`,
+    }));
     return null;
 }
 /** Remove an agent .md file. Returns error string or null on success. */
@@ -203,7 +262,7 @@ export function removeAgentFile(slug) {
     if (!SLUG_REGEX.test(slug)) {
         return `Invalid slug '${slug}'.`;
     }
-    if (RESERVED_SLUGS.has(slug)) {
+    if (isBuiltinAgent(slug)) {
         return `Cannot remove built-in agent '${slug}'. You can edit its file instead.`;
     }
     const filePath = join(AGENTS_DIR, `${slug}.agent.md`);
@@ -323,6 +382,14 @@ export function filterToolsForAgent(agent, allTools) {
     }
     return allTools.filter((t) => !MANAGEMENT_TOOL_NAMES.has(t.name));
 }
+/** Filter MCP servers based on agent config. */
+export function filterMcpServersForAgent(agent, allMcpServers) {
+    if (agent.mcpServers && agent.mcpServers.length > 0) {
+        const allowed = new Set(agent.mcpServers);
+        return Object.fromEntries(Object.entries(allMcpServers).filter(([name]) => allowed.has(name)));
+    }
+    return allMcpServers;
+}
 /** Create an ephemeral session for an agent. Always creates a fresh session — caller is responsible for destroying it. */
 export async function createEphemeralAgentSession(slug, client, allTools, modelOverride, systemMessagePrefix, taskId) {
     const agent = getAgent(slug);
@@ -334,7 +401,8 @@ export async function createEphemeralAgentSession(slug, client, allTools, modelO
         ? modelOverride
         : (agent.model === "auto" ? "claude-sonnet-4.6" : agent.model);
     const tools = bindToolsToAgent(agent.slug, filterToolsForAgent(agent, allTools), taskId);
-    const mcpServers = loadMcpConfig();
+    const allMcpServers = loadMcpConfig();
+    const mcpServers = filterMcpServersForAgent(agent, allMcpServers);
     const skillDirectories = getSkillDirectories();
     const baseSystemMessage = composeAgentSystemMessage(agent);
     const systemMessageContent = systemMessagePrefix