From 1902e478c997aa0e809588ad036ed7b05047f174 Mon Sep 17 00:00:00 2001
From: hopingmiao <3085273707@qq.com>
Date: Thu, 30 Jul 2026 19:53:13 +0800
Subject: [PATCH] feat(settings): configure subagent prompt templates

---
 crates/agent-gateway/web/src/i18n/config.ts   |   6 +
 .../web/src/lib/settings/index.ts             |   5 +
 .../settings/AgentPromptTemplateModal.tsx     |   4 +-
 .../web/src/pages/settings/AgentsSection.tsx  | 134 +++++++++++++++++-
 .../src/commands/config/settings/agents.rs    |  18 ++-
 .../src/commands/config/settings/db.rs        |  31 ++++
 .../src/commands/config/settings/mod.rs       |   6 +-
 .../src/commands/config/settings/tests.rs     | 114 ++++++++++++++-
 crates/agent-gui/src/i18n/config.ts           |   6 +
 crates/agent-gui/src/lib/settings/index.ts    |   5 +
 .../agent-gui/src/lib/subagents/agentTool.ts  |   6 +-
 crates/agent-gui/src/lib/subagents/errors.ts  |   2 +-
 crates/agent-gui/src/lib/subagents/roster.ts  |   2 +-
 .../agent-gui/src/lib/subagents/validate.ts   |   2 +-
 .../chat/turns/runAgentConversationTurn.ts    |  10 +-
 .../settings/AgentPromptTemplateModal.tsx     |   4 +-
 .../src/pages/settings/AgentsSection.tsx      | 134 +++++++++++++++++-
 .../agent-turn-cancelled-history.test.mjs     |  55 ++++++-
 .../test/settings/normalization.test.mjs      |  60 ++++++--
 .../test/subagents/agent-tool.test.mjs        |   2 +-
 .../test/subagents/bus-roster.test.mjs        |   5 +-
 .../test/subagents/validate.test.mjs          |   2 +-
 .../builtin-registry-subagent-mcp.test.mjs    |   2 +-
 23 files changed, 578 insertions(+), 37 deletions(-)

diff --git a/crates/agent-gateway/web/src/i18n/config.ts b/crates/agent-gateway/web/src/i18n/config.ts
index 665ded047..4e8a51d53 100644
--- a/crates/agent-gateway/web/src/i18n/config.ts
+++ b/crates/agent-gateway/web/src/i18n/config.ts
@@ -1601,6 +1601,9 @@ export const translations: Record<Locale, Record<string, string>> = {
     "settings.agentsShowPrompt": "查看 Prompt",
     "settings.agentsReady": "可以保存",
     "settings.agentsRequired": "名称和 Prompt 为必填项",
+    "settings.agentsSubagentTemplates": "子代理模板",
+    "settings.agentsSubagentTemplatesHint":
+      "选择可供子代理按需引用的模板，可同时选择多个；不会改变主代理当前激活的模板。",
 
     /* ── Settings SSH ── */
     "settings.sshTitle": "SSH",
@@ -3839,6 +3842,9 @@ export const translations: Record<Locale, Record<string, string>> = {
     "settings.agentsShowPrompt": "View Prompt",
     "settings.agentsReady": "Ready to save",
     "settings.agentsRequired": "Name and Prompt are required",
+    "settings.agentsSubagentTemplates": "Subagent Templates",
+    "settings.agentsSubagentTemplatesHint":
+      "Choose templates that subagents may reference. Multiple templates can be selected without changing the active main-agent template.",
 
     /* ── Settings SSH ── */
     "settings.sshTitle": "SSH",
diff --git a/crates/agent-gateway/web/src/lib/settings/index.ts b/crates/agent-gateway/web/src/lib/settings/index.ts
index 7f3fbeafd..9fb144d34 100644
--- a/crates/agent-gateway/web/src/lib/settings/index.ts
+++ b/crates/agent-gateway/web/src/lib/settings/index.ts
@@ -245,6 +245,7 @@ export type AgentPromptTemplate = {
   description: string;
   prompt: string;
   enabled: boolean;
+  availableToSubagents: boolean;
 };
 
 export type SshAuthType = "password" | "privateKey" | "keyboardInteractive";
@@ -1501,6 +1502,10 @@ export function normalizeAgentPromptTemplate(input: unknown): AgentPromptTemplat
     description: normalizeOptionalText(obj.description),
     prompt: normalizeOptionalText(obj.prompt),
     enabled: obj.enabled === true,
+    availableToSubagents:
+      typeof obj.availableToSubagents === "boolean"
+        ? obj.availableToSubagents
+        : obj.enabled === true,
   };
 }
 
diff --git a/crates/agent-gateway/web/src/pages/settings/AgentPromptTemplateModal.tsx b/crates/agent-gateway/web/src/pages/settings/AgentPromptTemplateModal.tsx
index 9768844b9..9b26dd583 100644
--- a/crates/agent-gateway/web/src/pages/settings/AgentPromptTemplateModal.tsx
+++ b/crates/agent-gateway/web/src/pages/settings/AgentPromptTemplateModal.tsx
@@ -10,9 +10,11 @@ import { useLocale } from "../../i18n";
 import type { AgentPromptTemplate } from "../../lib/settings";
 import { useModalMotion } from "../../lib/shared/modalMotion";
 
+type AgentPromptTemplateContent = Pick<AgentPromptTemplate, "name" | "description" | "prompt">;
+
 type AgentPromptTemplateModalProps = {
   initialData?: AgentPromptTemplate;
-  onSave: (data: Omit<AgentPromptTemplate, "id" | "enabled">) => void;
+  onSave: (data: AgentPromptTemplateContent) => void;
   onClose: () => void;
 };
 
diff --git a/crates/agent-gateway/web/src/pages/settings/AgentsSection.tsx b/crates/agent-gateway/web/src/pages/settings/AgentsSection.tsx
index 49767647c..950e1ca93 100644
--- a/crates/agent-gateway/web/src/pages/settings/AgentsSection.tsx
+++ b/crates/agent-gateway/web/src/pages/settings/AgentsSection.tsx
@@ -1,6 +1,18 @@
+import { Popover } from "@base-ui/react";
 import { useState } from "react";
 import { createPortal } from "react-dom";
