@stalfh233/omc-cli 0.6.6 → 0.6.10

package/dist/lanes/organization.js

@@ -128,22 +128,58 @@ async function readRoleTree(session) {
  * that `org.role.list` actually shows) to the platform role id. A reference that
  * matches nothing is refused with the list of real roles — never written blind.
  */
+/**
+ * r28h F11: `String(undefined)` → `"undefined"` must never leave a readback.
+ * Fail closed when a resolved id is empty / literally the word "undefined".
+ */
+function assertResolvedId(id, tool, label) {
+    if (!id || id === "undefined" || id === "null") {
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "wire-shape",
+            message: `${tool} 未能解析出真实 ${label}（得到 ${JSON.stringify(id)}）；不要把 undefined/null 序列化进回执`,
+        });
+    }
+    return id;
+}
 async function resolveRoleRef(session, args, tool) {
+    // r28h F10: both given → resolve code and refuse when it disagrees with roleId.
+    if (args.roleId !== undefined && args.roleCode !== undefined) {
+        const { roles } = await readRoleTree(session);
+        const match = roles.find((role) => role.code === args.roleCode) ?? roles.find((role) => role.name === args.roleCode);
+        if (!match) {
+            throw new ToolInputError({
+                status: "error",
+                blocker: "tool-input-invalid",
+                tool,
+                message: `角色 ${args.roleCode} 不存在。可用角色：${roles.slice(0, 30).map((role) => `${role.code}（${role.name}）`).join("；")}`,
+            });
+        }
+        if (args.roleId !== match.id && args.roleId !== match.code && args.roleId !== match.name) {
+            throw new ToolInputError({
+                status: "error",
+                blocker: "tool-input-invalid",
+                tool,
+                message: `roleId=${args.roleId} 与 roleCode=${args.roleCode}（→${match.id}）不一致；二者其一，都给且不一致则拒绝`,
+            });
+        }
+        return assertResolvedId(match.id, tool, "roleId");
+    }
     const requested = args.roleId ?? args.roleCode;
     if (!requested)
         throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool, message: "需要 roleId 或 roleCode（org.role.list 的 roles 码表给的是 code）" });
     // An explicit roleCode must resolve — never forward it as an id.
     if (args.roleId !== undefined && args.roleCode === undefined && /^[0-9a-f]{32}$/i.test(requested))
-        return requested;
+        return assertResolvedId(requested, tool, "roleId");
     const { roles } = await readRoleTree(session);
     const match = roles.find((role) => role.code === requested) ?? roles.find((role) => role.name === requested);
     if (match)
-        return match.id;
+        return assertResolvedId(match.id, tool, "roleId");
     // Not a known code/name. `roleId` may still be a valid id the tree does not
     // surface (e.g. a role in another corp); forward it and let the platform
     // judge, rather than breaking callers that hold an id we cannot see.
     if (args.roleId !== undefined)
-        return requested;
+        return assertResolvedId(requested, tool, "roleId");
     throw new ToolInputError({
         status: "error",
         blocker: "tool-input-invalid",
@@ -152,6 +188,97 @@ async function resolveRoleRef(session, args, tool) {
     });
 }
 const roleUserId = (row) => String(row.id ?? row.userId ?? row.recId ?? "");
+/**
+ * Walk `/role/list` and locate a role-group by id, returning the real
+ * code/path/parentId the create face itself often leaves null (r28h F9).
+ */
+function locateRoleGroup(rows, roleGroupId) {
+    const childKeys = ["children", "roles", "childRoles", "childList", "list"];
+    const childrenOf = (row) => {
+        for (const key of childKeys) {
+            const value = row[key];
+            if (Array.isArray(value))
+                return value;
+        }
+        return [];
+    };
+    let found = null;
+    const walk = (nodes, parents) => {
+        for (const node of nodes) {
+            const kids = childrenOf(node);
+            const hasGroupId = node.groupId !== undefined && node.groupId !== null;
+            const isGroup = node.group === true || (!hasGroupId && kids.length > 0);
+            if (!isGroup)
+                continue;
+            const id = String(node.id ?? "");
+            const name = String(node.name ?? "");
+            const path = [...parents.map((parent) => parent.name), name].filter((part) => part.length > 0).join(" / ");
+            if (id === roleGroupId) {
+                const parent = parents.length > 0 ? parents[parents.length - 1] : null;
+                const rawParent = node.parentId == null || node.parentId === "" ? null : String(node.parentId);
+                found = {
+                    id,
+                    code: node.code == null || node.code === "" ? null : String(node.code),
+                    name: name || null,
+                    parentId: parent?.id ?? rawParent,
+                    parentName: parent?.name ?? null,
+                    path,
+                };
+                return;
+            }
+            if (kids.length > 0)
+                walk(kids, [...parents, { id, name }]);
+            if (found)
+                return;
+        }
+    };
+    walk(rows, []);
+    return found;
+}
+/**
+ * Locate a role by id after create — platform often leaves code:null on the
+ * add_role response and fills SYS… on the subsequent list (r28h F9).
+ */
+function locateRole(rows, roleId) {
+    const childKeys = ["children", "roles", "childRoles", "childList", "list"];
+    const childrenOf = (row) => {
+        for (const key of childKeys) {
+            const value = row[key];
+            if (Array.isArray(value))
+                return value;
+        }
+        return [];
+    };
+    let found = null;
+    const walk = (nodes, group) => {
+        for (const node of nodes) {
+            const kids = childrenOf(node);
+            const hasGroupId = node.groupId !== undefined && node.groupId !== null;
+            const isGroup = node.group === true || (!hasGroupId && kids.length > 0);
+            if (isGroup) {
+                const next = { id: String(node.id ?? ""), code: node.code == null ? null : String(node.code), name: node.name == null ? null : String(node.name) };
+                if (kids.length > 0)
+                    walk(kids, next);
+                if (found)
+                    return;
+                continue;
+            }
+            if (String(node.id ?? "") === roleId) {
+                found = {
+                    id: roleId,
+                    code: node.code == null || node.code === "" ? null : String(node.code),
+                    name: node.name == null ? null : String(node.name),
+                    groupId: group?.id ?? (node.groupId == null ? null : String(node.groupId)),
+                    groupCode: group?.code ?? null,
+                    groupName: group?.name ?? null,
+                };
+                return;
+            }
+        }
+    };
+    walk(rows, null);
+    return found;
+}
 async function memberRows(session, roleId) {
     const data = (await wireCall(session, {
         path: ENDPOINTS.organizationRoleUsers,
@@ -194,18 +321,20 @@ export function registerOrganizationLane(tools) {
         kind: "read",
         lane: LANE,
         scope: SCOPES.roleUsers,
-        description: "列出角色成员（`GET organization/role/users`）。返回 members[{id(recId),name,...}]；**id 是 recId，不是账号**（addUsers/setUserScope 都传它）。",
+        description: "列出角色成员（`GET organization/role/users`）。返回 members[{id(recId),name,...}]；**id 是 recId，不是账号**（addUsers/setUserScope 都传它）。**roleId 与 roleCode 二者其一**（与写面对齐；都给且不一致则拒绝）。",
         inputSchema: {
             environment: environmentArg,
-            roleId: z.string().min(1).describe("角色 id（不是角色 code）"),
+            roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+            roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称；与 roleId 二选一"),
             page: z.number().int().min(0).optional(),
             size: z.number().int().min(1).max(500).optional(),
             capability: capabilityArg,
         },
         handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.users");
             const data = (await wireCall(session, {
                 path: ENDPOINTS.organizationRoleUsers,
-                query: { ...orgQuery(session), roleId: String(args.roleId), page: String(args.page ?? 0), size: String(args.size ?? 500) },
+                query: { ...orgQuery(session), roleId, page: String(args.page ?? 0), size: String(args.size ?? 500) },
             })).data;
             const rows = Array.isArray(data?.content) ? data.content : wireRows(data);
             // The wire row carries `deptId: null` and `departmentId` absent; the
@@ -241,7 +370,7 @@ export function registerOrganizationLane(tools) {
                 unitType: row.unitType ?? null,
             }));
             return {
-                roleId: String(args.roleId),
+                roleId,
                 count: members.length,
                 total: data?.totalElements ?? members.length,
                 members,
@@ -255,333 +384,387 @@ export function registerOrganizationLane(tools) {
         kind: "read",
         lane: LANE,
         scope: SCOPES.userScope,
-        description: "读成员的管理范围（`GET organization/role/get_ouscope`）。`type:\"1\"`=部门节点；update_ouscope 是覆盖语义，改前先读。",
+        description: "读成员的管理范围（`GET organization/role/get_ouscope`）。**不是枚举档位**（本人/本部门/全部这类不存在）：scopes 是一组部门节点 `{id,name,type:\"1\",deptPath}` 的自由列表。`type:\"1\"`=部门节点；update_ouscope 是覆盖语义，改前先读。**roleId 与 roleCode 二者其一**（与写面对齐；都给且不一致则拒绝）。",
         inputSchema: {
             environment: environmentArg,
-            roleId: z.string().min(1),
+            roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+            roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称；与 roleId 二选一"),
             userId: z.string().min(1).describe("成员的用户记录 id（recId）"),
             capability: capabilityArg,
         },
         handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.userScope");
             const data = (await wireCall(session, {
                 path: ENDPOINTS.organizationRoleGetOuScope,
-                query: { ...orgQuery(session), roleId: String(args.roleId), userId: String(args.userId) },
+                query: { ...orgQuery(session), roleId, userId: String(args.userId) },
             })).data;
             const scopes = wireRows(data).map((row) => ({ id: row.id ?? null, name: row.name ?? null, type: row.type ?? null, deptPath: row.deptPath ?? null }));
-            return { roleId: String(args.roleId), userId: String(args.userId), count: scopes.length, scopes };
+            return { roleId, userId: String(args.userId), count: scopes.length, scopes };
         }),
     }));
