@capybara-hq/kernel 0.1.0-rc.11 → 0.1.0-rc.12

package/dist/tools/connector-account-policies.d.ts

@@ -0,0 +1,51 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { type ToolPolicy } from "./registry.js";
+/**
+ * Why a member cannot set a tool's policy: the org switched the tool off (or it is not offered:
+ * pending review, gone), or the org set its default to deny. Either way it stays denied.
+ */
+export type MemberPolicyLock = "disabled" | "org_deny";
+/** One tool on the member's 权限 sheet (`GET …/connectors/:id/tool-policies/me`). */
+export interface MemberToolPolicyView {
+    name: string;
+    key: string;
+    title: string | null;
+    description: string;
+    /** The org's default for the tool (`connector_tools.default_policy`): what applies without a setting. */
+    defaultPolicy: ToolPolicy;
+    /** What the tool's annotations alone give (`readOnlyHint: true` allows, anything else asks). */
+    annotationPolicy: "allow" | "ask";
+    /** The member's own setting, null without one. */
+    policy: ToolPolicy | null;
+    /** Locked by the org: the member's setting does not apply, the tool is denied. */
+    locked: MemberPolicyLock | null;
+}
+/** Whether a connector's credential is per member: its calls are made with the member's connection. */
+export declare const personalAuth: (auth: unknown) => boolean;
+/**
+ * A member's own tool policies for their own connection of a personal-credential connector
+ * (maintainer decision 2026-11-09, the connector card's 权限). They apply to every agent the
+ * member uses; an agent's tool policy overrides them; a tool the org switched off or set to deny
+ * stays denied (`tools/policy.ts` `connectorPolicy`). Only the account itself reads or writes its
+ * rows: the routes take the account from the session, never from the request.
+ */
+export declare class ConnectorAccountPolicies {
+    private readonly kdb;
+    private readonly orgLock;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, orgLock: OrgLock, txHost: TransactionHost);
+    /** The kernel-schema handle of the current context (its transaction, else the pool). */
+    private get db();
+    /** The connector's tools with the account's settings; not personal -> 409 `connector.not_personal`. */
+    read(orgId: string, connectorId: string, accountId: string): Promise<MemberToolPolicyView[]>;
+    /**
+     * Sets (a policy) or clears (null) the account's policies for some of the connector's tools;
+     * an unknown tool -> 404 `connector.tool_not_found`. Locked tools may hold a setting: it does not
+     * apply while the lock lasts. Audits `connector.member_policies_changed`.
+     */
+    set(orgId: string, connectorId: string, accountId: string, changes: Record<string, ToolPolicy | null>, actorTokenId?: string): Promise<void>;
+    /** The org's live personal-credential connector, else 404 / 409. */
+    private connector;
+}

package/dist/tools/connector-account-policies.js

