@capybara-hq/kernel 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/agents/agents.service.js

@@ -25,13 +25,22 @@ import { assertOrgSkills, assertPinnedSkills } from "../skills/skills.service.js
 import { legacyKeySaveText } from "../tools/legacy-keys.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { AgentLookup, isAgentVisibleTo, visibleTo, } from "./agent-lookup.js";
-import { normalizeStoredDefinition, paramIssues, SUBAGENT_NAME_RE, SUBAGENT_ROSTER_MAX, } from "./definition.js";
+import { canonicalDisabledTools, normalizeStoredDefinition, paramIssues, SUBAGENT_NAME_RE, SUBAGENT_ROSTER_MAX, } from "./definition.js";
 import { deriveInstructions } from "./instruction-files.js";
 import { PendingConnectorRequests } from "./pending-connector-requests.js";
 import { randomPreset } from "./profile.js";
 import { loadTemplates, templateTypeOf } from "./templates.js";
 export { AGENT_VISIBILITIES, isAgentVisibleTo, visibleTo, } from "./agent-lookup.js";
 export { paramIssues, SUBAGENT_ROSTER_MAX } from "./definition.js";
+/**
+ * The definition with its description (run context spec §3.5): `given` when the save gives one
+ * (trimmed; empty removes it), else `kept` (the current version's).
+ */
+function withDescription(definition, given, kept) {
+    const { description: _drop, ...rest } = definition;
+    const next = given !== undefined ? given.trim() : kept;
+    return next === undefined || next === "" ? rest : { ...rest, description: next };
+}
 /** A new agent has no id to bind an upload to yet: a client can only choose a preset on create. */
 export function assertProfileWritable(profile) {
     if (profile?.avatar?.kind === "upload") {
@@ -86,6 +95,10 @@ export function keepPendingConnectors(definition, given, current) {
     }
     return next.length > 0 ? { ...rest, pendingConnectors: [...next] } : rest;
 }
+/** `definition` with `disabledTools` in its canonical form (tools default-on spec §2). */
+function withCanonicalTools(definition) {
+    return { ...definition, disabledTools: canonicalDisabledTools(definition.disabledTools ?? []) };
+}
 /**
  * Checks `subagents` of an agent definition in the caller's transaction (spec §5.2); throws 400
  * `agent.subagents_invalid` with one detail per problem (`{ reason, path, value? }`):
@@ -282,13 +295,21 @@ let AgentsService = class AgentsService {
         this.setupRequests = setupRequests;
     }
     /**
-     * 校验工具引用与工具策略：引用的内置 / 插件 / 连接器工具必须存在（见 `ToolRegistry.checkRefs`）；
-     * `toolPolicies` 的键必须是这些引用产生的工具 key（取值只能收紧，已由 schema 保证）。
-     * 不合法 → `validation_failed`，path 为 `tools.<i>` / `toolPolicies.<key>`。
+     * Checks the turned-off tools and the policies (tools default-on spec §2): `disabledTools` must
+     * name existing builtins, extensions and connectors (`ToolRegistry.checkDisabled`); `toolPolicies`
+     * keys must be tools the agent could have, on or off (values only tighten, by the schema); a
+     * sub-agent's key filter is never saved. Invalid → `validation_failed` at `disabledTools.<i>` /
+     * `toolPolicies.<key>` / `subagentTools`. The list is stored in canonical form.
      */
-    async checkTools(orgId, def) {
-        const { keys, issues } = await this.tools.checkRefs(orgId, def.tools);
+    async checkTools(orgId, def, kept = []) {
+        const { keys, issues } = await this.tools.checkDisabled(orgId, def.disabledTools ?? [], kept);
         const details = [...issues];
+        if (def.subagentTools !== undefined) {
+            details.push({
+                path: "subagentTools",
+                message: "subagentTools is set only on a sub-agent's definition at dispatch",
+            });
+        }
         for (const key of Object.keys(def.toolPolicies)) {
             if (!isToolPolicyKey(key, keys)) {
                 // an rc key (tool naming spec §8.3): saving writes current keys only, so name them
@@ -305,13 +326,32 @@ let AgentsService = class AgentsService {
         return keys;
     }
     /**
-     * 校验主模型与兜底都可解析，并用各自模型的参数声明严格校验 `modelParams` / `fallbackParams`
+     * The current version's `disabledTools` (empty for an agent that is not there: the update's own
+     * checks report that): entries kept from it are not re-checked, so a connector deleted or an
+     * extension uninstalled later never blocks other edits.
+     */
+    async keptDisabled(orgId, agentId) {
+        const row = await this.db.db
+            .selectFrom("agents")
+            .innerJoin("agent_versions", (j) => j
+            .onRef("agent_versions.agent_id", "=", "agents.id")
+            .onRef("agent_versions.version", "=", "agents.current_version"))
+            .select("agent_versions.definition")
+            .where("agents.id", "=", agentId)
+            .where("agents.org_id", "=", orgId)
+            .executeTakeFirst();
+        return row === undefined ? [] : (normalizeStoredDefinition(row.definition).disabledTools ?? []);
+    }
+    /**
+     * 校验主模型与兜底都可解析：enabled `chat` models in the org (`resolve`'s default kind; a model the
+     * platform or the org disabled, or an embedding model → 400 `agent.model_unavailable`, spec B
+     * §5.3），并用各自模型的参数声明严格校验 `modelParams` / `fallbackParams`
      * （没有兜底时 `fallbackParams` 必须为空）；不合法 → `validation_failed`，details 逐键点名。返回提示。
      */
-    async checkModels(def) {
+    async checkModels(orgId, def) {
         const registry = this.providers;
-        const main = await registry.resolve(def.model);
-        const fallback = def.fallback === null ? null : await registry.resolve(def.fallback);
+        const main = await registry.resolve(orgId, def.model);
+        const fallback = def.fallback === null ? null : await registry.resolve(orgId, def.fallback);
         const details = [
             ...paramIssues("modelParams", main.info.parameters, def.modelParams),
             ...paramIssues("fallbackParams", fallback?.info.parameters ?? [], def.fallbackParams),
@@ -367,9 +407,14 @@ let AgentsService = class AgentsService {
         return this.createChecked(orgId, actorAccountId, request, template, actorTokenId, auditDetail);
     }
     async createChecked(orgId, actorAccountId, request, template, actorTokenId, auditDetail) {
-        const input = { ...request, definition: deriveInstructions(request.definition, null) };
+        const input = {
+            ...request,
+            // run context spec §3.5: version 1 carries the description (the profile's when the
+            // definition gives none)
+            definition: withCanonicalTools(withDescription(deriveInstructions(request.definition, null), request.definition.description ?? request.profile?.description, undefined)),
+        };
         // 先解析模型（可能访问供应商），不在持有组织行锁时做
-        const warnings = await this.checkModels(input.definition);
+        const warnings = await this.checkModels(orgId, input.definition);
         const toolKeys = await this.checkTools(orgId, input.definition);
         if (input.visibility !== "members" && (input.memberIds?.length ?? 0) > 0) {
             throw new ApiError("validation_failed", "memberIds requires visibility 'members'");
@@ -407,7 +452,7 @@ let AgentsService = class AgentsService {
             visibility: input.visibility,
             current_version: 1,
             profile_avatar: JSON.stringify(input.profile?.avatar ?? { kind: "preset", id: randomPreset() }),
-            profile_description: input.profile?.description ?? "",
+            profile_description: input.definition.description ?? "",
             profile_quick_actions: JSON.stringify(input.profile?.quickActions ?? []),
             ...(template !== null && {
                 created_from_template_id: template.id,
@@ -478,8 +523,10 @@ let AgentsService = class AgentsService {
      */
     async update(orgId, agentId, actorAccountId, request, actorTokenId, auditDetail) {
         const patch = request;
-        const warnings = patch.definition ? await this.checkModels(patch.definition) : [];
-        const toolKeys = patch.definition ? await this.checkTools(orgId, patch.definition) : null;
+        const warnings = patch.definition ? await this.checkModels(orgId, patch.definition) : [];
+        const toolKeys = patch.definition
+            ? await this.checkTools(orgId, patch.definition, await this.keptDisabled(orgId, agentId))
+            : null;
         const agent = await this.updateIn(orgId, agentId, actorAccountId, patch, toolKeys, actorTokenId, auditDetail);
         return { agent, warnings };
     }
@@ -503,7 +550,15 @@ let AgentsService = class AgentsService {
                 .executeTakeFirstOrThrow();
             // the prompt: instructionFiles give instructions; a save given neither keeps the current one
             const currentDefinition = normalizeStoredDefinition(current.definition);
-            const definition = keepPendingConnectors(deriveInstructions(patch.definition, currentDefinition), patch.definition.pendingConnectors, currentDefinition.pendingConnectors);
+            const definition = withCanonicalTools(withDescription(keepPendingConnectors(deriveInstructions(patch.definition, currentDefinition), patch.definition.pendingConnectors, currentDefinition.pendingConnectors), patch.definition.description, currentDefinition.description));
+            // the display copy follows every description the save gives (run context spec §3.5)
+            if (patch.definition.description !== undefined) {
+                await t
+                    .updateTable("agents")
+                    .set({ profile_description: definition.description ?? "" })
+                    .where("id", "=", agentId)
+                    .execute();
+            }
             // 当前版本已有的技能引用保存时合法，不再核对（被删的技能不挡住其他改动）；新加的照常核对
             const kept = new Set(current.definition.skills?.orgSkills ?? []);
             await assertOrgSkills(t, orgId, definition.skills?.orgSkills ?? [], kept);
@@ -571,11 +626,11 @@ let AgentsService = class AgentsService {
         return this.lookup.view(agentId);
     }
     /** 软删除：权限同 update。待处理的技能改动与该 agent 评测集在执行的评测运行一并取消，提交后删除草稿（T15）。 */
-    async softDelete(orgId, agentId, actorAccountId, actorTokenId) {
-        const cancelled = await this.softDeleteIn(orgId, agentId, actorAccountId, actorTokenId);
+    async softDelete(orgId, agentId, actorAccountId, actorTokenId, auditDetail) {
+        const cancelled = await this.softDeleteIn(orgId, agentId, actorAccountId, actorTokenId, auditDetail);
         await this.skillChanges.finishCancel(orgId, cancelled);
     }
-    async softDeleteIn(orgId, agentId, actorAccountId, actorTokenId) {
+    async softDeleteIn(orgId, agentId, actorAccountId, actorTokenId, auditDetail) {
         const t = this.db.db;
         await this.lockForWrite(orgId, agentId, actorAccountId);
         await t
@@ -596,6 +651,7 @@ let AgentsService = class AgentsService {
             orgId,
             action: "agent.deleted",
             target: agentId,
+            ...(auditDetail !== undefined && { detail: auditDetail }),
         });
         // the agent row stays (soft delete), so its setup request is closed here (P4-T6-3)
         await this.setupRequests.settleIn({

package/dist/agents/definition.d.ts

@@ -14,28 +14,48 @@ export type ModelRef = z.infer<typeof ModelRef>;
 export declare const ModelParams: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
 export type ModelParams = z.infer<typeof ModelParams>;
 /**
- * 改名前（D17）保存的连接器引用 `{ kind: "app", appId, tools }` 规范化为 `{ kind: "connector", connectorId, tools }`
- * （C27：已存 agent 版本不改写，读入时规范化；新保存只写 connector 形）。其余值原样返回。
+ * A tool an agent turns off (tools default-on spec §2): agents have every builtin, every tool of
+ * the extensions enabled in the org and every tool of the org's connectors, minus these. A builtin
+ * by name; an extension's or a connector's tools by name, or `"all"` to turn it off as a unit
+ * (tools it gains later included). Connectors by id, so a renamed connector stays off.
  */
-export declare function normalizeToolRef(v: unknown): unknown;
-/**
- * agent 定义里对工具的引用：内置工具按名字；插件工具按插件名 + 工具名；连接器工具按连接器 id，
- * `tools: "all"` = 该连接器当前所有启用的工具。旧形 `{ kind: "app", appId }` 仍可解析（见 {@link normalizeToolRef}）。
- */
-export declare const AgentToolRef: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const DisabledToolRef: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"builtin">;
     name: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"plugin">;
     plugin: z.ZodString;
-    name: z.ZodString;
+    tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"connector">;
     connectorId: z.ZodString;
     tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
-}, z.core.$strict>], "kind">, unknown>;
-export type AgentToolRef = z.output<typeof AgentToolRef>;
-export { DEFAULT_AGENT_TOOLS } from "../tools/builtin-names.js";
+}, z.core.$strict>], "kind">;
+export type DisabledToolRef = z.output<typeof DisabledToolRef>;
+/** Is builtin `name` turned off by `disabled`? */
+export declare const builtinDisabled: (disabled: readonly DisabledToolRef[] | undefined, name: string) => boolean;
+/** Is tool `name` of extension `plugin` turned off by `disabled`? */
+export declare const extensionToolDisabled: (disabled: readonly DisabledToolRef[] | undefined, plugin: string, name: string) => boolean;
+/** Is tool `name` of connector `connectorId` turned off by `disabled`? */
+export declare const connectorToolDisabled: (disabled: readonly DisabledToolRef[] | undefined, connectorId: string, name: string) => boolean;
+/**
+ * `disabled` in its canonical form: one entry per builtin, extension and connector (in first-seen
+ * order), names deduplicated and sorted, `"all"` absorbing names. Saving stores this form, so two
+ * lists that turn off the same tools compare equal.
+ */
+export declare function canonicalDisabledTools(disabled: readonly DisabledToolRef[]): DisabledToolRef[];
+/**
+ * A sub-agent's tool filter by tool key (tools default-on spec §4): written only into a child's
+ * effective definition at dispatch (never accepted on save). `deny` removes keys (the child-removed
+ * tools, `Agent` at the depth limit, a template's `disallowedTools`); `allow`, when set, keeps only
+ * its keys (a template's `tools` allowlist). Registry-managed tools (`Skill`, `ToolSearch`,
+ * `SendMessage`, `SubagentHandback`) are not filtered.
+ */
+export declare const SubagentToolsSchema: z.ZodObject<{
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type SubagentTools = z.infer<typeof SubagentToolsSchema>;
 /** Roster names of inline templates and allowlisted org agents (the template name rule). */
 export declare const SUBAGENT_NAME_RE: RegExp;
 /**
@@ -142,6 +162,7 @@ export type PendingConnector = z.infer<typeof PendingConnectorSchema>;
 /** Agent 定义：每次变化写一个新版本（`capybara.agent_versions`）。 */
 export declare const AgentDefinitionSchema: z.ZodObject<{
     name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
     avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
     instructions: z.ZodDefault<z.ZodString>;
     instructionFiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -158,18 +179,22 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     modelParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     fallbackParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-    tools: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    disabledTools: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"builtin">;
         name: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
         plugin: z.ZodString;
-        name: z.ZodString;
+        tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"connector">;
         connectorId: z.ZodString;
         tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
-    }, z.core.$strict>], "kind">, unknown>>>;
+    }, z.core.$strict>], "kind">>>;
+    subagentTools: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     toolPolicies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
         ask: "ask";
         deny: "deny";
@@ -267,10 +292,12 @@ export declare function normalizeToolKeys(definition: unknown, scope?: LegacySco
  */
 export declare function needsLegacyScope(definition: unknown): boolean;
 /**
- * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
- * connector 形（C27），and rc tool keys to current keys ({@link normalizeToolKeys}: builtins
- * always, `<x>__<tool>` keys with `scope`). Other fields are kept; without old forms the same
- * object is returned.
+ * A definition read from the database or from history (not parsed by zod): rc tool keys read as
+ * current keys ({@link normalizeToolKeys}: builtins always, `<x>__<tool>` keys with `scope`), and
+ * a definition from before tools were on by default (an enabled `tools` list, history only: the
+ * migration rewrote stored versions) reads as nothing turned off, which is what the migration
+ * writes (tools default-on spec §2, §3). Other fields are kept; without old forms the same object
+ * is returned.
  */
 export declare function normalizeStoredDefinition(def: unknown, scope?: LegacyScope): AgentDefinition;
 /** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
@@ -280,3 +307,4 @@ export declare function paramIssues(field: string, decl: ModelParameter[], param
 }[];
 /** Roster entries an agent may list (spec §4.3), general-purpose included. */
 export declare const SUBAGENT_ROSTER_MAX = 20;
+export {};

package/dist/agents/definition.js

@@ -10,36 +10,74 @@ export const ModelRef = z.object({ provider: z.string(), model: z.string() });
  */
 export const ModelParams = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
 /**
- * 改名前（D17）保存的连接器引用 `{ kind: "app", appId, tools }` 规范化为 `{ kind: "connector", connectorId, tools }`
- * （C27：已存 agent 版本不改写，读入时规范化；新保存只写 connector 形）。其余值原样返回。
+ * A tool an agent turns off (tools default-on spec §2): agents have every builtin, every tool of
+ * the extensions enabled in the org and every tool of the org's connectors, minus these. A builtin
+ * by name; an extension's or a connector's tools by name, or `"all"` to turn it off as a unit
+ * (tools it gains later included). Connectors by id, so a renamed connector stays off.
  */
-export function normalizeToolRef(v) {
-    if (typeof v !== "object" || v === null || Array.isArray(v))
-        return v;
-    const r = v;
-    if (r.kind !== "app")
-        return v;
-    const { kind: _kind, appId, ...rest } = r;
-    return { kind: "connector", connectorId: appId, ...rest };
-}
-/**
- * agent 定义里对工具的引用：内置工具按名字；插件工具按插件名 + 工具名；连接器工具按连接器 id，
- * `tools: "all"` = 该连接器当前所有启用的工具。旧形 `{ kind: "app", appId }` 仍可解析（见 {@link normalizeToolRef}）。
- */
-export const AgentToolRef = z.preprocess(normalizeToolRef, z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("builtin"), name: z.string().min(1) }).strict(),
+export const DisabledToolRef = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("builtin"), name: z.string().min(1).max(200) }).strict(),
     z
-        .object({ kind: z.literal("plugin"), plugin: z.string().min(1), name: z.string().min(1) })
+        .object({
+        kind: z.literal("plugin"),
+        plugin: z.string().min(1).max(200),
+        tools: z.union([z.literal("all"), z.array(z.string().min(1).max(256)).min(1).max(500)]),
+    })
         .strict(),
     z
         .object({
         kind: z.literal("connector"),
-        connectorId: z.string().min(1),
-        tools: z.union([z.literal("all"), z.array(z.string().min(1)).min(1)]),
+        connectorId: z.string().min(1).max(100),
+        tools: z.union([z.literal("all"), z.array(z.string().min(1).max(256)).min(1).max(500)]),
     })
         .strict(),
-]));
-export { DEFAULT_AGENT_TOOLS } from "../tools/builtin-names.js";
+]);
+/** Is builtin `name` turned off by `disabled`? */
+export const builtinDisabled = (disabled, name) => (disabled ?? []).some((r) => r.kind === "builtin" && r.name === name);
+/** Is tool `name` of extension `plugin` turned off by `disabled`? */
+export const extensionToolDisabled = (disabled, plugin, name) => (disabled ?? []).some((r) => r.kind === "plugin" && r.plugin === plugin && (r.tools === "all" || r.tools.includes(name)));
+/** Is tool `name` of connector `connectorId` turned off by `disabled`? */
+export const connectorToolDisabled = (disabled, connectorId, name) => (disabled ?? []).some((r) => r.kind === "connector" &&
+    r.connectorId === connectorId &&
+    (r.tools === "all" || r.tools.includes(name)));
+/**
+ * `disabled` in its canonical form: one entry per builtin, extension and connector (in first-seen
+ * order), names deduplicated and sorted, `"all"` absorbing names. Saving stores this form, so two
+ * lists that turn off the same tools compare equal.
+ */
+export function canonicalDisabledTools(disabled) {
+    const out = [];
+    const merge = (cur, add) => cur === "all" || add === "all" ? "all" : [...new Set([...cur, ...add])].sort();
+    for (const r of disabled) {
+        if (r.kind === "builtin") {
+            if (!builtinDisabled(out, r.name))
+                out.push({ kind: "builtin", name: r.name });
+            continue;
+        }
+        const prev = out.find((x) => x.kind === r.kind &&
+            (r.kind === "plugin"
+                ? x.plugin === r.plugin
+                : x.connectorId === r.connectorId));
+        if (prev)
+            prev.tools = merge(prev.tools, r.tools);
+        else
+            out.push({ ...r, tools: r.tools === "all" ? "all" : [...new Set(r.tools)].sort() });
+    }
+    return out;
+}
+/**
+ * A sub-agent's tool filter by tool key (tools default-on spec §4): written only into a child's
+ * effective definition at dispatch (never accepted on save). `deny` removes keys (the child-removed
+ * tools, `Agent` at the depth limit, a template's `disallowedTools`); `allow`, when set, keeps only
+ * its keys (a template's `tools` allowlist). Registry-managed tools (`Skill`, `ToolSearch`,
+ * `SendMessage`, `SubagentHandback`) are not filtered.
+ */
+export const SubagentToolsSchema = z
+    .object({
+    allow: z.array(z.string().min(1).max(300)).max(500).optional(),
+    deny: z.array(z.string().min(1).max(300)).max(500).optional(),
+})
+    .strict();
 /** Roster names of inline templates and allowlisted org agents (the template name rule). */
 export const SUBAGENT_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 /**
@@ -134,6 +172,13 @@ export const PendingConnectorSchema = z
 /** Agent 定义：每次变化写一个新版本（`capybara.agent_versions`）。 */
 export const AgentDefinitionSchema = z.object({
     name: z.string().min(1).max(80),
+    /**
+     * What the agent is for, one short paragraph (run context spec §3.5): shown on the agent's
+     * cards (copied to `agents.profile_description`) and given to the model in the run context. No
+     * default: older versions are unchanged and gain no version. A save without it keeps the
+     * current version's; `""` removes it.
+     */
+    description: z.string().max(500).optional(),
     avatarUrl: z.url().nullable().default(null),
     /**
      * The model-visible system prompt. Derived on save from `instructionFiles` when they are given
@@ -151,11 +196,19 @@ export const AgentDefinitionSchema = z.object({
     modelParams: ModelParams.default({}),
     /** 兜底模型自己的参数（按兜底模型的声明校验）；兜底尝试只用这一份。 */
     fallbackParams: ModelParams.default({}),
-    /** 引用的工具（M2 保存的 `tools: []` 仍然合法）；保存时校验引用存在，运行时由注册表解析。 */
-    tools: z.array(AgentToolRef).default([]),
     /**
-     * 按工具 key 收紧策略（只能收紧：`ask` / `deny`，不接受 `allow`）；键必须是该 agent 引用的工具的 key。
-     * 较早保存的定义没有该字段，按空处理。
+     * The tools this agent turns off (tools default-on spec §2); everything else the org offers is
+     * on. Saved in canonical form ({@link canonicalDisabledTools}); checked on save.
+     */
+    disabledTools: z.array(DisabledToolRef).max(500).default([]),
+    /**
+     * A sub-agent's key filter, set only on a child's effective definition at dispatch (see
+     * {@link SubagentToolsSchema}); a save that carries it is refused.
+     */
+    subagentTools: SubagentToolsSchema.optional(),
+    /**
+     * Tightened policies by tool key (`ask` / `deny` only, never `allow`); keys are tools the agent
+     * could have (on or turned off). Older definitions without it read as empty.
      */
     toolPolicies: z.record(z.string(), z.enum(["ask", "deny"])).default({}),
     /**
@@ -180,7 +233,7 @@ export const AgentDefinitionSchema = z.object({
     })
         .strict()
         .optional(),
-    /** Sub-agents (phase C); offered only when the builtin `Agent` tool is in `tools`. */
+    /** Sub-agents (phase C); offered unless the builtin `Agent` tool is turned off. */
     subagents: SubagentsSchema.optional(),
     /**
      * Connectors still to configure (ruling P4-6), written only by creating from a template. No
@@ -190,14 +243,18 @@ export const AgentDefinitionSchema = z.object({
 });
 const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /**
- * The connector slugs and extension names `definition`'s `tools` name: connector refs (through
- * `scope.connectorSlugById`), plugin refs, and current-format keys of a template's `tools`;
- * `inherited` (the parent agent's, for an inline template) is added.
+ * The connector slugs and extension names `definition` names: connector refs (through
+ * `scope.connectorSlugById`) and plugin refs of a frozen definition's `tools` or of
+ * `disabledTools`, and current-format keys of a template's `tools`; `inherited` (the parent
+ * agent's, for an inline template) is added.
  */
 function ownRefs(definition, scope, inherited) {
     const connectors = new Set(inherited?.connectors);
     const extensions = new Set(inherited?.extensions);
-    const tools = Array.isArray(definition.tools) ? definition.tools : [];
+    const tools = [
+        ...(Array.isArray(definition.tools) ? definition.tools : []),
+        ...(Array.isArray(definition.disabledTools) ? definition.disabledTools : []),
+    ];
     for (const r of tools) {
         if (typeof r === "string") {
             const m = /^(mcp|plugin)__([^_].*?)__./.exec(r);
@@ -289,7 +346,10 @@ function policyKeys(v, scope, own) {
     }
     return out;
 }
-/** An agent definition's `tools`: builtin refs by their current names (connector and plugin refs name tools, not keys). */
+/**
+ * A definition's `tools`: a template's allowlist of keys, or the refs of a definition frozen into
+ * history before tools were on by default (builtin refs by their current names).
+ */
 function toolRefs(v, scope, own) {
     if (!Array.isArray(v))
         return v;
@@ -369,18 +429,39 @@ export function needsLegacyScope(definition) {
     return isRecord(sub) && Array.isArray(sub.inline) && sub.inline.some(needsLegacyScope);
 }
 /**
- * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
- * connector 形（C27），and rc tool keys to current keys ({@link normalizeToolKeys}: builtins
- * always, `<x>__<tool>` keys with `scope`). Other fields are kept; without old forms the same
- * object is returned.
+ * A tool ref of a definition frozen into history (logs, eval case snapshots) before tools were on
+ * by default (tools default-on spec §2): `{ kind: "app", appId }` (before D17) reads as a
+ * connector ref. Other values are returned as they are.
+ */
+function normalizeToolRef(v) {
+    if (!isRecord(v) || v.kind !== "app")
+        return v;
+    const { kind: _kind, appId, ...rest } = v;
+    return { kind: "connector", connectorId: appId, ...rest };
+}
+/**
+ * A definition read from the database or from history (not parsed by zod): rc tool keys read as
+ * current keys ({@link normalizeToolKeys}: builtins always, `<x>__<tool>` keys with `scope`), and
+ * a definition from before tools were on by default (an enabled `tools` list, history only: the
+ * migration rewrote stored versions) reads as nothing turned off, which is what the migration
+ * writes (tools default-on spec §2, §3). Other fields are kept; without old forms the same object
+ * is returned.
  */
 export function normalizeStoredDefinition(def, scope) {
     let d = def;
     const tools = d.tools;
-    if (Array.isArray(tools) && tools.some((t) => t?.kind === "app")) {
+    if (Array.isArray(tools) && tools.some((t) => isRecord(t) && t.kind === "app")) {
         d = { ...d, tools: tools.map(normalizeToolRef) };
     }
-    return normalizeToolKeys(d, scope);
+    d = normalizeToolKeys(d, scope);
+    if ("tools" in d) {
+        const { tools: _enabled, ...rest } = d;
+        d = { ...rest, disabledTools: Array.isArray(d.disabledTools) ? d.disabledTools : [] };
+    }
+    else if (!Array.isArray(d.disabledTools)) {
+        d = { ...d, disabledTools: [] };
+    }
+    return d;
 }
 /** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
 export function paramIssues(field, decl, params) {

package/dist/agents/from-template.d.ts

@@ -12,8 +12,8 @@ export type PlanItemKind = "instruction_file" | "description" | "quick_action" |
  * qualifies some carried ones:
  * - instruction_file: unavailable `invalid_name`, `duplicate`, `too_many`, `too_long` (the joined
  *   files exceed the agent's limit);
- * - tool: `default` (the template names no tools: the defaults of a new agent), `subagents`
- *   (`Agent` added because the template describes sub-agents); unavailable `plugin_unavailable`
+ * - tool (the template's `tools` allowlist): `subagents` (`Agent` kept on because the template
+ *   describes sub-agents, though its allowlist leaves it out); unavailable `plugin_unavailable`
  *   (its plugin is not enabled in the org or not loaded), `unknown_tool`, `connector_key` (a
  *   connector tool key: connectors carry over only through `connectors` entries);
  * - skill: `pinned`, `not_pinned_manual_only`, `not_pinned_too_large`, `subagent` (named only by an