-    writeTool(tools, "org.roleGroup.create", LANE, SCOPES.groupCreate, "创建角色组（`POST organization/role/add_role_group`）。返回 roleGroupId，角色挂在它下面。**corpId 默认写当前企业**（`session.enterpriseId()`）：平台的 `corpId` 只从 body 取，body 缺省时才按 parentId 反查企业设置，查不到就 NPE（被吞成 errcode 0）；`corpId=\"other\"` 是平台合法的「非组织分组」语义，只有明确要建非组织分组时才传。", {
-        roleGroupName: z.string().min(1).describe("角色组名称（界面显示的分组名）"),
-        parentId: z.string().min(1).describe("上级角色组 id。**必填**：1.1.25 的 add_role_group 会先 getByParentId(parentId)，空值直接 Preconditions 异常（50000 parentIds cannot be empty）；顶层组请传现有组 id（如「默认」组），平台允许嵌套"),
-        code: z.string().optional(),
-        corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组（该组在组织管理里不归属任何企业）"),
-    }, async (session, args) => {
-        const corpId = args.corpId ?? session.enterpriseId();
-        const data = (await wireCall(session, {
-            path: ENDPOINTS.organizationRoleAddGroup, method: "POST",
-            query: orgQuery(session),
-            body: { roleGroupName: args.roleGroupName, corpId, ...(args.parentId ? { parentId: args.parentId } : {}), ...(args.code ? { code: args.code } : {}) },
-        })).data;
-        const roleGroupId = String(data?.roleGroupId ?? data?.id ?? "");
-        if (!roleGroupId)
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回 roleGroupId；不要假设创建成功，先 org.role.list 回读" });
-        const readbackCorpId = data?.corpId ?? null;
-        // The platform takes corpId from the body verbatim (RoleGroupHelper
-        // .createRoleGroupModel, 1.1.25): a silent rewrite means the value we sent
-        // did not land, and participants built from this group would not resolve
-        // in the org tree.
-        const corpIdHonoured = readbackCorpId === null || String(readbackCorpId) === corpId;
-        return {
-            performed: { errcode: 0 },
-            readback: {
-                roleGroupId,
-                roleGroupName: data?.roleGroupName ?? args.roleGroupName,
-                code: data?.code ?? null,
-                corpId: readbackCorpId,
-                ...(corpIdHonoured ? {} : { warning: `平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致；该组可能不归属当前企业，先 org.role.list 核对` }),
-            },
-        };
+    writeTool({
+        tools,
+        name: "org.roleGroup.create",
+        lane: LANE,
+        scope: SCOPES.groupCreate,
+        description: "创建角色组（`POST organization/role/add_role_group`）。返回 roleGroupId，角色挂在它下面。**corpId 默认写当前企业**（`session.enterpriseId()`）：平台的 `corpId` 只从 body 取，body 缺省时才按 parentId 反查企业设置，查不到就 NPE（被吞成 errcode 0）；`corpId=\"other\"` 是平台合法的「非组织分组」语义，只有明确要建非组织分组时才传。**parentId 必填**：空值会 50000；根级组请传 `\"0\"`（真机 1.1.25 实测可建根级，path=组名、不挂在既有组下）；挂到既有组下则传该组 id（`org.role.list` 的 groups[].id）。创建回执会再读一次 role/list，补上真实 `code`/`parentId`/`path`（平台 add 瞬间 code 常为 null）。",
+        inputSchema: {
+            roleGroupName: z.string().min(1).describe("角色组名称（界面显示的分组名）"),
+            parentId: z.string().min(1).describe("上级角色组 id。**必填**：空值直接 50000 parentIds cannot be empty。根级组传 \"0\"；挂到既有组下传该组 id（如「默认」组）。挂到既有组=给该组添子节点（会改既有组的层级语义）"),
+            code: z.string().optional(),
+            corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组（该组在组织管理里不归属任何企业）"),
+        },
+        execute: async (session, args) => {
+            const corpId = args.corpId ?? session.enterpriseId();
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleAddGroup, method: "POST",
+                query: orgQuery(session),
+                body: { roleGroupName: args.roleGroupName, corpId, ...(args.parentId ? { parentId: args.parentId } : {}), ...(args.code ? { code: args.code } : {}) },
+            })).data;
+            const roleGroupId = assertResolvedId(String(data?.roleGroupId ?? data?.id ?? ""), "org.roleGroup.create", "roleGroupId");
+            const readbackCorpId = data?.corpId ?? null;
+            // The platform takes corpId from the body verbatim (RoleGroupHelper
+            // .createRoleGroupModel, 1.1.25): a silent rewrite means the value we sent
+            // did not land, and participants built from this group would not resolve
+            // in the org tree.
+            const corpIdHonoured = readbackCorpId === null || String(readbackCorpId) === corpId;
+            // r28h F9: create response leaves code:null; re-read the tree so the
+            // write face itself carries the real code/path/parentId.
+            const tree = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleList,
+                query: { corpId: session.enterpriseId(), expandAll: "true" },
+            })).data;
+            const located = locateRoleGroup(wireRows(tree), roleGroupId);
+            return {
+                performed: { errcode: 0 },
+                readback: {
+                    roleGroupId,
+                    roleGroupName: located?.name ?? data?.roleGroupName ?? args.roleGroupName,
+                    code: located?.code ?? data?.code ?? null,
+                    parentId: located?.parentId ?? (args.parentId === "0" ? "0" : args.parentId ?? null),
+                    parentName: located?.parentName ?? null,
+                    path: located?.path ?? null,
+                    corpId: readbackCorpId,
+                    ...(corpIdHonoured ? {} : { warning: `平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致；该组可能不归属当前企业，先 org.role.list 核对` }),
+                },
+            };
+        },
     });
-    writeTool(tools, "org.role.create", LANE, SCOPES.roleCreate, "创建角色（界面「分组」；`POST organization/role/add_role`）。返回 roleId；code 创建时 null、随后补 SYS<时间戳>，要稳定编码就传 code。**所属角色组推荐用 `roleGroupCode`（如 SYS_1000000）**：`org.role.list` 的紧凑码表只给 `code｜name`、不显示组 id，而平台对错的 roleGroupId **静默接受**——存进去的值不是真实组 id 时角色会变成看不见的孤儿（r70 实测：在库里、role/users 查得到，role/list 永不返回、role/get 50000）。工具会把 code 归一成真实 id，并在创建后回读可见性。", {
-        roleName: z.string().min(1),
-        roleGroupCode: z.string().min(1).optional().describe("所属角色组的 code（org.role.list 的 groups 码表，如 SYS_1000000）或名称。**推荐**；与 roleGroupId 二选一"),
-        roleGroupId: z.string().min(1).optional().describe("所属角色组 id（32 位 hex，只能从 artifact get <role.list 的 detailArtifactId> --jq groups 取到）。误传组 code 时工具会归一成真实 id"),
-        roleGroupName: z.string().optional(),
-        roleType: z.enum(["SYS", "CUSTOMIZE", "OTHER"]).optional().describe("默认 SYS（平台会把角色统一落成 SYS，见 RoleHelper.createRoleModel）"),
-        code: z.string().optional(),
-        remarks: z.string().optional(),
-        corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组角色"),
-    }, async (session, args) => {
-        if (!args.roleGroupCode && !args.roleGroupId) {
-            throw new ToolInputError({ message: "必须给 roleGroupCode（推荐）或 roleGroupId；先 org.role.list 取 groups 码表" });
-        }
-        const { groups } = await readRoleTree(session);
-        if (groups.length === 0) {
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "org.role.list 未解析出任何角色组；先确认组织树可读，不要盲建角色" });
-        }
-        const requested = args.roleGroupId ?? args.roleGroupCode;
-        const match = groups.find((group) => group.id === requested) ??
-            groups.find((group) => group.code === requested) ??
-            groups.find((group) => group.name === requested);
-        // A code/name that resolves to nothing is a definite typo → refuse.
-        // A 32-hex id absent from the tree may be a group created moments ago in
-        // this same session; let it through and rely on the visibility backstop.
-        if (!match && args.roleGroupCode) {
-            throw new ToolInputError({
-                message: `角色组 ${requested} 不存在。可用组：${groups.map((group) => `${group.code}（id=${group.id}，${group.name}）`).join("；")}`,
-            });
-        }
-        const roleGroupId = match?.id ?? String(requested);
-        const corpId = args.corpId ?? session.enterpriseId();
-        const data = (await wireCall(session, {
-            path: ENDPOINTS.organizationRoleAdd, method: "POST",
-            query: orgQuery(session),
-            body: {
-                roleName: args.roleName,
-                roleGroupId,
-                ...(args.roleGroupName ? { roleGroupName: args.roleGroupName } : {}),
-                roleType: args.roleType ?? "SYS",
-                corpId,
-                ...(args.code ? { code: args.code } : {}),
-                ...(args.remarks ? { remarks: args.remarks } : {}),
-            },
-        })).data;
-        const roleId = String(data?.roleId ?? data?.id ?? "");
-        if (!roleId)
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回 roleId；先 org.role.list 回读确认" });
-        // Backstop against the silent-orphan trap: re-read the tree and report the
-        // truth instead of reporting success for a role nobody can see.
-        const visible = (await readRoleTree(session)).roles.some((role) => role.id === roleId);
-        const readbackCorpId = data?.corpId ?? null;
-        const warnings = [];
-        if (!visible) {
-            warnings.push(`角色 ${roleId} 创建后不在 org.role.list 任何组下（孤儿角色）：groupId 很可能没落到真实组 id。请 org.role.delete 后按 roleGroupCode 重建`);
-        }
-        if (readbackCorpId !== null && String(readbackCorpId) !== corpId) {
-            warnings.push(`平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致`);
-        }
-        return {
-            performed: { errcode: 0 },
-            readback: {
-                roleId,
-                roleName: data?.roleName ?? args.roleName,
-                code: data?.code ?? null,
-                roleGroupId,
-                roleGroupCode: match?.code ?? null,
-                roleGroupName: match?.name ?? null,
-                visibleInRoleList: visible,
-                corpId: readbackCorpId,
-                ...(warnings.length > 0 ? { warning: warnings.join("；") } : {}),
-            },
-        };
+    writeTool({
+        tools,
+        name: "org.role.create",
+        lane: LANE,
+        scope: SCOPES.roleCreate,
+        description: "创建角色（界面「分组」；`POST organization/role/add_role`）。返回 roleId；code 创建时 null、随后补 SYS<时间戳>，要稳定编码就传 code。**所属角色组推荐用 `roleGroupCode`（如 SYS_1000000）**：`org.role.list` 的紧凑码表只给 `code｜name`、不显示组 id，而平台对错的 roleGroupId **静默接受**——存进去的值不是真实组 id 时角色会变成看不见的孤儿（r70 实测：在库里、role/users 查得到，role/list 永不返回、role/get 50000）。工具会把 code 归一成真实 id，并在创建后回读可见性。",
+        inputSchema: {
+            roleName: z.string().min(1),
+            roleGroupCode: z.string().min(1).optional().describe("所属角色组的 code（org.role.list 的 groups 码表，如 SYS_1000000）或名称。**推荐**；与 roleGroupId 二选一"),
+            roleGroupId: z.string().min(1).optional().describe("所属角色组 id（32 位 hex，只能从 artifact get <role.list 的 detailArtifactId> --jq groups 取到）。误传组 code 时工具会归一成真实 id"),
+            roleGroupName: z.string().optional(),
+            roleType: z.enum(["SYS", "CUSTOMIZE", "OTHER"]).optional().describe("默认 SYS（平台会把角色统一落成 SYS，见 RoleHelper.createRoleModel）"),
+            code: z.string().optional(),
+            remarks: z.string().optional(),
+            corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组角色"),
+        },
+        execute: async (session, args) => {
+            if (!args.roleGroupCode && !args.roleGroupId) {
+                throw new ToolInputError({ message: "必须给 roleGroupCode（推荐）或 roleGroupId；先 org.role.list 取 groups 码表" });
+            }
+            const { groups } = await readRoleTree(session);
+            if (groups.length === 0) {
+                throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "org.role.list 未解析出任何角色组；先确认组织树可读，不要盲建角色" });
+            }
+            const requested = args.roleGroupId ?? args.roleGroupCode;
+            const match = groups.find((group) => group.id === requested) ??
+                groups.find((group) => group.code === requested) ??
+                groups.find((group) => group.name === requested);
+            // A code/name that resolves to nothing is a definite typo → refuse.
+            // A 32-hex id absent from the tree may be a group created moments ago in
+            // this same session; let it through and rely on the visibility backstop.
+            if (!match && args.roleGroupCode) {
+                throw new ToolInputError({
+                    message: `角色组 ${requested} 不存在。可用组：${groups.map((group) => `${group.code}（id=${group.id}，${group.name}）`).join("；")}`,
+                });
+            }
+            const roleGroupId = match?.id ?? String(requested);
+            const corpId = args.corpId ?? session.enterpriseId();
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleAdd, method: "POST",
+                query: orgQuery(session),
+                body: {
+                    roleName: args.roleName,
+                    roleGroupId,
+                    ...(args.roleGroupName ? { roleGroupName: args.roleGroupName } : {}),
+                    roleType: args.roleType ?? "SYS",
+                    corpId,
+                    ...(args.code ? { code: args.code } : {}),
+                    ...(args.remarks ? { remarks: args.remarks } : {}),
+                },
+            })).data;
+            const roleId = assertResolvedId(String(data?.roleId ?? data?.id ?? ""), "org.role.create", "roleId");
+            // Backstop against the silent-orphan trap: re-read the tree and report the
+            // truth instead of reporting success for a role nobody can see.
+            // r28h F9: also pull the real code (create often leaves it null).
+            const treeData = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleList,
+                query: { corpId: session.enterpriseId(), expandAll: "true" },
+            })).data;
+            const located = locateRole(wireRows(treeData), roleId);
+            const visible = located !== null || (await readRoleTree(session)).roles.some((role) => role.id === roleId);
+            const readbackCorpId = data?.corpId ?? null;
+            const warnings = [];
+            if (!visible) {
+                warnings.push(`角色 ${roleId} 创建后不在 org.role.list 任何组下（孤儿角色）：groupId 很可能没落到真实组 id。请 org.role.delete 后按 roleGroupCode 重建`);
+            }
+            if (readbackCorpId !== null && String(readbackCorpId) !== corpId) {
+                warnings.push(`平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致`);
+            }
+            return {
+                performed: { errcode: 0 },
+                readback: {
+                    roleId,
+                    roleName: located?.name ?? data?.roleName ?? args.roleName,
+                    code: located?.code ?? data?.code ?? null,
+                    roleGroupId: located?.groupId ?? roleGroupId,
+                    roleGroupCode: located?.groupCode ?? match?.code ?? null,
+                    roleGroupName: located?.groupName ?? match?.name ?? null,
+                    visibleInRoleList: visible,
+                    corpId: readbackCorpId,
+                    ...(warnings.length > 0 ? { warning: warnings.join("；") } : {}),
+                },
+            };
+        },
     });
     // ── department ────────────────────────────────────────────────────────────