-import { BookOpen, Eye, FileText, Pencil, Plus, Trash2, X } from "../../components/icons";
+import {
+  BookOpen,
+  Bot,
+  Check,
+  ChevronDown,
+  Eye,
+  FileText,
+  Pencil,
+  Plus,
+  Trash2,
+  X,
+} from "../../components/icons";
 
 import { Button } from "../../components/ui/button";
 import { useLocale } from "../../i18n";
@@ -33,7 +45,7 @@ export function AgentsSection(props: SettingsSectionProps) {
     setEditingTemplate(null);
   }
 
-  function handleSave(data: Omit<AgentPromptTemplate, "id" | "enabled">) {
+  function handleSave(data: Pick<AgentPromptTemplate, "name" | "description" | "prompt">) {
     setSettings((prev) => {
       if (editingTemplate) {
         return updateAgents(
@@ -48,6 +60,7 @@ export function AgentsSection(props: SettingsSectionProps) {
         id: createUuid(),
         ...data,
         enabled: false,
+        availableToSubagents: false,
       };
       return updateAgents(prev, [...prev.agents, newTemplate]);
     });
@@ -76,8 +89,24 @@ export function AgentsSection(props: SettingsSectionProps) {
     );
   }
 
+  function handleToggleAvailableToSubagents(id: string) {
+    setSettings((prev) =>
+      updateAgents(
+        prev,
+        prev.agents.map((template) =>
+          template.id === id
+            ? { ...template, availableToSubagents: !template.availableToSubagents }
+            : template,
+        ),
+      ),
+    );
+  }
+
   const templates = settings.agents;
   const enabledCount = templates.filter((template) => template.enabled).length;
+  const subagentTemplateCount = templates.filter(
+    (template) => template.availableToSubagents,
+  ).length;
 
   return (
     <>
@@ -112,6 +141,13 @@ export function AgentsSection(props: SettingsSectionProps) {
                 ) : null}
               </div>
             ) : null}
+            {templates.length > 0 ? (
+              <SubagentTemplatePicker
+                templates={templates}
+                selectedCount={subagentTemplateCount}
+                onToggle={handleToggleAvailableToSubagents}
+              />
+            ) : null}
             <Button variant="outline" size="sm" className="gap-1.5" onClick={openAdd}>
               <Plus className="h-3.5 w-3.5" />
               {t("settings.agentsAdd")}
@@ -245,6 +281,100 @@ export function AgentsSection(props: SettingsSectionProps) {
   );
 }
 
+function SubagentTemplatePicker(props: {
+  templates: AgentPromptTemplate[];
+  selectedCount: number;
+  onToggle: (id: string) => void;
+}) {
+  const { templates, selectedCount, onToggle } = props;
+  const { t } = useLocale();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger
+        render={
+          <Button
+            variant="outline"
+            size="sm"
+            className="gap-1.5"
+            aria-label={t("settings.agentsSubagentTemplates")}
+          />
+        }
+      >
+        <Bot className="h-3.5 w-3.5" />
+        <span>{t("settings.agentsSubagentTemplates")}</span>
+        <span className="rounded-full bg-sky-500/10 px-1.5 py-0.5 text-[10px] font-semibold tabular-nums text-sky-600 dark:text-sky-400">
+          {selectedCount}
+        </span>
+        <ChevronDown
+          className={`h-3.5 w-3.5 text-muted-foreground transition-transform ${open ? "rotate-180" : ""}`}
+        />
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Positioner
+          side="bottom"
+          align="end"
+          sideOffset={6}
+          collisionPadding={8}
+          className="z-[9999]"
+        >
+          <Popover.Popup
+            aria-label={t("settings.agentsSubagentTemplates")}
+            className="w-[min(22rem,calc(100vw-1rem))] overflow-hidden rounded-xl border bg-popover text-popover-foreground shadow-lg outline-none"
+          >
+            <div className="border-b border-border/60 px-3 py-2.5">
+              <p className="text-xs font-semibold">{t("settings.agentsSubagentTemplates")}</p>
+              <p className="mt-0.5 text-[11px] leading-relaxed text-muted-foreground">
+                {t("settings.agentsSubagentTemplatesHint")}
+              </p>
+            </div>
+            <div className="max-h-72 space-y-1 overflow-y-auto p-1.5">
+              {templates.map((template) => {
+                const checked = template.availableToSubagents;
+                return (
+                  <label
+                    key={template.id}
+                    className={`flex w-full cursor-pointer items-start gap-2.5 rounded-lg px-2.5 py-2 text-left transition-colors hover:bg-muted/70 focus-within:ring-2 focus-within:ring-ring ${
+                      checked ? "bg-sky-500/[0.07]" : ""
+                    }`}
+                  >
+                    <input
+                      type="checkbox"
+                      checked={checked}
+                      className="sr-only"
+                      onChange={() => onToggle(template.id)}
+                    />
+                    <span
+                      className={`mt-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded border transition-colors ${
+                        checked
+                          ? "border-sky-500 bg-sky-500 text-white"
+                          : "border-border bg-background"
+                      }`}
+                    >
+                      {checked ? <Check className="h-3 w-3" /> : null}
+                    </span>
+                    <span className="min-w-0 flex-1">
+                      <span className="block truncate text-xs font-medium text-foreground">
+                        {template.name}
+                      </span>
+                      {template.description ? (
+                        <span className="mt-0.5 block line-clamp-2 text-[11px] leading-relaxed text-muted-foreground">
+                          {template.description}
+                        </span>
+                      ) : null}
+                    </span>
+                  </label>
+                );
+              })}
+            </div>
+          </Popover.Popup>
+        </Popover.Positioner>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}
+
 type AgentPromptViewModalProps = {
   template: AgentPromptTemplate;
   onClose: () => void;
diff --git a/crates/agent-gui/src-tauri/src/commands/config/settings/agents.rs b/crates/agent-gui/src-tauri/src/commands/config/settings/agents.rs
index 5a51057c3..27fdf9f8f 100644
--- a/crates/agent-gui/src-tauri/src/commands/config/settings/agents.rs
+++ b/crates/agent-gui/src-tauri/src/commands/config/settings/agents.rs
@@ -10,13 +10,14 @@ fn load_agents(conn: &Connection) -> Result<Option<Value>, String> {
                 row.get::<_, String>(2)?,
                 row.get::<_, String>(3)?,
                 row.get::<_, i64>(4)?,
+                row.get::<_, i64>(5)?,
             ))
         })
         .map_err(|e| format!("读取 {AGENT_PROMPT_TEMPLATES_TABLE} 失败：{e}"))?;
 
     let mut templates = Vec::new();
     for row in rows {
-        let (template_id, name, description, prompt, enabled) =
+        let (template_id, name, description, prompt, enabled, available_to_subagents) =
             row.map_err(|e| format!("读取 {AGENT_PROMPT_TEMPLATES_TABLE} 行失败：{e}"))?;
         templates.push(Value::Object(Map::from_iter([
             ("id".to_string(), Value::String(template_id)),
@@ -24,6 +25,10 @@ fn load_agents(conn: &Connection) -> Result<Option<Value>, String> {
             ("description".to_string(), Value::String(description)),
             ("prompt".to_string(), Value::String(prompt)),
             ("enabled".to_string(), Value::Bool(enabled != 0)),
+            (
+                "availableToSubagents".to_string(),
+                Value::Bool(available_to_subagents != 0),
+            ),
         ])));
     }
 
@@ -73,6 +78,16 @@ fn save_agents(conn: &mut Connection, payload: Value) -> Result<(), String> {
             }
             enabled_template_id = Some(template_id.clone());
         }