@@ -0,0 +1,165 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { connectorToolKey } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { policyFromAnnotations } from "./registry.js";
+/** Whether a connector's credential is per member: its calls are made with the member's connection. */
+export const personalAuth = (auth) => {
+    const a = auth;
+    return a !== null && a.type !== "none" && a.ownership === "personal";
+};
+const notPersonal = () => new ApiError("connector.not_personal", "This connector uses one credential for the whole organization; only a connector each member connects to with their own credential has per-member tool policies");
+const notFound = () => new ApiError("connector.not_found", "Connector not found");
+/**
+ * A member's own tool policies for their own connection of a personal-credential connector
+ * (maintainer decision 2026-11-09, the connector card's 权限). They apply to every agent the
+ * member uses; an agent's tool policy overrides them; a tool the org switched off or set to deny
+ * stays denied (`tools/policy.ts` `connectorPolicy`). Only the account itself reads or writes its
+ * rows: the routes take the account from the session, never from the request.
+ */
+let ConnectorAccountPolicies = class ConnectorAccountPolicies {
+    kdb;
+    orgLock;
+    txHost;
+    constructor(kdb, orgLock, txHost) {
+        this.kdb = kdb;
+        this.orgLock = orgLock;
+        this.txHost = txHost;
+    }
+    /** The kernel-schema handle of the current context (its transaction, else the pool). */
+    get db() {
+        return this.kdb.db;
+    }
+    /** The connector's tools with the account's settings; not personal -> 409 `connector.not_personal`. */
+    async read(orgId, connectorId, accountId) {
+        const c = await this.connector(orgId, connectorId);
+        const tools = await this.db
+            .selectFrom("connector_tools")
+            .select(["name", "spec", "status", "default_policy", "missing_since"])
+            .where("connector_id", "=", connectorId)
+            .orderBy("name")
+            .execute();
+        const mine = new Map((await this.db
+            .selectFrom("connector_tool_account_policies")
+            .select(["tool_name", "policy"])
+            .where("connector_id", "=", connectorId)
+            .where("account_id", "=", accountId)
+            .execute()).map((r) => [r.tool_name, r.policy]));
+        return tools.map((t) => {
+            const spec = t.spec;
+            const locked = t.status !== "enabled" || t.missing_since !== null
+                ? "disabled"
+                : t.default_policy === "deny"
+                    ? "org_deny"
+                    : null;
+            return {
+                name: t.name,
+                key: connectorToolKey(c.slug, t.name),
+                title: typeof spec.title === "string" ? spec.title : null,
+                description: spec.description,
+                defaultPolicy: t.default_policy,
+                annotationPolicy: policyFromAnnotations(spec.annotations),
+                policy: mine.get(t.name) ?? null,
+                locked,
+            };
+        });
+    }
+    /**
+     * Sets (a policy) or clears (null) the account's policies for some of the connector's tools;
+     * an unknown tool -> 404 `connector.tool_not_found`. Locked tools may hold a setting: it does not
+     * apply while the lock lasts. Audits `connector.member_policies_changed`.
+     */
+    async set(orgId, connectorId, accountId, changes, actorTokenId) {
+        await this.orgLock.lockAndAuthorize(orgId, accountId, "connectors.use");
+        await this.connector(orgId, connectorId);
+        const names = Object.keys(changes);
+        if (names.length === 0)
+            return;
+        const known = new Set((await this.db
+            .selectFrom("connector_tools")
+            .select("name")
+            .where("connector_id", "=", connectorId)
+            .where("name", "in", names)
+            .execute()).map((r) => r.name));
+        const unknown = names.find((n) => !known.has(n));
+        if (unknown !== undefined) {
+            throw new ApiError("connector.tool_not_found", `No tool ${unknown} in this connector`);
+        }
+        const cleared = names.filter((n) => changes[n] === null);
+        if (cleared.length > 0) {
+            await this.db
+                .deleteFrom("connector_tool_account_policies")
+                .where("connector_id", "=", connectorId)
+                .where("account_id", "=", accountId)
+                .where("tool_name", "in", cleared)
+                .execute();
+        }
+        const set = names.flatMap((n) => {
+            const p = changes[n];
+            return p === null || p === undefined ? [] : [{ name: n, policy: p }];
+        });
+        if (set.length > 0) {
+            await this.db
+                .insertInto("connector_tool_account_policies")
+                .values(set.map((x) => ({
+                org_id: orgId,
+                connector_id: connectorId,
+                account_id: accountId,
+                tool_name: x.name,
+                policy: x.policy,
+            })))
+                .onConflict((oc) => oc.columns(["connector_id", "account_id", "tool_name"]).doUpdateSet({
+                policy: (eb) => eb.ref("excluded.policy"),
+                updated_at: sql `now()`,
+            }))
+                .execute();
+        }
+        await audit(this.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "connector.member_policies_changed",
+            target: connectorId,
+            detail: { tools: changes },
+        });
+    }
+    /** The org's live personal-credential connector, else 404 / 409. */
+    async connector(orgId, connectorId) {
+        const c = await this.db
+            .selectFrom("connectors")
+            .select(["slug", "auth"])
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!c)
+            throw notFound();
+        if (!personalAuth(c.auth))
+            throw notPersonal();
+        return { slug: c.slug };
+    }
+};
+__decorate([
+    Transactional()
+], ConnectorAccountPolicies.prototype, "set", null);
+ConnectorAccountPolicies = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(OrgLock)),
+    __param(2, Inject(TransactionHost))
+], ConnectorAccountPolicies);
+export { ConnectorAccountPolicies };

package/dist/tools/connectors.controller.d.ts

@@ -1,7 +1,9 @@
 import { z } from "zod";
