Added: Ability to hide subagents from primary agents.

packages/opencode/src/agent/agent.ts

@@ -17,12 +17,14 @@ export namespace Agent {
       topP: z.number().optional(),
       temperature: z.number().optional(),
       color: z.string().optional(),
+      visible: z.boolean().optional(),
       permission: z.object({
         edit: Config.Permission,
         bash: z.record(z.string(), Config.Permission),
         webfetch: Config.Permission.optional(),
         doom_loop: Config.Permission.optional(),
         external_directory: Config.Permission.optional(),
+        task: z.record(z.string(), Config.Permission).optional(),
       }),
       model: z
         .object({
@@ -195,6 +197,7 @@ export namespace Agent {
         permission,
         color,
         maxSteps,
+        visible,
         ...extra
       } = value
       item.options = {
@@ -217,6 +220,7 @@ export namespace Agent {
       if (top_p != undefined) item.topP = top_p
       if (mode) item.mode = mode
       if (color) item.color = color
+      if (visible != undefined) item.visible = visible
       // just here for consistency & to prevent it from being added as an option
       if (name) item.name = name
       if (maxSteps != undefined) item.maxSteps = maxSteps
@@ -303,12 +307,25 @@ function mergeAgentPermissions(basePermission: any, overridePermission: any): Ag
     }
   }
 
+  let mergedTask
+  if (merged.task) {
+    if (typeof merged.task === "object") {
+      mergedTask = mergeDeep(
+        {
+          "*": "allow",
+        },
+        merged.task,
+      )
+    }
+  }
+
   const result: Agent.Info["permission"] = {
     edit: merged.edit ?? "allow",
     webfetch: merged.webfetch ?? "allow",
     bash: mergedBash ?? { "*": "allow" },
     doom_loop: merged.doom_loop,
     external_directory: merged.external_directory,
+    task: mergedTask,
   }
 
   return result

packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx

@@ -182,9 +182,9 @@ export function Autocomplete(props: {
   )
 
   const agents = createMemo(() => {
-    const agents = sync.data.agent
-    return agents
+    return sync.data.agent
       .filter((agent) => !agent.builtIn && agent.mode !== "primary")
+      .filter((agent) => agent.visible !== false)
       .map(
         (agent): AutocompleteOption => ({
           display: "@" + agent.name,

packages/opencode/src/config/config.ts

@@ -392,6 +392,10 @@ export namespace Config {
       disable: z.boolean().optional(),
       description: z.string().optional().describe("Description of when to use the agent"),
       mode: z.enum(["subagent", "primary", "all"]).optional(),
+      visible: z
+        .boolean()
+        .optional()
+        .describe("Whether this subagent appears in the agent menu (default: true, only applies to mode: subagent)"),
       color: z
         .string()
         .regex(/^#[0-9a-fA-F]{6}$/, "Invalid hex color format")
@@ -410,6 +414,7 @@ export namespace Config {
           webfetch: Permission.optional(),
           doom_loop: Permission.optional(),
           external_directory: Permission.optional(),
+          task: z.record(z.string(), Permission).optional(),
         })
         .optional(),
     })

packages/opencode/src/session/prompt.ts

@@ -48,7 +48,7 @@ import { Config } from "../config/config"
 import { NamedError } from "@opencode-ai/util/error"
 import { fn } from "@/util/fn"
 import { SessionProcessor } from "./processor"
-import { TaskTool } from "@/tool/task"
+import { TaskTool, filterSubagents, TASK_DESCRIPTION } from "@/tool/task"
 import { SessionStatus } from "./status"
 
 // @ts-ignore
@@ -483,12 +483,17 @@ export namespace SessionPrompt {
         system: lastUser.system,
         isLastStep,
       })
+      const userInvokedAgents = msgs
+        .filter((m) => m.info.role === "user")
+        .flatMap((m) => m.parts.filter((p) => p.type === "agent") as MessageV2.AgentPart[])
+        .map((p) => p.name)
       const tools = await resolveTools({
         agent,
         sessionID,
         model,
         tools: lastUser.tools,
         processor,
+        userInvokedAgents,
       })
       const provider = await Provider.getProvider(model.providerID)
       const params = await Plugin.trigger(
@@ -705,6 +710,7 @@ export namespace SessionPrompt {
     sessionID: string
     tools?: Record<string, boolean>
     processor: SessionProcessor.Info
+    userInvokedAgents: string[]
   }) {
     const tools: Record<string, AITool> = {}
     const enabledTools = pipe(
@@ -736,7 +742,7 @@ export namespace SessionPrompt {
             abort: options.abortSignal!,
             messageID: input.processor.message.id,
             callID: options.toolCallId,
-            extra: { model: input.model },
+            extra: { model: input.model, userInvokedAgents: input.userInvokedAgents },
             agent: input.agent.name,
             metadata: async (val) => {
               const match = input.processor.partFromToolCall(options.toolCallId)
@@ -841,6 +847,23 @@ export namespace SessionPrompt {
       }
       tools[key] = item
     }
+
+    // Regenerate task tool description with filtered subagents
+    if (tools.task) {
+      const all = await Agent.list().then((x) => x.filter((a) => a.mode !== "primary"))
+      const filtered = filterSubagents(all, input.agent.permission.task ?? {})
+      const description = TASK_DESCRIPTION.replace(
+        "{agents}",
+        filtered
+          .map((a) => `- ${a.name}: ${a.description ?? "This subagent should only be called manually by the user."}`)
+          .join("\n"),
+      )
+      tools.task = {
+        ...tools.task,
+        description,
+      }
+    }
+
     return tools
   }
 
@@ -1075,6 +1098,8 @@ export namespace SessionPrompt {
         }
 
         if (part.type === "agent") {
+          const perm = Wildcard.all(part.name, agent.permission.task ?? {})
+          const hint = perm === "deny" ? " . Invoked by user; guaranteed to exist." : ""
           return [
             {
               id: Identifier.ascending("part"),
@@ -1089,8 +1114,11 @@ export namespace SessionPrompt {
               type: "text",
               synthetic: true,
               text:
-                "Use the above message and context to generate a prompt and call the task tool with subagent: " +
-                part.name,
+                // An extra space is added here. Otherwise the 'Use' gets appended 
+                // to user's last word; making a combined word
+                " Use the above message and context to generate a prompt and call the task tool with subagent: " +
+                part.name +
+                hint,
             },
           ]
         }

packages/opencode/src/tool/task.ts

@@ -9,6 +9,14 @@ import { Agent } from "../agent/agent"
 import { SessionPrompt } from "../session/prompt"
 import { iife } from "@/util/iife"
 import { defer } from "@/util/defer"
+import { Wildcard } from "@/util/wildcard"
+import { Permission } from "../permission"
+
+export { DESCRIPTION as TASK_DESCRIPTION }
+
+export function filterSubagents(agents: Agent.Info[], permissions: Record<string, Config.Permission>) {
+  return agents.filter((a) => Wildcard.all(a.name, permissions) !== "deny")
+}
 import { Config } from "../config/config"
 
 export const TaskTool = Tool.define("task", async () => {
@@ -30,6 +38,31 @@ export const TaskTool = Tool.define("task", async () => {
     async execute(params, ctx) {
       const agent = await Agent.get(params.subagent_type)
       if (!agent) throw new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`)
+      const calling = await Agent.get(ctx.agent)
+      if (calling) {
+        const userInvokedAgents = (ctx.extra?.userInvokedAgents ?? []) as string[]
+        // Skip permission check if user explicitly invoked this agent via @ autocomplete
+        if (!userInvokedAgents.includes(params.subagent_type)) {
+          const perm = Wildcard.all(params.subagent_type, calling.permission.task ?? {})
+          if (perm === "deny") {
+            throw new Error(`Agent '${params.subagent_type}' is not available to ${ctx.agent}`)
+          }
+          if (perm === "ask") {
+            await Permission.ask({
+              type: "task",
+              title: `Invoke subagent: ${params.subagent_type}`,
+              pattern: params.subagent_type,
+              callID: ctx.callID,
+              sessionID: ctx.sessionID,
+              messageID: ctx.messageID,
+              metadata: {
+                subagent: params.subagent_type,
+                description: params.description,
+              },
+            })
+          }
+        }
+      }
       const session = await iife(async () => {
         if (params.session_id) {
           const found = await Session.get(params.session_id).catch(() => {})