Activity

1. github-actions

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   on Jun 12, 2026
2. github-actions commented on Jun 12, 2026

   

   github-actionsbot

   on Jun 12, 2026 – with GitHub Actions

   Contributor

   More actions

   Thanks for the detailed report and the thorough evidence — this is a real documentation gap. Here's a summary of what we've identified:

   Documentation Gap Summary

   What is missing or unclear

   The Custom agents configuration → Tools → Tool aliases reference table does not clearly communicate per-host availability of each alias. Specifically:

   1. todo / TodoWrite host scope is understated. The table notes todo is "Not supported in cloud agent today, but supported by VS Code" — but it does not note that todo is also unavailable in the Copilot CLI (-p) and .NET/SDK sessions. The introductory text says the tools property applies "in GitHub.com, the Copilot CLI, and supported IDEs", which implies all aliases work in all those hosts. The reality is that todo silently resolves to nothing outside VS Code.

   2. No per-host built-in tool inventory for SDK sessions. GitHub.Copilot.BuiltInTools.Isolated returns 10 names (ask_user, task_complete, exit_plan_mode, task, read_agent, write_agent, list_agents, send_inbox, context_board, skill) that do not correspond to either the CLI -p tool set or the alias table. There is no documentation that explains which tool names are authoritative for SDK-hosted sessions, making it impossible to reason about what tools: filters will actually produce.

   Affected documentation

   Location	Problem
   docs.github.com/en/copilot/reference/custom-agents-configuration#tools — alias table	todo row should note it is VS Code only (not CLI or SDK)
   Same page, introductory tools property description	Should clarify that alias support varies by host, not uniform across all
   SDK README / reference (Node, .NET, etc.)	Should document the built-in tool surface available in SDK sessions so users understand what tools: filtering yields

   Suggested improvements

   • Alias table: add a "Hosts" or "Availability" column (or host-specific notes per row) so readers can immediately see that todo is VS Code-only, while execute, read, edit, search, agent, and web are available more broadly.
   • SDK docs: add a section listing the built-in tools available in each SDK host context (at minimum, the Isolated set), and explain how the tools: allowlist maps to those names.
   • tools property description: add a note that "All unrecognized tool names are silently ignored" applies per-host — so an alias valid in VS Code may resolve to nothing in CLI/SDK, producing no error but also no tool.

   The behavior you observed (silent drop, graceful model adaptation) is consistent with the documented "unrecognized names are ignored" rule — but without per-host clarity in the docs it reads as a bug rather than expected behavior. Clarifying this in the reference would set the right expectations and save others the same investigation.

   Generated by Documentation Handler for issue #1641 · sonnet46 476K · ◷