-    writeTool(tools, "org.department.create", LANE, SCOPES.deptCreate, "新建部门（`POST organization/department/add`）。**1.1.25 平台强制 parentId**（省略会 200007「部门parentId不能为空！」）——省略时工具自动取部门树的第一个根部门作父级；deptType 传名字或 0..3（平台按 int 枚举反序列化，写 \"dept\" 会 10009）。返回 deptId。", {
-        name: z.string().min(1).describe("部门名称"),
-        parentId: z.string().min(1).optional().describe("上级部门 id；省略则自动挂到部门树的第一个根部门（1.1.25 不接受空 parentId）"),
-        deptType: z.union([z.string(), z.number().int()]).optional().describe("默认 0=部门；1=家校部门 2=云枢部门 3=虚拟家校部门"),
-        code: z.string().optional(),
-        managerId: z.string().optional().describe("部门主管的用户 id"),
-        sortKey: z.number().int().optional(),
-        remarks: z.string().optional(),
-    }, async (session, args) => {
-        // department/add answers 200007 「部门parentId不能为空！」 on an empty
-        // parentId (live 1.1.25, r10 F5). Resolve the tree's first root instead of
-        // forwarding an omission the platform rejects.
-        let parentId = args.parentId;
-        if (!parentId) {
-            const treeData = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentTree })).data;
-            // `/department/tree` answers `{departmentList:[…]}` (the same shape
-            // org.department.list handles); wireRows alone would throw
-            // "expected row array in envelope data".
-            const roots = Array.isArray(treeData?.departmentList) ? treeData.departmentList : wireRows(treeData);
-            const root = roots.find((row) => {
-                const pid = row.parentId;
-                return pid === undefined || pid === null || pid === "";
-            });
-            parentId = root ? String(root.id ?? "") : "";
-            if (!parentId)
-                throw new ToolRefusalError({ status: "refused", blocker: "org-department-root-absent", message: "部门树没有任何根部门，无法推断 parentId；平台 1.1.25 不接受空 parentId，请先建根部门或显式传 parentId" });
-        }
-        const data = (await wireCall(session, {
-            path: ENDPOINTS.organizationDepartmentAdd, method: "POST", query: orgQuery(session),
-            body: {
-                name: args.name, corpId: session.enterpriseId(), unitType: "1", enabled: true, deptType: deptTypeCode(args.deptType),
-                parentId,
-                ...(args.code ? { code: args.code } : {}),
-                ...(args.managerId ? { managerId: args.managerId } : {}),
-                ...(args.sortKey !== undefined ? { sortKey: args.sortKey } : {}),
-                ...(args.remarks ? { remarks: args.remarks } : {}),
-            },
-        })).data;
-        const deptId = String(data?.id ?? "");
-        if (!deptId)
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回部门 id；先 org.department.list 回读确认" });
-        return { performed: { errcode: 0 }, readback: { deptId, name: data?.name ?? args.name, parentId: data?.parentId ?? args.parentId ?? null, code: data?.code ?? null } };
+    writeTool({
+        tools,
+        name: "org.department.create",
+        lane: LANE,
+        scope: SCOPES.deptCreate,
+        description: "新建部门（`POST organization/department/add`）。**1.1.25 平台强制 parentId**（省略会 200007「部门parentId不能为空！」）——省略时工具自动取部门树的第一个根部门作父级；deptType 传名字或 0..3（平台按 int 枚举反序列化，写 \"dept\" 会 10009）。返回 deptId。",
+        inputSchema: {
+            name: z.string().min(1).describe("部门名称"),
+            parentId: z.string().min(1).optional().describe("上级部门 id；省略则自动挂到部门树的第一个根部门（1.1.25 不接受空 parentId）"),
+            deptType: z.union([z.string(), z.number().int()]).optional().describe("默认 0=部门；1=家校部门 2=云枢部门 3=虚拟家校部门"),
+            code: z.string().optional(),
+            managerId: z.string().optional().describe("部门主管的用户 id"),
+            sortKey: z.number().int().optional(),
+            remarks: z.string().optional(),
+        },
+        execute: async (session, args) => {
+            // department/add answers 200007 「部门parentId不能为空！」 on an empty
+            // parentId (live 1.1.25, r10 F5). Resolve the tree's first root instead of
+            // forwarding an omission the platform rejects.
+            let parentId = args.parentId;
+            if (!parentId) {
+                const treeData = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentTree })).data;
+                // `/department/tree` answers `{departmentList:[…]}` (the same shape
+                // org.department.list handles); wireRows alone would throw
+                // "expected row array in envelope data".
+                const roots = Array.isArray(treeData?.departmentList) ? treeData.departmentList : wireRows(treeData);
+                const root = roots.find((row) => {
+                    const pid = row.parentId;
+                    return pid === undefined || pid === null || pid === "";
+                });
+                parentId = root ? String(root.id ?? "") : "";
+                if (!parentId)
+                    throw new ToolRefusalError({ status: "refused", blocker: "org-department-root-absent", message: "部门树没有任何根部门，无法推断 parentId；平台 1.1.25 不接受空 parentId，请先建根部门或显式传 parentId" });
+            }
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationDepartmentAdd, method: "POST", query: orgQuery(session),
+                body: {
+                    name: args.name, corpId: session.enterpriseId(), unitType: "1", enabled: true, deptType: deptTypeCode(args.deptType),
+                    parentId,
+                    ...(args.code ? { code: args.code } : {}),
+                    ...(args.managerId ? { managerId: args.managerId } : {}),
+                    ...(args.sortKey !== undefined ? { sortKey: args.sortKey } : {}),
+                    ...(args.remarks ? { remarks: args.remarks } : {}),
+                },
+            })).data;
+            const deptId = String(data?.id ?? "");
+            if (!deptId)
+                throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回部门 id；先 org.department.list 回读确认" });
+            return { performed: { errcode: 0 }, readback: { deptId, name: data?.name ?? args.name, parentId: data?.parentId ?? args.parentId ?? null, code: data?.code ?? null } };
+        },
     });
-    writeTool(tools, "org.department.update", LANE, SCOPES.deptUpdate, "改部门（`POST organization/department/modefied`）。先 get_dept_info 读现状再合并提交，只传要改的字段（名称/上级/主管/排序/备注/启用）。", {
-        deptId: z.string().min(1),
-        name: z.string().optional(),
-        parentId: z.string().optional(),
-        managerId: z.string().optional(),
-        sortKey: z.number().int().optional(),
-        remarks: z.string().optional(),
-        enabled: z.boolean().optional(),
-    }, async (session, args) => {
-        const current = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { ...orgQuery(session), deptId: args.deptId } })).data;
-        if (!current)
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `get_dept_info 未返回部门 ${args.deptId}` });
-        const body = {
-            ...current,
-            ...(args.name !== undefined ? { name: args.name } : {}),
-            ...(args.parentId !== undefined ? { parentId: args.parentId } : {}),
-            ...(args.managerId !== undefined ? { managerId: args.managerId } : {}),
-            ...(args.sortKey !== undefined ? { sortKey: args.sortKey } : {}),
-            ...(args.remarks !== undefined ? { remarks: args.remarks } : {}),
-            ...(args.enabled !== undefined ? { enabled: args.enabled } : {}),
-        };
-        await wireCall(session, { path: ENDPOINTS.organizationDepartmentModify, method: "POST", query: orgQuery(session), body });
-        const after = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { ...orgQuery(session), deptId: args.deptId } })).data;
-        return { performed: { errcode: 0 }, readback: { deptId: args.deptId, name: after?.name ?? null, parentId: after?.parentId ?? null, managerId: after?.managerId ?? null, enabled: after?.enabled ?? null } };
+    writeTool({
+        tools,
+        name: "org.department.update",
+        lane: LANE,
+        scope: SCOPES.deptUpdate,
+        description: "改部门（`POST organization/department/modefied`）。先 get_dept_info 读现状再合并提交，只传要改的字段（名称/上级/主管/排序/备注/启用）。",
+        inputSchema: {
+            deptId: z.string().min(1),
+            name: z.string().optional(),
+            parentId: z.string().optional(),
+            managerId: z.string().optional(),
+            sortKey: z.number().int().optional(),
+            remarks: z.string().optional(),
+            enabled: z.boolean().optional(),
+        },
+        execute: async (session, args) => {
+            const current = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { ...orgQuery(session), deptId: args.deptId } })).data;
+            if (!current)
+                throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `get_dept_info 未返回部门 ${args.deptId}` });
+            const body = {
+                ...current,
+                ...(args.name !== undefined ? { name: args.name } : {}),
+                ...(args.parentId !== undefined ? { parentId: args.parentId } : {}),
+                ...(args.managerId !== undefined ? { managerId: args.managerId } : {}),
+                ...(args.sortKey !== undefined ? { sortKey: args.sortKey } : {}),
+                ...(args.remarks !== undefined ? { remarks: args.remarks } : {}),
+                ...(args.enabled !== undefined ? { enabled: args.enabled } : {}),
+            };
+            await wireCall(session, { path: ENDPOINTS.organizationDepartmentModify, method: "POST", query: orgQuery(session), body });
+            const after = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { ...orgQuery(session), deptId: args.deptId } })).data;
+            return { performed: { errcode: 0 }, readback: { deptId: args.deptId, name: after?.name ?? null, parentId: after?.parentId ?? null, managerId: after?.managerId ?? null, enabled: after?.enabled ?? null } };
+        },
     });
