refactor(kosong): rename select_tools capability to dynamically_loaded_tools

ModelCapability describes what the model can do; the model's ability is
accepting message-level tool declarations (dynamically loaded tools) —
select_tools is the name of the client-side tool that drives it, and the
config-to-mechanism translation is the agent layer's business. Rename
the capability bit to the canonical dynamically_loaded_tools everywhere
it is declared, detected, catalogued, and forwarded.

No breaking change: the deprecated select_tools spelling stays accepted
— as a ModelCapability/CatalogModelEntry field and as a model-alias
capabilities config string — through the single hasDynamicallyLoadedTools
read point, so existing configs keep working unchanged. The client-side
vocabulary (the select_tools builtin tool, the tool-select experimental
flag) is deliberately untouched.

Author: fengchenchen

.changeset/dynamically-loaded-tools-capability.md

@@ -0,0 +1,7 @@
+---
+"@moonshot-ai/kosong": patch
+"@moonshot-ai/kimi-code": patch
+"@moonshot-ai/kimi-code-sdk": patch
+---
+
+Rename the dynamic tool loading model capability to its canonical name `dynamically_loaded_tools` (the model-level ability to accept message-level tool declarations). The previous `select_tools` spelling — which named the client-side mechanism rather than the model capability — remains fully supported as a deprecated alias in model alias `capabilities` config and in catalog entries, so no configuration changes are required. The SDK's catalog-to-alias mapping now emits the canonical name.

.changeset/select-tools-discard-on-compaction.md

@@ -2,4 +2,4 @@
 "@moonshot-ai/kimi-code": patch
 ---
 
-Progressive tool disclosure (`select_tools`, experimental): compaction now discards the loaded tool schemas instead of re-injecting them. After a compaction the boundary announcement re-lists every loadable tool name and the model re-selects what it still needs; a from-memory call to a no-longer-loaded tool is rejected with guidance to select it first. This keeps the post-compaction context at its minimal users+summary floor and removes the schema-rebuild budget heuristics. No effect unless the `tool-select` experimental flag and a `select_tools`-capable model are active.
+Progressive tool disclosure (`select_tools`, experimental): compaction now discards the loaded tool schemas instead of re-injecting them. After a compaction the boundary announcement re-lists every loadable tool name and the model re-selects what it still needs; a from-memory call to a no-longer-loaded tool is rejected with guidance to select it first. This keeps the post-compaction context at its minimal users+summary floor and removes the schema-rebuild budget heuristics. No effect unless the `tool-select` experimental flag and a model with the dynamically-loaded-tools capability are active.

packages/agent-core/src/agent/context/dynamic-tools.ts