3. NiceAsiv commented on Jun 15, 2026

   

   NiceAsiv

   on Jun 15, 2026

   Last edited by NiceAsiv

   Author

   More actions

   Follow-ups: todo "missing" in .NET / SDK sessions

   I dug into this and want to share findings that I
   think resolve the confusion: this is not a bug, and the .NET SDK is not
   actually missing the ability to manage todos. The short version is that todo
   is not a standalone runtime tool — it's a UI concept rendered by interactive
   hosts (CLI TUI, VS Code) on top of a todos table that the agent manipulates
   through the sql / session_store_sql tools. Those tools are available in
   SDK / headless sessions, so todos work fine; you just don't get the rendered
   "Todo" panel.

   ---

   1. The headless tool surface (copilot -p, all SDKs)

   Asking the model to enumerate its tools in -p mode returns 21 tools. Crucially,
   this is identical across --mode interactive, --mode plan, and --plan — i.e.
   --mode / AgentMode does not change which tools are registered. There is no
   standalone todo / TodoWrite / update_plan, but sql and
   session_store_sql are both present:

   powershell, read_powershell, write_powershell, stop_powershell, list_powershell,
   view, create, edit, web_fetch, report_intent,
   fetch_copilot_cli_documentation, skill, sql, session_store_sql,
   read_agent, list_agents, write_agent, grep, glob, task,
   web_search, tool_search_tool_regex
   

   2. "todo" is the sql tool operating a todos table

   The repo's own docs/features/fleet-mode.md
   documents the schema and describes "SQL todos as the shared coordination state":

   CREATE TABLE todos (
       id TEXT PRIMARY KEY,
       title TEXT NOT NULL,
       description TEXT,
       status TEXT DEFAULT 'pending'
   );

   When I asked an agent (in the interactive TUI) how todos work, it answered
   verbatim:

   "Yes — todos work via the sql tool. The table is reachable and currently empty."

   3. Proof: a single todo creation in the .NET SDK

   Minimal .NET SDK session (bundled CLI, headless), subscribing to
   tool.execution_start, asking for a 3-item list:

   [tool] report_intent  {"intent":"Creating todo list"}
   [tool] sql            {"description":"Insert three todos",
                          "query":"INSERT INTO todos (id, title, status) VALUES
                            ('write-spec','Write spec','in_progress'), ('implement','Impl…"}
   

   Assistant: "I used the sql tool (the session SQLite todos table) to create
   the three todos and set 'Write spec' to in_progress."

   Verdict: used sql = ✅, used a dedicated todo tool = ❌.

   4. Proof: full multi-task lifecycle in the .NET SDK

   I then drove four todos through pending → in_progress → done, capturing every
   sql call and re-SELECTing the table after each change. All 19 calls were the
   sql tool — there is no separate todo tool anywhere in the trace:

   sql #	Statement	Table state after (id → status)
   #1	INSERT INTO todos … 4 rows ('pending')	all 4 = pending
   #2	SELECT id,title,status …	all pending
   #3	UPDATE … 'in_progress' WHERE id='write-spec'	write-spec=in_progress
   #5	UPDATE … 'done' WHERE id='write-spec'	write-spec=done
   #7	UPDATE … 'in_progress' WHERE id='implement'	implement=in_progress
   #9	UPDATE … 'done' WHERE id='implement'	implement=done
   #11	UPDATE … 'in_progress' WHERE id='test'	test=in_progress
   #13	UPDATE … 'done' WHERE id='test'	test=done
   #15	UPDATE … 'in_progress' WHERE id='release'	release=in_progress
   #17	UPDATE … 'done' WHERE id='release'	all 4 = done
   #19	SELECT status, COUNT(*) … GROUP BY status	done = 4

   Final assistant summary: "4 done."

   This is exactly the state machine documented in fleet-mode.md
   (pending -> in_progress -> done), observed programmatically via the SDK's tool
   events — the same underlying mechanism the TUI renders as its "Todo" panel.

   5. About BuiltInTools.Isolated

   BuiltInTools.Isolated (the 10-name list) is a curated safe subset for
   CopilotClientMode.Empty multi-tenant scenarios — session-only tools with no
   host FS / network / cross-session access. It is intentionally not the full
   SDK tool surface and shouldn't be compared against the CLI's 21-tool set or the
   docs alias table. Note sql / session_store_sql are deliberately excluded
   (they touch session storage), so in Empty mode you'd add them explicitly:

   var session = await client.CreateSessionAsync(new SessionConfig
   {
       EnableSessionStore = true,
       AvailableTools = new ToolSet()
           .AddBuiltIn(BuiltInTools.Isolated)
           .AddBuiltIn("sql")
           .AddBuiltIn("session_store_sql"),
   });

   ---

   Per-host summary

   Host	Mode	Dedicated todo tool	sql/session_store_sql	"Todo" panel	Todos work
   Interactive CLI (copilot)	TUI	no	yes	✅ rendered	✅
   VS Code Copilot	IDE	no (alias/view)	yes	✅ rendered	✅
   copilot -p	headless	no	yes	❌	✅
   SDK (.NET/Node/Py)	headless	no	yes	❌	✅

   The only real difference is whether the host renders a Todo panel — not whether
   todos can be managed.

   Suggested docs fixes

   1. Clarify that todo / TodoWrite is a host-rendered view over a sql-managed
      todos table, not a runtime tool registered in every host. The alias table
      should note it's surfaced by VS Code / the interactive CLI, and that in
      SDK / -p you use sql + session_store_sql (see fleet-mode.md).
   2. Note that --mode / AgentMode does not change tool registration and
      can't be used to "enable" todo.
   3. Document that BuiltInTools.Isolated is a curated safe subset, and that todos
      in Empty mode require explicitly allowing sql / session_store_sql with
      EnableSessionStore = true.

   Happy to share the small repro project (a .NET console app that subscribes to
   tool.execution_start / tool.execution_complete and prints the SQL trace above)
   if useful.
4. NiceAsiv

   closed this as completedon Jun 15, 2026
5. NiceAsiv

   reopened this on Jun 15, 2026
6. NiceAsiv

   closed this as completedon Jun 16, 2026
7. rotationtv1-crypto commented on Jun 16, 2026

   

   rotationtv1-crypto

   on Jun 16, 2026

   More actions

   Commit reviewed