-    writeTool(tools, "org.department.delete", LANE, SCOPES.deptDelete, "删除部门（`GET organization/department/strike_out?id=`）。平台会拒绝：有子部门 → 200009「部门下面存在子部门，不能删除！」；有用户 → 200002「部门下面存在用户，不能删除！」。工具先计数并在回读里给出，仍由平台裁决。", {
-        deptId: z.string().min(1),
-        force: z.boolean().optional().describe("true = 先逐个删除子部门（仅当子部门无用户）再删本部门；有用户仍由平台裁决"),
-        transferUsersTo: z
-            .string()
-            .min(1)
-            .optional()
-            .describe("有员工时的转出目标部门 id：给了它就先把本部门（及 force 时的子树各部门）的员工逐人 transferDepartment 到该部门再删；不给则带人即拒绝。目标必须是现存部门，且不能是被删子树的一部分"),
-    }, async (session, args) => {
-        const users = wireRows((await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: args.deptId } })).data);
-        // Pre-check children: the platform's 200009 ("部门下面存在子部门") is
-        // accurate but sends the caller hunting for ids. Name them and hand over
-        // the child-delete command (found during r15 org cleanup).
-        const walked = await collectOrgDepartments(session);
-        // transferUsersTo (opt-in member evacuation): the target must be a real
-        // department and must NOT be inside the subtree being deleted — moving
-        // people into a dept that is about to be deleted would lose them.
-        const transferTarget = typeof args.transferUsersTo === "string" ? args.transferUsersTo.trim() : "";
-        let transferUsers;
-        if (transferTarget) {
-            if (!walked.rows.some((row) => row.id === transferTarget))
-                throw new ToolRefusalError({
-                    status: "refused", blocker: "department-transfer-target-absent", deptId: String(args.deptId), transferUsersTo: transferTarget,
-                    message: `transferUsersTo 的目标部门 ${transferTarget} 不存在（org.department.list 里没有）。先确认部门 id，或先创建目标部门。`,
-                });
-            const subtreeIds = new Set([String(args.deptId)]);
-            let grew = true;
-            while (grew) {
-                grew = false;
-                for (const row of walked.rows)
-                    if (subtreeIds.has(row.parentId) && !subtreeIds.has(row.id)) {
-                        subtreeIds.add(row.id);
-                        grew = true;
+    writeTool({
+        tools,
+        name: "org.department.delete",
+        lane: LANE,
+        scope: SCOPES.deptDelete,
+        description: "删除部门（`GET organization/department/strike_out?id=`）。平台会拒绝：有子部门 → 200009「部门下面存在子部门，不能删除！」；有用户 → 200002「部门下面存在用户，不能删除！」。工具先计数并在回读里给出，仍由平台裁决。",
+        inputSchema: {
+            deptId: z.string().min(1),
+            force: z.boolean().optional().describe("true = 先逐个删除子部门（仅当子部门无用户）再删本部门；有用户仍由平台裁决"),
+            transferUsersTo: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("有员工时的转出目标部门 id：给了它就先把本部门（及 force 时的子树各部门）的员工逐人 transferDepartment 到该部门再删；不给则带人即拒绝。目标必须是现存部门，且不能是被删子树的一部分"),
+        },
+        execute: async (session, args) => {
+            const users = wireRows((await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: args.deptId } })).data);
+            // Pre-check children: the platform's 200009 ("部门下面存在子部门") is
+            // accurate but sends the caller hunting for ids. Name them and hand over
+            // the child-delete command (found during r15 org cleanup).
+            const walked = await collectOrgDepartments(session);
+            // transferUsersTo (opt-in member evacuation): the target must be a real
+            // department and must NOT be inside the subtree being deleted — moving
+            // people into a dept that is about to be deleted would lose them.
+            const transferTarget = typeof args.transferUsersTo === "string" ? args.transferUsersTo.trim() : "";
+            let transferUsers;
+            if (transferTarget) {
+                if (!walked.rows.some((row) => row.id === transferTarget))
+                    throw new ToolRefusalError({
+                        status: "refused", blocker: "department-transfer-target-absent", deptId: String(args.deptId), transferUsersTo: transferTarget,
+                        message: `transferUsersTo 的目标部门 ${transferTarget} 不存在（org.department.list 里没有）。先确认部门 id，或先创建目标部门。`,
+                    });
+                const subtreeIds = new Set([String(args.deptId)]);
+                let grew = true;
+                while (grew) {
+                    grew = false;
+                    for (const row of walked.rows)
+                        if (subtreeIds.has(row.parentId) && !subtreeIds.has(row.id)) {
+                            subtreeIds.add(row.id);
+                            grew = true;
+                        }
+                }
+                if (subtreeIds.has(transferTarget))
+                    throw new ToolRefusalError({
+                        status: "refused", blocker: "department-transfer-into-subtree", deptId: String(args.deptId), transferUsersTo: transferTarget,
+                        message: `transferUsersTo=${transferTarget} 在被删除的子树里——把人转进一个即将被删的部门会丢成员。换一个子树外的部门。`,
+                    });
+                transferUsers = async (fromDeptId, deptUsers) => {
+                    let moved = 0;
+                    for (const member of deptUsers) {
+                        const userId = String(member.id ?? member.userId ?? "");
+                        if (!userId)
+                            continue;
+                        await wireCall(session, {
+                            path: ENDPOINTS.organizationUserDeptTransfer, method: "POST", query: orgQuery(session),
+                            body: { userIds: [userId], sourceDept: fromDeptId, targetDept: transferTarget },
+                        });
+                        moved += 1;
                     }
+                    return moved;
+                };
             }
-            if (subtreeIds.has(transferTarget))
-                throw new ToolRefusalError({
-                    status: "refused", blocker: "department-transfer-into-subtree", deptId: String(args.deptId), transferUsersTo: transferTarget,
-                    message: `transferUsersTo=${transferTarget} 在被删除的子树里——把人转进一个即将被删的部门会丢成员。换一个子树外的部门。`,
-                });
-            transferUsers = async (fromDeptId, deptUsers) => {
-                let moved = 0;
-                for (const member of deptUsers) {
-                    const userId = String(member.id ?? member.userId ?? "");
-                    if (!userId)
-                        continue;
-                    await wireCall(session, {
-                        path: ENDPOINTS.organizationUserDeptTransfer, method: "POST", query: orgQuery(session),
-                        body: { userIds: [userId], sourceDept: fromDeptId, targetDept: transferTarget },
+            const children = walked.rows
+                .filter((row) => row.parentId === String(args.deptId))
+                .map((row) => ({ id: row.id, name: row.name }))
+                .filter((row) => row.id.length > 0);
+            let deletedChildren = 0;
+            if (children.length > 0) {
+                if (args.force !== true)
+                    throw new ToolRefusalError({
+                        status: "refused", blocker: "department-has-children", deptId: String(args.deptId), children,
+                        nextCommand: `omc call org.department.delete --args '${JSON.stringify({ deptId: children[0].id })}'`,
+                        message: `部门 ${args.deptId} 下还有 ${children.length} 个子部门，平台拒绝删除（200009）。先删子部门，或传 force:true 让工具按顺序删除：${children.map((child) => `${child.name}(${child.id})`).join("、")}。`,
                     });
-                    moved += 1;
+                // force = deepest-first over the WHOLE subtree (a direct child with its
+                // own children would fail 200009 otherwise).
+                const byParent = new Map();
+                for (const row of walked.rows) {
+                    if (row.id === String(args.deptId))
+                        continue;
+                    const list = byParent.get(row.parentId) ?? [];
+                    list.push({ id: row.id, name: row.name });
+                    byParent.set(row.parentId, list);
                 }
-                return moved;
-            };
-        }
-        const children = walked.rows
-            .filter((row) => row.parentId === String(args.deptId))
-            .map((row) => ({ id: row.id, name: row.name }))
-            .filter((row) => row.id.length > 0);
-        let deletedChildren = 0;
-        if (children.length > 0) {
-            if (args.force !== true)
+                const ordered = [];
+                const walk = (parentId) => {
+                    for (const child of byParent.get(parentId) ?? []) {
+                        walk(child.id);
+                        ordered.push(child);
+                    }
+                };
+                walk(String(args.deptId));
+                deletedChildren = ordered.length;
+                for (const child of ordered) {
+                    try {
+                        if (transferUsers) {
+                            const childUsers = wireRows((await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: child.id } })).data);
+                            if (childUsers.length > 0)
+                                await transferUsers(child.id, childUsers);
+                        }
+                        await wireCall(session, { path: ENDPOINTS.organizationDepartmentDelete, query: { ...orgQuery(session), id: child.id } });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        const usersPending = /200002|用户/.test(message);
+                        throw new ToolRefusalError({
+                            status: "refused", blocker: usersPending ? "department-has-users" : "department-delete-failed",
+                            deptId: String(args.deptId), blockedChild: child,
+                            nextCommand: `omc call org.department.users --args '${JSON.stringify({ deptId: child.id })}'`,
+                            message: `force 清理到子部门 ${child.name}(${child.id}) 时失败：${message}。${usersPending ? "该部门下还有员工——先转出再删（或传 transferUsersTo 让工具搬）。" : "平台拒绝删除该子部门。"}`,
+                        });
+                    }
+                }
+            }
+            let transferredUsers = 0;
+            if (users.length > 0 && transferUsers) {
+                transferredUsers = await transferUsers(String(args.deptId), users);
+            }
+            if (users.length > 0 && !transferUsers) {
+                // Name every member and hand over a runnable transfer for the first one:
+                // "先看人再转出" left the caller to assemble the transfer args (item 9).
+                const members = users.map((row) => ({ id: row.id ?? row.userId ?? null, name: row.name ?? null, username: row.username ?? null }));
+                const parentId = walked.rows.find((row) => row.id === String(args.deptId))?.parentId ?? "";
+                const first = members.find((member) => typeof member.id === "string" && member.id.length > 0);
                 throw new ToolRefusalError({
-                    status: "refused", blocker: "department-has-children", deptId: String(args.deptId), children,
-                    nextCommand: `omc call org.department.delete --args '${JSON.stringify({ deptId: children[0].id })}'`,
-                    message: `部门 ${args.deptId} 下还有 ${children.length} 个子部门，平台拒绝删除（200009）。先删子部门，或传 force:true 让工具按顺序删除：${children.map((child) => `${child.name}(${child.id})`).join("、")}。`,
+                    status: "refused", blocker: "department-has-users", deptId: String(args.deptId), users: users.length, members,
+                    nextCommand: first && parentId
+                        ? `omc call org.user.transferDepartment --args '${JSON.stringify({ userId: first.id, departmentId: parentId })}'`
+                        : `omc call org.department.users --args '${JSON.stringify({ deptId: String(args.deptId) })}'`,
+                    message: `部门 ${args.deptId} 下还有 ${users.length} 名员工，平台拒绝删除（200002）。成员：${members.map((member) => `${member.name ?? "?"}(${member.id ?? "?"})`).join("、")}。` +
+                        `平台不允许删带人的部门，也不提供"随部门级联转出"。两个选择：` +
+                        `① 逐个 org.user.transferDepartment 转到 ${parentId ? `父部门 ${parentId}` : "目标部门"} 后再删；` +
+                        `② 本命令直接带 transferUsersTo:"<目标部门id>"，工具会先把人逐人转出（含 force 时的子树各部门）再删。` +
+                        `（默认不搬人——搬人是组织语义决策，不替你选目标部门。）`,
                 });
-            // force = deepest-first over the WHOLE subtree (a direct child with its
-            // own children would fail 200009 otherwise).
-            const byParent = new Map();
-            for (const row of walked.rows) {
-                if (row.id === String(args.deptId))
-                    continue;
-                const list = byParent.get(row.parentId) ?? [];
-                list.push({ id: row.id, name: row.name });
-                byParent.set(row.parentId, list);
             }
-            const ordered = [];
-            const walk = (parentId) => {
-                for (const child of byParent.get(parentId) ?? []) {
-                    walk(child.id);
-                    ordered.push(child);
-                }
+            await wireCall(session, { path: ENDPOINTS.organizationDepartmentDelete, query: { ...orgQuery(session), id: args.deptId } });
+            return {
+                performed: { errcode: 0 },
+                readback: {
+                    deptId: args.deptId, deleted: true, usersBeforeDelete: users.length, deletedChildren,
+                    ...(transferredUsers > 0 ? { transferredUsers, transferredTo: transferTarget } : {}),
+                },
             };
-            walk(String(args.deptId));
-            deletedChildren = ordered.length;
-            for (const child of ordered) {
-                try {
-                    if (transferUsers) {
-                        const childUsers = wireRows((await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: child.id } })).data);
-                        if (childUsers.length > 0)
-                            await transferUsers(child.id, childUsers);
-                    }
-                    await wireCall(session, { path: ENDPOINTS.organizationDepartmentDelete, query: { ...orgQuery(session), id: child.id } });
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    const usersPending = /200002|用户/.test(message);
-                    throw new ToolRefusalError({
-                        status: "refused", blocker: usersPending ? "department-has-users" : "department-delete-failed",
-                        deptId: String(args.deptId), blockedChild: child,
-                        nextCommand: `omc call org.department.users --args '${JSON.stringify({ deptId: child.id })}'`,
-                        message: `force 清理到子部门 ${child.name}(${child.id}) 时失败：${message}。${usersPending ? "该部门下还有员工——先转出再删（或传 transferUsersTo 让工具搬）。" : "平台拒绝删除该子部门。"}`,
-                    });
-                }
-            }
-        }
-        let transferredUsers = 0;
-        if (users.length > 0 && transferUsers) {
-            transferredUsers = await transferUsers(String(args.deptId), users);
-        }
-        if (users.length > 0 && !transferUsers) {
-            // Name every member and hand over a runnable transfer for the first one:
-            // "先看人再转出" left the caller to assemble the transfer args (item 9).
-            const members = users.map((row) => ({ id: row.id ?? row.userId ?? null, name: row.name ?? null, username: row.username ?? null }));
-            const parentId = walked.rows.find((row) => row.id === String(args.deptId))?.parentId ?? "";
-            const first = members.find((member) => typeof member.id === "string" && member.id.length > 0);
-            throw new ToolRefusalError({
-                status: "refused", blocker: "department-has-users", deptId: String(args.deptId), users: users.length, members,
-                nextCommand: first && parentId
-                    ? `omc call org.user.transferDepartment --args '${JSON.stringify({ userId: first.id, departmentId: parentId })}'`
-                    : `omc call org.department.users --args '${JSON.stringify({ deptId: String(args.deptId) })}'`,
-                message: `部门 ${args.deptId} 下还有 ${users.length} 名员工，平台拒绝删除（200002）。成员：${members.map((member) => `${member.name ?? "?"}(${member.id ?? "?"})`).join("、")}。` +
-                    `平台不允许删带人的部门，也不提供"随部门级联转出"。两个选择：` +
-                    `① 逐个 org.user.transferDepartment 转到 ${parentId ? `父部门 ${parentId}` : "目标部门"} 后再删；` +
-                    `② 本命令直接带 transferUsersTo:"<目标部门id>"，工具会先把人逐人转出（含 force 时的子树各部门）再删。` +
-                    `（默认不搬人——搬人是组织语义决策，不替你选目标部门。）`,
-            });
-        }
-        await wireCall(session, { path: ENDPOINTS.organizationDepartmentDelete, query: { ...orgQuery(session), id: args.deptId } });
-        return {
-            performed: { errcode: 0 },
-            readback: {
-                deptId: args.deptId, deleted: true, usersBeforeDelete: users.length, deletedChildren,
-                ...(transferredUsers > 0 ? { transferredUsers, transferredTo: transferTarget } : {}),
-            },
-        };
+        },
     });
     tools.push(defineTool({
         name: "org.department.users",
@@ -595,114 +778,138 @@ export function registerOrganizationLane(tools) {
         }),
     }));
     // ── employee ──────────────────────────────────────────────────────────────