+        let available_to_subagents = match template.get("availableToSubagents") {
+            Some(Value::Bool(value)) => *value,
+            Some(Value::Null) | None => enabled,
+            Some(_) => {
+                return Err(
+                    "settings_save_agents payload[].availableToSubagents 必须是布尔值"
+                        .to_string(),
+                );
+            }
+        };
 
         tx.execute(
             AGENT_PROMPT_TEMPLATES_INSERT_SQL,
@@ -82,6 +97,7 @@ fn save_agents(conn: &mut Connection, payload: Value) -> Result<(), String> {
                 description,
                 prompt,
                 if enabled { 1_i64 } else { 0_i64 },
+                if available_to_subagents { 1_i64 } else { 0_i64 },
                 sort_index as i64,
                 updated_at
             ],
diff --git a/crates/agent-gui/src-tauri/src/commands/config/settings/db.rs b/crates/agent-gui/src-tauri/src/commands/config/settings/db.rs
index f9b91a64c..8cde0cadd 100644
--- a/crates/agent-gui/src-tauri/src/commands/config/settings/db.rs
+++ b/crates/agent-gui/src-tauri/src/commands/config/settings/db.rs
@@ -48,6 +48,7 @@ pub(crate) fn initialize_schema(conn: &Connection) -> Result<(), String> {
             description TEXT NOT NULL,
             prompt TEXT NOT NULL,
             enabled INTEGER NOT NULL DEFAULT 0,
+            available_to_subagents INTEGER NOT NULL DEFAULT 0,
             sort_index INTEGER NOT NULL,
             updated_at INTEGER NOT NULL
         );
@@ -105,6 +106,36 @@ pub(crate) fn initialize_schema(conn: &Connection) -> Result<(), String> {
         ",
     )
     .map_err(|e| format!("初始化设置表失败：{e}"))?;
+
+    let has_subagent_template_column = {
+        let mut stmt = conn
+            .prepare("PRAGMA table_info(agent_prompt_templates)")
+            .map_err(|e| format!("检查 {AGENT_PROMPT_TEMPLATES_TABLE} 表结构失败：{e}"))?;
+        let columns = stmt
+            .query_map([], |row| row.get::<_, String>(1))
+            .map_err(|e| format!("读取 {AGENT_PROMPT_TEMPLATES_TABLE} 表结构失败：{e}"))?;
+        let mut found = false;
+        for column in columns {
+            if column.map_err(|e| format!("读取 {AGENT_PROMPT_TEMPLATES_TABLE} 列失败：{e}"))?
+                == "available_to_subagents"
+            {
+                found = true;
+                break;
+            }
+        }
+        found
+    };
+    if !has_subagent_template_column {
+        conn.execute_batch(
+            "
+            ALTER TABLE agent_prompt_templates
+                ADD COLUMN available_to_subagents INTEGER NOT NULL DEFAULT 0;
+            UPDATE agent_prompt_templates
+                SET available_to_subagents = enabled;
+            ",
+        )
+        .map_err(|e| format!("迁移 {AGENT_PROMPT_TEMPLATES_TABLE} 子代理模板字段失败：{e}"))?;
+    }
     Ok(())
 }
 
diff --git a/crates/agent-gui/src-tauri/src/commands/config/settings/mod.rs b/crates/agent-gui/src-tauri/src/commands/config/settings/mod.rs
index ecf34f264..fc2c3521c 100644
--- a/crates/agent-gui/src-tauri/src/commands/config/settings/mod.rs
+++ b/crates/agent-gui/src-tauri/src/commands/config/settings/mod.rs
@@ -80,14 +80,14 @@ const MCP_SETTINGS_INSERT_SQL: &str = "
 const MCP_SETTINGS_DELETE_SQL: &str = "DELETE FROM mcp_settings";
 
 const AGENT_PROMPT_TEMPLATES_SELECT_SQL: &str = "
-    SELECT template_id, name, description, prompt, enabled
+    SELECT template_id, name, description, prompt, enabled, available_to_subagents
     FROM agent_prompt_templates
     ORDER BY sort_index ASC, template_id ASC
 ";
 const AGENT_PROMPT_TEMPLATES_INSERT_SQL: &str = "
     INSERT INTO agent_prompt_templates