@@ -39,10 +39,10 @@ export function isLoadableToolsAnnouncement(message: ContextMessage): boolean {
  * Shape a history for a consumer that must not see dynamic-tool protocol
  * context: drop the loadable-tools announcements and strip `message.tools`
  * (dropping the message entirely when nothing else remains). Two callers:
- *   - projection for a model without the `select_tools` capability (mid-session
- *     model switch — the canonical history keeps its shape, only the outgoing
- *     view changes; announcements would be noise and even reference a
- *     select_tools tool the model does not have);
+ *   - projection for a model without the dynamically-loaded-tools capability
+ *     (mid-session model switch — the canonical history keeps its shape, only
+ *     the outgoing view changes; announcements would be noise and even
+ *     reference a select_tools tool the model does not have);
  *   - the compaction summarizer input (schemas and announcements are protocol
  *     context, not conversation — summarizing them wastes tokens and risks
  *     leaking schema text into the summary).

packages/agent-core/src/agent/context/index.ts

@@ -376,11 +376,12 @@ export class ContextMemory {
 
   project(messages: readonly ContextMessage[], options?: ProjectOptions): Message[] {
     // Shape for the current model BEFORE projecting: a model without the
-    // select_tools capability must not see dynamic-tool schema messages or
-    // loadable-tools announcements (the canonical history keeps them; only
-    // this outgoing view is shaped). Must run pre-projection — project()
-    // strips `origin`, the only anchor for the announcements. setModel never
-    // rewrites history, so a mid-session switch degrades/upgrades losslessly.
+    // dynamically-loaded-tools capability must not see dynamic-tool schema
+    // messages or loadable-tools announcements (the canonical history keeps
+    // them; only this outgoing view is shaped). Must run pre-projection —
+    // project() strips `origin`, the only anchor for the announcements.
+    // setModel never rewrites history, so a mid-session switch
+    // degrades/upgrades losslessly.
     const shaped = this.agent.toolSelectEnabled ? messages : stripDynamicToolContext(messages);
     const anomalies: ProjectionAnomaly[] = [];
     const result = project(this.agent.microCompaction.compact(shaped), {

packages/agent-core/src/agent/index.ts

@@ -6,7 +6,7 @@ import { ErrorCodes, KimiError, makeErrorPayload } from '#/errors';
 import { log } from '#/logging/logger';
 import type { Logger } from '#/logging/types';
 import type { AgentAPI, AgentEvent, KimiConfig, SDKAgentRPC, UsageStatus } from '#/rpc';
-import { generate } from '@moonshot-ai/kosong';
+import { generate, hasDynamicallyLoadedTools } from '@moonshot-ai/kosong';
 
 import type { EnabledPluginSessionStart, PluginCommandDef } from '#/plugin';
 import { expandCommandArguments } from '../plugin/commands';
@@ -236,18 +236,20 @@ export class Agent {
 
   /**
    * Single decision point for select_tools progressive disclosure. All three
-   * gates must be open: the model declares the `select_tools` capability, the
-   * model declares `tool_use` (a model without tool use registering
-   * select_tools is a contradiction), and the `tool-select` experimental flag
-   * is on. Every consumer — top-level tools[] convergence, select_tools
-   * registration, manifest announcements, projection shaping — reads this
-   * instead of re-deriving the conditions, so degradation is lossless: any
-   * closed gate reproduces the inline behavior byte-for-byte.
+   * gates must be open: the model has the dynamically-loaded-tools capability
+   * (message-level tool declarations; the deprecated `select_tools` spelling
+   * is honored via hasDynamicallyLoadedTools), the model declares `tool_use`
+   * (a model without tool use loading tools dynamically is a contradiction),
+   * and the `tool-select` experimental flag is on. Every consumer — top-level
+   * tools[] convergence, select_tools registration, manifest announcements,
+   * projection shaping — reads this instead of re-deriving the conditions, so
+   * degradation is lossless: any closed gate reproduces the inline behavior
+   * byte-for-byte.
    */
   get toolSelectEnabled(): boolean {
     const capability = this.config.modelCapabilities;
     return (
-      capability.select_tools === true &&
+      hasDynamicallyLoadedTools(capability) &&
       capability.tool_use &&
       this.experimentalFlags.enabled('tool-select')
     );

packages/agent-core/src/flags/registry.ts

@@ -27,7 +27,7 @@ export const FLAG_DEFINITIONS = [
     id: 'tool-select',
     title: 'Tool select (progressive tool disclosure)',
     description:
-      'Keep MCP tool schemas out of the immutable top-level tools[]; the model loads them on demand via the select_tools tool. Only takes effect on models whose capability catalog declares select_tools.',
+      'Keep MCP tool schemas out of the immutable top-level tools[]; the model loads them on demand via the select_tools tool. Only takes effect on models whose capability catalog declares dynamically loaded tools.',
     env: 'KIMI_CODE_EXPERIMENTAL_TOOL_SELECT',
     default: false,
     surface: 'core',

packages/agent-core/src/session/provider-manager.ts

@@ -1,6 +1,6 @@
 import type { Logger } from '#/logging/types';
 import type { ProviderConfig as KosongProviderConfig, ModelCapability, ProviderRequestAuth } from '@moonshot-ai/kosong';
-import { APIStatusError, getModelCapability, UNKNOWN_CAPABILITY } from '@moonshot-ai/kosong';
+import { APIStatusError, getModelCapability, hasDynamicallyLoadedTools, UNKNOWN_CAPABILITY } from '@moonshot-ai/kosong';
 import { parseKimiCodeCustomHeaders } from '@moonshot-ai/kimi-code-oauth';
 import {
   effectiveModelAlias,
@@ -233,10 +233,14 @@ function resolveModelCapabilities(
     thinking: declared.has('thinking') || declared.has('always_thinking') || detected.thinking,
     tool_use: declared.has('tool_use') || detected.tool_use,
     max_context_tokens: alias.maxContextSize,
-    // Message-level tool declarations (select_tools progressive disclosure).
-    // Every field here must be merged explicitly — a capability registered in
-    // kosong that is not forwarded here never reaches the agent.
-    select_tools: declared.has('select_tools') || detected.select_tools === true,
+    // Message-level tool declarations ("dynamically loaded tools"). Every
+    // field here must be merged explicitly — a capability registered in
+    // kosong that is not forwarded here never reaches the agent. The
+    // deprecated `select_tools` spelling stays accepted in alias configs.
+    dynamically_loaded_tools:
+      declared.has('dynamically_loaded_tools') ||
+      declared.has('select_tools') ||
+      hasDynamicallyLoadedTools(detected),
   };
 }
 

packages/agent-core/test/agent/harness/agent.ts

@@ -1094,6 +1094,9 @@ function capabilityNames(capabilities: ModelCapability | undefined): string[] {
     capabilities.audio_in ? 'audio_in' : undefined,
     capabilities.thinking ? 'thinking' : undefined,
     capabilities.tool_use ? 'tool_use' : undefined,
+    capabilities.dynamically_loaded_tools === true ? 'dynamically_loaded_tools' : undefined,
+    // Deliberately kept as the legacy string so tests exercising the
+    // deprecated field also exercise the deprecated declared-name path.
     capabilities.select_tools === true ? 'select_tools' : undefined,
   ].filter((capability): capability is string => capability !== undefined);
 }

packages/agent-core/test/agent/tool-select.e2e.test.ts

@@ -2,7 +2,7 @@
  * select_tools progressive disclosure — end-to-end agent tests.
  *
  * Uses the scripted-generate harness: real ToolManager/turn loop/context, fake
- * LLM. The three-condition gate (model capability.select_tools ×
+ * LLM. The three-condition gate (model capability.dynamically_loaded_tools ×
  * capability.tool_use × `tool-select` flag) is driven through the alias
  * capability declarations and an injected FlagResolver.
  *
@@ -28,6 +28,18 @@ import { testAgent, type TestAgentContext } from './harness/agent';
 
 const DISCLOSURE_PROVIDER = { type: 'kimi', apiKey: 'test-key', model: 'select-capable-model' } as const;
 const DISCLOSURE_CAPABILITIES = {
+  image_in: false,
+  video_in: false,
+  audio_in: false,
+  thinking: false,
+  tool_use: true,
+  max_context_tokens: 256_000,
+  dynamically_loaded_tools: true,
+} as const;
+
+// Same capability through the deprecated field name — must keep working
+// (declared as the legacy `select_tools` capability string by the harness).
+const LEGACY_DISCLOSURE_CAPABILITIES = {
   image_in: false,
   video_in: false,
   audio_in: false,
@@ -220,6 +232,31 @@ describe('disclosure mode — top-level convergence and announcements', () => {
     expect(JSON.stringify(call.history)).toContain(GRAFANA_TOOL);
   });
 
+  it('honors the deprecated select_tools capability spelling end to end', async () => {
+    // Declared through the harness as the legacy `select_tools` capability
+    // string; the gate, convergence, select and dispatch must all still work.
+    const callLog: Array<[string, unknown]> = [];
+    const ctx = testAgent({ experimentalFlags: toolSelectFlagOn() });
+    ctx.configure({
+      tools: ['Read', 'mcp__*'],
+      provider: DISCLOSURE_PROVIDER,
+      modelCapabilities: LEGACY_DISCLOSURE_CAPABILITIES,
+    });
+    await registerGrafana(ctx, callLog);
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+    expect(ctx.agent.toolSelectEnabled).toBe(true);
+
+    ctx.mockNextResponse({ type: 'text', text: 'loading' }, selectCall('call-1', [GRAFANA_TOOL]));
+    ctx.mockNextResponse({ type: 'text', text: 'querying' }, mcpCall('call-2', 'errors'));
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+    await runTurn(ctx, 'use the tool');
+
+    const wireNames = ctx.llmCalls.at(-3)!.tools.map((t) => t.name);
+    expect(wireNames).toContain('select_tools');
+    expect(wireNames.some((n) => n.startsWith('mcp__'))).toBe(false);
+    expect(callLog).toEqual([['query_range', { query: 'errors' }]]);
+  });
+
   it('does not re-announce when the loadable set is unchanged', async () => {
     const ctx = await disclosureAgent();
     ctx.mockNextResponse({ type: 'text', text: 'one' });

packages/kosong/src/capability.ts

@@ -16,14 +16,31 @@ export interface ModelCapability {
   readonly tool_use: boolean;
   readonly max_context_tokens: number;
   /**
-   * Model accepts message-level tool declarations (`messages[].tools`), the
-   * primitive behind select_tools progressive disclosure. Absent means
-   * unsupported: only models explicitly catalogued or declared with this
-   * capability may ever receive a message carrying `tools`.
+   * Model accepts message-level tool declarations (`messages[].tools`) — the
+   * "dynamically loaded tools" wire feature that clients can drive with
+   * progressive tool disclosure. Absent means unsupported: only models
+   * explicitly catalogued or declared with this capability may ever receive a
+   * message carrying `tools`.
+   */
+  readonly dynamically_loaded_tools?: boolean;
+  /**
+   * @deprecated Legacy alias of {@link ModelCapability.dynamically_loaded_tools}
+   * (this bit originally shipped under the client-side mechanism's tool name).
+   * Still honored everywhere via {@link hasDynamicallyLoadedTools}; write the
+   * canonical field instead.
    */
   readonly select_tools?: boolean;
 }
 
+/**
+ * True when the model accepts message-level tool declarations. Single read
+ * point for the capability so the deprecated `select_tools` spelling keeps
+ * working wherever the bit is consumed.
+ */
+export function hasDynamicallyLoadedTools(capability: ModelCapability): boolean {
+  return capability.dynamically_loaded_tools === true || capability.select_tools === true;
+}
+
 const UNKNOWN_CAPABILITY_MARKER = Symbol.for('moonshot-ai.kosong.UNKNOWN_CAPABILITY');
 
 /**
@@ -40,7 +57,10 @@ export const UNKNOWN_CAPABILITY: ModelCapability = Object.freeze(
       thinking: false,
       tool_use: false,
       max_context_tokens: 0,
-      select_tools: false,
+      // Only the canonical spelling in the default output shape; the
+      // deprecated `select_tools` field is accepted on input but never
+      // emitted (this object reaches RPC/SDK consumers via config snapshots).
+      dynamically_loaded_tools: false,
     },
     UNKNOWN_CAPABILITY_MARKER,
     { value: true },
@@ -58,7 +78,7 @@ export function isUnknownCapability(capability: ModelCapability): boolean {
     !capability.audio_in &&
     !capability.thinking &&
     !capability.tool_use &&
-    capability.select_tools !== true &&
+    !hasDynamicallyLoadedTools(capability) &&
     capability.max_context_tokens === 0
   );
 }