+import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import { CredentialValue } from "./connectors.schemas.js";
+import { ConnectorAccountPolicies, type MemberToolPolicyView } from "./connector-account-policies.js";
+import { CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
 import { type ConnectorDetail, type ConnectorPreview, type ConnectorSummary, ConnectorsService, type ToolIssue } from "./connectors.service.js";
 declare const CreateBody: z.ZodObject<{
     name: z.ZodString;
@@ -173,9 +175,19 @@ declare const UpdateBody: z.ZodObject<{
  */
 export declare class ConnectorsController {
     private readonly connectors;
-    constructor(connectors: ConnectorsService);
+    private readonly icons;
+    private readonly memberPolicies;
+    constructor(connectors: ConnectorsService, icons: PluginIcons, memberPolicies: ConnectorAccountPolicies);
+    /**
+     * Each connector with `icon`: the icon of the plugin its template came from, on the org's catalog
+     * route (null for a custom connector, a plugin without an icon, or one the reader's catalog does
+     * not show: the share gate holds; maintainer decision 2026-11-09).
+     */
+    private withIcons;
     list(org: OrgContext): Promise<{
-        connectors: ConnectorSummary[];
+        connectors: (ConnectorSummary & {
+            icon: string | null;
+        })[];
     }>;
     /**
      * The connector kinds the org can create connectors of, each with the plugin providing it (the
@@ -197,7 +209,9 @@ export declare class ConnectorsController {
      */
     preview(principal: Principal, org: OrgContext, body: z.infer<typeof PreviewBody>): Promise<ConnectorPreview>;
     get(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorDetail & {
+            icon: string | null;
+        };
     }>;
     update(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof UpdateBody>): Promise<{
         connector: ConnectorDetail;
@@ -218,6 +232,23 @@ export declare class ConnectorsController {
     }>;
     setOrgCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;
     setMyCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;
+    /**
+     * The caller's own tool policies for their own connection of a personal-credential connector
+     * (the card's 权限, decision 2026-11-09): each tool with the org default, the annotation default,
+     * the caller's setting and whether the org locked it. Only ever the caller's rows. A connector
+     * with one org credential -> 409 `connector.not_personal`.
+     */
+    myToolPolicies(principal: Principal, org: OrgContext, connectorId: string): Promise<{
+        tools: MemberToolPolicyView[];
+    }>;
+    /**
+     * Sets (`allow` / `ask` / `deny`) or clears (null) the caller's own policies for some tools:
+     * `{ tools: { <name>: policy | null } }` -> the sheet again. Unknown tool -> 404
+     * `connector.tool_not_found`.
+     */
+    setMyToolPolicies(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof MemberToolPoliciesBody>): Promise<{
+        tools: MemberToolPolicyView[];
+    }>;
     clearMyCredential(principal: Principal, org: OrgContext, connectorId: string): Promise<void>;
 }
 export {};

package/dist/tools/connectors.controller.js

@@ -10,12 +10,14 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { ConnectorAuthSchema } from "@capybara-hq/plugin-sdk";
 import { Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, Put } from "@nestjs/common";
 import { z } from "zod";
+import { orgIconScope, PluginIcons } from "../extensions/plugin-icons.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { can } from "../orgs/roles.js";
-import { CredentialValue } from "./connectors.schemas.js";
+import { ConnectorAccountPolicies, } from "./connector-account-policies.js";
+import { CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
 import { ConnectorsService, } from "./connectors.service.js";
 import { publicEndpoint } from "./endpoint.js";
 /**
@@ -84,17 +86,37 @@ class ConnectorToolReviewBody extends createZodDto(ReviewBody, "ConnectorToolRev
 }
 class ConnectorCredentialBody extends createZodDto(CredentialValue, "ConnectorCredentialBody") {
 }
+class MemberToolPoliciesDto extends createZodDto(MemberToolPoliciesBody, "MemberToolPoliciesBody") {
+}
 /**
  * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
  * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
  */
 let ConnectorsController = class ConnectorsController {
     connectors;
-    constructor(connectors) {
+    icons;
+    memberPolicies;
+    constructor(connectors, icons, memberPolicies) {
         this.connectors = connectors;
+        this.icons = icons;
+        this.memberPolicies = memberPolicies;
+    }
+    /**
+     * Each connector with `icon`: the icon of the plugin its template came from, on the org's catalog
+     * route (null for a custom connector, a plugin without an icon, or one the reader's catalog does
+     * not show: the share gate holds; maintainer decision 2026-11-09).
+     */
+    async withIcons(org, rows) {
+        const ids = rows.flatMap((r) => (r.catalogItemId === null ? [] : [r.catalogItemId]));
+        const urls = await this.icons.ofItems(ids, orgIconScope(org));
+        return rows.map((r) => ({
+            ...r,
+            icon: r.catalogItemId === null ? null : (urls.get(r.catalogItemId) ?? null),
+        }));
     }
     async list(org) {
-        return { connectors: (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a)) };
+        const rows = (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a));
+        return { connectors: await this.withIcons(org, rows) };
     }
     /**
      * The connector kinds the org can create connectors of, each with the plugin providing it (the
@@ -117,9 +139,9 @@ let ConnectorsController = class ConnectorsController {
     }
     async get(principal, org, connectorId) {
         const p = requireUser(principal);
-        return {
-            connector: forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id)),
-        };
+        const c = forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id));
+        const [connector] = await this.withIcons(org, [c]);
+        return { connector: connector };
     }
     async update(principal, org, connectorId, body) {
         const p = requireUser(principal);
@@ -150,6 +172,26 @@ let ConnectorsController = class ConnectorsController {
         const p = requireUser(principal);
         await this.connectors.setCredential(org.orgId, connectorId, p.account.id, "personal", body, patTokenId(p));
     }
+    /**
+     * The caller's own tool policies for their own connection of a personal-credential connector
+     * (the card's 权限, decision 2026-11-09): each tool with the org default, the annotation default,
+     * the caller's setting and whether the org locked it. Only ever the caller's rows. A connector
+     * with one org credential -> 409 `connector.not_personal`.
+     */
+    async myToolPolicies(principal, org, connectorId) {
+        const p = requireUser(principal);
+        return { tools: await this.memberPolicies.read(org.orgId, connectorId, p.account.id) };
+    }
+    /**
+     * Sets (`allow` / `ask` / `deny`) or clears (null) the caller's own policies for some tools:
+     * `{ tools: { <name>: policy | null } }` -> the sheet again. Unknown tool -> 404
+     * `connector.tool_not_found`.
+     */
+    async setMyToolPolicies(principal, org, connectorId, body) {
+        const p = requireUser(principal);
+        await this.memberPolicies.set(org.orgId, connectorId, p.account.id, body.tools, patTokenId(p));
+        return { tools: await this.memberPolicies.read(org.orgId, connectorId, p.account.id) };
+    }
     async clearMyCredential(principal, org, connectorId) {
         const p = requireUser(principal);
         await this.connectors.clearMyCredential(org.orgId, connectorId, p.account.id, patTokenId(p));
@@ -239,6 +281,21 @@ __decorate([
     __param(2, Param("connectorId")),
     __param(3, ZBody(ConnectorCredentialBody))
 ], ConnectorsController.prototype, "setMyCredential", null);
+__decorate([
+    Get(":connectorId/tool-policies/me"),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId"))
+], ConnectorsController.prototype, "myToolPolicies", null);
+__decorate([
+    Put(":connectorId/tool-policies/me"),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, ZBody(MemberToolPoliciesDto))
+], ConnectorsController.prototype, "setMyToolPolicies", null);
 __decorate([
     Delete(":connectorId/credentials/me"),
     HttpCode(204),
@@ -249,6 +306,8 @@ __decorate([
 ], ConnectorsController.prototype, "clearMyCredential", null);
 ConnectorsController = __decorate([
     Controller("api/v1/orgs/:orgId/connectors"),
-    __param(0, Inject(ConnectorsService))
+    __param(0, Inject(ConnectorsService)),
+    __param(1, Inject(PluginIcons)),
+    __param(2, Inject(ConnectorAccountPolicies))
 ], ConnectorsController);
 export { ConnectorsController };

package/dist/tools/connectors.schemas.d.ts

@@ -10,3 +10,14 @@ export declare const ConnectorPathParams: z.ZodObject<{
     connectorId: z.ZodString;
 }, z.core.$strip>;
 export declare const CONNECTOR_ROUTES: readonly RouteSchemas[];
+/**
+ * `PUT …/connectors/:connectorId/tool-policies/me`: the caller's own policy per tool name (null
+ * clears it; decision 2026-11-09).
+ */
+export declare const MemberToolPoliciesBody: z.ZodObject<{
+    tools: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        deny: "deny";
+    }>>>;
+}, z.core.$strict>;

package/dist/tools/connectors.schemas.js

@@ -17,3 +17,14 @@ export const CONNECTOR_ROUTES = [
         params: ConnectorPathParams,
     },
 ];
+/**
+ * `PUT …/connectors/:connectorId/tool-policies/me`: the caller's own policy per tool name (null
+ * clears it; decision 2026-11-09).
+ */
+export const MemberToolPoliciesBody = z
+    .object({
+    tools: z
+        .record(z.string().min(1).max(200), z.enum(["allow", "ask", "deny"]).nullable())
+        .refine((v) => Object.keys(v).length <= 1000, { message: "Too many tools" }),
+})
+    .strict();

package/dist/tools/connectors.service.d.ts

@@ -66,6 +66,8 @@ export interface ConnectorSummary {
      * a custom one: the web offers it for a pending connector of that template (ruling P4-7).
      */
     platformTemplateId: string | null;
+    /** The plugin (catalog item) its template came from (`connectors.catalog_item_id`), else null. */
+    catalogItemId: string | null;
     createdBy: string;
     createdAt: Date;
     updatedAt: Date;

package/dist/tools/connectors.service.js

@@ -760,6 +760,7 @@ let ConnectorsService = class ConnectorsService {
             auth: r.auth,
             status: r.status,
             platformTemplateId: r.platform_template_id ?? null,
+            catalogItemId: r.catalog_item_id ?? null,
             createdBy: r.created_by,
             createdAt: r.created_at,
             updatedAt: r.updated_at,

package/dist/tools/pipeline.d.ts

@@ -65,7 +65,7 @@ export interface AskRequest {
  * policy, a fixed ask (R3, `requiresUserInteraction`), the org's `sandboxToolPolicy`, or the tool's
  * own default. `org` and `fixed` were added after the first B events (older logs say `default`).
  */
-export type ApprovalPolicySource = "agent" | "connector" | "default" | "role" | "org" | "fixed";
+export type ApprovalPolicySource = "agent" | "connector" | "member" | "default" | "role" | "org" | "fixed";
 /**
  * `unavailable`：调用那一刻工具已不可用（连接器 / 工具不存在、停用、删除、待审核），值为事实原因；
  * 管线写「工具不可用」说明，而不是「策略拒绝」。

package/dist/tools/policy.d.ts

@@ -25,6 +25,28 @@ export declare function decide(input: PolicyInput): ToolPolicy;
  * 除非 agent 当前版本的 `skills.writePolicy` 为 `ask`（`skillWritePolicy`）；不知道可见性时按共享处理（更严）。
  */
 export declare function isFixedAsk(tool: ResolvedTool, visibility?: "private" | "org" | "members" | undefined, skillWritePolicy?: "allow" | "ask" | undefined): boolean;
+/** Which level decided a connector tool's policy ({@link connectorPolicy}). */
+export type ConnectorPolicySource = "org" | "member" | "agent";
+/**
+ * A personal-credential connector tool's policy for one call (maintainer decisions 2026-11-09;
+ * an org-credential connector's tool keeps the org default with the agent's tightening only),
+ * highest first:
+ * 1. the org's default `deny` (a tool the org switched off never gets here: it is unavailable);
+ * 2. the member's own `deny` for calls with their connection (`member`): a floor no agent lifts;
+ * 3. the agent's setting (`agent`, from its tools page): `allow` / `ask` / `deny`;
+ * 4. the member's own `allow` / `ask`;
+ * 5. the org's default (`connector_tools.default_policy`, the annotation default unless an org
+ *    admin changed it: `readOnlyHint: true` allows, anything else asks).
+ * Fixed asks (R3, `requiresUserInteraction`), role escalation and grants apply after this.
+ */
+export declare function connectorPolicy(input: {
+    orgDefault: ToolPolicy;
+    member?: ToolPolicy | undefined;
+    agent?: ToolPolicy | undefined;
+}): {
+    policy: ToolPolicy;
+    source: ConnectorPolicySource;
+};
 /**
  * 执行时的策略判定（spec 3.6 R5：在动作执行那一刻判定）。每次调用都实时读取：
  * - 沙箱工具（bash / write / edit / deliver）的组织设置 `sandboxToolPolicy`（为 ask 时组织默认至少 ask）；
@@ -36,7 +58,7 @@ export declare function isFixedAsk(tool: ResolvedTool, visibility?: "private" |
  *   parent's current version still tightens it (sub-agents spec §5.3, §9); its "this conversation"
  *   grants are the root conversation's (agent map spec §7); an org agent sub-agent (§5.5): `ctx.agentId` is the
  *   dispatched agent (its current version, its "always" grants) and the parent agent's current
- *   policies apply on top ({@link parentAgentOverride});
+ *   policies apply on top ({@link parentAgentSetting});
  * - 授权表（`conversation_tool_grants` / `tool_grants`），`spec_hash` 与当前定义不一致视为无效（D8），
  *   `connector_id` 与工具的来源连接器不一致也无效（删除后用同一 slug 重新安装的连接器不继承旧授权）；
  * - 工具声明了 `requiredRole`（R1）时，发起人在组织中的当前角色：不是成员 → 拒绝；角色不足 → 按角色升级的审批