-        (template_id, name, description, prompt, enabled, sort_index, updated_at)
-    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)
+        (template_id, name, description, prompt, enabled, available_to_subagents, sort_index, updated_at)
+    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
 ";
 const AGENT_PROMPT_TEMPLATES_DELETE_SQL: &str = "DELETE FROM agent_prompt_templates";
 
diff --git a/crates/agent-gui/src-tauri/src/commands/config/settings/tests.rs b/crates/agent-gui/src-tauri/src/commands/config/settings/tests.rs
index 4793f7443..adaafe3ed 100644
--- a/crates/agent-gui/src-tauri/src/commands/config/settings/tests.rs
+++ b/crates/agent-gui/src-tauri/src/commands/config/settings/tests.rs
@@ -45,6 +45,61 @@ mod tests {
         }
     }
 
+    #[test]
+    fn initialize_schema_creates_and_migrates_subagent_template_availability() {
+        let conn = open_memory_db();
+        assert!(
+            table_columns(&conn, AGENT_PROMPT_TEMPLATES_TABLE)
+                .iter()
+                .any(|column| column == "available_to_subagents")
+        );
+
+        let legacy = Connection::open_in_memory().expect("open legacy sqlite");
+        legacy
+            .execute_batch(
+                "
+                CREATE TABLE agent_prompt_templates (
+                    template_id TEXT PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    description TEXT NOT NULL,
+                    prompt TEXT NOT NULL,
+                    enabled INTEGER NOT NULL DEFAULT 0,
+                    sort_index INTEGER NOT NULL,
+                    updated_at INTEGER NOT NULL
+                );
+                INSERT INTO agent_prompt_templates
+                    (template_id, name, description, prompt, enabled, sort_index, updated_at)
+                VALUES
+                    ('active', 'Active', '', 'Prompt A', 1, 0, 1),
+                    ('inactive', 'Inactive', '', 'Prompt B', 0, 1, 1);
+                ",
+            )
+            .expect("seed legacy agent templates");
+
+        initialize_schema(&legacy).expect("migrate legacy agent templates");
+        initialize_schema(&legacy).expect("migration remains idempotent");
+        assert_eq!(
+            legacy
+                .query_row(
+                    "SELECT available_to_subagents FROM agent_prompt_templates WHERE template_id = 'active'",
+                    [],
+                    |row| row.get::<_, i64>(0),
+                )
+                .expect("query active availability"),
+            1
+        );
+        assert_eq!(
+            legacy
+                .query_row(
+                    "SELECT available_to_subagents FROM agent_prompt_templates WHERE template_id = 'inactive'",
+                    [],
+                    |row| row.get::<_, i64>(0),
+                )
+                .expect("query inactive availability"),
+            0
+        );
+    }
+
     #[test]
     fn initialize_schema_creates_columnar_ssh_settings_table() {
         let conn = open_memory_db();
@@ -1025,14 +1080,16 @@ mod tests {
                     "name": "代码审查",
                     "description": "用于审查 PR 和补测试缺口",
                     "prompt": "你是一个严格的代码审查助手。",
-                    "enabled": true
+                    "enabled": true,
+                    "availableToSubagents": true
                 },
                 {
                     "id": "planner",
                     "name": "任务规划",
                     "description": "",
                     "prompt": "先拆任务，再执行。",
-                    "enabled": false
+                    "enabled": false,
+                    "availableToSubagents": true
                 }
             ]),
         )
@@ -1050,10 +1107,18 @@ mod tests {
                 |row| row.get::<_, i64>(0),
             )
             .expect("query reviewer enabled");
+        let subagent_available_count = conn
+            .query_row(
+                "SELECT COUNT(*) FROM agent_prompt_templates WHERE available_to_subagents = 1",
+                [],
+                |row| row.get::<_, i64>(0),
+            )
+            .expect("count subagent templates");
         let loaded = load_agents(&conn).expect("load agents");
 
         assert_eq!(row_count, 2);
         assert_eq!(stored_enabled, 1);
+        assert_eq!(subagent_available_count, 2);
         assert_eq!(
             loaded,
             Some(json!([
@@ -1062,19 +1127,60 @@ mod tests {
                     "name": "代码审查",
                     "description": "用于审查 PR 和补测试缺口",
                     "prompt": "你是一个严格的代码审查助手。",
-                    "enabled": true
+                    "enabled": true,
+                    "availableToSubagents": true
                 },
                 {
                     "id": "planner",
                     "name": "任务规划",
                     "description": "",
                     "prompt": "先拆任务，再执行。",
-                    "enabled": false
+                    "enabled": false,
+                    "availableToSubagents": true
                 }
             ]))
         );
     }
 
