@guuey/host 0.7.0 → 0.7.1

package/dist/frameworks/claude-options.d.ts

@@ -96,11 +96,27 @@ export interface BuildOptionsContext {
      */
     authToken?: string;
     /**
-     * Per-session GuueyFS layer mounts (the invoke's `fs`). When present, the
-     * invoke binds `cwd`=session, exposes home+app as `additionalDirectories`,
-     * enables the file tools, and injects `GUUEY_*` env. Absent → no FS binding.
+     * Per-session layer mounts (the invoke's `fs`). When present, the invoke
+     * binds `cwd`=session, exposes home+app as `additionalDirectories`, and
+     * injects the `HOME`/`GUUEY_*`/`CLAUDE_CONFIG_DIR` env. NOTE: the wire
+     * carries a NON-NULL `fs` on every turn (spec §1.4 — the spec-default
+     * `/app`/`/home`/`/session` mounts when GuueyFS is off), so presence here
+     * says nothing about whether durable storage is bound. It is therefore NOT
+     * the tool-catalog gate — {@link fsBound} is (guuey#234).
      */
     fs?: Fs;
+    /**
+     * Whether {@link fs} names REAL GuueyFS layers this turn — the pod has
+     * `GUUEY_FS_BASE` armed and the Router resolved per-session layer dirs under
+     * it — as opposed to the spec-default / federation-ephemeral mounts. THE gate
+     * for the built-in file tools + `Bash` (`tools`, and their `allowedTools`
+     * entries): absent/false → `tools: []`, purely MCP-driven. Threaded from the
+     * runtime on the invoke (`Invoke.fsBound`); mirrors {@link memoryAttached}
+     * (the memory-mcp T5 lesson: gate on the real signal, not on `fs` presence —
+     * which is why the pre-#234 `Boolean(ctx.fs)` gate put Bash in EVERY no-code
+     * agent's catalog on EVERY env).
+     */
+    fsBound?: boolean;
     /** Recent conversation window for the `<conversation_history>` preamble. */
     history?: HistoryMessage[];
     /** Thread-scoped memory for the `<thread_memory>` preamble (the §1.4 push). */
@@ -164,20 +180,34 @@ export interface BuildOptionsContext {
  */
 export declare function buildOptions(snapshot: GuueyAgent, ctx: BuildOptionsContext): Options;
 /**
- * Auto-allow permission callback. Installed when fs is bound and the operator
- * did NOT pin `claude.permissions.mode`, so the default no-code agent's `Bash`
- * (and the file tools) run prompt-free. Returns `{ behavior: 'allow' }` for
+ * Auto-allow permission callback. Installed when the operator did NOT pin
+ * `claude.permissions.mode` and the snapshot has NO explicit `tools.allowlist`,
+ * so the default no-code agent's MCP tools (and, on a GuueyFS-armed pod, its
+ * `Bash` + file tools) run prompt-free. Returns `{ behavior: 'allow' }` for
  * every request, passing the input through unchanged.
  *
  * Safe because the model's tool surface is already locked down BEFORE the
- * callback ever fires — `tools`/`allowedTools` cap which tools exist,
- * `settingSources:[]` blocks filesystem-loaded settings, `strictMcpConfig`
- * pins the MCP catalog — and the real OS isolation is the Router's bubblewrap
- * jail this whole process runs inside. The callback only collapses the SDK's
- * final interactive "ask" stage (which would otherwise hang a headless pod);
- * the earlier hook/deny-rule stages of the permission flow still run.
+ * callback ever fires — `tools`/`allowedTools`/`disallowedTools` cap which
+ * tools exist, `settingSources:[]` blocks filesystem-loaded settings,
+ * `strictMcpConfig` pins the MCP catalog — and the real OS isolation is the
+ * Router's bubblewrap jail this whole process runs inside. The callback only
+ * collapses the SDK's final interactive "ask" stage (which would otherwise
+ * hang a headless pod); the earlier hook/deny-rule stages still run.
  */
 export declare const autoAllowTool: CanUseTool;
+/**
+ * Deny-unlisted permission callback (guuey#234). Installed instead of
+ * {@link autoAllowTool} when the snapshot carries an explicit `tools.allowlist`
+ * (and no pinned mode). Tools that ARE listed never reach any callback — they
+ * are SDK allow rules (`allowedTools`) and are auto-allowed upstream. So every
+ * tool that DOES arrive here is, by construction, one the builder did not
+ * list: it is denied with a message the model can act on. Never `null`, never
+ * an ask — the invariant "an explicit allowlist can never hang the pod".
+ *
+ * `allowedSet` is consulted anyway (belt-and-braces against an SDK that
+ * routes an allow-listed name here after all): a listed name is allowed.
+ */
+export declare function denyUnlistedTool(allowedSet: ReadonlySet<string>): CanUseTool;
 /**
  * Map the Router-resolved cred files to the framework-neutral SdkMcpServer map.
  * The Router (credential-broker) owns ALL resolution — default, federation, mint,
@@ -185,5 +215,37 @@ export declare const autoAllowTool: CanUseTool;
  * (via ctx.listCredentials) and shapes each entry. Keyed by the server name.
  */
 export declare function resolveMcpServers(ctx: BuildOptionsContext): Record<string, SdkMcpServer>;
+/**
+ * The resolved tool surface for one invoke — what `buildOptions` hands the SDK.
+ * Exported for the invariant tests ("an explicit allowlist can never hang").
+ */
+export interface ResolvedToolGates {
+    /** The built-in catalog: `[...FS_TOOLS, Bash]` when fs is bound, else `[]`. */
+    tools: string[];
+    /** SDK allow rules — MCP names in the SDK's `mcp__<server>[__<tool>]` spelling plus the built-ins in `tools`. */
+    allowedTools: string[];
+    /** SDK `disallowedTools` — the translated `tools.denylist` (removed from the catalog). */
+    disallowedTools: string[];
+    /** Whether the snapshot carried a non-empty `tools.allowlist` (→ deny-unlisted posture). */
+    explicitAllowlist: boolean;
+    /** `allowedTools` as a set, for the deny-unlisted callback. */
+    allowedSet: ReadonlySet<string>;
+}
+/**
+ * Resolve the invoke's tool surface (guuey#234). Pure.
+ *
+ * - `tools` (the built-in catalog) is keyed ONLY on `fsBound` — the real
+ *   "GuueyFS layers are bound this turn" signal from the runtime.
+ * - `allowedTools`: an explicit `tools.allowlist` is TRANSLATED from the config
+ *   grammar (`<server>.<tool>` / `<server>.*` / bare) into SDK names — never
+ *   passed verbatim; absent → every tool of every declared server
+ *   (`mcp__<server>`). When fs is bound the built-ins join as allow rules so
+ *   the platform's memory feature (file tools + `Bash` in the jail) is never
+ *   silently switched off by a builder's MCP-only allowlist; a builder who
+ *   wants them gone deny-lists them (`"Bash"`).
+ * - `disallowedTools`: the translated `tools.denylist` — the SDK removes those
+ *   from the model's catalog outright.
+ */
+export declare function resolveToolGates(snapshot: GuueyAgent, declaredServerNames: readonly string[], fsBound: boolean): ResolvedToolGates;
 export { withContextPreamble } from "../preamble.js";
 //# sourceMappingURL=claude-options.d.ts.map

package/dist/frameworks/claude-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-options.d.ts","sourceRoot":"","sources":["../../src/frameworks/claude-options.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude-options.d.ts","sourceRoot":"","sources":["../../src/frameworks/claude-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAY,MAAM,gCAAgC,CAAC;AAChG,OAAO,KAAK,EAAE,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,UAAU,EAAE,CAAC;AAa3B;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAC7C,eAAO,MAAM,WAAW,kBAAkB,CAAC;AA6E3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACpF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,WAAW,GAAG,eAAe,CAAA;KAAE,CAAC;IACtE;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,EAAE,CAAC,EAAE,EAAE,CAAC;IACR;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,mEAAmE;IACnE,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;iEAC6D;IAC7D,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC;;;;;OAKG;IACH,eAAe,EAAE,MAAM,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IACrE,iEAAiE;IACjE,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAiLpF;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,EAAE,UACiC,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,UAAU,CAU5E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAgBxF;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,iHAAiH;IACjH,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0FAA0F;IAC1F,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,4FAA4F;IAC5F,iBAAiB,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC;AAmCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,mBAAmB,EAAE,SAAS,MAAM,EAAE,EACtC,OAAO,EAAE,OAAO,GACf,iBAAiB,CAkBnB;AAUD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/frameworks/claude-options.js

@@ -1,4 +1,4 @@
-import { GUUEY_DEFAULT_SYSTEM_PROMPT, defaultModelFor, } from "@guuey/config";
+import { GUUEY_DEFAULT_SYSTEM_PROMPT, defaultModelFor, parseToolGateEntry, } from "@guuey/config";
 /**
  * Default Claude model — only used when the snapshot omits `model`. Derived
  * from the `@guuey/config` registry (single source of truth per the
@@ -20,8 +20,9 @@ const DEFAULT_MAX_TURNS = 25;
 export const ENV_HOME_DIR = "GUUEY_HOME_DIR";
 export const ENV_APP_DIR = "GUUEY_APP_DIR";
 /**
- * File tools enabled when GuueyFS layers are bound. `Bash` is added separately
- * (see {@link BASH_TOOL}) so the two are independently testable.
+ * File tools enabled when GuueyFS layers are bound
+ * ({@link BuildOptionsContext.fsBound}). `Bash` is added separately (see
+ * {@link BASH_TOOL}) so the two are independently testable.
  */
 const FS_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep"];
 /**
@@ -33,6 +34,12 @@ const FS_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep"];
  * bubblewrap inside the Router's bwrap); the Router's bwrap IS the isolation.
  */
 const BASH_TOOL = "Bash";
+/**
+ * The built-in tool catalog this host can expose — exactly the file tools plus
+ * `Bash`, all keyed on {@link BuildOptionsContext.fsBound}. A bare tool-gate
+ * entry (`"Bash"`, `"Write"`) matches one of these by name.
+ */
+const BUILTIN_TOOLS = [...FS_TOOLS, BASH_TOOL];
 /**
  * Belt-and-braces (spec §4): guuey's memory mechanism is prompted file memory
  * (a platform-owned system-prompt section, below), never the SDK's own
@@ -105,7 +112,8 @@ export function buildOptions(snapshot, ctx) {
         throw new Error(`@guuey/host: snapshot.systemPrompt must be a resolved string (got ${JSON.stringify(snapshot.systemPrompt)}). The CLI inlines {file} references before upload; workers never read the filesystem.`);
     }
     const mcpServers = resolveMcpServers(ctx);
-    const allowedTools = buildAllowedTools(snapshot, Object.keys(mcpServers), Boolean(ctx.fs));
+    const fsBound = ctx.fsBound === true;
+    const gates = resolveToolGates(snapshot, Object.keys(mcpServers), fsBound);
     const systemPrompt = withContextPreamble(snapshot.systemPrompt ?? GUUEY_DEFAULT_SYSTEM_PROMPT, ctx.history, ctx.priorMemory, ctx.priorState) +
         buildMemorySection(ctx) +
         // cross-app-profile T7: the profile section is a SIBLING of the memory
@@ -175,13 +183,17 @@ export function buildOptions(snapshot, ctx) {
     }
     // Whether the operator pinned a Claude permission mode in agent.json. When
     // set we forward it verbatim and let the SDK's mode govern the posture; when
-    // unset we install the auto-allow `canUseTool` below so the default no-code
-    // agent's Bash runs prompt-free (a never-answered prompt would hang the pod).
+    // unset we ALWAYS install a `canUseTool` below (guuey#234) so no tool pick can
+    // ever reach the SDK's interactive ask stage — a never-answered prompt would
+    // hang this headless pod.
     const explicitMode = snapshot.claude?.permissions?.mode;
     const options = {
         model,
         mcpServers,
-        allowedTools,
+        allowedTools: gates.allowedTools,
+        // Deny-listed tools (`tools.denylist`, translated) are removed from the
+        // model's catalog outright — the SDK's own mechanism, not a callback.
+        ...(gates.disallowedTools.length > 0 ? { disallowedTools: gates.disallowedTools } : {}),
         // Token streaming (guuey#91 consumer half): the SDK interleaves
         // `stream_event` partials, which `@silverprotocol/claude-agent-sdk` ≥0.4
         // maps to token-granular text/reasoning/tool.args deltas and dedupes
@@ -191,11 +203,12 @@ export function buildOptions(snapshot, ctx) {
         // idempotent by tool_use id), so this flag's only observable effect is
         // incremental frames on the SSE wire.
         includePartialMessages: true,
-        // With GuueyFS layers bound, expose the file tools PLUS real `Bash`; without
-        // them this is byte-identical to the source (purely MCP-driven). `Bash` is
-        // safe here because the host already runs inside the Router's bubblewrap
-        // jail — that bwrap, NOT the SDK's own `sandbox:{}` block, is the isolation.
-        tools: fs ? [...FS_TOOLS, BASH_TOOL] : [],
+        // With GuueyFS layers REALLY bound (`fsBound`, guuey#234 — never `fs`
+        // presence, which is unconditional on the wire), expose the file tools PLUS
+        // real `Bash`; otherwise purely MCP-driven. `Bash` is safe here because the
+        // host already runs inside the Router's bubblewrap jail — that bwrap, NOT
+        // the SDK's own `sandbox:{}` block, is the isolation.
+        tools: gates.tools,
         // Settings isolation. Empty array = "no filesystem settings loaded" — guards
         // against a future SDK change auto-pulling `~/.claude/settings.json` and
         // leaking the operator's logged-in Claude Code MCPs into the tool catalog.
@@ -217,44 +230,68 @@ export function buildOptions(snapshot, ctx) {
         //
         //  - Operator pinned `claude.permissions.mode` → forward it verbatim; the
         //    operator owns the posture (e.g. `acceptEdits`).
-        //  - No explicit mode + fs bound → install an auto-allow `canUseTool`. In
-        //    the SDK permission flow (hooks → deny → allow → ask → mode/canUseTool),
-        //    `default` mode with no callback routes Bash subcommands through an
-        //    interactive permission prompt — which, in this headless ephemeral pod,
-        //    no one answers, so the agent would HANG. The auto-allow callback short-
-        //    circuits that: every tool the model picks (already constrained to
-        //    `tools`/`allowedTools` + `settingSources:[]` + `strictMcpConfig`) is
-        //    allowed without a prompt. This is safe precisely because the Router's
-        //    bubblewrap jail is the real isolation boundary — NOT the SDK's own
-        //    `sandbox:{}` block (which is intentionally absent to avoid a nested
-        //    bwrap inside the Router's bwrap). We do NOT use `bypassPermissions`
-        //    here: it requires `allowDangerouslySkipPermissions` and globally
-        //    disables hooks/deny-rule evaluation, whereas the callback keeps the
-        //    deny/hook stages intact while only collapsing the final ask stage.
+        //  - No explicit mode → ALWAYS install a `canUseTool` (guuey#234: it used
+        //    to be installed only when fs was "bound", which was every turn — once
+        //    the gate is real, an fs-off pod with an explicit allowlist would sit
+        //    in `default` mode). In the SDK permission flow (hooks → deny → allow →
+        //    ask → mode/canUseTool), `default` mode with no callback routes any
+        //    tool not covered by an allow rule through an interactive permission
+        //    prompt — which, in this headless ephemeral pod, no one answers, so
+        //    the agent would HANG. The callback short-circuits that stage: with no
+        //    explicit allowlist every pick is allowed (the tool surface is already
+        //    capped by `tools`/`allowedTools` + `settingSources:[]` +
+        //    `strictMcpConfig`, and the Router's bubblewrap jail is the real
+        //    isolation boundary — NOT the SDK's own `sandbox:{}` block, which is
+        //    intentionally absent to avoid a nested bwrap); with an explicit
+        //    allowlist an UNLISTED pick is DENIED with a message the model can read
+        //    — that is what makes the allowlist a real narrowing, and it can never
+        //    hang. We do NOT use `bypassPermissions`: it requires
+        //    `allowDangerouslySkipPermissions` and globally disables hooks/deny-rule
+        //    evaluation, whereas the callback keeps those stages intact while only
+        //    collapsing the final ask stage.
         ...(explicitMode
             ? { permissionMode: explicitMode }
-            : fs
-                ? { canUseTool: autoAllowTool }
-                : {}),
+            : { canUseTool: gates.explicitAllowlist ? denyUnlistedTool(gates.allowedSet) : autoAllowTool }),
         ...(ctx.abortController ? { abortController: ctx.abortController } : {}),
     };
     return options;
 }
 /**
- * Auto-allow permission callback. Installed when fs is bound and the operator
- * did NOT pin `claude.permissions.mode`, so the default no-code agent's `Bash`
- * (and the file tools) run prompt-free. Returns `{ behavior: 'allow' }` for
+ * Auto-allow permission callback. Installed when the operator did NOT pin
+ * `claude.permissions.mode` and the snapshot has NO explicit `tools.allowlist`,
+ * so the default no-code agent's MCP tools (and, on a GuueyFS-armed pod, its
+ * `Bash` + file tools) run prompt-free. Returns `{ behavior: 'allow' }` for
  * every request, passing the input through unchanged.
  *
  * Safe because the model's tool surface is already locked down BEFORE the
- * callback ever fires — `tools`/`allowedTools` cap which tools exist,
- * `settingSources:[]` blocks filesystem-loaded settings, `strictMcpConfig`
- * pins the MCP catalog — and the real OS isolation is the Router's bubblewrap
- * jail this whole process runs inside. The callback only collapses the SDK's
- * final interactive "ask" stage (which would otherwise hang a headless pod);
- * the earlier hook/deny-rule stages of the permission flow still run.
+ * callback ever fires — `tools`/`allowedTools`/`disallowedTools` cap which
+ * tools exist, `settingSources:[]` blocks filesystem-loaded settings,
+ * `strictMcpConfig` pins the MCP catalog — and the real OS isolation is the
+ * Router's bubblewrap jail this whole process runs inside. The callback only
+ * collapses the SDK's final interactive "ask" stage (which would otherwise
+ * hang a headless pod); the earlier hook/deny-rule stages still run.
  */
 export const autoAllowTool = (_toolName, input) => Promise.resolve({ behavior: "allow", updatedInput: input });
+/**
+ * Deny-unlisted permission callback (guuey#234). Installed instead of
+ * {@link autoAllowTool} when the snapshot carries an explicit `tools.allowlist`
+ * (and no pinned mode). Tools that ARE listed never reach any callback — they
+ * are SDK allow rules (`allowedTools`) and are auto-allowed upstream. So every
+ * tool that DOES arrive here is, by construction, one the builder did not
+ * list: it is denied with a message the model can act on. Never `null`, never
+ * an ask — the invariant "an explicit allowlist can never hang the pod".
+ *
+ * `allowedSet` is consulted anyway (belt-and-braces against an SDK that
+ * routes an allow-listed name here after all): a listed name is allowed.
+ */
+export function denyUnlistedTool(allowedSet) {
+    return (toolName, input) => Promise.resolve(allowedSet.has(toolName)
+        ? { behavior: "allow", updatedInput: input }
+        : {
+            behavior: "deny",
+            message: `Tool "${toolName}" is not in this agent's tools.allowlist. Allowed: ${[...allowedSet].join(", ") || "(none)"}.`,
+        });
+}
 /**
  * Map the Router-resolved cred files to the framework-neutral SdkMcpServer map.
  * The Router (credential-broker) owns ALL resolution — default, federation, mint,
@@ -279,24 +316,68 @@ export function resolveMcpServers(ctx) {
     return out;
 }
 /**
- * Build the SDK's `allowedTools` array. MCP tools are auto-namespaced by the SDK
- * as `mcp__<server>__<tool>`; we can't enumerate the namespaces ahead of time,
- * so the allowlist is necessarily wildcard-ish.
- *
- * - explicit `tools.allowlist` → pass those literal names through.
- * - else → allow every tool from every declared server via `mcp__<server>`.
+ * Translate one parsed tool-gate entry (the `@guuey/config` grammar) into the
+ * SDK's tool-name spelling(s). MCP tools are auto-namespaced by the SDK as
+ * `mcp__<server>__<tool>`, and `mcp__<server>` is the SDK's own "every tool of
+ * that server" rule. A bare name fans out to EVERY declared server (we cannot
+ * enumerate a server's tools ahead of connecting) and, when it names one of the
+ * host's built-ins, to that built-in — but only while fs is bound, since an
+ * unbound turn has no built-in catalog for it to match.
+ */
+function toSdkToolNames(raw, declaredServerNames, fsBound) {
+    const parsed = parseToolGateEntry(raw);
+    // Deploy-time validation (`validateToolGates`) rejects malformed entries
+    // before a snapshot ever ships; a stale snapshot that slips one through is
+    // dropped here (NOT passed verbatim — an unknown allow rule is inert, and an
+    // unknown name reaching the ask stage is the hang this fix exists to close).
+    if ("error" in parsed)
+        return [];
+    switch (parsed.kind) {
+        case "server-tool":
+            return [`mcp__${parsed.server}__${parsed.tool}`];
+        case "server-all":
+            return [`mcp__${parsed.server}`];
+        case "bare":
+            return [
+                ...declaredServerNames.map((s) => `mcp__${s}__${parsed.tool}`),
+                ...(fsBound && BUILTIN_TOOLS.includes(parsed.tool) ? [parsed.tool] : []),
+            ];
+    }
+}
+/**
+ * Resolve the invoke's tool surface (guuey#234). Pure.
  *
- * When GuueyFS layers are bound, the file tools AND `Bash` join the allowlist
- * (an allow rule in the SDK permission flow), so the model may use them
- * alongside the MCP allowlist. The auto-allow `canUseTool` (or the operator's
- * pinned mode) governs whether those still prompt — see `buildOptions`.
+ * - `tools` (the built-in catalog) is keyed ONLY on `fsBound` — the real
+ *   "GuueyFS layers are bound this turn" signal from the runtime.
+ * - `allowedTools`: an explicit `tools.allowlist` is TRANSLATED from the config
+ *   grammar (`<server>.<tool>` / `<server>.*` / bare) into SDK names — never
+ *   passed verbatim; absent → every tool of every declared server
+ *   (`mcp__<server>`). When fs is bound the built-ins join as allow rules so
+ *   the platform's memory feature (file tools + `Bash` in the jail) is never
+ *   silently switched off by a builder's MCP-only allowlist; a builder who
+ *   wants them gone deny-lists them (`"Bash"`).
+ * - `disallowedTools`: the translated `tools.denylist` — the SDK removes those
+ *   from the model's catalog outright.
  */
-function buildAllowedTools(snapshot, declaredServerNames, fsBound) {
-    const explicit = snapshot.tools?.allowlist;
-    const base = explicit && explicit.length > 0
-        ? explicit.slice()
+export function resolveToolGates(snapshot, declaredServerNames, fsBound) {
+    const explicit = snapshot.tools?.allowlist ?? [];
+    const explicitAllowlist = explicit.length > 0;
+    const builtins = fsBound ? [...BUILTIN_TOOLS] : [];
+    const mcpAllowed = explicitAllowlist
+        ? explicit.flatMap((e) => toSdkToolNames(e, declaredServerNames, fsBound))
         : declaredServerNames.map((s) => `mcp__${s}`);
-    return fsBound ? [...base, ...FS_TOOLS, BASH_TOOL] : base;
+    const allowedTools = dedupe([...mcpAllowed, ...builtins]);
+    const disallowedTools = dedupe((snapshot.tools?.denylist ?? []).flatMap((e) => toSdkToolNames(e, declaredServerNames, fsBound)));
+    return {
+        tools: builtins,
+        allowedTools,
+        disallowedTools,
+        explicitAllowlist,
+        allowedSet: new Set(allowedTools),
+    };
+}
+function dedupe(names) {
+    return [...new Set(names)];
 }
 // withContextPreamble now lives in ../preamble.js (framework-neutral — the
 // ADK runner renders the same preamble); re-exported for existing importers.

package/dist/frameworks/claude.d.ts

@@ -23,6 +23,12 @@ export interface HostInvoke {
     input: string;
     identity: Identity;
     fs: Fs;
+    /**
+     * Whether `fs` names REAL GuueyFS layers this turn (guuey#234) — the gate
+     * for the built-in file tools + `Bash`. See `Invoke.fsBound` in
+     * `@guuey/worker`. Absent/false → purely MCP-driven.
+     */
+    fsBound?: boolean;
     history: HistoryMessage[];
     priorMemory?: PriorMemoryRecord[];
     priorState?: JsonValue;

package/dist/frameworks/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/frameworks/claude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,KAAK,EACV,cAAc,EACd,OAAO,EACP,EAAE,EACF,cAAc,EACd,QAAQ,EACR,SAAS,EACT,cAAc,EAEf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EAEZ,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAQ7B;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,EAAE,EAAE,EAAE,CAAC;IACP,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IACtC;gEAC4D;IAC5D,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,EAAE,MAAM,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,8EAA8E;AAC9E,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,KAAK,aAAa,CAAC,UAAU,CAAC,CAAC;AA0BhC;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EACrE,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAoDf"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/frameworks/claude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,KAAK,EACV,cAAc,EACd,OAAO,EACP,EAAE,EACF,cAAc,EACd,QAAQ,EACR,SAAS,EACT,cAAc,EAEf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EAEZ,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAQ7B;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,EAAE,EAAE,EAAE,CAAC;IACP;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IACtC;gEAC4D;IAC5D,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,EAAE,MAAM,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,8EAA8E;AAC9E,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,KAAK,aAAa,CAAC,UAAU,CAAC,CAAC;AA0BhC;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EACrE,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAqDf"}

package/dist/frameworks/claude.js

@@ -42,6 +42,7 @@ export async function runInvoke(snapshot, invoke, runtime, emit, query) {
             input: invoke.input,
             identity: invoke.identity,
             fs: invoke.fs,
+            ...(invoke.fsBound !== undefined ? { fsBound: invoke.fsBound } : {}),
             history: invoke.history,
             listCredentials: runtime.listCredentials,
             ...(runtime.apiKey !== undefined ? { apiKey: runtime.apiKey } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/host",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "The universal config-driven Guuey worker. Reads the resolved agent.json snapshot, runs the Claude Agent SDK, and emits each native SDKMessage to fd-3 as a `native` WorkerEvent.",
   "license": "MIT",
   "type": "module",
@@ -22,8 +22,8 @@
     }
   },
   "dependencies": {
-    "@guuey/worker": "0.7.0",
-    "@guuey/config": "0.7.0"
+    "@guuey/worker": "0.7.1",
+    "@guuey/config": "0.7.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",