@rubytech/create-maxy-code 0.1.191 → 0.1.193

package/dist/__tests__/brew-resolve.test.js

@@ -110,7 +110,7 @@ test("DARWIN_ALIASES contains nodejs → node@22 and is the only entry", () => {
 // ---------------------------------------------------------------------------
 // Mirrors `DARWIN_BASE_DEPS` in packages/create-maxy-code/src/index.ts. Every
 // entry must be either a real brew formula (pass-through) or an alias.
-const DARWIN_BASE_DEPS_FIXTURE = ["curl", "git", "unzip", "jq", "poppler", "ffmpeg"];
+const DARWIN_BASE_DEPS_FIXTURE = ["curl", "git", "unzip", "jq", "poppler", "ffmpeg", "tesseract", "ocrmypdf"];
 // `neo4j` and `cloudflared` are passed to installAllBrewPackages from
 // installNeo4j (index.ts:1265) and installCloudflared (index.ts:1728). Both are
 // concrete brew formula names — no alias hop expected.

package/dist/__tests__/macos-darwin-branch.test.js

@@ -34,7 +34,7 @@ test("installSystemDeps darwin branch installs DARWIN_BASE_DEPS via brew", () =>
     // The shared dep set the darwin path feeds to installAllBrewPackages. If
     // this list shrinks or a name changes, brew-resolve.test.ts (DARWIN_BASE_DEPS_FIXTURE)
     // must move in lockstep — the comment in brew-resolve.test.ts says so.
-    assert.match(SRC, /DARWIN_BASE_DEPS\s*=\s*\[\s*"curl"\s*,\s*"git"\s*,\s*"unzip"\s*,\s*"jq"\s*,\s*"poppler"\s*,\s*"ffmpeg"\s*\]/);
+    assert.match(SRC, /DARWIN_BASE_DEPS\s*=\s*\[\s*"curl"\s*,\s*"git"\s*,\s*"unzip"\s*,\s*"jq"\s*,\s*"poppler"\s*,\s*"ffmpeg"\s*,\s*"tesseract"\s*,\s*"ocrmypdf"\s*\]/);
     assert.match(SRC, /installAllBrewPackages\(DARWIN_BASE_DEPS,\s*logFile\)/);
 });
 test("installCloudflared darwin branch logs the documented skip and brew-installs cloudflared", () => {

package/dist/index.js

@@ -649,11 +649,11 @@ function installSystemDeps() {
         // out-of-scope note). mDNS is provided by the OS, so avahi-* drop out.
         // Translate the remaining apt names through decideBrewResolution and
         // let installAllBrewPackages handle the install + verify pattern.
-        const DARWIN_BASE_DEPS = ["curl", "git", "unzip", "jq", "poppler", "ffmpeg"];
+        const DARWIN_BASE_DEPS = ["curl", "git", "unzip", "jq", "poppler", "ffmpeg", "tesseract", "ocrmypdf"];
         installAllBrewPackages(DARWIN_BASE_DEPS, logFile);
         return;
     }
-    const BASE_DEPS = ["curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg", "bind9-dnsutils"];
+    const BASE_DEPS = ["curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg", "bind9-dnsutils", "tesseract-ocr", "ocrmypdf"];
     // xterm is the *preferred* terminal-emulator binary for the VNC-rendered
     // Terminal surface
     // delegates window creation to the session's gnome-terminal-server,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.191",
+  "version": "0.1.193",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/lib/mcp-eager/dist/index.d.ts

@@ -20,6 +20,41 @@
  */
 /** Wire-format metadata key the Claude Code SDK reads. */
 export declare const ALWAYS_LOAD_META_KEY: "anthropic/alwaysLoad";
+/**
+ * Admin-seat detection. The rc-daemon exports `MAXY_SESSION_ROLE=admin` and
+ * `MAXY_SPECIALIST=""` for the orchestrator process and its MCP plugin
+ * children; specialist spawns set `MAXY_SPECIALIST=<name>`. A plugin process
+ * inheriting the env can therefore decide at registration AND invocation
+ * time whether it is loaded inside the admin seat.
+ *
+ * Mirrors `isAdminSeat` in platform/plugins/admin/mcp/src/skill-resolution.ts
+ * — this is a duplicate at the library layer so plugins that cannot import
+ * from the admin plugin (a sibling, not a dependency) share the same rule.
+ */
+export declare function isAdminSeat(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * MCP refusal envelope returned when the admin seat invokes a specialist-
+ * owned tool. The text names the dispatch route so the model's next action
+ * is the `Agent` dispatch rather than a dead end.
+ */
+export declare function adminBlockedResponse(toolName: string, owner: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+/**
+ * Wrap a tool handler so any admin-seat invocation short-circuits with the
+ * refusal envelope above and emits one `[admin-tool-gate]` line to stderr.
+ *
+ * Specialist seats pass through unchanged: this is the primitive Task 529
+ * defines for closing the in-message authoring path that Task 516 could
+ * not reach. The handler signature is preserved so existing call sites
+ * substitute `eagerTool(... handler)` for `eagerTool(... withAdminGate(name,
+ * owner, handler))` mechanically.
+ */
+export declare function withAdminGate<H extends (...args: any[]) => any>(toolName: string, owner: string, handler: H): H;
 /**
  * Loose structural type for any object exposing a `registerTool` method. The
  * MCP SDK ships dual ESM/CJS packages with conditional exports, so importing
@@ -57,5 +92,25 @@ type LocalZodRawShape = Record<string, unknown>;
  * the consumer's own zod version) infers the handler args.
  */
 export declare function eagerTool<Args extends LocalZodRawShape>(server: EagerCapableServer, name: string, description: string, inputSchema: Args, handler: (...args: any[]) => any): void;
+/**
+ * Loose structural type for the legacy four-arg `server.tool(name, desc,
+ * schema, handler)` call shape — used when the admin seat must register a
+ * specialist-owned tool as deferred (not eager) so it does not appear in
+ * the admin's eager tool list.
+ */
+type DeferredCapableServer = {
+    tool: (name: string, description: string, inputSchema: any, handler: (...args: any[]) => any) => any;
+};
+/**
+ * Register a tool that is eager for specialists but deferred + admin-gated
+ * for the admin seat. The owning specialist name is named here so the
+ * refusal envelope (and the `[admin-tool-gate]` log line) carries it.
+ *
+ * Use for every tool whose owner is a specialist (database-operator, writer-
+ * craft, research-assistant, personal-assistant, content-producer). The
+ * admin seat sees the tool only via ToolSearch — and any invocation from the
+ * admin seat refuses with the dispatch hint.
+ */
+export declare function eagerToolGated<Args extends LocalZodRawShape>(server: EagerCapableServer & DeferredCapableServer, name: string, owner: string, description: string, inputSchema: Args, handler: (...args: any[]) => any): void;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/mcp-eager/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAC;AAEpE;;;;;;;GAOG;AAEH,KAAK,kBAAkB,GAAG;IAAE,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAA;CAAE,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,IAAI,SAAS,gBAAgB,EACrD,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,IAAI,EAEjB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GAC/B,IAAI,CAUN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IACrE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,OAAO,EAAE,IAAI,CAAC;CACf,CAYA;AAED;;;;;;;;;GASG;AAEH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC7D,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,GACT,CAAC,CAYH;AAED;;;;;;;GAOG;AAEH,KAAK,kBAAkB,GAAG;IAAE,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAA;CAAE,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,IAAI,SAAS,gBAAgB,EACrD,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,IAAI,EAEjB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GAC/B,IAAI,CAUN;AAED;;;;;GAKG;AAEH,KAAK,qBAAqB,GAAG;IAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,GAAG,CAAA;CAAE,CAAC;AAEtI;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,gBAAgB,EAC1D,MAAM,EAAE,kBAAkB,GAAG,qBAAqB,EAClD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,IAAI,EAEjB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GAC/B,IAAI,CAMN"}

package/payload/platform/lib/mcp-eager/dist/index.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ALWAYS_LOAD_META_KEY = void 0;
+exports.isAdminSeat = isAdminSeat;
+exports.adminBlockedResponse = adminBlockedResponse;
+exports.withAdminGate = withAdminGate;
 exports.eagerTool = eagerTool;
+exports.eagerToolGated = eagerToolGated;
 /**
  * MCP eager-load helper.
  *
@@ -24,6 +28,59 @@ exports.eagerTool = eagerTool;
  */
 /** Wire-format metadata key the Claude Code SDK reads. */
 exports.ALWAYS_LOAD_META_KEY = "anthropic/alwaysLoad";
+/**
+ * Admin-seat detection. The rc-daemon exports `MAXY_SESSION_ROLE=admin` and
+ * `MAXY_SPECIALIST=""` for the orchestrator process and its MCP plugin
+ * children; specialist spawns set `MAXY_SPECIALIST=<name>`. A plugin process
+ * inheriting the env can therefore decide at registration AND invocation
+ * time whether it is loaded inside the admin seat.
+ *
+ * Mirrors `isAdminSeat` in platform/plugins/admin/mcp/src/skill-resolution.ts
+ * — this is a duplicate at the library layer so plugins that cannot import
+ * from the admin plugin (a sibling, not a dependency) share the same rule.
+ */
+function isAdminSeat(env = process.env) {
+    return env.MAXY_SESSION_ROLE === "admin" && !(env.MAXY_SPECIALIST && env.MAXY_SPECIALIST.length > 0);
+}
+/**
+ * MCP refusal envelope returned when the admin seat invokes a specialist-
+ * owned tool. The text names the dispatch route so the model's next action
+ * is the `Agent` dispatch rather than a dead end.
+ */
+function adminBlockedResponse(toolName, owner) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Tool \`${toolName}\` is owned by the \`${owner}\` specialist and is not callable from the admin seat. ` +
+                    `Dispatch \`${owner}\` with the Agent tool and pass the work as the brief.`,
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Wrap a tool handler so any admin-seat invocation short-circuits with the
+ * refusal envelope above and emits one `[admin-tool-gate]` line to stderr.
+ *
+ * Specialist seats pass through unchanged: this is the primitive Task 529
+ * defines for closing the in-message authoring path that Task 516 could
+ * not reach. The handler signature is preserved so existing call sites
+ * substitute `eagerTool(... handler)` for `eagerTool(... withAdminGate(name,
+ * owner, handler))` mechanically.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function withAdminGate(toolName, owner, handler) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const wrapped = ((...args) => {
+        if (isAdminSeat(process.env)) {
+            process.stderr.write(`[admin-tool-gate] role=admin tool=${toolName} decision=block reason=specialist-owned owner=${owner}\n`);
+            return adminBlockedResponse(toolName, owner);
+        }
+        return handler(...args);
+    });
+    return wrapped;
+}
 /**
  * Register an MCP tool that the Claude Code SDK eager-loads into the
  * model's prompt at session boot, bypassing the ToolSearch round-trip.
@@ -46,4 +103,23 @@ handler) {
         _meta: { [exports.ALWAYS_LOAD_META_KEY]: true },
     }, handler);
 }
+/**
+ * Register a tool that is eager for specialists but deferred + admin-gated
+ * for the admin seat. The owning specialist name is named here so the
+ * refusal envelope (and the `[admin-tool-gate]` log line) carries it.
+ *
+ * Use for every tool whose owner is a specialist (database-operator, writer-
+ * craft, research-assistant, personal-assistant, content-producer). The
+ * admin seat sees the tool only via ToolSearch — and any invocation from the
+ * admin seat refuses with the dispatch hint.
+ */
+function eagerToolGated(server, name, owner, description, inputSchema, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+handler) {
+    if (isAdminSeat(process.env)) {
+        server.tool(name, description, inputSchema, withAdminGate(name, owner, handler));
+        return;
+    }
+    eagerTool(server, name, description, inputSchema, handler);
+}
 //# sourceMappingURL=index.js.map

package/payload/platform/lib/mcp-eager/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AA4DA,8BAiBC;AA7ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DAA0D;AAC7C,QAAA,oBAAoB,GAAG,sBAA+B,CAAC;AA0BpE;;;;;;;;;;;;GAYG;AACH,SAAgB,SAAS,CACvB,MAA0B,EAC1B,IAAY,EACZ,WAAmB,EACnB,WAAiB;AACjB,8DAA8D;AAC9D,OAAgC;IAEhC,MAAM,CAAC,YAAY,CACjB,IAAI,EACJ;QACE,WAAW;QACX,WAAW;QACX,KAAK,EAAE,EAAE,CAAC,4BAAoB,CAAC,EAAE,IAAI,EAAE;KACxC,EACD,OAAO,CACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAkCA,kCAEC;AAOD,oDAeC;AAaD,sCAgBC;AAuCD,8BAiBC;AAqBD,wCAcC;AAlLD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DAA0D;AAC7C,QAAA,oBAAoB,GAAG,sBAA+B,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,SAAgB,WAAW,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC9D,OAAO,GAAG,CAAC,iBAAiB,KAAK,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvG,CAAC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB,CAAC,QAAgB,EAAE,KAAa;IAIlE,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EACF,UAAU,QAAQ,wBAAwB,KAAK,yDAAyD;oBACxG,cAAc,KAAK,wDAAwD;aAC9E;SACF;QACD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,8DAA8D;AAC9D,SAAgB,aAAa,CAC3B,QAAgB,EAChB,KAAa,EACb,OAAU;IAEV,8DAA8D;IAC9D,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE;QAClC,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,qCAAqC,QAAQ,iDAAiD,KAAK,IAAI,CACxG,CAAC;YACF,OAAO,oBAAoB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1B,CAAC,CAAiB,CAAC;IACnB,OAAO,OAAO,CAAC;AACjB,CAAC;AA0BD;;;;;;;;;;;;GAYG;AACH,SAAgB,SAAS,CACvB,MAA0B,EAC1B,IAAY,EACZ,WAAmB,EACnB,WAAiB;AACjB,8DAA8D;AAC9D,OAAgC;IAEhC,MAAM,CAAC,YAAY,CACjB,IAAI,EACJ;QACE,WAAW;QACX,WAAW;QACX,KAAK,EAAE,EAAE,CAAC,4BAAoB,CAAC,EAAE,IAAI,EAAE;KACxC,EACD,OAAO,CACR,CAAC;AACJ,CAAC;AAWD;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAC5B,MAAkD,EAClD,IAAY,EACZ,KAAa,EACb,WAAmB,EACnB,WAAiB;AACjB,8DAA8D;AAC9D,OAAgC;IAEhC,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;QACjF,OAAO;IACT,CAAC;IACD,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC"}

package/payload/platform/lib/mcp-eager/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@maxy/mcp-eager",
+  "version": "0.1.0",
+  "private": true,
+  "type": "commonjs",
+  "main": "dist/index.js"
+}

package/payload/platform/lib/mcp-eager/src/index.ts

@@ -21,6 +21,72 @@
 /** Wire-format metadata key the Claude Code SDK reads. */
 export const ALWAYS_LOAD_META_KEY = "anthropic/alwaysLoad" as const;
 
+/**
+ * Admin-seat detection. The rc-daemon exports `MAXY_SESSION_ROLE=admin` and
+ * `MAXY_SPECIALIST=""` for the orchestrator process and its MCP plugin
+ * children; specialist spawns set `MAXY_SPECIALIST=<name>`. A plugin process
+ * inheriting the env can therefore decide at registration AND invocation
+ * time whether it is loaded inside the admin seat.
+ *
+ * Mirrors `isAdminSeat` in platform/plugins/admin/mcp/src/skill-resolution.ts
+ * — this is a duplicate at the library layer so plugins that cannot import
+ * from the admin plugin (a sibling, not a dependency) share the same rule.
+ */
+export function isAdminSeat(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.MAXY_SESSION_ROLE === "admin" && !(env.MAXY_SPECIALIST && env.MAXY_SPECIALIST.length > 0);
+}
+
+/**
+ * MCP refusal envelope returned when the admin seat invokes a specialist-
+ * owned tool. The text names the dispatch route so the model's next action
+ * is the `Agent` dispatch rather than a dead end.
+ */
+export function adminBlockedResponse(toolName: string, owner: string): {
+  content: { type: "text"; text: string }[];
+  isError: true;
+} {
+  return {
+    content: [
+      {
+        type: "text",
+        text:
+          `Tool \`${toolName}\` is owned by the \`${owner}\` specialist and is not callable from the admin seat. ` +
+          `Dispatch \`${owner}\` with the Agent tool and pass the work as the brief.`,
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Wrap a tool handler so any admin-seat invocation short-circuits with the
+ * refusal envelope above and emits one `[admin-tool-gate]` line to stderr.
+ *
+ * Specialist seats pass through unchanged: this is the primitive Task 529
+ * defines for closing the in-message authoring path that Task 516 could
+ * not reach. The handler signature is preserved so existing call sites
+ * substitute `eagerTool(... handler)` for `eagerTool(... withAdminGate(name,
+ * owner, handler))` mechanically.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function withAdminGate<H extends (...args: any[]) => any>(
+  toolName: string,
+  owner: string,
+  handler: H,
+): H {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const wrapped = ((...args: any[]) => {
+    if (isAdminSeat(process.env)) {
+      process.stderr.write(
+        `[admin-tool-gate] role=admin tool=${toolName} decision=block reason=specialist-owned owner=${owner}\n`,
+      );
+      return adminBlockedResponse(toolName, owner);
+    }
+    return handler(...args);
+  }) as unknown as H;
+  return wrapped;
+}
+
 /**
  * Loose structural type for any object exposing a `registerTool` method. The
  * MCP SDK ships dual ESM/CJS packages with conditional exports, so importing
@@ -76,3 +142,38 @@ export function eagerTool<Args extends LocalZodRawShape>(
     handler,
   );
 }
+
+/**
+ * Loose structural type for the legacy four-arg `server.tool(name, desc,
+ * schema, handler)` call shape — used when the admin seat must register a
+ * specialist-owned tool as deferred (not eager) so it does not appear in
+ * the admin's eager tool list.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type DeferredCapableServer = { tool: (name: string, description: string, inputSchema: any, handler: (...args: any[]) => any) => any };
+
+/**
+ * Register a tool that is eager for specialists but deferred + admin-gated
+ * for the admin seat. The owning specialist name is named here so the
+ * refusal envelope (and the `[admin-tool-gate]` log line) carries it.
+ *
+ * Use for every tool whose owner is a specialist (database-operator, writer-
+ * craft, research-assistant, personal-assistant, content-producer). The
+ * admin seat sees the tool only via ToolSearch — and any invocation from the
+ * admin seat refuses with the dispatch hint.
+ */
+export function eagerToolGated<Args extends LocalZodRawShape>(
+  server: EagerCapableServer & DeferredCapableServer,
+  name: string,
+  owner: string,
+  description: string,
+  inputSchema: Args,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  handler: (...args: any[]) => any,
+): void {
+  if (isAdminSeat(process.env)) {
+    server.tool(name, description, inputSchema, withAdminGate(name, owner, handler));
+    return;
+  }
+  eagerTool(server, name, description, inputSchema, handler);
+}

package/payload/platform/plugins/admin/hooks/__tests__/pre-tool-use-admin-tool-gate.test.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Task 529 — admin-tool-gate enforces orchestration-only at the PreToolUse
+# hook. Admin-direct invocations of Write/Edit/MultiEdit/Bash/WebFetch/
+# WebSearch are refused with the dispatch hint; in-window Task subagents
+# (transcript_path matching `*/subagents/agent-*.jsonl`) pass through
+# (Task 222 propagation regression class — subagents must keep their full
+# tool surface). Missing transcript_path is fail-closed (matches Task 222
+# contract).
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/pre-tool-use.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+TMPFILES=()
+cleanup() {
+  for f in "${TMPFILES[@]:-}"; do
+    [[ -n "$f" ]] && rm -f "$f" 2>/dev/null || true
+  done
+}
+trap cleanup EXIT
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "PASS: $1"; }
+fail() { FAIL=$((FAIL+1)); echo "FAIL: $1" >&2; }
+
+ADMIN_TRANSCRIPT="/tmp/sess/admin-3104d4b4.jsonl"
+SUBAGENT_TRANSCRIPT="/tmp/sess/subagents/agent-content-producer-1.jsonl"
+
+run() {
+  local tool="$1" transcript="$2" expected_rc="$3" expected_pattern="$4" label="$5"
+  local input_json
+  if [[ -n "$transcript" ]]; then
+    input_json=$(python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name":"PreToolUse","tool_name":sys.argv[1],"tool_input":{"file_path":"/tmp/x","content":"x"},"transcript_path":sys.argv[2]}, separators=(",", ":")))
+' "$tool" "$transcript")
+  else
+    input_json=$(python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name":"PreToolUse","tool_name":sys.argv[1],"tool_input":{"file_path":"/tmp/x","content":"x"}}, separators=(",", ":")))
+' "$tool")
+  fi
+  local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
+  local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
+  printf '%s' "$input_json" | bash "$HOOK" admin >"$stdout_file" 2>"$stderr_file"
+  local rc=$?
+  if [[ "$rc" -ne "$expected_rc" ]]; then
+    fail "$label: expected exit $expected_rc, got $rc. Stderr: $(cat "$stderr_file")"
+    return
+  fi
+  if [[ -n "$expected_pattern" ]] && ! grep -qE "$expected_pattern" "$stderr_file"; then
+    fail "$label: stderr missing pattern '$expected_pattern'. Got: $(cat "$stderr_file")"
+    return
+  fi
+  pass "$label"
+}
+
+# ── Admin-direct refusals ───────────────────────────────────────────────
+run Write     "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=Write decision=block.*owner=content-producer' \
+  "Test 1: admin-direct Write rejected with content-producer dispatch hint"
+run Edit      "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=Edit decision=block.*owner=content-producer' \
+  "Test 2: admin-direct Edit rejected"
+run MultiEdit "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=MultiEdit decision=block.*owner=content-producer' \
+  "Test 3: admin-direct MultiEdit rejected"
+run Bash      "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=Bash decision=block' \
+  "Test 4: admin-direct Bash rejected"
+run WebFetch  "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=WebFetch decision=block.*owner=research-assistant' \
+  "Test 5: admin-direct WebFetch rejected"
+run WebSearch "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=WebSearch decision=block.*owner=research-assistant' \
+  "Test 6: admin-direct WebSearch rejected"
+
+# ── In-window subagent passthrough (Task 222 regression class) ──────────
+run Write     "$SUBAGENT_TRANSCRIPT" 0 '\[admin-tool-gate\] role=subagent tool=Write decision=allow' \
+  "Test 7: subagent Write passes through"
+run Edit      "$SUBAGENT_TRANSCRIPT" 0 '\[admin-tool-gate\] role=subagent tool=Edit decision=allow' \
+  "Test 8: subagent Edit passes through"
+run Bash      "$SUBAGENT_TRANSCRIPT" 0 '\[admin-tool-gate\] role=subagent tool=Bash decision=allow' \
+  "Test 9: subagent Bash passes through"
+run WebFetch  "$SUBAGENT_TRANSCRIPT" 0 '\[admin-tool-gate\] role=subagent tool=WebFetch decision=allow' \
+  "Test 10: subagent WebFetch passes through"
+
+# ── Missing transcript_path is fail-closed (Task 222 contract) ──────────
+run Write     ""                     2 '\[admin-tool-gate\] role=unknown tool=Write decision=block reason=missing-transcript-path' \
+  "Test 11: missing transcript_path on Write fails closed"
+run Bash      ""                     2 '\[admin-tool-gate\] role=unknown tool=Bash decision=block reason=missing-transcript-path' \
+  "Test 12: missing transcript_path on Bash fails closed"
+
+# ── Unrelated tools untouched ───────────────────────────────────────────
+run Read      "$ADMIN_TRANSCRIPT"    0 '' \
+  "Test 13: admin-direct Read passes (Read is admin-keep-list)"
+
+echo
+echo "──────── pre-tool-use admin-tool-gate test summary ────────"
+echo "PASS: $PASS"
+echo "FAIL: $FAIL"
+
+[[ "$FAIL" -gt 0 ]] && exit 1
+exit 0

package/payload/platform/plugins/admin/hooks/__tests__/pre-tool-use-base64-guard.test.sh

@@ -41,7 +41,7 @@ run_bash() {
   # Build the input JSON via python3 so command_text with quotes / specials is safe.
   input_json=$(python3 -c '
 import json, sys
-print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": sys.argv[1]}}, separators=(",", ":")))
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": sys.argv[1]}, "transcript_path": "/tmp/sess/subagents/agent-x.jsonl"}, separators=(",", ":")))
 ' "$command_text")
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
@@ -64,7 +64,7 @@ run_write() {
   local input_json
   input_json=$(python3 -c '
 import json, sys
-print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "/tmp/test.html", "content": sys.argv[1]}}, separators=(",", ":")))
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "/tmp/test.html", "content": sys.argv[1]}, "transcript_path": "/tmp/sess/subagents/agent-x.jsonl"}, separators=(",", ":")))
 ' "$content")
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
@@ -87,7 +87,7 @@ run_edit() {
   local input_json
   input_json=$(python3 -c '
 import json, sys
-print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "/tmp/test.html", "old_string": "OLD", "new_string": sys.argv[1]}}, separators=(",", ":")))
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "/tmp/test.html", "old_string": "OLD", "new_string": sys.argv[1]}, "transcript_path": "/tmp/sess/subagents/agent-x.jsonl"}, separators=(",", ":")))
 ' "$new_string")
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
@@ -185,7 +185,7 @@ else
 fi
 
 # Pre-existing guards still active — entitlement file edit still rejected.
