fix(cli): require explicit user intent before starting Agent Manager sessions or worktrees

.changeset/agent-session-explicit-intent.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Tune the `agent_manager` and `task` tool instructions so agents only start new Agent Manager sessions or worktrees when the user explicitly asks, or after confirming with the user first.

packages/opencode/src/kilocode/tool/agent-manager.txt

@@ -10,7 +10,7 @@ Permission blockers are separate from questions: a session may report `attention
 
 For any assignment request, the required sequence is: (1) call `agent_manager` with `{ "action": "list" }`; (2) read the returned `sections[].id`, `sections[].worktrees[].session.id` or `sessions[].id`, and `ungrouped[].session.id` or `sessions[].sessions[].id`; (3) call `agent_manager` with `{ "action": "move", "sessionID": "<returned session id>", "sectionID": "<returned section id>" }` once for each worktree; (4) use `sectionID: null` to unassign. Never invent IDs, use section names instead of IDs, or edit `.kilo/agent-manager.json`. The `list` result is the source of truth for IDs and assignments: each `sections` entry includes the section `id`, name, and its assigned `worktrees`; each worktree includes its worktree `id` and its session ID(s) in `session` or `sessions`; `ungrouped` lists worktrees that have no section; and `local.sessions` lists local sessions that cannot be assigned to a section. For `move`, pass the target session's ID as `sessionID` and a section ID as `sectionID`; pass `null` to unassign it. Optional filters can narrow by section ID or by `idle`, `busy`, `retry`, `offline`, or `waiting` state. Prompting, stopping, and moving are targeted only: they do not broadcast or create sessions, and prompting does not wait for the target to finish. Prompts to busy or retrying sessions are queued behind active work instead of rejected; you do not need to wait for idle before prompting. Moving a session moves its whole worktree, including multi-version siblings; local sessions cannot be assigned to a section.
 
-To start sessions, keep using the existing `mode` and `tasks` input without an action. Use start mode when the user explicitly asks you to fan out work into Agent Manager, create Agent Manager worktrees, or start multiple Agent Manager sessions for independent tasks.
+To start sessions, keep using the existing `mode` and `tasks` input without an action. Only use start mode when the user explicitly asks you to fan out work into Agent Manager, create Agent Manager worktrees, or start multiple Agent Manager sessions, or after you have confirmed with the user first. Never start Agent Manager sessions on your own initiative just to parallelize, delegate, or organize routine work; starting sessions is user-visible and each worktree costs disk space and tokens.
 
 Modes:
 - `worktree`: creates a new Agent Manager git worktree for each task, like the New Worktree dialog.
@@ -22,4 +22,4 @@ By default, multiple tasks are started as independent Agent Manager sessions. Se
 
 If available, use `kilo_local_recall` only if you need context from a completed Agent Manager session.
 
-Do not use this for ordinary subagent research. Use the `task` tool for internal subagents, and use this only when the user wants visible Agent Manager sessions in the extension.
+Do not use this for ordinary subagent research. Use the `task` tool for internal subagents. Starting sessions here creates user-visible worktrees and interactive sessions in the extension, so reserve it for explicit user requests; if the user has not asked for new sessions or worktrees and you believe they would help, ask the user before starting them.

packages/opencode/src/kilocode/tool/task.ts

@@ -35,6 +35,9 @@ const ModelState = z
   .passthrough()
 
 export namespace KiloTask {
+  export const usageDescription =
+    "Subagents launched with this tool are internal to the current session: they do not create worktrees or interactive sessions, and only their final report returns to you. Routine subtask decomposition is expected and does not need user confirmation. Do not confuse this with agent_manager: starting Agent Manager sessions or worktrees is user-visible and requires an explicit user request, or you must confirm with the user first."
+
   export const ModelFields = {
     model: Schema.optional(Schema.NullOr(Schema.String)).annotate({
       description:

packages/opencode/src/tool/task.ts

@@ -529,6 +529,7 @@ export const TaskTool = Tool.define(
         return {
           description: [
             DESCRIPTION,
+            KiloTask.usageDescription, // kilocode_change - distinguish internal subagents from user-visible Agent Manager sessions
             ...(flags.experimentalBackgroundSubagents ? [BACKGROUND_DESCRIPTION] : []),
             ...(selection ? [KiloTask.modelDescription] : []),
           ].join("\n\n"),