-    writeTool(tools, "org.user.create", LANE, SCOPES.userCreate, "新建员工账号（`POST organization/user/add`）。必填 name/username/departmentId；工具自动补 `userLabelIds:[]`、`userManagerConfigList:[]`、`roleIds:[]` —— 平台 dealUserLabel 对 null 直接 NPE（50000，真机 1.1.25）。返回 userId(recId)；初始密码由平台默认策略生成。", {
-        name: z.string().min(1),
-        username: z.string().min(1).describe("登录账号"),
-        departmentId: z.string().min(1).describe("所属部门 id（必须先存在，否则 201011「用户的部门不存在！」）"),
-        mobile: z.string().optional(),
-        email: z.string().optional(),
-        employeeNo: z.string().optional(),
-        gender: z.enum(["MALE", "FEMALE", "OTHER"]).optional(),
-        roleIds: z.array(z.string()).optional().describe("同时授予的角色 id"),
-        partTimeDeptIds: z.array(z.string()).optional().describe("兼职部门 id（主部门仍是 departmentId）"),
-        deptIds: z.array(z.string()).optional().describe("`partTimeDeptIds` 的别名"),
-        userLabelIds: z.array(z.string()).optional(),
-        active: z.boolean().optional(),
-        status: z.enum(["ENABLE", "DISABLE", "LOCK"]).optional(),
-    }, async (session, args) => {
-        const data = (await wireCall(session, {
-            path: ENDPOINTS.organizationUserAdd, method: "POST", query: orgQuery(session),
-            body: {
-                name: args.name, username: args.username, departmentId: args.departmentId, currentDeptId: args.departmentId,
-                corpId: session.enterpriseId(), unitType: "3", enabled: true, active: args.active ?? true,
-                status: args.status ?? "ENABLE",
-                userLabelIds: args.userLabelIds ?? [], userManagerConfigList: [], roleIds: args.roleIds ?? [], deptIds: args.partTimeDeptIds ?? args.deptIds ?? [],
-                ...(args.mobile ? { mobile: args.mobile } : {}),
-                ...(args.email ? { email: args.email } : {}),
-                ...(args.employeeNo ? { employeeNo: args.employeeNo } : {}),
-                ...(args.gender ? { gender: args.gender } : {}),
-            },
-        })).data;
-        const userId = String(data?.id ?? "");
-        if (!userId)
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回用户 id；先 org.user.search 回读确认" });
-        return {
-            performed: { errcode: 0 },
-            readback: {
-                userId,
-                name: data?.name ?? args.name,
-                username: data?.username ?? args.username,
-                departmentId: data?.departmentId ?? args.departmentId,
-                // 1.1.25 does not echo `active` on add and does not honour an update to
-                // it (r15 P7): the flag looks derived from account activation/binding.
-                // Say so, so nobody re-creates the user to "fix" it.
-                ...(args.active !== undefined
-                    ? { activeWarning: `平台不回读 active（1.1.25 上它疑似由账号激活/绑定派生，不是可直接写的开关）。启停账号用 status=ENABLE/DISABLE/LOCK；不要为改 active 新建用户。` }
-                    : {}),
-            },
-        };
+    writeTool({
+        tools,
+        name: "org.user.create",
+        lane: LANE,
+        scope: SCOPES.userCreate,
+        description: "新建员工账号（`POST organization/user/add`）。必填 name/username/departmentId；工具自动补 `userLabelIds:[]`、`userManagerConfigList:[]`、`roleIds:[]` —— 平台 dealUserLabel 对 null 直接 NPE（50000，真机 1.1.25）。返回 userId(recId)；初始密码由平台默认策略生成。",
+        inputSchema: {
+            name: z.string().min(1),
+            username: z.string().min(1).describe("登录账号"),
+            departmentId: z.string().min(1).describe("所属部门 id（必须先存在，否则 201011「用户的部门不存在！」）"),
+            mobile: z.string().optional(),
+            email: z.string().optional(),
+            employeeNo: z.string().optional(),
+            gender: z.enum(["MALE", "FEMALE", "OTHER"]).optional(),
+            roleIds: z.array(z.string()).optional().describe("同时授予的角色 id"),
+            partTimeDeptIds: z.array(z.string()).optional().describe("兼职部门 id（主部门仍是 departmentId）"),
+            deptIds: z.array(z.string()).optional().describe("`partTimeDeptIds` 的别名"),
+            userLabelIds: z.array(z.string()).optional(),
+            active: z.boolean().optional(),
+            status: z.enum(["ENABLE", "DISABLE", "LOCK"]).optional(),
+        },
+        execute: async (session, args) => {
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationUserAdd, method: "POST", query: orgQuery(session),
+                body: {
+                    name: args.name, username: args.username, departmentId: args.departmentId, currentDeptId: args.departmentId,
+                    corpId: session.enterpriseId(), unitType: "3", enabled: true, active: args.active ?? true,
+                    status: args.status ?? "ENABLE",
+                    userLabelIds: args.userLabelIds ?? [], userManagerConfigList: [], roleIds: args.roleIds ?? [], deptIds: args.partTimeDeptIds ?? args.deptIds ?? [],
+                    ...(args.mobile ? { mobile: args.mobile } : {}),
+                    ...(args.email ? { email: args.email } : {}),
+                    ...(args.employeeNo ? { employeeNo: args.employeeNo } : {}),
+                    ...(args.gender ? { gender: args.gender } : {}),
+                },
+            })).data;
+            const userId = String(data?.id ?? "");
+            if (!userId)
+                throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回用户 id；先 org.user.search 回读确认" });
+            return {
+                performed: { errcode: 0 },
+                readback: {
+                    userId,
+                    name: data?.name ?? args.name,
+                    username: data?.username ?? args.username,
+                    departmentId: data?.departmentId ?? args.departmentId,
+                    // 1.1.25 does not echo `active` on add and does not honour an update to
+                    // it (r15 P7): the flag looks derived from account activation/binding.
+                    // Say so, so nobody re-creates the user to "fix" it.
+                    ...(args.active !== undefined
+                        ? { activeWarning: `平台不回读 active（1.1.25 上它疑似由账号激活/绑定派生，不是可直接写的开关）。启停账号用 status=ENABLE/DISABLE/LOCK；不要为改 active 新建用户。` }
+                        : {}),
+                },
+            };
+        },
     });
-    writeTool(tools, "org.user.update", LANE, SCOPES.userUpdate, "改员工（`POST organization/user/modify`）。先 user/info 读现状再合并；工具强制补 `deptIds:[]` 等四个数组——平台 modified 对 null 的 deptIds 直接 NPE（50000，真机 1.1.25）。可改姓名/部门/手机/邮箱/角色/启停。", {
-        userId: z.string().min(1),
-        name: z.string().optional(),
-        departmentId: z.string().optional(),
-        mobile: z.string().optional(),
-        email: z.string().optional(),
-        employeeNo: z.string().optional(),
-        gender: z.enum(["MALE", "FEMALE", "OTHER"]).optional(),
-        roleIds: z.array(z.string()).optional(),
-        partTimeDeptIds: z.array(z.string()).optional().describe("兼职部门 id；**覆盖语义**（传 [] 清空兼职，主部门不变）"),
-        active: z.boolean().optional(),
-        status: z.enum(["ENABLE", "DISABLE", "LOCK"]).optional(),
-    }, async (session, args) => {
-        const current = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: args.userId } })).data;
-        if (!current)
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `user/info 未返回用户 ${args.userId}` });
-        const body = {
-            ...current,
-            id: args.userId,
-            ...(args.name !== undefined ? { name: args.name } : {}),
-            ...(args.departmentId !== undefined ? { departmentId: args.departmentId, currentDeptId: args.departmentId } : {}),
-            ...(args.mobile !== undefined ? { mobile: args.mobile } : {}),
-            ...(args.email !== undefined ? { email: args.email } : {}),
-            ...(args.employeeNo !== undefined ? { employeeNo: args.employeeNo } : {}),
-            ...(args.gender !== undefined ? { gender: args.gender } : {}),
-            ...(args.active !== undefined ? { active: args.active } : {}),
-            ...(args.status !== undefined ? { status: args.status } : {}),
-            deptIds: args.partTimeDeptIds ?? (Array.isArray(current.deptIds) ? current.deptIds : []),
-            userLabelIds: Array.isArray(current.userLabelIds) ? current.userLabelIds : [],
-            userManagerConfigList: Array.isArray(current.userManagerConfigList) ? current.userManagerConfigList : [],
-            roleIds: args.roleIds ?? (Array.isArray(current.roleIds) ? current.roleIds : []),
-        };
-        await wireCall(session, { path: ENDPOINTS.organizationUserModify, method: "POST", query: orgQuery(session), body });
-        const after = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: args.userId } })).data;
-        const departments = wireRows((await wireCall(session, {
-            path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) },
-        })).data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
-        return {
-            performed: { errcode: 0 },
-            readback: {
-                userId: args.userId,
-                name: after?.name ?? null,
-                departmentId: after?.departmentId ?? null,
-                mobile: after?.mobile ?? null,
-                email: after?.email ?? null,
-                active: after?.active ?? null,
-                userStatus: after?.status ?? null,
-                departments,
-                // r15 P7: `active` did not persist on 1.1.25 (passed true, read false).
-                // It looks derived from account activation/binding rather than a
-                // writable switch — say so instead of letting the caller re-create the
-                // user to "fix" it.
-                ...(args.active !== undefined && after?.active !== args.active
-                    ? { activeWarning: `传了 active=${String(args.active)}，平台读回 ${String(after?.active)}：active 在 1.1.25 上不是可直接写的开关（疑似由账号激活/绑定派生）。启停账号用 status=ENABLE/DISABLE/LOCK；不要为改 active 新建用户。` }
-                    : {}),
-            },
-        };
+    writeTool({
+        tools,
+        name: "org.user.update",
+        lane: LANE,
+        scope: SCOPES.userUpdate,
+        description: "改员工（`POST organization/user/modify`）。先 user/info 读现状再合并；工具强制补 `deptIds:[]` 等四个数组——平台 modified 对 null 的 deptIds 直接 NPE（50000，真机 1.1.25）。可改姓名/部门/手机/邮箱/角色/启停。",
+        inputSchema: {
+            userId: z.string().min(1),
+            name: z.string().optional(),
+            departmentId: z.string().optional(),
+            mobile: z.string().optional(),
+            email: z.string().optional(),
+            employeeNo: z.string().optional(),
+            gender: z.enum(["MALE", "FEMALE", "OTHER"]).optional(),
+            roleIds: z.array(z.string()).optional(),
+            partTimeDeptIds: z.array(z.string()).optional().describe("兼职部门 id；**覆盖语义**（传 [] 清空兼职，主部门不变）"),
+            active: z.boolean().optional(),
+            status: z.enum(["ENABLE", "DISABLE", "LOCK"]).optional(),
+        },
+        execute: async (session, args) => {
+            const current = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: args.userId } })).data;
+            if (!current)
+                throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `user/info 未返回用户 ${args.userId}` });
+            const body = {
+                ...current,
+                id: args.userId,
+                ...(args.name !== undefined ? { name: args.name } : {}),
+                ...(args.departmentId !== undefined ? { departmentId: args.departmentId, currentDeptId: args.departmentId } : {}),
+                ...(args.mobile !== undefined ? { mobile: args.mobile } : {}),
+                ...(args.email !== undefined ? { email: args.email } : {}),
+                ...(args.employeeNo !== undefined ? { employeeNo: args.employeeNo } : {}),
+                ...(args.gender !== undefined ? { gender: args.gender } : {}),
+                ...(args.active !== undefined ? { active: args.active } : {}),
+                ...(args.status !== undefined ? { status: args.status } : {}),
+                deptIds: args.partTimeDeptIds ?? (Array.isArray(current.deptIds) ? current.deptIds : []),
+                userLabelIds: Array.isArray(current.userLabelIds) ? current.userLabelIds : [],
+                userManagerConfigList: Array.isArray(current.userManagerConfigList) ? current.userManagerConfigList : [],
+                roleIds: args.roleIds ?? (Array.isArray(current.roleIds) ? current.roleIds : []),
+            };
+            await wireCall(session, { path: ENDPOINTS.organizationUserModify, method: "POST", query: orgQuery(session), body });
+            const after = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: args.userId } })).data;
+            const departments = wireRows((await wireCall(session, {
+                path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) },
+            })).data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
+            return {
+                performed: { errcode: 0 },
+                readback: {
+                    userId: args.userId,
+                    name: after?.name ?? null,
+                    departmentId: after?.departmentId ?? null,
+                    mobile: after?.mobile ?? null,
+                    email: after?.email ?? null,
+                    active: after?.active ?? null,
+                    userStatus: after?.status ?? null,
+                    departments,
+                    // r15 P7: `active` did not persist on 1.1.25 (passed true, read false).
+                    // It looks derived from account activation/binding rather than a
+                    // writable switch — say so instead of letting the caller re-create the
+                    // user to "fix" it.
+                    ...(args.active !== undefined && after?.active !== args.active
+                        ? { activeWarning: `传了 active=${String(args.active)}，平台读回 ${String(after?.active)}：active 在 1.1.25 上不是可直接写的开关（疑似由账号激活/绑定派生）。启停账号用 status=ENABLE/DISABLE/LOCK；不要为改 active 新建用户。` }
+                        : {}),
+                },
+            };
+        },
     });