-ENT_JSON=$(python3 -c 'import json; print(json.dumps({"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"/srv/entitlement.json","content":"{\"tier\":\"max\"}"}}, separators=(",", ":")))')
+ENT_JSON=$(python3 -c 'import json; print(json.dumps({"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"/srv/entitlement.json","content":"{\"tier\":\"max\"}"},"transcript_path":"/tmp/sess/subagents/agent-x.jsonl"}, separators=(",", ":")))')
 STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
 printf '%s' "$ENT_JSON" | bash "$HOOK" admin >"$STDOUT_FILE" 2>"$STDERR_FILE"
 RC=$?

package/payload/platform/plugins/admin/hooks/pre-tool-use.sh

@@ -21,6 +21,62 @@ TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"'
 # ---------------------------------------------------------------------------
 if [ "$AGENT_TYPE" = "admin" ]; then
 
+  # ── Orchestration-only authoring + research block (Task 529) ─────────────
+  # The admin seat is orchestration + clarification + delivery only.
+  # Write/Edit/MultiEdit/Bash/WebFetch/WebSearch are specialist-owned —
+  # content-producer for authoring, research-assistant for research, the
+  # shell tools for whichever specialist owns the workflow that needs them.
+  # In-window Task subagents must keep these tools (Task 222 regression
+  # class) — the discriminator is the transcript_path: Claude Code stores
+  # subagent turns in separate `*/subagents/agent-*.jsonl` files.
+  #
+  # Admin direct → exit 2 with dispatch hint.
+  # Subagent → exit 0 (passthrough).
+  # Missing/malformed transcript_path → fail-closed block (matches Task 222).
+  case "$TOOL_NAME" in
+    Write|Edit|MultiEdit|Bash|WebFetch|WebSearch)
+      TRANSCRIPT_PATH=$(echo "$INPUT" | python3 -c '
+import sys, json
+try:
+    print(json.load(sys.stdin).get("transcript_path", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+      case "$TRANSCRIPT_PATH" in
+        */subagents/agent-*.jsonl)
+          # In-window subagent — passthrough. Tool name resolves on the
+          # subagent's own frontmatter `tools:` allowlist downstream.
+          echo "[admin-tool-gate] role=subagent tool=${TOOL_NAME} decision=allow source=hook-passthrough" >&2
+          ;;
+        "")
+          # Missing transcript_path on a denied native tool — fail closed
+          # rather than guess (Task 222 fail-closed contract).
+          echo "[admin-tool-gate] role=unknown tool=${TOOL_NAME} decision=block reason=missing-transcript-path" >&2
+          echo "Blocked: ${TOOL_NAME} is unavailable from the admin seat and the caller cannot be classified (no transcript_path). Failing closed." >&2
+          exit 2
+          ;;
+        *)
+          # Admin direct invocation — refuse with dispatch hint.
+          case "$TOOL_NAME" in
+            Write|Edit|MultiEdit)
+              OWNER="content-producer"
+              ;;
+            Bash)
+              OWNER="the specialist that owns the workflow needing shell access"
+              ;;
+            WebFetch|WebSearch)
+              OWNER="research-assistant"
+              ;;
+          esac
+          echo "[admin-tool-gate] role=admin tool=${TOOL_NAME} decision=block reason=orchestration-only owner=${OWNER}" >&2
+          echo "Blocked: \`${TOOL_NAME}\` is not callable from the admin seat. The admin seat is orchestration + clarification + delivery only — authoring, shell work, and web research are owned by specialists." >&2
+          echo "Dispatch the work to ${OWNER} via the Agent tool." >&2
+          exit 2
+          ;;
+      esac
+      ;;
+  esac
+
   # ── Code directory protection ────────────────────────────────────────────
   case "$TOOL_NAME" in
     Write|Edit)