From 5279226171fc17cf3d72492f678acc3824297896 Mon Sep 17 00:00:00 2001
From: marius-kilocode <marius@kilocode.ai>
Date: Mon, 24 Aug 2026 17:57:10 +0200
Subject: [PATCH] docs(agent-manager): clarify pending question blockers

---
 packages/opencode/src/kilocode/tool/agent-manager.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/opencode/src/kilocode/tool/agent-manager.txt b/packages/opencode/src/kilocode/tool/agent-manager.txt
index 42b2584439..1d081b91df 100644
--- a/packages/opencode/src/kilocode/tool/agent-manager.txt
+++ b/packages/opencode/src/kilocode/tool/agent-manager.txt
@@ -4,6 +4,8 @@ Use `action: "list"` to inspect the Agent Manager overview, `action: "prompt"` t
 
 A session waiting on a question reports `attention: ["question"]` in the list output and refuses prompts; a failed prompt names the target session ID, the pending question with its ID, text, and option labels. Use those exact IDs in the answer call. Answer it with `{ "action": "answer", "sessionID": "<id>", "answers": [["<label>"]] }`, providing one label array per question of the request in order and matching the advertised option labels exactly. Omit `questionID` only when that error or a prior answer error shows exactly one pending question; otherwise pass the ID it names. If the question was already answered by a person, the call fails instead of overwriting, and the reported state is stale rather than wrong. Treat answering as consequential: questions such as plan approval ("Ready to implement?") start implementation when answered affirmatively. Never guess labels for options you have not seen; if the pending question's text is unknown, prompt once to surface it in the error before answering.
 
+Permission blockers are separate from questions: a session may report `attention: ["permission"]`; resolve that request in Agent Manager before prompting. The `answer` action resolves questions only and requires its own `answer` permission approval.
+
 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. 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.