-    writeTool(tools, "org.user.delete", LANE, SCOPES.userDelete, "删除员工（`GET organization/user/strike_out?id=`）。只传用户 id；返回 deleted。", { userId: z.string().min(1) }, async (session, args) => {
-        await wireCall(session, { path: ENDPOINTS.organizationUserDelete, query: { ...orgQuery(session), id: args.userId } });
-        return { performed: { errcode: 0 }, readback: { userId: args.userId, deleted: true } };
+    writeTool({
+        tools,
+        name: "org.user.delete",
+        lane: LANE,
+        scope: SCOPES.userDelete,
+        description: "删除员工（`GET organization/user/strike_out?id=`）。只传用户 id；返回 deleted。",
+        inputSchema: { userId: z.string().min(1) },
+        execute: async (session, args) => {
+            await wireCall(session, { path: ENDPOINTS.organizationUserDelete, query: { ...orgQuery(session), id: args.userId } });
+            return { performed: { errcode: 0 }, readback: { userId: args.userId, deleted: true } };
+        },
     });
     tools.push(defineTool({
         name: "org.user.info",
@@ -746,240 +953,298 @@ export function registerOrganizationLane(tools) {
             return { userId: String(args.userId), count: departments.length, departments };
         }),
     }));
-    writeTool(tools, "org.role.delete", LANE, SCOPES.roleDelete, "删除角色（`GET organization/role/strike_out_role?ids=`）。平台**拒绝删除仍有成员的角色**（`-1 角色下已经包含用户数据！`，实测 1.1.25）：默认先读成员数、非空即拒绝并给出人数；`force:true` 才会先逐人移出再删。**可用 roleCode 代替 roleId**（org.role.list 的码表只有 code）。", {
-        roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
-        roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表，如 qc_manager）或名称"),
-        force: z.boolean().optional().describe("true = 先移出全部成员再删角色"),
-    }, async (session, args) => {
-        const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.delete");
-        const rows = await memberRows(session, roleId);
-        if (rows.length > 0 && args.force !== true)
-            throw new ToolRefusalError({
-                status: "refused", blocker: "role-has-members", roleId, members: rows.length,
-                nextCommand: `omc call org.role.delete --args '${JSON.stringify({ roleId, force: true })}'`,
-                message: `角色下还有 ${rows.length} 名成员，平台拒绝删除（errmsg：角色下已经包含用户数据）。先 org.role.removeUsers，或传 force:true 让工具移出后再删。`,
-            });
-        if (rows.length > 0)
-            await removeMembers(session, roleId, rows.map(roleUserId));
-        await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: roleId } });
-        return { performed: { errcode: 0 }, readback: { roleId, deleted: true, removedMembers: rows.length } };
+    writeTool({
+        tools,
+        name: "org.role.delete",
+        lane: LANE,
+        scope: SCOPES.roleDelete,
+        description: "删除角色（`GET organization/role/strike_out_role?ids=`）。平台**拒绝删除仍有成员的角色**（`-1 角色下已经包含用户数据！`，实测 1.1.25）：默认先读成员数、非空即拒绝并给出人数；`force:true` 才会先逐人移出再删。**可用 roleCode 代替 roleId**（org.role.list 的码表只有 code）。",
+        inputSchema: {
+            roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+            roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表，如 qc_manager）或名称"),
+            force: z.boolean().optional().describe("true = 先移出全部成员再删角色"),
+        },
+        execute: async (session, args) => {
+            const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.delete");
+            const rows = await memberRows(session, roleId);
+            if (rows.length > 0 && args.force !== true)
+                throw new ToolRefusalError({
+                    status: "refused", blocker: "role-has-members", roleId, members: rows.length,
+                    nextCommand: `omc call org.role.delete --args '${JSON.stringify({ roleId, force: true })}'`,
+                    message: `角色下还有 ${rows.length} 名成员，平台拒绝删除（errmsg：角色下已经包含用户数据）。先 org.role.removeUsers，或传 force:true 让工具移出后再删。`,
+                });
+            if (rows.length > 0)
+                await removeMembers(session, roleId, rows.map(roleUserId));
+            await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: roleId } });
+            return { performed: { errcode: 0 }, readback: { roleId, deleted: true, removedMembers: rows.length } };
+        },
     });
-    writeTool(tools, "org.roleGroup.delete", LANE, SCOPES.roleGroupDelete, "删除角色组（`GET organization/role/strike_out_role_group?ids=`）。平台**拒绝删除仍含角色的组**（`-1 角色组下已经包含角色数据！`）：默认先数角色、非空即拒绝；`force:true` 会逐个删角色（含其成员）再删组。", {
-        roleGroupId: z.string().min(1),
-        force: z.boolean().optional(),
-    }, async (session, args) => {
-        const roles = await rolesInGroup(session, String(args.roleGroupId));
-        if (roles.length > 0 && args.force !== true)
-            throw new ToolRefusalError({
-                status: "refused", blocker: "role-group-has-roles", roleGroupId: String(args.roleGroupId), roles: roles.length,
-                nextCommand: `omc call org.roleGroup.delete --args '${JSON.stringify({ roleGroupId: String(args.roleGroupId), force: true })}'`,
-                message: `角色组下还有 ${roles.length} 个角色，平台拒绝删除（errmsg：角色组下已经包含角色数据）。先删角色，或传 force:true。`,
-            });
-        for (const role of roles) {
-            const members = await memberRows(session, role.id);
-            if (members.length > 0)
-                await removeMembers(session, role.id, members.map(roleUserId));
-            await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: role.id } });
-        }
-        await wireCall(session, { path: ENDPOINTS.organizationRoleGroupDelete, query: { ...orgQuery(session), ids: String(args.roleGroupId) } });
-        return { performed: { errcode: 0 }, readback: { roleGroupId: String(args.roleGroupId), deleted: true, removedRoles: roles.map((role) => role.id) } };
+    writeTool({
+        tools,
+        name: "org.roleGroup.delete",
+        lane: LANE,
+        scope: SCOPES.roleGroupDelete,
+        description: "删除角色组（`GET organization/role/strike_out_role_group?ids=`）。平台**拒绝删除仍含角色的组**（`-1 角色组下已经包含角色数据！`）：默认先数角色、非空即拒绝；`force:true` 会逐个删角色（含其成员）再删组。",
+        inputSchema: {
+            roleGroupId: z.string().min(1),
+            force: z.boolean().optional(),
+        },
+        execute: async (session, args) => {
+            const roles = await rolesInGroup(session, String(args.roleGroupId));
+            if (roles.length > 0 && args.force !== true)
+                throw new ToolRefusalError({
+                    status: "refused", blocker: "role-group-has-roles", roleGroupId: String(args.roleGroupId), roles: roles.length,
+                    nextCommand: `omc call org.roleGroup.delete --args '${JSON.stringify({ roleGroupId: String(args.roleGroupId), force: true })}'`,
+                    message: `角色组下还有 ${roles.length} 个角色，平台拒绝删除（errmsg：角色组下已经包含角色数据）。先删角色，或传 force:true。`,
+                });
+            for (const role of roles) {
+                const members = await memberRows(session, role.id);
+                if (members.length > 0)
+                    await removeMembers(session, role.id, members.map(roleUserId));
+                await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: role.id } });
+            }
+            await wireCall(session, { path: ENDPOINTS.organizationRoleGroupDelete, query: { ...orgQuery(session), ids: String(args.roleGroupId) } });
+            return { performed: { errcode: 0 }, readback: { roleGroupId: String(args.roleGroupId), deleted: true, removedRoles: roles.map((role) => role.id) } };
+        },
     });
-    writeTool(tools, "org.user.transferDepartment", LANE, SCOPES.userTransfer, "把员工从一个部门移到另一个部门（`POST organization/user/dept_transfer`，body `{userIds,sourceDept,targetDept}`）。sourceDept 必填（缺它 50000）；移动后原部门不再包含该员工，主部门保持。", {
-        userId: z.string().min(1),
-        fromDeptId: z.string().min(1).describe("原部门 id（必填）"),
-        toDeptId: z.string().min(1).describe("目标部门 id"),
-    }, async (session, args) => {
-        await wireCall(session, {
-            path: ENDPOINTS.organizationUserDeptTransfer, method: "POST", query: orgQuery(session),
-            body: { userIds: [String(args.userId)], sourceDept: String(args.fromDeptId), targetDept: String(args.toDeptId) },
-        });
-        const departments = wireRows((await wireCall(session, {
-            path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) },
-        })).data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
-        return { performed: { errcode: 0 }, readback: { userId: String(args.userId), fromDeptId: String(args.fromDeptId), toDeptId: String(args.toDeptId), departments } };
+    writeTool({
+        tools,
+        name: "org.user.transferDepartment",
+        lane: LANE,
+        scope: SCOPES.userTransfer,
+        description: "把员工从一个部门移到另一个部门（`POST organization/user/dept_transfer`，body `{userIds,sourceDept,targetDept}`）。sourceDept 必填（缺它 50000）；移动后原部门不再包含该员工，主部门保持。",
+        inputSchema: {
+            userId: z.string().min(1),
+            fromDeptId: z.string().min(1).describe("原部门 id（必填）"),
+            toDeptId: z.string().min(1).describe("目标部门 id"),
+        },
+        execute: async (session, args) => {
+            await wireCall(session, {
+                path: ENDPOINTS.organizationUserDeptTransfer, method: "POST", query: orgQuery(session),
+                body: { userIds: [String(args.userId)], sourceDept: String(args.fromDeptId), targetDept: String(args.toDeptId) },
+            });
+            const departments = wireRows((await wireCall(session, {
+                path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) },
+            })).data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
+            return { performed: { errcode: 0 }, readback: { userId: String(args.userId), fromDeptId: String(args.fromDeptId), toDeptId: String(args.toDeptId), departments } };
+        },
     });
