feat: support custom agent files

.changeset/agent-file-subagents.md

@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/agent-core-v2": minor
+"@moonshot-ai/kimi-code": minor
+---
+
+Let custom agent files restrict which sub-agent types they may delegate to (v2 engine only).

.changeset/custom-agent-files.md

@@ -0,0 +1,8 @@
+---
+"@moonshot-ai/agent-core-v2": minor
+"@moonshot-ai/kap-server": minor
+"@moonshot-ai/protocol": minor
+"@moonshot-ai/kimi-code": minor
+---
+
+Support custom agents defined as Markdown files with frontmatter, usable as the main agent or a sub-agent (v2 engine only).

.changeset/global-tool-gating.md

@@ -0,0 +1,11 @@
+---
+"@moonshot-ai/agent-core": patch
+"@moonshot-ai/agent-core-v2": minor
+"@moonshot-ai/kap-server": minor
+"@moonshot-ai/protocol": minor
+"@moonshot-ai/klient": minor
+"@moonshot-ai/kimi-code-sdk": minor
+"@moonshot-ai/kimi-code": minor
+---
+
+Add global tool gating to constrain which tools agents may use, with a per-session override (v2 engine only).

.changeset/system-md-override.md

@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/agent-core-v2": minor
+"@moonshot-ai/kimi-code": minor
+---
+
+Support overriding the default main-agent system prompt with a user-level file for every session (v2 engine only).

.changeset/tool-pattern-warnings.md

@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/agent-core-v2": patch
+"@moonshot-ai/kimi-code": patch
+---
+
+Warn when a tool allow/deny list entry can never match any tool, for example a misspelled name (v2 engine only).

apps/kimi-code/src/cli/commands.ts

@@ -1,6 +1,6 @@
 import { CLI_COMMAND_NAME } from '#/constant/app';
 import { registerMigrateCommand } from '#/migration/index';
-import { Command, Option } from 'commander';
+import { Command, InvalidArgumentError, Option } from 'commander';
 
 import type { CLIOptions } from './options';
 import { registerAcpCommand } from './sub/acp';
@@ -74,6 +74,33 @@ export function createProgram(
         .argParser((value: string, previous: string[] | undefined) => [...(previous ?? []), value])
         .default([]),
     )