+    #[test]
+    fn save_agents_defaults_legacy_availability_and_rejects_invalid_values() {
+        let mut conn = open_memory_db();
+        save_agents(
+            &mut conn,
+            json!([{
+                "id": "legacy",
+                "name": "Legacy",
+                "description": "",
+                "prompt": "Prompt",
+                "enabled": true
+            }]),
+        )
+        .expect("save legacy agent payload");
+        assert_eq!(
+            conn.query_row(
+                "SELECT available_to_subagents FROM agent_prompt_templates WHERE template_id = 'legacy'",
+                [],
+                |row| row.get::<_, i64>(0),
+            )
+            .expect("query legacy availability"),
+            1
+        );
+
+        let error = save_agents(
+            &mut conn,
+            json!([{
+                "id": "invalid",
+                "name": "Invalid",
+                "description": "",
+                "prompt": "Prompt",
+                "enabled": false,
+                "availableToSubagents": "yes"
+            }]),
+        )
+        .expect_err("reject invalid subagent availability");
+        assert!(error.contains("availableToSubagents 必须是布尔值"));
+    }
+
     /// 归一后的 systemProxy 默认值（save/load 全量断言共用）。
     fn default_system_proxy_json() -> Value {
         json!({
diff --git a/crates/agent-gui/src/i18n/config.ts b/crates/agent-gui/src/i18n/config.ts
index 1d5a9014a..a9820ad3c 100644
--- a/crates/agent-gui/src/i18n/config.ts
+++ b/crates/agent-gui/src/i18n/config.ts
@@ -1671,6 +1671,9 @@ export const translations: Record<Locale, Record<string, string>> = {
     "settings.agentsShowPrompt": "查看 Prompt",
     "settings.agentsReady": "可以保存",
     "settings.agentsRequired": "名称和 Prompt 为必填项",
+    "settings.agentsSubagentTemplates": "子代理模板",
+    "settings.agentsSubagentTemplatesHint":
+      "选择可供子代理按需引用的模板，可同时选择多个；不会改变主代理当前激活的模板。",
 
     /* ── Settings SSH ── */
     "settings.sshTitle": "SSH",
@@ -4002,6 +4005,9 @@ export const translations: Record<Locale, Record<string, string>> = {
     "settings.agentsShowPrompt": "View Prompt",
     "settings.agentsReady": "Ready to save",
     "settings.agentsRequired": "Name and Prompt are required",
+    "settings.agentsSubagentTemplates": "Subagent Templates",
+    "settings.agentsSubagentTemplatesHint":
+      "Choose templates that subagents may reference. Multiple templates can be selected without changing the active main-agent template.",
 
     /* ── Settings SSH ── */
     "settings.sshTitle": "SSH",
diff --git a/crates/agent-gui/src/lib/settings/index.ts b/crates/agent-gui/src/lib/settings/index.ts
index d924432fc..aee14bd6e 100644
--- a/crates/agent-gui/src/lib/settings/index.ts
+++ b/crates/agent-gui/src/lib/settings/index.ts
@@ -264,6 +264,7 @@ export type AgentPromptTemplate = {
   description: string;
   prompt: string;
   enabled: boolean;
+  availableToSubagents: boolean;
 };
 
 export type SshAuthType = "password" | "privateKey" | "keyboardInteractive";
@@ -1465,6 +1466,10 @@ export function normalizeAgentPromptTemplate(input: unknown): AgentPromptTemplat
     description: normalizeOptionalText(obj.description),
     prompt: normalizeOptionalText(obj.prompt),
     enabled: obj.enabled === true,
+    availableToSubagents:
+      typeof obj.availableToSubagents === "boolean"
+        ? obj.availableToSubagents
+        : obj.enabled === true,
   };
 }
 
diff --git a/crates/agent-gui/src/lib/subagents/agentTool.ts b/crates/agent-gui/src/lib/subagents/agentTool.ts
index c1dffa32e..0e0be897c 100644
--- a/crates/agent-gui/src/lib/subagents/agentTool.ts
+++ b/crates/agent-gui/src/lib/subagents/agentTool.ts
@@ -73,7 +73,7 @@ const AGENT_PARAMETERS = Type.Object(
           template: Type.Optional(
             Type.String({
               description:
-                "Enabled AGENTS template id or name. Only valid when the id is first created.",
+                "AGENTS template id or name available to subagents. Only valid when the id is first created.",
             }),
           ),
           mode: Type.Optional(
@@ -241,10 +241,10 @@ export function createSubagentTools(params: {
       "Subagents cannot call Agent recursively. Worktree mode must not modify global LiveAgent settings, MCP server configuration, cron tasks, or user-level skills.",
       "Subagents communicate through SendMessage (to=parent is parent-private; to=* is a shared broadcast); do not use workspace files as a message channel.",
       "Include the new user request and any parent-conversation context each subagent needs in that agent's prompt. The parent conversation is not copied automatically.",
-      "Invalid calls start no agents and return a structured error listing the roster and enabled templates — fix every issue and retry with one corrected call.",
+      "Invalid calls start no agents and return a structured error listing the roster and templates available to subagents — fix every issue and retry with one corrected call.",
       "Existing agents that may be resumed by id:",
       formatRoster(rosterEntries),
-      "Enabled AGENTS templates (reference by template=<id>):",
+      "AGENTS templates available to subagents (reference by template=<id>):",
       formatTemplates(templateEntries),
     ].join("\n"),
     parameters: AGENT_PARAMETERS,
diff --git a/crates/agent-gui/src/lib/subagents/errors.ts b/crates/agent-gui/src/lib/subagents/errors.ts
index 974b218ff..da3b1daa8 100644
--- a/crates/agent-gui/src/lib/subagents/errors.ts
+++ b/crates/agent-gui/src/lib/subagents/errors.ts
@@ -98,7 +98,7 @@ export function renderBatchRejectionText(params: {
   if (params.templates.length > 0) {
     lines.push(
       "",
-      "Enabled templates (reference by template=<id>):",
+      "Templates available to subagents (reference by template=<id>):",
       ...params.templates.map((entry) => {
         const description = entry.description ? ` - ${entry.description}` : "";
         return `- ${entry.id} (${entry.name})${description}`;
diff --git a/crates/agent-gui/src/lib/subagents/roster.ts b/crates/agent-gui/src/lib/subagents/roster.ts
index 934f379a9..19543d2cb 100644
--- a/crates/agent-gui/src/lib/subagents/roster.ts
+++ b/crates/agent-gui/src/lib/subagents/roster.ts
@@ -90,7 +90,7 @@ export function formatRoster(entries: SubagentRosterEntry[]) {
 
 /** Template block embedded in the Agent tool description. */
 export function formatTemplates(entries: SubagentTemplateEntry[]) {
-  if (entries.length === 0) return "No enabled AGENTS templates are available.";
+  if (entries.length === 0) return "No AGENTS templates are available to subagents.";
   return entries
     .slice(0, MAX_LISTED_AGENTS)
     .map((entry) => {
diff --git a/crates/agent-gui/src/lib/subagents/validate.ts b/crates/agent-gui/src/lib/subagents/validate.ts
index 60556dbef..0e13ad9cd 100644
--- a/crates/agent-gui/src/lib/subagents/validate.ts
+++ b/crates/agent-gui/src/lib/subagents/validate.ts
@@ -241,7 +241,7 @@ export function parseSubagentBatch(
         issues.push(
           issue(
             "unknown_template",
-            `Unknown template "${templateRef}". Only enabled AGENTS templates can be referenced.`,
+            `Unknown template "${templateRef}". Only AGENTS templates available to subagents can be referenced.`,
             agentRef,
           ),
         );
diff --git a/crates/agent-gui/src/pages/chat/turns/runAgentConversationTurn.ts b/crates/agent-gui/src/pages/chat/turns/runAgentConversationTurn.ts
index 41c03c475..eb4698b44 100644
--- a/crates/agent-gui/src/pages/chat/turns/runAgentConversationTurn.ts
+++ b/crates/agent-gui/src/pages/chat/turns/runAgentConversationTurn.ts
@@ -181,10 +181,12 @@ function finishAgentPerfSpan(
   return durationMs;
 }
 
-// Only enabled, non-empty templates are resolvable from Agent calls.
-function enabledSubagentTemplates(agentTemplates: AppSettings["agents"]): SubagentTemplate[] {
+// Only templates selected for subagents and carrying a non-empty prompt are resolvable from Agent calls.
+export function availableSubagentTemplates(
+  agentTemplates: AppSettings["agents"],
+): SubagentTemplate[] {
   return (agentTemplates ?? [])
-    .filter((template) => template.enabled && template.prompt.trim())
+    .filter((template) => template.availableToSubagents && template.prompt.trim())
     .map((template) => ({
       id: template.id,
       name: template.name,
@@ -430,7 +432,7 @@ export async function runAgentConversationTurn(params: RunAgentConversationTurnP
           model,
           runtime,
           sessionId,
-          templates: enabledSubagentTemplates(agentTemplates),
+          templates: availableSubagentTemplates(agentTemplates),
           store: subagentStore,
           scheduler: subagentScheduler,
         }
diff --git a/crates/agent-gui/src/pages/settings/AgentPromptTemplateModal.tsx b/crates/agent-gui/src/pages/settings/AgentPromptTemplateModal.tsx
index 9768844b9..9b26dd583 100644
--- a/crates/agent-gui/src/pages/settings/AgentPromptTemplateModal.tsx
+++ b/crates/agent-gui/src/pages/settings/AgentPromptTemplateModal.tsx
@@ -10,9 +10,11 @@ import { useLocale } from "../../i18n";
 import type { AgentPromptTemplate } from "../../lib/settings";
 import { useModalMotion } from "../../lib/shared/modalMotion";
 
+type AgentPromptTemplateContent = Pick<AgentPromptTemplate, "name" | "description" | "prompt">;
+
 type AgentPromptTemplateModalProps = {
   initialData?: AgentPromptTemplate;
-  onSave: (data: Omit<AgentPromptTemplate, "id" | "enabled">) => void;
+  onSave: (data: AgentPromptTemplateContent) => void;
   onClose: () => void;
 };
 
diff --git a/crates/agent-gui/src/pages/settings/AgentsSection.tsx b/crates/agent-gui/src/pages/settings/AgentsSection.tsx
index 6cb22b458..518d1a090 100644
--- a/crates/agent-gui/src/pages/settings/AgentsSection.tsx
+++ b/crates/agent-gui/src/pages/settings/AgentsSection.tsx
@@ -1,6 +1,18 @@
+import { Popover } from "@base-ui/react";
 import { useState } from "react";
 import { createPortal } from "react-dom";
-import { BookOpen, Eye, FileText, Pencil, Plus, Trash2, X } from "../../components/icons";
+import {
+  BookOpen,
+  Bot,
+  Check,
+  ChevronDown,
+  Eye,
+  FileText,
+  Pencil,
+  Plus,
+  Trash2,
+  X,
+} from "../../components/icons";
 
 import { Button } from "../../components/ui/button";
 import { useLocale } from "../../i18n";
@@ -33,7 +45,7 @@ export function AgentsSection(props: SettingsSectionProps) {
     setEditingTemplate(null);
   }
 
-  function handleSave(data: Omit<AgentPromptTemplate, "id" | "enabled">) {
+  function handleSave(data: Pick<AgentPromptTemplate, "name" | "description" | "prompt">) {
     setSettings((prev) => {
       if (editingTemplate) {
         return updateAgents(
@@ -48,6 +60,7 @@ export function AgentsSection(props: SettingsSectionProps) {
         id: createUuid(),
         ...data,
         enabled: false,
+        availableToSubagents: false,
       };
       return updateAgents(prev, [...prev.agents, newTemplate]);
     });
@@ -76,8 +89,24 @@ export function AgentsSection(props: SettingsSectionProps) {
     );
   }
 
+  function handleToggleAvailableToSubagents(id: string) {
+    setSettings((prev) =>
+      updateAgents(
+        prev,
+        prev.agents.map((template) =>
+          template.id === id
+            ? { ...template, availableToSubagents: !template.availableToSubagents }
+            : template,
+        ),
+      ),
+    );
+  }
+
   const templates = settings.agents;
   const enabledCount = templates.filter((template) => template.enabled).length;
+  const subagentTemplateCount = templates.filter(
+    (template) => template.availableToSubagents,
+  ).length;
 
   return (
     <>
@@ -112,6 +141,13 @@ export function AgentsSection(props: SettingsSectionProps) {
                 ) : null}
               </div>
             ) : null}
+            {templates.length > 0 ? (
+              <SubagentTemplatePicker
+                templates={templates}
+                selectedCount={subagentTemplateCount}
+                onToggle={handleToggleAvailableToSubagents}
+              />
+            ) : null}
             <Button variant="outline" size="sm" className="gap-1.5" onClick={openAdd}>
               <Plus className="h-3.5 w-3.5" />
               {t("settings.agentsAdd")}
@@ -245,6 +281,100 @@ export function AgentsSection(props: SettingsSectionProps) {
   );
 }
 
+function SubagentTemplatePicker(props: {
+  templates: AgentPromptTemplate[];
+  selectedCount: number;
+  onToggle: (id: string) => void;
+}) {
+  const { templates, selectedCount, onToggle } = props;
+  const { t } = useLocale();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger
+        render={
+          <Button
+            variant="outline"
+            size="sm"
+            className="gap-1.5"
+            aria-label={t("settings.agentsSubagentTemplates")}
+          />
+        }
+      >
+        <Bot className="h-3.5 w-3.5" />
+        <span>{t("settings.agentsSubagentTemplates")}</span>
+        <span className="rounded-full bg-sky-500/10 px-1.5 py-0.5 text-[10px] font-semibold tabular-nums text-sky-600 dark:text-sky-400">
+          {selectedCount}
+        </span>
+        <ChevronDown
+          className={`h-3.5 w-3.5 text-muted-foreground transition-transform ${open ? "rotate-180" : ""}`}
+        />
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Positioner
+          side="bottom"
+          align="end"
+          sideOffset={6}
+          collisionPadding={8}
+          className="z-[9999]"
+        >
+          <Popover.Popup
+            aria-label={t("settings.agentsSubagentTemplates")}
+            className="w-[min(22rem,calc(100vw-1rem))] overflow-hidden rounded-xl border bg-popover text-popover-foreground shadow-lg outline-none"
+          >
+            <div className="border-b border-border/60 px-3 py-2.5">
+              <p className="text-xs font-semibold">{t("settings.agentsSubagentTemplates")}</p>
+              <p className="mt-0.5 text-[11px] leading-relaxed text-muted-foreground">
+                {t("settings.agentsSubagentTemplatesHint")}
+              </p>
+            </div>
+            <div className="max-h-72 space-y-1 overflow-y-auto p-1.5">
+              {templates.map((template) => {
+                const checked = template.availableToSubagents;
+                return (
+                  <label
+                    key={template.id}
+                    className={`flex w-full cursor-pointer items-start gap-2.5 rounded-lg px-2.5 py-2 text-left transition-colors hover:bg-muted/70 focus-within:ring-2 focus-within:ring-ring ${
+                      checked ? "bg-sky-500/[0.07]" : ""
+                    }`}
+                  >
+                    <input
+                      type="checkbox"
+                      checked={checked}
+                      className="sr-only"
+                      onChange={() => onToggle(template.id)}
+                    />
+                    <span
+                      className={`mt-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded border transition-colors ${
+                        checked
+                          ? "border-sky-500 bg-sky-500 text-white"
+                          : "border-border bg-background"
+                      }`}
+                    >
+                      {checked ? <Check className="h-3 w-3" /> : null}
+                    </span>
+                    <span className="min-w-0 flex-1">
+                      <span className="block truncate text-xs font-medium text-foreground">
+                        {template.name}
+                      </span>
+                      {template.description ? (
+                        <span className="mt-0.5 block line-clamp-2 text-[11px] leading-relaxed text-muted-foreground">
+                          {template.description}
+                        </span>
+                      ) : null}
+                    </span>
+                  </label>
+                );
+              })}
+            </div>
+          </Popover.Popup>
+        </Popover.Positioner>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}
+
 type AgentPromptViewModalProps = {
   template: AgentPromptTemplate;
   onClose: () => void;
diff --git a/crates/agent-gui/test/chat/agent-turn-cancelled-history.test.mjs b/crates/agent-gui/test/chat/agent-turn-cancelled-history.test.mjs
index ea712995c..84603ddfd 100644
--- a/crates/agent-gui/test/chat/agent-turn-cancelled-history.test.mjs
+++ b/crates/agent-gui/test/chat/agent-turn-cancelled-history.test.mjs
@@ -150,7 +150,7 @@ const loader = createTsModuleLoader({
   },
 });
 
-const { runAgentConversationTurn } = loader.loadModule(
+const { runAgentConversationTurn, availableSubagentTemplates } = loader.loadModule(
   "src/pages/chat/turns/runAgentConversationTurn.ts",
 );
 const conversationState = loader.loadModule("src/lib/chat/conversation/conversationState.ts");
@@ -168,6 +168,59 @@ function createHookLifecycle() {
   };
 }
 
+test("subagent templates use independent availability instead of main-agent activation", () => {
+  assert.deepEqual(
+    availableSubagentTemplates([
+      {
+        id: "main-only",
+        name: "Main only",
+        description: "",
+        prompt: "Main prompt",
+        enabled: true,
+        availableToSubagents: false,
+      },
+      {
+        id: "child-a",
+        name: "Child A",
+        description: "First child template",
+        prompt: "Child prompt A",
+        enabled: false,
+        availableToSubagents: true,
+      },
+      {
+        id: "child-b",
+        name: "Child B",
+        description: "Second child template",
+        prompt: "Child prompt B",
+        enabled: false,
+        availableToSubagents: true,
+      },
+      {
+        id: "empty",
+        name: "Empty",
+        description: "",
+        prompt: "   ",
+        enabled: false,
+        availableToSubagents: true,
+      },
+    ]),
+    [
+      {
+        id: "child-a",
+        name: "Child A",
+        description: "First child template",
+        prompt: "Child prompt A",
+      },
+      {
+        id: "child-b",
+        name: "Child B",
+        description: "Second child template",
+        prompt: "Child prompt B",
+      },
+    ],
+  );
+});
+
 test("agent turn preserves suppressed parent Agent trace for cancellation persistence", async () => {
   let liveRounds = [];
   const progressUpdates = [];
diff --git a/crates/agent-gui/test/settings/normalization.test.mjs b/crates/agent-gui/test/settings/normalization.test.mjs
index 6396fc646..236bd5e91 100644
--- a/crates/agent-gui/test/settings/normalization.test.mjs
+++ b/crates/agent-gui/test/settings/normalization.test.mjs
@@ -2104,23 +2104,67 @@ test("web storage redaction clears ssh secrets but keeps configured state", () =
   assert.equal(redacted.ssh.hosts[0].proxy.passwordConfigured, true);
 });
 
-test("only one agent prompt template remains enabled after normalization", () => {
+test("main-agent activation stays single-select while subagent templates remain multi-select", () => {
   const agents = settings.normalizeAgentPromptTemplates([
-    { id: "a", name: "A", prompt: "Prompt A", enabled: true },
-    { id: "b", name: "B", prompt: "Prompt B", enabled: true },
-    { id: "c", name: "C", prompt: "Prompt C", enabled: false },
+    {
+      id: "a",
+      name: "A",
+      prompt: "Prompt A",
+      enabled: true,
+      availableToSubagents: true,
+    },
+    {
+      id: "b",
+      name: "B",
+      prompt: "Prompt B",
+      enabled: true,
+      availableToSubagents: true,
+    },
+    {
+      id: "c",
+      name: "C",
+      prompt: "Prompt C",
+      enabled: false,
+      availableToSubagents: false,
+    },
   ]);
 
   assert.deepEqual(
-    agents.map((agent) => [agent.id, agent.enabled]),
+    agents.map((agent) => [agent.id, agent.enabled, agent.availableToSubagents]),
     [
-      ["a", true],
-      ["b", false],
-      ["c", false],
+      ["a", true, true],
+      ["b", false, true],
+      ["c", false, false],
     ],
   );
 });
 
+test("legacy agent templates default subagent availability from main activation", () => {
+  const enabledLegacy = settings.normalizeAgentPromptTemplate({
+    id: "legacy-enabled",
+    name: "Legacy Enabled",
+    prompt: "Prompt",
+    enabled: true,
+  });
+  const disabledLegacy = settings.normalizeAgentPromptTemplate({
+    id: "legacy-disabled",
+    name: "Legacy Disabled",
+    prompt: "Prompt",
+    enabled: false,
+  });
+  const explicitlyUnavailable = settings.normalizeAgentPromptTemplate({
+    id: "explicit",
+    name: "Explicit",
+    prompt: "Prompt",
+    enabled: true,
+    availableToSubagents: false,
+  });
+
+  assert.equal(enabledLegacy.availableToSubagents, true);
+  assert.equal(disabledLegacy.availableToSubagents, false);
+  assert.equal(explicitlyUnavailable.availableToSubagents, false);
+});
+
 test("mcp and remote settings normalize transport, selection, ports, and tokens", () => {
   const mcp = settings.normalizeMcpSettings({
     servers: [
diff --git a/crates/agent-gui/test/subagents/agent-tool.test.mjs b/crates/agent-gui/test/subagents/agent-tool.test.mjs
index 49aa9416c..f2e62f049 100644
--- a/crates/agent-gui/test/subagents/agent-tool.test.mjs
+++ b/crates/agent-gui/test/subagents/agent-tool.test.mjs
@@ -519,7 +519,7 @@ test("unknown template rejects the batch before any agent starts", async () => {
   assert.equal(result.isError, true);
   assert.equal(result.details.status, "rejected");
   assert.equal(result.details.issues[0].code, "unknown_template");
-  assert.match(result.content[0].text, /Enabled templates/);
+  assert.match(result.content[0].text, /Templates available to subagents/);
   assert.equal(harness.runnerCalls.length, 0);
 });
 
diff --git a/crates/agent-gui/test/subagents/bus-roster.test.mjs b/crates/agent-gui/test/subagents/bus-roster.test.mjs
index 8f376a04e..2940918d4 100644
--- a/crates/agent-gui/test/subagents/bus-roster.test.mjs
+++ b/crates/agent-gui/test/subagents/bus-roster.test.mjs
@@ -159,7 +159,10 @@ test("formatRoster and formatTemplates render bounded description blocks", () =>
   }));
   assert.equal(roster.formatRoster(manyEntries).split("\n").length, 12);
 
-  assert.equal(roster.formatTemplates([]), "No enabled AGENTS templates are available.");
+  assert.equal(
+    roster.formatTemplates([]),
+    "No AGENTS templates are available to subagents.",
+  );
   assert.equal(
     roster.formatTemplates([
       { id: "reviewer", name: "Reviewer", description: "Review code" },
diff --git a/crates/agent-gui/test/subagents/validate.test.mjs b/crates/agent-gui/test/subagents/validate.test.mjs
index af0b9bad7..7ac80b5c0 100644
--- a/crates/agent-gui/test/subagents/validate.test.mjs
+++ b/crates/agent-gui/test/subagents/validate.test.mjs
@@ -120,7 +120,7 @@ test("duplicate agent ids are rejected case-insensitively", () => {
   assert.match(result.issues[0].message, /Duplicate agent id "expert-a"/);
 });
 
-test("unknown template is rejected; enabled templates resolve by id or name case-insensitively", () => {
+test("unknown template is rejected; available templates resolve by id or name case-insensitively", () => {
   const bad = parse({ agents: [{ id: "a", prompt: "ok", template: "ghost" }] });
   assert.deepEqual(issueCodes(bad), ["unknown_template"]);
   assert.match(bad.issues[0].message, /Unknown template "ghost"/);
diff --git a/crates/agent-gui/test/tools/builtin-registry-subagent-mcp.test.mjs b/crates/agent-gui/test/tools/builtin-registry-subagent-mcp.test.mjs
index 27547be06..239253279 100644
--- a/crates/agent-gui/test/tools/builtin-registry-subagent-mcp.test.mjs
+++ b/crates/agent-gui/test/tools/builtin-registry-subagent-mcp.test.mjs
@@ -170,7 +170,7 @@ test("registry with a subagent runtime exposes Agent and the parent SendMessage"
   assert.ok(registry.hasTool("agent"));
 });
 
-test("Agent tool description embeds the hydrated roster and enabled templates", async () => {
+test("Agent tool description embeds the hydrated roster and available templates", async () => {
   const harness = createRegistryHarness();
   const storeIpc = createFakeStoreIpc();
   storeIpc.seedIdentity({