From 1f3d35726bd2744ba3f1843b2f8b28c0f59a40dd Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Tue, 17 Feb 2026 09:40:11 -0800
Subject: [PATCH] docs(config): document agent backend routing and add schema
 guard test

---
 config/default.yaml       | 21 +++++++++++++++++++++
 src/config/schema.test.ts | 13 +++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/config/default.yaml b/config/default.yaml
index ad6754d..0ac5980 100644
--- a/config/default.yaml
+++ b/config/default.yaml
@@ -261,6 +261,27 @@ hooks:
 #   extra_sections: []
 #   context_level: normal  # minimal | normal | detailed | debug
 
+# Optional: named agent profiles and routing.
+# Each agent can pin model tier, tool profile, sandbox mode, and execution backend.
+#
+# agent_configs:
+#   assistant:
+#     system_prompt: You are helpful.
+#     model_tier: default
+#     backend: native          # native | codex | claude_code | opencode | gemini
+#   coder:
+#     system_prompt: Write code.
+#     model_tier: complex
+#     backend: codex
+#     sandbox: true
+#
+# routing:
+#   default_agent: assistant
+#   channels:
+#     telegram: assistant
+#   senders:
+#     telegram:admin: coder
+
 # ── Context Compaction ────────────────────────────────────────────────
 # Optional proactive context monitoring and checkpointing.
 #
diff --git a/src/config/schema.test.ts b/src/config/schema.test.ts
index 1f0e8f1..f58cc80 100644
--- a/src/config/schema.test.ts
+++ b/src/config/schema.test.ts
@@ -418,6 +418,19 @@ describe('configSchema — agent_configs', () => {
     expect(result.agent_configs.assistant.tool_profile).toBe('messaging');
     expect(result.agent_configs.coder.sandbox).toBe(true);
   });
+
+  it('rejects invalid backend name in agent config', () => {
+    expect(() => configSchema.parse({
+      ...minimalConfig,
+      agent_configs: {
+        assistant: {
+          system_prompt: 'You are helpful.',
+          model_tier: 'default',
+          backend: 'unknown_backend',
+        },
+      },
+    })).toThrow();
+  });
 });
 
 describe('configSchema — backends', () => {