+    .addOption(
+      new Option(
+        '--agent <name>',
+        'Agent profile to use for this invocation (v2 engine only). Custom profiles are discovered from agent directories or loaded via --agent-file.',
+      )
+        .argParser((value: string, previous: string | undefined) => {
+          if (previous !== undefined) {
+            throw new InvalidArgumentError('--agent may only be specified once.');
+          }
+          return value;
+        })
+        .conflicts('agentFile'),
+    )
+    .addOption(
+      new Option(
+        '--agent-file <path>',
+        'Load an agent definition from a Markdown file and select it (v2 engine only).',
+      )
+        .argParser((value: string, previous: string[] | undefined) => {
+          if ((previous?.length ?? 0) > 0) {
+            throw new InvalidArgumentError('--agent-file may only be specified once.');
+          }
+          return [value];
+        })
+        .conflicts('agent')
+        .default([]),
+    )
     .addOption(
       new Option(
         '--add-dir <dir>',
@@ -133,6 +160,8 @@ export function createProgram(
       outputFormat: raw['outputFormat'] as CLIOptions['outputFormat'],
       prompt: raw['prompt'] as string | undefined,
       skillsDirs: raw['skillsDir'] as string[],
+      agent: raw['agent'] as string | undefined,
+      agentFiles: raw['agentFile'] as string[],
       addDirs: raw['addDir'] as string[],
     };
 

apps/kimi-code/src/cli/options.ts

@@ -1,3 +1,5 @@
+import { isKimiV2Enabled } from './experimental-v2';
+
 export type UIMode = 'shell' | 'print';
 export type PromptOutputFormat = 'text' | 'stream-json';
 
@@ -44,6 +46,8 @@ export interface CLIOptions {
   outputFormat: PromptOutputFormat | undefined;
   prompt: string | undefined;
   skillsDirs: string[];
+  agent: string | undefined;
+  agentFiles: string[];
   addDirs?: string[];
 }
 
@@ -83,6 +87,26 @@ export function validateOptions(
   if (promptMode && opts.plan) {
     throw new OptionConflictError('Cannot combine --prompt with --plan.');
   }
+  if (opts.agent !== undefined && opts.agent.trim().length === 0) {
+    throw new OptionConflictError('Agent cannot be empty.');
+  }
+  if (opts.agentFiles.length > 1) {
+    throw new OptionConflictError('--agent-file may only be specified once.');
+  }
+  if (opts.agentFiles.some((file) => file.trim().length === 0)) {
+    throw new OptionConflictError('Agent file path cannot be empty.');
+  }
+  if (opts.agent !== undefined && opts.agentFiles.length > 0) {
+    throw new OptionConflictError('Cannot combine --agent with --agent-file.');
+  }
+  if (
+    (opts.agent !== undefined || opts.agentFiles.length > 0) &&
+    (!promptMode || !isKimiV2Enabled(env))
+  ) {
+    throw new OptionConflictError(
+      '--agent/--agent-file are only available with the v2 engine (kimi -p with KIMI_CODE_EXPERIMENTAL_FLAG=1).',
+    );
+  }
   if (promptMode && opts.session === '') {
     throw new OptionConflictError('Cannot use --session without an id in prompt mode.');
   }

apps/kimi-code/src/cli/v2/run-v2-print.ts

@@ -16,6 +16,8 @@
  * Selected by `runPrompt` when `KIMI_CODE_EXPERIMENTAL_FLAG` is set.
  */
 
+import { readFile } from 'node:fs/promises';
+
 import {
   IAgentGoalService,
   IAgentLifecycleService,
@@ -24,17 +26,21 @@ import {
   IAgentPromptService,
   IAgentTaskService,
   IAuthSummaryService,
+  IBootstrapService,
   IConfigService,
   IEventBus,
   IOAuthToolkit,
   ISessionIndex,
   ISessionLifecycleService,
   ITelemetryService,
+  agentCatalogRuntimeOptionsSeed,
   bootstrap,
   createCloudAppender,
   ensureMainAgent,
   hostRequestHeadersSeed,
   logSeed,
+  parseAgentFileText,
+  resolveAgentPath,
   resolveAgentTaskConfig,
   resolveKimiHome,
   resolveLoggingConfig,
@@ -120,6 +126,11 @@ export async function runV2Print(
     // `--skillsDir` (v1 print parity): explicit skill dirs replace default
     // user / project discovery for this process.
     ...skillCatalogRuntimeOptionsSeed(opts.skillsDirs),
+    // `--agent-file`: explicit agent definition files, registered with the
+    // highest-precedence source for this process. Passed through unresolved —
+    // the engine expands `~` and resolves relative paths against the session
+    // workDir (mirroring `--skills-dir`).
+    ...agentCatalogRuntimeOptionsSeed(opts.agentFiles),
   ]);
   const auth = app.accessor.get(IOAuthToolkit);
 
@@ -236,6 +247,63 @@ async function resolveNativeSession(
   const lifecycle = app.accessor.get(ISessionLifecycleService);
   const index = app.accessor.get(ISessionIndex);
 
+  // `--agent` selects a catalog profile by name; otherwise `--agent-file`
+  // implicitly selects the profile that file defines. The file
+  // is parsed here (fatal on error) so a bad file fails before any turn.
+  let agentProfileName = opts.agent;
+  const agentFile = opts.agentFiles[0];
+  if (agentProfileName === undefined && agentFile !== undefined) {
+    const agentFilePath = resolveAgentPath(
+      agentFile,
+      workDir,
+      app.accessor.get(IBootstrapService).osHomeDir,
+    );
+    let agentFileText: string;
+    try {
+      agentFileText = await readFile(agentFilePath, 'utf8');
+    } catch (error) {
+      throw new Error(
+        `Failed to read agent file "${agentFilePath}": ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+    try {
+      agentProfileName = parseAgentFileText({
+        path: agentFilePath,
+        source: 'explicit',
+        text: agentFileText,
+      }).name;
+    } catch (error) {
+      throw new Error(
+        `Invalid agent file "${agentFilePath}": ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+  }
+
+  // `--agent` / `--agent-file` bind an explicit profile; without them the
+  // historical setModel path (default profile on first bind) is kept. A
+  // same-name re-select on a resumed session keeps the profile and only applies
+  // an explicitly requested model; a different name is rejected by the
+  // engine's first-bind guard inside `bind`.
+  const applyProfileSelection = async (
+    profile: IAgentProfileService,
+    model: string | undefined,
+  ): Promise<void> => {
+    if (agentProfileName !== undefined) {
+      if (profile.data().profileName === agentProfileName) {
+        if (model !== undefined) await profile.setModel(model);
+        return;
+      }
+      await profile.bind({
+        profile: agentProfileName,
+        model: requireConfiguredModel(model ?? profile.getModel(), defaultModel),
+      });
+    } else if (model !== undefined) {
+      await profile.setModel(model);
+    }
+  };
+
   const resumeById = async (id: string): Promise<ISessionScopeHandle> => {
     const session = await lifecycle.resume(id);
     if (session === undefined) {
@@ -273,9 +341,7 @@ async function resolveNativeSession(
     const session = await resumeById(opts.session);
     const agent = await ensureMainAgent(session);
     const profile = agent.accessor.get(IAgentProfileService);
-    if (opts.model !== undefined) {
-      await profile.setModel(opts.model);
-    }
+    await applyProfileSelection(profile, opts.model);
     const currentModel = profile.getModel();
     const { restorePermission } = forceAuto(agent);
     return {
@@ -294,9 +360,7 @@ async function resolveNativeSession(
       const session = await resumeById(previous.id);
       const agent = await ensureMainAgent(session);
       const profile = agent.accessor.get(IAgentProfileService);
-      if (opts.model !== undefined) {
-        await profile.setModel(opts.model);
-      }
+      await applyProfileSelection(profile, opts.model);
       const currentModel = profile.getModel();
       const { restorePermission } = forceAuto(agent);
       return {
@@ -314,9 +378,12 @@ async function resolveNativeSession(
   const session = await lifecycle.create({
     workDir,
     additionalDirs: opts.addDirs?.length ? opts.addDirs : undefined,
+    mainAgentBinding: {
+      profile: agentProfileName ?? 'agent',
+      model,
+    },
   });
   const agent = await ensureMainAgent(session);
-  await agent.accessor.get(IAgentProfileService).setModel(model);
   agent.accessor.get(IAgentPermissionModeService).setMode('auto');
   return {
     session,

apps/kimi-code/src/main.ts

@@ -130,6 +130,8 @@ const MIGRATE_CLI_OPTIONS: CLIOptions = {
   outputFormat: undefined,
   prompt: undefined,
   skillsDirs: [],
+  agent: undefined,
+  agentFiles: [],
 };
 
 export function main(): void {

apps/kimi-code/test/cli/main.test.ts

@@ -151,6 +151,8 @@ function defaultOpts(): CLIOptions {
     outputFormat: undefined,
     prompt: undefined,
     skillsDirs: [],
+    agent: undefined,
+    agentFiles: [],
   };
 }