-    writeTool(tools, "org.role.update", LANE, SCOPES.roleUpdate, "改角色名称/编码/备注/所属角色组（`POST organization/role/modify_role`）。先读现状再提交，只传要改的字段。**平台要求 roleGroupId 必填**（缺则 202012「角色组主键Id不能为空」），工具默认回填当前组；**corpId 不可改**（RoleHelper.update 不读该字段），要换企业只能在目标企业下重建角色。", {
-        roleId: z.string().min(1),
-        roleName: z.string().optional(),
-        roleGroupId: z.string().min(1).optional().describe("移到别的角色组（默认保持当前组）。平台 update 必填该字段，且目标组必须存在、roleType=SYS"),
-        code: z.string().optional(),
-        remarks: z.string().optional(),
-    }, async (session, args) => {
-        const current = (await wireCall(session, { path: ENDPOINTS.organizationRoleGet, query: { ...orgQuery(session), roleId: String(args.roleId) } })).data;
-        if (!current)
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `role/get 未返回角色 ${String(args.roleId)}；不要盲目 modify` });
-        // RoleHelper.update (1.1.25) validates roleName AND roleGroupId as
-        // REQUIRED before touching the row (validateRoleParam): a delta that omits
-        // either answers 202001 「角色名称不能为空」 / 202012 「角色组主键Id不能为空」.
-        // Both are backfilled from role/get, so a remarks-only edit works.
-        const roleName = String(args.roleName ?? current.roleName ?? current.name ?? "");
-        if (roleName === "")
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `角色 ${String(args.roleId)} 读不到 roleName；平台 modify_role 要求该字段，请显式传 roleName` });
-        const roleGroupId = String(args.roleGroupId ?? current.roleGroupId ?? current.groupId ?? "");
-        if (roleGroupId === "")
-            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `角色 ${String(args.roleId)} 读不到 roleGroupId；平台 modify_role 要求该字段，请显式传 roleGroupId` });
-        const body = {
-            ...current,
-            roleId: String(args.roleId),
-            roleName,
-            roleGroupId,
-            ...(args.code !== undefined ? { code: args.code } : {}),
-            ...(args.remarks !== undefined ? { remarks: args.remarks } : {}),
-            corpId: current.corpId ?? "other",
-            roleType: current.roleType ?? "SYS",
-        };
-        await wireCall(session, { path: ENDPOINTS.organizationRoleModify, method: "POST", query: orgQuery(session), body });
-        const after = (await wireCall(session, { path: ENDPOINTS.organizationRoleGet, query: { ...orgQuery(session), roleId: String(args.roleId) } })).data;
-        // role/get answers RoleModel (name/groupId), not RoleVO (roleName/
-        // roleGroupId) — read both spellings so the readback is never null.
-        return {
-            performed: { errcode: 0 },
-            readback: {
+    writeTool({
+        tools,
+        name: "org.role.update",
+        lane: LANE,
+        scope: SCOPES.roleUpdate,
+        description: "改角色名称/编码/备注/所属角色组（`POST organization/role/modify_role`）。先读现状再提交，只传要改的字段。**平台要求 roleGroupId 必填**（缺则 202012「角色组主键Id不能为空」），工具默认回填当前组；**corpId 不可改**（RoleHelper.update 不读该字段），要换企业只能在目标企业下重建角色。",
+        inputSchema: {
+            roleId: z.string().min(1),
+            roleName: z.string().optional(),
+            roleGroupId: z.string().min(1).optional().describe("移到别的角色组（默认保持当前组）。平台 update 必填该字段，且目标组必须存在、roleType=SYS"),
+            code: z.string().optional(),
+            remarks: z.string().optional(),
+        },
+        execute: async (session, args) => {
+            const current = (await wireCall(session, { path: ENDPOINTS.organizationRoleGet, query: { ...orgQuery(session), roleId: String(args.roleId) } })).data;
+            if (!current)
+                throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `role/get 未返回角色 ${String(args.roleId)}；不要盲目 modify` });
+            // RoleHelper.update (1.1.25) validates roleName AND roleGroupId as
+            // REQUIRED before touching the row (validateRoleParam): a delta that omits
+            // either answers 202001 「角色名称不能为空」 / 202012 「角色组主键Id不能为空」.
+            // Both are backfilled from role/get, so a remarks-only edit works.
+            const roleName = String(args.roleName ?? current.roleName ?? current.name ?? "");
+            if (roleName === "")
+                throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `角色 ${String(args.roleId)} 读不到 roleName；平台 modify_role 要求该字段，请显式传 roleName` });
+            const roleGroupId = String(args.roleGroupId ?? current.roleGroupId ?? current.groupId ?? "");
+            if (roleGroupId === "")
+                throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `角色 ${String(args.roleId)} 读不到 roleGroupId；平台 modify_role 要求该字段，请显式传 roleGroupId` });
+            const body = {
+                ...current,
                 roleId: String(args.roleId),
-                roleName: after?.roleName ?? after?.name ?? null,
-                roleGroupId: after?.roleGroupId ?? after?.groupId ?? null,
-                code: after?.code ?? null,
-                remarks: after?.remarks ?? null,
-            },
-        };
+                roleName,
+                roleGroupId,
+                ...(args.code !== undefined ? { code: args.code } : {}),
+                ...(args.remarks !== undefined ? { remarks: args.remarks } : {}),
+                corpId: current.corpId ?? "other",
+                roleType: current.roleType ?? "SYS",
+            };
+            await wireCall(session, { path: ENDPOINTS.organizationRoleModify, method: "POST", query: orgQuery(session), body });
+            const after = (await wireCall(session, { path: ENDPOINTS.organizationRoleGet, query: { ...orgQuery(session), roleId: String(args.roleId) } })).data;
+            // role/get answers RoleModel (name/groupId), not RoleVO (roleName/
+            // roleGroupId) — read both spellings so the readback is never null.
+            return {
+                performed: { errcode: 0 },
+                readback: {
+                    roleId: String(args.roleId),
+                    roleName: after?.roleName ?? after?.name ?? null,
+                    roleGroupId: after?.roleGroupId ?? after?.groupId ?? null,
+                    code: after?.code ?? null,
+                    remarks: after?.remarks ?? null,
+                },
+            };
+        },
     });
-    writeTool(tools, "org.role.addUsers", LANE, SCOPES.addUsers, "加成员并（可选）一次设好管理范围（`add_role_user` + 逐人 `update_ouscope`，一个工具调用）。users[].id 必须是 recId（org.user.search 的 id）；传 `scopes` 会应用到本次新增的每个人。**平台的 add_role_user 虽然收 `ouScope` 但会忽略它**（实测 1.1.25，回读仍为空），所以范围必须单独写——工具内部已按顺序完成。加完回读成员与范围。", {
-        roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
-        roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称——省掉取 artifact 找 id"),
-        users: z.array(z.object({ id: z.string().min(1).describe("用户记录 id（recId）"), name: z.string().min(1) })).min(1),
-        scopes: z.array(z.object({
-            id: z.string().min(1).describe("部门 id"),
-            name: z.string().min(1),
-            deptPath: z.string().optional(),
-            type: z.string().optional().describe("默认 \"1\"（部门节点）"),
-        })).optional().describe("应用到本次新增的每个成员的管​理范围；省略则不设（成员 ouScope 为空）"),
-        sortKey: z.number().int().optional(),
-        userIds: z.array(z.object({ id: z.string().min(1), name: z.string().min(1) })).optional().describe("`users` 的别名"),
-    }, async (session, args) => {
-        const users = args.users ?? args.userIds ?? [];
-        if (users.length === 0)
-            throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "org.role.addUsers", message: "需要 users（或 userIds）至少一人" });
-        const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.addUsers");
-        await wireCall(session, {
-            path: ENDPOINTS.organizationRoleAddUser, method: "POST",
-            query: orgQuery(session),
-            body: { roleId, sortKey: args.sortKey ?? 999, userIds: users.map((user) => ({ id: user.id, name: user.name, type: 3, unitType: "3" })) },
-        });
-        const readback = async () => {
+    writeTool({
+        tools,
+        name: "org.role.addUsers",
+        lane: LANE,
+        scope: SCOPES.addUsers,
+        description: "加成员并（可选）一次设好管理范围（`add_role_user` + 逐人 `update_ouscope`，一个工具调用）。users[].id 必须是 recId（org.user.search 的 id）；传 `scopes` 会应用到本次新增的每个人。**平台的 add_role_user 虽然收 `ouScope` 但会忽略它**（实测 1.1.25，回读仍为空），所以范围必须单独写——工具内部已按顺序完成。加完回读成员与范围。",
+        inputSchema: {
+            roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+            roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称——省掉取 artifact 找 id"),
+            users: z.array(z.object({ id: z.string().min(1).describe("用户记录 id（recId）"), name: z.string().min(1) })).min(1),
+            scopes: z.array(z.object({
+                id: z.string().min(1).describe("部门 id"),
+                name: z.string().min(1),
+                deptPath: z.string().optional(),
+                type: z.string().optional().describe("默认 \"1\"（部门节点）"),
+            })).optional().describe("应用到本次新增的每个成员的管​理范围；省略则不设（成员 ouScope 为空）"),
+            sortKey: z.number().int().optional(),
+            userIds: z.array(z.object({ id: z.string().min(1), name: z.string().min(1) })).optional().describe("`users` 的别名"),
+        },
+        execute: async (session, args) => {
+            const users = args.users ?? args.userIds ?? [];
+            if (users.length === 0)
+                throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "org.role.addUsers", message: "需要 users（或 userIds）至少一人" });
+            const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.addUsers");
+            await wireCall(session, {
+                path: ENDPOINTS.organizationRoleAddUser, method: "POST",
+                query: orgQuery(session),
+                body: { roleId, sortKey: args.sortKey ?? 999, userIds: users.map((user) => ({ id: user.id, name: user.name, type: 3, unitType: "3" })) },
+            });
+            const readback = async () => {
+                const data = (await wireCall(session, {
+                    path: ENDPOINTS.organizationRoleUsers,
+                    query: { ...orgQuery(session), roleId: roleId, page: "0", size: "500" },
+                })).data;
+                return Array.isArray(data?.content) ? data.content : wireRows(data);
+            };
+            const rows = await readback();
+            const present = new Set(rows.map(roleUserId));
+            const added = users.filter((user) => present.has(user.id)).map((user) => user.id);
+            const missing = users.filter((user) => !present.has(user.id)).map((user) => user.id);
+            const scopeResults = [];
+            if (args.scopes !== undefined && args.scopes.length > 0) {
+                const ouScopeList = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type ?? "1", ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
+                for (const id of added) {
+                    await wireCall(session, {
+                        path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST", query: orgQuery(session),
+                        body: { roleId: roleId, userId: id, unitType: 3, sortKey: args.sortKey ?? 999, ouScopeList },
+                    });
+                    const scope = wireRows((await wireCall(session, {
+                        path: ENDPOINTS.organizationRoleGetOuScope,
+                        query: { ...orgQuery(session), roleId: roleId, userId: id },
+                    })).data);
+                    scopeResults.push({ userId: id, scopes: scope.length });
+                }
+            }
+            return {
+                performed: { errcode: 0 },
+                readback: {
+                    roleId: roleId, added,
+                    ...(missing.length > 0 ? { missing, hint: "这些 recId 未出现在成员列表：确认 id 是 recId、用户未离职/禁用" } : {}),
+                    ...(scopeResults.length > 0 ? { scopeResults } : {}),
+                    // ouScope 是流程角色参与人解析的过滤维度：平台
+                    // ParticipantService.listManagerIdsByUserIdsAndRoleCode 用
+                    // `h_org_role_user.ouScope ∩ 发起人部门链`，ouScope 为空 = 该成员
+                    // 永远解析不到。没传 scopes 时把这条代价显式说出来（r9+r10 两次
+                    // 真机坐实；不是 corpId 问题）。
+                    ...(args.scopes === undefined || args.scopes.length === 0
+                        ? {
+                            warnings: [
+                                {
+                                    code: "org-role-member-scope-empty",
+                                    severity: "warning",
+                                    message: "本次未传 scopes：新增成员的 ouScope 为空，**不能作为流程角色参与人被解析**（平台按 ouScope ∩ 发起人部门链过滤，r9/r10 真机坐实）。如果这个角色要用于审批/参与人，请补 scopes（部门节点）或随后调用 org.role.setUserScope；只用于权限分配可忽略。",
+                                },
+                            ],
+                        }
+                        : {}),
+                    total: rows.length,
+                },
+            };
+        },
+    });
+    writeTool({
+        tools,
+        name: "org.role.removeUsers",
+        lane: LANE,
+        scope: SCOPES.removeUsers,
+        description: "把成员移出角色（`POST organization/role/strike_out_role_user`）。**平台要求 JSON body `{roleId,userIds:[...]}`**——用 query 或 `ids` 会报 10009 `Required request body is missing`（实测 1.1.25）。只移出角色，不删用户。",
+        inputSchema: {
+            roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+            roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称"),
+            ids: z.array(z.string().min(1)).min(1).describe("要移出的成员 recId 列表"),
+        },
+        execute: async (session, args) => {
+            // r28h F11: always echo the *resolved* roleId — never String(args.roleId)
+            // (that becomes the literal "undefined" when the caller passed roleCode).
+            const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.removeUsers");
+            await wireCall(session, {
+                path: ENDPOINTS.organizationRoleRemoveUser, method: "POST", query: orgQuery(session),
+                body: { roleId, userIds: args.ids },
+            });
             const data = (await wireCall(session, {
                 path: ENDPOINTS.organizationRoleUsers,
-                query: { ...orgQuery(session), roleId: roleId, page: "0", size: "500" },
+                query: { ...orgQuery(session), roleId, page: "0", size: "500" },
             })).data;
-            return Array.isArray(data?.content) ? data.content : wireRows(data);
-        };
-        const rows = await readback();
-        const present = new Set(rows.map(roleUserId));
-        const added = users.filter((user) => present.has(user.id)).map((user) => user.id);
-        const missing = users.filter((user) => !present.has(user.id)).map((user) => user.id);
-        const scopeResults = [];
-        if (args.scopes !== undefined && args.scopes.length > 0) {
-            const ouScopeList = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type ?? "1", ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
-            for (const id of added) {
-                await wireCall(session, {
-                    path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST", query: orgQuery(session),
-                    body: { roleId: roleId, userId: id, unitType: 3, sortKey: args.sortKey ?? 999, ouScopeList },
-                });
-                const scope = wireRows((await wireCall(session, {
-                    path: ENDPOINTS.organizationRoleGetOuScope,
-                    query: { ...orgQuery(session), roleId: roleId, userId: id },
-                })).data);
-                scopeResults.push({ userId: id, scopes: scope.length });
-            }
-        }
-        return {
-            performed: { errcode: 0 },
-            readback: {
-                roleId: roleId, added,
-                ...(missing.length > 0 ? { missing, hint: "这些 recId 未出现在成员列表：确认 id 是 recId、用户未离职/禁用" } : {}),
-                ...(scopeResults.length > 0 ? { scopeResults } : {}),
-                // ouScope 是流程角色参与人解析的过滤维度：平台
-                // ParticipantService.listManagerIdsByUserIdsAndRoleCode 用
-                // `h_org_role_user.ouScope ∩ 发起人部门链`，ouScope 为空 = 该成员
-                // 永远解析不到。没传 scopes 时把这条代价显式说出来（r9+r10 两次
-                // 真机坐实；不是 corpId 问题）。
-                ...(args.scopes === undefined || args.scopes.length === 0
-                    ? {
-                        warnings: [
-                            {
-                                code: "org-role-member-scope-empty",
-                                severity: "warning",
-                                message: "本次未传 scopes：新增成员的 ouScope 为空，**不能作为流程角色参与人被解析**（平台按 ouScope ∩ 发起人部门链过滤，r9/r10 真机坐实）。如果这个角色要用于审批/参与人，请补 scopes（部门节点）或随后调用 org.role.setUserScope；只用于权限分配可忽略。",
-                            },
-                        ],
-                    }
-                    : {}),
-                total: rows.length,
-            },
-        };
-    });
-    writeTool(tools, "org.role.removeUsers", LANE, SCOPES.removeUsers, "把成员移出角色（`POST organization/role/strike_out_role_user`）。**平台要求 JSON body `{roleId,userIds:[...]}`**——用 query 或 `ids` 会报 10009 `Required request body is missing`（实测 1.1.25）。只移出角色，不删用户。", {
-        roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
-        roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称"),
-        ids: z.array(z.string().min(1)).min(1).describe("要移出的成员 recId 列表"),
-    }, async (session, args) => {
-        const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.removeUsers");
-        await wireCall(session, {
-            path: ENDPOINTS.organizationRoleRemoveUser, method: "POST", query: orgQuery(session),
-            body: { roleId, userIds: args.ids },
-        });
-        const data = (await wireCall(session, {
-            path: ENDPOINTS.organizationRoleUsers,
-            query: { ...orgQuery(session), roleId: String(args.roleId), page: "0", size: "500" },
-        })).data;
-        const rows = Array.isArray(data?.content) ? data.content : wireRows(data);
-        const present = new Set(rows.map(roleUserId));
-        return { performed: { errcode: 0 }, readback: { roleId: String(args.roleId), removed: args.ids.filter((id) => !present.has(id)), stillPresent: args.ids.filter((id) => present.has(id)), total: data?.totalElements ?? rows.length } };
+            const rows = Array.isArray(data?.content) ? data.content : wireRows(data);
+            const present = new Set(rows.map(roleUserId));
+            return { performed: { errcode: 0 }, readback: { roleId, removed: args.ids.filter((id) => !present.has(id)), stillPresent: args.ids.filter((id) => present.has(id)), total: data?.totalElements ?? rows.length } };
+        },
     });
