Custom agent `tools:` — `web` and `search` aliases bind zero tools on CLI 1.0.81-9, silently disabling web + file search

[doomslayer2k]

Describe the bug

A custom agent that declares its tools with the documented category aliases web or search gets zero tools bound for those categories. There is no error, no warning, and no log line — the agent simply has no web access and no file search, while its own description and instructions still claim it does. It then silently degrades to shelling out (Select-String / Get-ChildItem instead of grep / glob, curl against search engines instead of web_search).

The failure is specific to these two aliases. In the same probe run, on the same agent, read resolved correctly while web and search bound nothing:

Alias in tools:	Should bind	Actually bound
read	view	✅ view
search	grep + glob	❌ neither
web	web_search + web_fetch	❌ neither

Using the literal tool names instead of the aliases works correctly, which is the available workaround.

This contradicts the published reference, Custom agents configuration → Tool aliases, which documents both aliases as supported:

Primary alias	Compatible aliases	Purpose
search	Grep, Glob	Search for files or text in files.
web	WebSearch, WebFetch	Allows fetching content from URLs and performing a web search

Affected version

GitHub Copilot CLI 1.0.81-9

Previously reported against 1.0.68 in #4023 (2026-07-03). Still reproduces 13 patch versions and ~7 weeks later.

Steps to reproduce

1. Create .github/agents/aliasprobe.agent.md in any trusted directory:

   ---
   name: AliasProbe
   description: probe agent for alias resolution
   tools:
     - read
     - search
     - web
   ---
   Probe agent.

2. Dispatch it and ask it to report which tools are bound:

   copilot --agent "AliasProbe" --allow-all-tools \
     -p "Answer ONLY from your actual available tools list. Reply in this exact format and nothing else: grep=YES|NO, glob=YES|NO, web_search=YES|NO, web_fetch=YES|NO, view=YES|NO"

3. Observed output:

   grep=NO, glob=NO, web_search=NO, web_fetch=NO, view=YES
   

4. Replace the two aliases with literal tool names (grep, glob, web_search, web_fetch) and re-run:

   grep=YES, glob=YES, web_search=YES, web_fetch=YES, view=YES
   

Expected behavior

search binds grep + glob, and web binds web_search + web_fetch — the same way read binds view and execute binds powershell. Failing that, an unresolvable alias should produce a startup warning rather than silently binding nothing.

Additional context

Environment

copilot : GitHub Copilot CLI 1.0.81-9
OS      : Microsoft Windows 11 Enterprise 10.0.26200.0
Arch    : AMD64
Shell   : PowerShell 7.6.5
Terminal: ConsoleHost
Surface : standalone CLI, headless (-p) dispatch

Why this is worth prioritizing over its blast radius

The bug is silent and self-concealing, which makes it much more expensive than a normal missing-tool bug:

• The agent doesn't know it's degraded. It has a description and system prompt saying "web research available", so it confidently reports web-derived conclusions produced by improvised curl calls against search engines — which return bot-protection or JS-rendered junk. The user gets a confident wrong answer, not a visible failure.
• It defeats the obvious diagnostic. An agent asked "can you browse the web?" answers from its instructions, not its bindings.
• It hits the most-used aliases. search and web are two of the seven documented aliases, and they are exactly the ones a coding agent needs.
• It is reproducibly hitting real fleets. bug: 'web'/'search' tool-category aliases silently resolve to no bound tool in headless --agent dispatch #4023 reported 5 affected agent specs. Independently, this reporter found the identical count — 5 agents, all silently web-less, one of which had carried the defect since its creation.

Related

• bug: 'web'/'search' tool-category aliases silently resolve to no bound tool in headless --agent dispatch #4023 — same root cause, reported 2026-07-03 against 1.0.68, still open with no maintainer response. This issue is filed as a fuller report rather than a comment, per the "file complete, link related" convention; happy for it to be closed as a duplicate of bug: 'web'/'search' tool-category aliases silently resolve to no bound tool in headless --agent dispatch #4023 if that thread is preferred.
• web_search tool missing in Copilot app 1.1.6 — agent falls back to curl/Bing/DuckDuckGo guessing app#2733 — unrelated (app-side web_search registration gap in app 1.1.6, fixed in 1.1.7). Mentioned only to rule it out.

Scope explicitly not verified

Both this report and #4023 tested headless -p dispatch only. Interactive-mode behavior is untested — noting it because #4592 shows custom-agent activation already diverging between interactive and --prompt paths, so the two may not share a code path here either.

Suggested labels

area:tools, area:agents, area:non-interactive — filed unlabelled because an outside contributor has push:false / triage:false on this repo and cannot set labels or type.

In-depth investigation — isolating the alias as the cause

Three probes were run in one standalone CLI environment, changing only the agent's tools: declaration, so environment, MCP config, and CWD are held constant:

#	tools: configuration	web_fetch	web_search
A	web alias	❌ NO	❌ NO
B	bare web_search + web_fetch	✅ YES	✅ YES
C	control — no tools: key at all	✅ YES	✅ YES

Probe C is the important one: with no tools: filter the CLI binds both web tools in this exact environment, which rules out MCP config, network policy, auth state, and CLI build as explanations. The only variable that changes the outcome is whether the category alias or the literal name is used — isolating alias resolution as the cause.

A separate control within probe A confirms the alias mechanism is otherwise healthy: the same agent's read alias resolved to view in the same run. So this is not "aliases are ignored", it is "these two aliases resolve to nothing".

The same enumeration also showed the alias produces no partial binding — it is not that web binds only web_fetch and drops web_search; it binds neither.

Suggested fix, matching #4023: route web → web_search + web_fetch and search → grep + glob in the same alias table that already maps read → view and execute → powershell. A startup warning on any alias that resolves to an empty tool set would have surfaced both bugs immediately and would prevent the next one.