AGENTS.md

1# Agent host system-prompt customization
2 
3This directory customizes the system prompt for Copilot CLI **agent host**
4(ahp+cli) sessions. Read this before changing how the system message is built or
5adding per-model / per-tool guidance. It mirrors the Copilot extension's
6`extensions/copilot/.../prompts/node/agent/` (agentPrompts), but the agent host
7runs in its own process and cannot use prompt-tsx, so contributors return plain
8data the SDK accepts directly.
9 
10## Files
11 
12- `promptRegistry.ts` — `AgentHostPromptRegistry`: resolves the final
13  `SystemMessageConfig` for a session's model. Defines the `IAgentHostPrompt`
14  contributor interface and the `IAgentHostPromptContext` read-time context.
15- `systemMessage.ts` — the default message (`COPILOT_AGENT_HOST_SYSTEM_MESSAGE`),
16  shared identity text, the `fullSystemPrompt` / `sectionOverrides` builders, and
17  `describeSystemMessageConfig` (the one-line log summary).
18- `toolInstructions.ts` — the model-agnostic `tool_instructions` layer: gated
19  one-line nudges (`TOOL_INSTRUCTION_LINES`) composed into the SDK's
20  `tool_instructions` section. The browser line is the one registered today.
21- `anthropicPrompt.ts` — example per-model contributor (Claude Opus 4.8).
22- `allPrompts.ts` — side-effect import hub; importing it registers every
23  contributor into the shared `agentHostPromptRegistry`.
24 
25## How the system message is built
26 
27`resolveSystemMessageConfig(model, context)` runs two steps:
28 
291. **`_resolveModelConfig`** — picks the per-model (or default) config. Falls
30   back to `COPILOT_AGENT_HOST_SYSTEM_MESSAGE` when there's no model, no matching
31   contributor, or the contributor opts out for this `context`.
322. **`_withUniversalSections`** — layers the model-agnostic sections (currently
33   just `tool_instructions`) on top, **composing** with — never clobbering — any
34   per-model override for that section.
35 
36> **Launch-time freeze.** The SDK accepts a system message only at session
37> create/resume; there is no mid-session update. The prompt is resolved once per
38> (re)launch and any tool-gated content reflects the tool set at that moment. A
39> change to the session's tools/plugins is part of the launcher's restart
40> snapshot, so it re-launches and recomputes; an in-flight turn keeps the prompt
41> it launched with.
42 
43There are two ways to customize, and a model can use both at once.
44 
45## Lever 1 — universal, all models (`toolInstructions.ts`)
46 
47Guidance for a tool that should apply to **every** model whenever that tool is in
48the session. This is what the browser line does.
49 
501. Write a `ToolInstructionLine` — a function `(hasTool) => string | undefined`
51   that returns one sentence (no surrounding newlines) when its tool is present,
52   or `undefined` to contribute nothing.
532. Add it to `TOOL_INSTRUCTION_LINES`.
54 
55```ts
56const exampleToolInstructions: ToolInstructionLine = hasTool =>
57	hasTool('someClientToolReferenceName')
58		? 'One sentence of guidance, shown only when that tool is present.'
59		: undefined;
60 
61const TOOL_INSTRUCTION_LINES: readonly ToolInstructionLine[] = [browserToolInstructions, exampleToolInstructions];
62```
63 
64**Caveat — `hasTool` sees CLIENT tools only.** It is `context.hasClientTool`,
65which knows only the forwarded workbench tools, addressed by their **camelCase
66`toolReferenceName`** (e.g. `openBrowserPage`, `runTask`, `getTaskOutput`) — NOT
67the extension's snake_case ids, and NOT shell / server-SDK / MCP tools (MCP is
68discovered dynamically and isn't in the launch snapshot). A
69line gated on a name that is never a client tool silently never renders. The
70default client-tool allowlist is `chat.agentHost.clientTools` (see
71`chat.shared.contribution.ts`). Broadening this context is a known follow-up.
72 
73These lines compose with a per-model `tool_instructions` override (see
74`composeToolInstructions`), so Lever 1 and Lever 2 stack.
75 
76## Tool search (deferred tool loading)
77 
78When `chat.agentHost.copilot.toolSearch.enabled` is on AND the session's model
79supports it (`agentHostModelSupportsToolSearch`), the launcher sets
80`toolSearch: { enabled: true, deferThreshold: 1 }` and the session defers MCP +
81non-core client tools behind the runtime's `tool_search_tool`:
82 
83- **The override** (`copilotAgentSession._createClientSdkTools`): the client's
84  forwarded `toolSearch` tool is registered as `tool_search_tool` with
85  `overridesBuiltInTool: true` and `defer: 'never'`, so the runtime routes the
86  model's search to the client's semantic search. The SDK supplies the runtime's
87  live deferred-tool metadata to the override handler; Agent Host carries that
88  corpus as transient tool-call metadata and injects it only into the local
89  `toolSearch` invocation, so embeddings rank the runtime/MCP tools rather than
90  the extension's registry. The corpus is never added to model-facing tool input.
91  Every other client tool gets
92  `defer: 'never'` if it is in `NON_DEFERRED_CLIENT_TOOL_NAMES`
93  (`runTests`, `rename`, `usages`), else `defer: 'auto'`. Built-in runtime tools
94  are never deferred. The renderer (`agentHostSessionHandler._setupClientToolCall`)
95  maps `tool_search_tool` back to `toolSearch` to execute the real VS Code tool.
96- **The prompt** (this folder): `toolSearchInstructionLines(toolSearchActive)`
97  adds a `tool_instructions` line (`toolSearchToolInstructions`) telling the
98  model to load deferred tools via `tool_search_tool` first — gated on
99  `context.toolSearchActive` because the `toolSearch` tool is *always* forwarded,
100  so presence alone can't gate it. The runtime already emits its own
101  deferred-tools reminder (`build_deferred_tools_user_message`) with the accurate
102  deferred set, so this layer intentionally does NOT re-list the deferred tools.
103 
104The two identity/count levers are independent: `deferThreshold` is a total
105tool-count gate (1 ⇒ always active), while each tool's `defer` flag decides
106whether *that* tool is deferred.
107 
108This B-inject bridge is intentionally interim. A follow-up moves tool-search
109registration and ranking into VS Code core so Agent Host no longer depends on
110the Copilot extension's tool implementation or embeddings plumbing.
111 
112## Lever 2 — per-model contributor (`promptRegistry.ts` + `allPrompts.ts`)
113 
114Guidance scoped to a model or family. Implement `IAgentHostPrompt` and register
115it. Use `anthropicPrompt.ts` as the template.
116 
117A contributor provides EITHER:
118 
119- `resolveSectionOverrides` → `{ mode: 'customize' }` — overrides named sections,
120  keeps the SDK foundation prompt and its guardrails. **Prefer this.**
121- `resolveFullSystemPrompt` → `{ mode: 'replace' }` — owns the entire prompt and
122  **drops all SDK guardrails (including safety)**. Only for callers that truly
123  own the whole prompt. A replace contributor bypasses Lever 1, so it must inline
124  any universal guidance itself (`universalToolInstructions(hasTool)` renders the
125  same gated lines; add a small replace-mode helper alongside it when the first
126  such contributor lands).
127 
128```ts
129class MyModelPrompt implements IAgentHostPrompt {
130	static readonly familyPrefixes = ['my-model'];        // or implement static matchesModel(model)
131	resolveSectionOverrides(model: ModelSelection, context: IAgentHostPromptContext) {
132		// Gate on host settings; return undefined to fall back to the default message.
133		return context.getSetting(CopilotCliConfigKey.SomeFlag) === true
134			? { tool_instructions: { action: 'append', content: '\nFor this model, batch independent tool calls.' } }
135			: undefined;
136	}
137}
138agentHostPromptRegistry.registerPrompt(MyModelPrompt);   // then add `import './myModelPrompt.js'` to allPrompts.ts
139```
140 
141Matching: a contributor matches a model by `static matchesModel(model)` (takes
142precedence) or by `familyPrefixes` (model-id `startsWith`). The registry resolves
143**exactly one** contributor per model (first match wins) — base + version
144layering is a known follow-up.
145 
146## Reference
147 
148- **Modes** (`SystemMessageConfig.mode`): `append` (foundation + text, default),
149  `customize` (override named sections), `replace` (own the whole prompt, no
150  guardrails).
151- **Sections** (`SystemMessageSection`): `identity`, `tone`, `tool_efficiency`,
152  `environment_context`, `code_change_rules`, `guidelines`, `safety`,
153  `tool_instructions`, `custom_instructions`, `runtime_instructions`,
154  `last_instructions`.
155- **Override actions** (`SectionOverride.action`): `replace`, `append`,
156  `prepend`, `remove`, or a `(content: string) => string` transform.
157 
158## Gotchas
159 
160- **Empty overrides = no override.** `resolveSectionOverrides` returning `{}`
161  (or `undefined`) falls back to the default message rather than emitting an
162  empty customize config that would drop the default identity.
163- **Don't mutate the shared default.** `COPILOT_AGENT_HOST_SYSTEM_MESSAGE` is a
164  shared constant; layering spreads into a fresh object, preserving any other
165  customize-mode fields (e.g. `content`). Keep it that way.
166- **Spacing is relative to the foundation.** `composeToolInstructions` pads by
167  action (`append` leads with `\n`, `prepend` trails with `\n`, `replace` owns
168  the section). When writing a section's `content` by hand, a leading `\n` keeps
169  appended text off the foundation's last line.
170- **Observability.** The launcher logs `describeSystemMessageConfig(...)` at
171  `info` (mode + overridden sections) and the full config at `trace`. Keep new
172  config shapes summarizable there.
173- **Tests.** `../../../test/node/agentHostPromptRegistry.test.ts` covers the
174  registry/wiring; `../../../test/node/toolInstructions.test.ts` covers the
175  composition/gating. Add cases there, not new harnesses.
176