-    writeTool(tools, "org.role.setUserScope", LANE, SCOPES.setScope, "设置成员管理范围（`POST organization/role/update_ouscope`）。平台覆盖语义、无回滚：默认读旧值合并（mode:\"merge\"），mode:\"replace\" 才整体替换。unitType 传数字 3（addUsers 里是字符串 \"3\"）。节点 {id,name,type:\"1\",deptPath}。", {
-        roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
-        roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称"),
-        userId: z.string().min(1).describe("成员 recId"),
-        scopes: z.array(z.object({
-            id: z.string().min(1).describe("部门 id"),
-            name: z.string().min(1),
-            deptPath: z.string().optional().describe("完整路径，如 根组织/广州总所"),
-            // The wire wants the enum as a STRING ("1"); a number used to die in
-            // input validation with a generic tool-input-invalid (r10). Accept both
-            // and normalize, so the mistake cannot cost a round.
-            type: z.union([z.string(), z.number()]).optional().describe("部门节点固定 \"1\"（字符串；也接受数字 1，工具会归一化）"),
-        })).describe("要设置的管理范围节点"),
-        mode: z.enum(["merge", "replace"]).optional().describe("默认 merge（读旧值合并）；replace = 覆盖整个范围"),
-        dryRun: z.boolean().optional(),
-    }, async (session, args) => {
-        const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.setUserScope");
-        const before = wireRows((await wireCall(session, {
-            path: ENDPOINTS.organizationRoleGetOuScope,
-            query: { ...orgQuery(session), roleId, userId: args.userId },
-        })).data);
-        const wanted = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type === undefined ? "1" : String(scope.type), ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
-        const merged = args.mode === "replace"
-            ? wanted
-            : [...before.map((row) => ({ id: String(row.id ?? ""), name: String(row.name ?? ""), type: String(row.type ?? "1"), ...(row.deptPath ? { deptPath: String(row.deptPath) } : {}) })).filter((row) => row.id !== ""), ...wanted]
-                .filter((row, index, all) => all.findIndex((candidate) => candidate.id === row.id) === index);
-        const removed = before.map((row) => String(row.id ?? "")).filter((id) => id !== "" && !merged.some((row) => row.id === id));
-        if (args.mode === "replace" && removed.length > 0)
-            // A data-loss write without an explicit acknowledgement is exactly the
-            // failure mode the customer hit manually; refuse unless replace was
-            // chosen deliberately (mode): the caller already opted in.
-            void removed;
-        await wireCall(session, {
-            path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST",
-            query: orgQuery(session),
-            body: { roleId, userId: args.userId, unitType: 3, sortKey: 999, ouScopeList: merged },
-        });
-        const after = wireRows((await wireCall(session, {
-            path: ENDPOINTS.organizationRoleGetOuScope,
-            query: { ...orgQuery(session), roleId, userId: args.userId },
-        })).data).map((row) => ({ id: row.id ?? null, name: row.name ?? null, type: row.type ?? null, deptPath: row.deptPath ?? null }));
-        return {
-            performed: { errcode: 0 },
-            readback: { roleId, userId: args.userId, mode: args.mode ?? "merge", before: before.length, after: after.length, scopes: after, ...(removed.length > 0 ? { removedScopeIds: removed } : {}) },
-        };
+    writeTool({
+        tools,
+        name: "org.role.setUserScope",
+        lane: LANE,
+        scope: SCOPES.setScope,
+        description: "设置成员管理范围（`POST organization/role/update_ouscope`）。**不是枚举档位**（本人/本部门/本部门及下级/全部这类平台没有）：scopes 是一组部门节点的自由列表。平台覆盖语义、无回滚：默认读旧值合并（mode:\"merge\"），mode:\"replace\" 才整体替换。**类型对照表**：setUserScope 的 unitType 传数字 3；addUsers 的 unitType 传字符串 \"3\"；节点 type 传字符串 \"1\"（部门节点）。最小可跑示例：`{\"roleCode\":\"X\",\"userId\":\"<recId>\",\"scopes\":[{\"id\":\"<deptId>\",\"name\":\"<deptName>\",\"type\":\"1\"}]}`。",
+        inputSchema: {
+            roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+            roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称"),
+            userId: z.string().min(1).describe("成员 recId"),
+            scopes: z.array(z.object({
+                id: z.string().min(1).describe("部门 id（org.department.list 的 id）"),
+                name: z.string().min(1).describe("部门名（与 id 对应）"),
+                deptPath: z.string().optional().describe("完整路径，如 根组织/广州总所"),
+                // The wire wants the enum as a STRING ("1"); a number used to die in
+                // input validation with a generic tool-input-invalid (r10). Accept both
+                // and normalize, so the mistake cannot cost a round.
+                type: z.union([z.string(), z.number()]).optional().describe("部门节点固定 \"1\"（字符串；也接受数字 1，工具会归一化）"),
+            })).describe("要设置的管理范围节点列表（自由列表，不是枚举档位）；每项 {id,name,type:\"1\"}"),
+            mode: z.enum(["merge", "replace"]).optional().describe("默认 merge（读旧值合并）；replace = 覆盖整个范围"),
+            dryRun: z.boolean().optional(),
+        },
+        execute: async (session, args) => {
+            const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.setUserScope");
+            const before = wireRows((await wireCall(session, {
+                path: ENDPOINTS.organizationRoleGetOuScope,
+                query: { ...orgQuery(session), roleId, userId: args.userId },
+            })).data);
+            const wanted = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type === undefined ? "1" : String(scope.type), ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
+            const merged = args.mode === "replace"
+                ? wanted
+                : [...before.map((row) => ({ id: String(row.id ?? ""), name: String(row.name ?? ""), type: String(row.type ?? "1"), ...(row.deptPath ? { deptPath: String(row.deptPath) } : {}) })).filter((row) => row.id !== ""), ...wanted]
+                    .filter((row, index, all) => all.findIndex((candidate) => candidate.id === row.id) === index);
+            const removed = before.map((row) => String(row.id ?? "")).filter((id) => id !== "" && !merged.some((row) => row.id === id));
+            if (args.mode === "replace" && removed.length > 0)
+                // A data-loss write without an explicit acknowledgement is exactly the
+                // failure mode the customer hit manually; refuse unless replace was
+                // chosen deliberately (mode): the caller already opted in.
+                void removed;
+            await wireCall(session, {
+                path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST",
+                query: orgQuery(session),
+                body: { roleId, userId: args.userId, unitType: 3, sortKey: 999, ouScopeList: merged },
+            });
+            const after = wireRows((await wireCall(session, {
+                path: ENDPOINTS.organizationRoleGetOuScope,
+                query: { ...orgQuery(session), roleId, userId: args.userId },
+            })).data).map((row) => ({ id: row.id ?? null, name: row.name ?? null, type: row.type ?? null, deptPath: row.deptPath ?? null }));
+            return {
+                performed: { errcode: 0 },
+                readback: { roleId, userId: args.userId, mode: args.mode ?? "merge", before: before.length, after: after.length, scopes: after, ...(removed.length > 0 ? { removedScopeIds: removed } : {}) },
+            };
+        },
     });
 }
 //# sourceMappingURL=organization.js.map