@luckydraw/cumulus 1.0.3 → 1.0.4

package/dist/lib/tool-inventory.js

@@ -0,0 +1,309 @@
+/**
+ * Tool inventory + allowlist compilation (task 137).
+ *
+ * WHY THIS EXISTS
+ * A thread that should only be able to do a few things (a public web-app visitor
+ * panel) previously had to be configured with a DENYLIST — @cdda hand-enumerated 47
+ * tool names to get a safe surface. That inverts maintenance onto every app author:
+ * any tool cumulus or the Claude CLI adds in a future release is silently granted to
+ * every visitor on every deployed app until each author notices and edits their list.
+ *
+ * The fix is an allowlist. But `--allowedTools` on the Claude CLI is an AUTO-APPROVE
+ * list, not a restriction — measured under three permission modes, `--allowedTools Glob`
+ * failed to block Bash every time, and cumulus spawns with `--permission-mode
+ * bypassPermissions` where an auto-approve list is a guaranteed no-op. `--disallowedTools`
+ * DOES restrict there (also measured). So an allowlist has to be COMPILED into a denylist:
+ *
+ *     denylist = (everything that exists) − (what this thread may use)
+ *
+ * which is why this module has to know the full inventory.
+ *
+ * WHERE THE INVENTORY COMES FROM (three sources, because no single one is complete)
+ *  1. Built-in CLI tools — read from the `system:init` stream event, which carries the
+ *     CLI's own `tools[]`. Probed once per process (see probeBuiltinTools).
+ *  2. cumulus's own MCP tools — derived from the definitions cumulus itself ships.
+ *  3. Namespace `extraMcpServers` — NOT knowable here, and deliberately not closed over.
+ *     Those are the app author's own shim tools, granted to that namespace on purpose.
+ *
+ * The seed list is a FLOOR, not merely a fallback: the inventory is always the union of
+ * the probe and the seed, so a probe that returns a short list (different cwd, different
+ * plugin set, a future CLI that changes the event shape) can never quietly widen what a
+ * constrained thread is allowed to reach.
+ */
+import { spawn } from 'child_process';
+import * as os from 'os';
+import { getToolDefinitions } from '../mcp/tool-handler.js';
+/**
+ * Built-in Claude CLI tools, as reported by `system:init` on CLI 2.1.217.
+ *
+ * This is a FLOOR for the inventory, not a fallback — see the module comment. Adding a
+ * name here can only ever deny more on an allowlisted thread; it has no effect on a
+ * thread without `allowedTools`. Safe to update from a probe of a newer CLI.
+ */
+export const SEED_BUILTIN_TOOLS = [
+    'Bash',
+    'CronCreate',
+    'CronDelete',
+    'CronList',
+    'DesignSync',
+    'Edit',
+    'EnterWorktree',
+    'ExitWorktree',
+    'Monitor',
+    'NotebookEdit',
+    'PushNotification',
+    'Read',
+    'RemoteTrigger',
+    'ReportFindings',
+    'ScheduleWakeup',
+    'SendMessage',
+    'Skill',
+    'Task',
+    'TaskCreate',
+    'TaskGet',
+    'TaskList',
+    'TaskOutput',
+    'TaskStop',
+    'TaskUpdate',
+    'ToolSearch',
+    'WebFetch',
+    'WebSearch',
+    'Workflow',
+    'Write',
+];
+/**
+ * Tools served by the `gateway-agents` MCP server.
+ *
+ * Duplicated here rather than imported because `gateway-agents-mcp.ts` calls `main()`
+ * at top level — it is a stdio binary, and importing it would start a server. A source
+ * tripwire test asserts this list matches the tool definitions in that file, so the two
+ * cannot drift (same shape as task 132's artifact tripwire).
+ *
+ * `broadcast` is absent on purpose: it is deliberately not served (task 135).
+ */
+export const GATEWAY_AGENTS_TOOL_NAMES = [
+    'cancel_schedule',
+    'create_plastic_app',
+    'list_agents',
+    'list_emails',
+    'list_schedules',
+    'notify_user',
+    'schedule_trigger',
+    'send_email',
+    'send_to_agent',
+    'update_pipeline',
+    'upload_media',
+];
+/** MCP server keys cumulus attaches itself (see generateMcpConfig). */
+const CUMULUS_HISTORY_SERVER = 'cumulus-history';
+const GATEWAY_AGENTS_SERVER = 'gateway-agents';
+/** How long to wait for the CLI to emit its init event before giving up on the probe. */
+const PROBE_TIMEOUT_MS = 15_000;
+/** Fully-qualified names of the MCP tools cumulus ships itself. */
+export function cumulusMcpToolNames() {
+    const history = getToolDefinitions().map(t => `mcp__${CUMULUS_HISTORY_SERVER}__${t.name}`);
+    const agents = GATEWAY_AGENTS_TOOL_NAMES.map(n => `mcp__${GATEWAY_AGENTS_SERVER}__${n}`);
+    return [...history, ...agents];
+}
+/**
+ * Ask the Claude CLI what built-in tools it has, by reading the `tools[]` array off its
+ * `system:init` stream event and killing the subprocess immediately.
+ *
+ * Measured cost: init arrives ~871ms in and is the ONLY event before the kill — no
+ * assistant output, no result event, so nothing comes back from the model. A prompt is
+ * required: with stdin closed the CLI exits before emitting init (0 lines), and merely
+ * holding stdin open emits nothing at all (20s). Hence the one-character `x`.
+ *
+ * Runs in a neutral cwd so a project's own settings cannot shape the answer, and the
+ * result is unioned with the seed floor by the caller either way.
+ *
+ * Rejects on timeout, spawn failure, or a missing/empty `tools[]`. Never throws
+ * synchronously; the caller treats any rejection as "use the floor".
+ *
+ * `claudePath` is supplied by the caller, which already has it resolved. Taking it as a
+ * parameter rather than importing `resolveClaudeCli` avoids a module cycle: that function
+ * lives in gateway.ts, which imports this module.
+ */
+export function probeBuiltinTools(claudePath) {
+    return new Promise((resolve, reject) => {
+        const bin = claudePath || 'claude';
+        // Same env hygiene as the real spawn: CLAUDE* vars would leak the parent session.
+        const cleanEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('CLAUDE') && key !== 'CLAUDECODE'));
+        let child;
+        try {
+            child = spawn(bin, [
+                '--print',
+                '--output-format',
+                'stream-json',
+                '--verbose',
+                '--permission-mode',
+                'bypassPermissions',
+                'x',
+            ], { stdio: ['ignore', 'pipe', 'ignore'], cwd: os.tmpdir(), env: cleanEnv });
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        let settled = false;
+        let buf = '';
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+            fn();
+        };
+        const timer = setTimeout(() => finish(() => reject(new Error('tool inventory probe timed out'))), PROBE_TIMEOUT_MS);
+        // Don't hold the event loop open on a probe nobody is waiting for.
+        timer.unref?.();
+        child.stdout?.on('data', (chunk) => {
+            buf += chunk.toString();
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.type !== 'system' || parsed.subtype !== 'init')
+                    continue;
+                const tools = Array.isArray(parsed.tools)
+                    ? parsed.tools.filter((t) => typeof t === 'string')
+                    : [];
+                if (tools.length === 0) {
+                    finish(() => reject(new Error('init event carried no tools')));
+                    return;
+                }
+                finish(() => resolve(tools));
+                return;
+            }
+        });
+        child.on('error', err => finish(() => reject(err)));
+        // 'close', not 'exit': close fires after stdio has drained, so a CLI that prints init
+        // and exits immediately still resolves. On 'exit' the reject could win the race.
+        child.on('close', () => finish(() => reject(new Error('CLI exited before emitting init'))));
+    });
+}
+/** Memoized so the probe runs at most once per gateway process. */
+let inventoryPromise = null;
+/**
+ * The full set of tool names a spawned turn could otherwise reach.
+ *
+ * Deliberately NOT threaded through `MessagePipelineOptions`: task 113 is the recorded
+ * case of a field added to one of four spawn paths and silently doing nothing in the
+ * other three, and here a miss would fail OPEN. Module-scope memoization means the single
+ * args-assembly site is the only consumer and it cannot be half-wired.
+ */
+export function getToolInventory(claudePath) {
+    if (!inventoryPromise) {
+        inventoryPromise = probeBuiltinTools(claudePath)
+            .catch(err => {
+            console.warn(`[Gateway] Tool inventory probe failed (${err instanceof Error ? err.message : err}); ` +
+                'using the seed floor. Allowlisted threads stay closed.');
+            return [];
+        })
+            .then(probed => {
+            const all = new Set([...SEED_BUILTIN_TOOLS, ...probed, ...cumulusMcpToolNames()]);
+            return [...all].sort();
+        });
+    }
+    return inventoryPromise;
+}
+/** Test seam: drop the memo so a suite can probe with a stub. */
+export function resetToolInventoryCache() {
+    inventoryPromise = null;
+}
+/** The bare tool name of an `mcp__server__tool` entry, or the name itself. */
+export function bareToolName(name) {
+    if (!name.startsWith('mcp__'))
+        return name;
+    const parts = name.split('__');
+    return parts.length > 2 ? parts.slice(2).join('__') : name;
+}
+/**
+ * Compile an allowlist into the denylist the CLI actually honours.
+ *
+ * Returns `existingDisallowed` UNCHANGED when no allowlist is configured — additive, so
+ * every thread that does not opt in behaves exactly as before.
+ *
+ * An allowlist entry matches an inventory entry exactly, or as its bare name, so
+ * `read_file` allows `mcp__cumulus-history__read_file` (the system prompt calls it
+ * `read_file`; a user should not have to know the prefix). An entry that matches nothing
+ * is inert — and inertness DENIES, so a typo fails closed.
+ *
+ * `disallowedTools` still applies on top: it can subtract from an allowlist but never add.
+ */
+export function compileDisallowedTools(allowedTools, inventory, existingDisallowed) {
+    if (!allowedTools)
+        return existingDisallowed;
+    const allowed = new Set(allowedTools);
+    const denied = new Set(existingDisallowed ?? []);
+    for (const name of inventory) {
+        if (allowed.has(name) || allowed.has(bareToolName(name)))
+            continue;
+        denied.add(name);
+    }
+    return denied.size ? [...denied].sort() : undefined;
+}
+/**
+ * Is `name` (a bare tool name) reachable on this thread?
+ *
+ * Deliberately inventory-INDEPENDENT: it reads the thread's stated intent, so it gives the
+ * same answer on the Claude CLI path and the direct-provider path, whose real inventories
+ * differ. Available iff the allowlist admits it (or there is no allowlist) and the denylist
+ * does not name it.
+ */
+export function toolAvailable(name, policy) {
+    const denied = (policy.disallowedTools ?? []).some(d => d === name || bareToolName(d) === name);
+    if (denied)
+        return false;
+    if (!policy.allowedTools)
+        return true;
+    return policy.allowedTools.some(a => a === name || bareToolName(a) === name);
+}
+export function promptCapabilities(policy) {
+    return {
+        backgroundWork: toolAvailable('Bash', policy),
+        scheduling: toolAvailable('schedule_trigger', policy),
+        interAgent: toolAvailable('send_to_agent', policy),
+    };
+}
+/** Section header prefixes, keyed by the capability that keeps them. */
+const GATED_SECTIONS = [
+    ['backgroundWork', 'BACKGROUND WORK:'],
+    ['scheduling', 'SCHEDULING'],
+    ['interAgent', 'INTER-AGENT MESSAGING:'],
+];
+/**
+ * Remove prompt sections whose tools this thread cannot reach.
+ *
+ * Sections in SYSTEM_PROMPT_TEMPLATE are blank-line-delimited blocks whose first line is a
+ * header, so this is a split/filter/join — lossless when nothing is gated (regression-locked),
+ * and a no-op on a custom template that has no such headers.
+ *
+ * Only ever REMOVES text, so an unconstrained thread's prompt is byte-identical and the task
+ * 117 static-prompt budget cannot be breached by this function.
+ */
+export function applyCapabilityGates(template, caps) {
+    const dropPrefixes = GATED_SECTIONS.filter(([cap]) => !caps[cap]).map(([, prefix]) => prefix);
+    if (dropPrefixes.length === 0)
+        return template;
+    return template
+        .split('\n\n')
+        .filter(block => !dropPrefixes.some(prefix => block.startsWith(prefix)))
+        .join('\n\n');
+}
+//# sourceMappingURL=tool-inventory.js.map

package/dist/lib/tool-inventory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-inventory.js","sourceRoot":"","sources":["../../src/lib/tool-inventory.ts"],"names":[],"mappings":"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"}

package/docs/web-app-agent-guide.md

@@ -152,6 +152,7 @@ myapp.config.json              (only if the -v file is absent)
   "claudeModel": "claude-haiku-4-5",
   "effort": "medium",
   "alwaysInclude": ["docs/myapp-system-prompt.md"],
+  "allowedTools": ["Read", "read_file", "search_content", "retrieve_content", "search_history"],
   "disallowedTools": ["AskUserQuestion"]
 }
 ```
@@ -159,7 +160,33 @@ myapp.config.json              (only if the -v file is absent)
 - `projectDir` — the working directory for the agent's turns (where `alwaysInclude` paths resolve).
 - `alwaysInclude` — the app's **system prompt document**: what the app is, how to talk to its users, when to use which commands, tone. This is where the agent's product knowledge and persona live. Usually the same document for both threads.
 - `model` / `effort` / `claudeModel` — the per-thread quality, latency and cost dial. `claudeModel` pins the specific Claude model; leave it out to follow the gateway default.
-- `disallowedTools` — on visitor threads, strip `AskUserQuestion`: there is no operator on the other end, so a turn that asks one hangs.
+- `allowedTools` — **the only tools a visitor turn may use.** See below; this is the most important line in the visitor file.
+- `disallowedTools` — applied on top of the allowlist, and it can only subtract. Keep `AskUserQuestion` here: there is no operator on the other end of a visitor turn, so a question hangs.
+
+#### `allowedTools` is deny-by-default, and that is the whole point
+
+Omit it and the thread is unrestricted — it gets the same harness as your maintainer
+thread, including shell, file writes, sub-agent spawning, and the ability to message your
+other threads. Set it and **everything not named is refused, including tools a future
+cumulus or Claude CLI release adds.**
+
+That last clause is why an allowlist rather than a denylist. With a denylist, every newly
+shipped tool is silently granted to every visitor of every deployed app until each author
+notices and edits their list. One real app on this gateway needed **47 deny entries** to
+reach a safe surface; the allowlist above is five.
+
+Your app's **own MCP shim tools are not affected** — cumulus does not know their names, so
+it cannot deny them. They stay available, which is what you want: they are the tools you
+deliberately gave this namespace. The allowlist governs cumulus's and the CLI's tools.
+
+Entries may be bare (`read_file`) or fully qualified (`mcp__cumulus-history__read_file`).
+An entry that matches nothing is **inert, and inertness denies** — a typo fails closed, so
+check the journal after a deploy rather than assuming silence means success.
+
+Setting `allowedTools` also, deliberately, shrinks the system prompt: sections describing
+tools the thread cannot reach (background work, scheduling, inter-agent messaging) are
+dropped from that thread's prompt. Dead instructions are worse than absent ones — they cost
+tokens every turn and invite the model to improvise a substitute for a tool it cannot call.
 
 Both files ship as editable examples in the kit (`thread-config.example.json`, `thread-config.visitor.example.json`), with a one-command applier:
 
@@ -168,7 +195,7 @@ GATEWAY_ORIGIN=https://gw.example.com GATEWAY_ADMIN_KEY=sk-... \
   node agent/apply-thread-configs.mjs --namespace myapp
 ```
 
-Use the **admin** key: a namespace covers `myapp-*`, so the app's scoped key can write `myapp-v` but is refused (403) on the bare `myapp` base thread. Note that the config API applies a whitelist — `projectDir`, `template`, `model`, `effort`, `claudeModel`, `contextLimit` — so `alwaysInclude` and `disallowedTools` must be added to the file on the gateway host. (That is deliberate: `alwaysInclude` plus `projectDir` would let a scoped key read an arbitrary file into its own prompt.) The applier reads each config back and names anything that did not stick, so the gap is visible rather than silent.
+Use the **admin** key: a namespace covers `myapp-*`, so the app's scoped key can write `myapp-v` but is refused (403) on the bare `myapp` base thread. Note that the config API applies a whitelist — `projectDir`, `template`, `model`, `effort`, `claudeModel`, `contextLimit` — so `alwaysInclude`, `allowedTools` and `disallowedTools` must be added to the file on the gateway host. That is deliberate in each case: `alwaysInclude` plus `projectDir` would let a scoped key read an arbitrary file into its own prompt, and `allowedTools` is writable in the _widening_ direction, so a scoped key could relax its own restrictions. The applier reads each config back and names anything that did not stick, so the gap is visible rather than silent.
 
 No gateway reload is needed — thread config is read per turn.
 
@@ -538,7 +565,51 @@ Per the global standards: every interactive element gets a `data-testid` (`agent
 
 ### 5.4 What else the agent can do
 
-Every gateway thread also gets cumulus's standard tools: persistent RAG over its own history and stored content (`search_history`, `read_file`, …), inter-agent messaging (`send_to_agent` — e.g. a visitor session escalating to your `myapp` management thread), push notifications (`notify_user`), and email if configured. The system prompt doc decides what the agent should actually use.
+Every gateway thread also gets cumulus's standard tools: persistent RAG over its own history and stored content (`search_history`, `read_file`, …), inter-agent messaging (`send_to_agent` — e.g. a visitor session escalating to your `myapp` management thread), push notifications (`notify_user`), and email if configured. `allowedTools` decides what the agent _can_ use; the system prompt doc decides what it _should_.
+
+### 5.5 How retrieval behaves on a visitor surface (it is not like a dev thread)
+
+Worth understanding before you debug a strange answer, because visitor threads sit at the
+opposite end of cumulus's retrieval design from the threads it was tuned on.
+
+Cumulus replaces the model's context every turn: recent conversation, plus whatever
+semantic + keyword search pulls out of that thread's own history and content store. On a
+maintainer thread that works well — the store is full of prose about the same subject the
+next question will be about, so the query lands _on_ the corpus.
+
+A visitor thread inverts both sides:
+
+- **The store is mostly JSON.** Its content is tool results — `records_get` payloads,
+  `app_describe` snapshots — not prose. Little of it reads like a sentence.
+- **The queries are English questions** about your product, often about things no prior turn
+  ever touched.
+
+So an **off-manifold query — one that matches nothing in the store — is routine here, not
+exceptional.** That matters because retrieval has a relevance floor, not a hard cutoff: when
+nothing scores well, whatever survives the floor is what gets packed. On a visitor thread
+that can be a document with no topical relationship to the question at all, simply because
+it is the least-bad match available.
+
+This was measured, not theorised: a topic-free operational document seeded into every store
+was retrieved on **2 of 24** visitor turns on a live app — including one turn where it
+outranked 24 genuine tool results — and on one of those turns the model acted on it,
+inventing an HTTP call that did not exist. The document has since been removed from
+visitor threads (it is only seeded into threads that could actually run it), but the
+mechanism is general and will apply to anything else in the store.
+
+Practical consequences:
+
+- **Put product knowledge in `alwaysInclude`, not in the store.** `alwaysInclude` is
+  unconditional — it is in every prompt regardless of what retrieval scores. Anything the
+  agent must always know belongs there. Retrieval is a bonus, not a guarantee.
+- **Say so in the system prompt doc.** Instruct the agent to answer from its tools and the
+  system prompt, and to call a tool rather than infer from retrieved fragments. A visitor
+  thread should reach for `records_get`, not for whatever came back from search.
+- **Expect a cold first turn.** A brand-new visitor thread has an almost empty store, so its
+  first turns retrieve very little (or the only thing present). Do not tune retrieval on the
+  first exchange of a fresh session.
+- **The store still earns its keep within a session** — it is what makes turn 12 remember
+  turn 3 for that visitor. The caution is about cross-topic recall, not about memory.
 
 ---
 

package/examples/web-app-agent/README.md

@@ -197,7 +197,7 @@ anything.
 
 ---
 
-## The six things that are easy to get wrong
+## The seven things that are easy to get wrong
 
 ### 1. The thread name is the capability
 
@@ -294,19 +294,51 @@ GATEWAY_ORIGIN=http://127.0.0.1:8080 GATEWAY_ADMIN_KEY=sk-... \
 The **admin** key, not the app's: a namespace covers `demoapp-*`, so the scoped
 key can write `demoapp-v` but is refused on the bare `demoapp`. The config API
 takes `projectDir`, `template`, `model`, `effort`, `claudeModel` and
-`contextLimit`; `alwaysInclude` and `disallowedTools` have to be added to the file
-on the gateway host (that is deliberate — `alwaysInclude` plus `projectDir` would
-let a public scoped key read any file into its own prompt). The applier reads each
-config back and tells you exactly what didn't stick. No reload needed.
+`contextLimit`; `alwaysInclude`, `allowedTools` and `disallowedTools` have to be
+added to the file on the gateway host. That is deliberate in both directions —
+`alwaysInclude` plus `projectDir` would let a public scoped key read any file into
+its own prompt, and `allowedTools` is writable in the _widening_ direction, so a
+scoped key could relax its own restrictions. The applier reads each config back and
+tells you exactly what didn't stick. No reload needed.
+
+### 4. Visitor threads need an `allowedTools` allowlist
+
+The model is the cost dial; `allowedTools` is the **capability** dial, and omitting
+it is the other expensive mistake. A thread with no allowlist gets the full harness:
+shell, file writes, sub-agent spawning, and the ability to message your other
+threads — handed to anonymous traffic.
+
+```json
+"allowedTools": ["Read", "read_file", "search_content", "retrieve_content", "search_history"]
+```
+
+It is **deny-by-default**: anything not named is refused, _including tools a future
+cumulus or Claude CLI release adds_. That is why it is an allowlist and not a
+denylist — with a denylist, every newly shipped tool is silently granted to every
+visitor of every deployed app until you notice. One real app needed **47 deny
+entries** to reach a safe surface; the list above is five.
+
+Two things people expect wrongly:
+
+- **Your own shim tools are unaffected.** Cumulus doesn't know their names, so it
+  can't deny them. They stay available — they're the tools you deliberately gave
+  this namespace.
+- **A typo denies.** An entry matching nothing is inert, and inertness is a denial,
+  so a misspelled tool silently disappears. Check the journal after a deploy.
+
+Setting it also shrinks that thread's system prompt: sections about tools it can't
+reach (background work, scheduling, inter-agent messaging) are dropped, because dead
+instructions cost tokens every turn and invite the model to improvise a substitute
+for a tool it cannot call.
 
-### 4. Commands act through an adapter, not the DOM
+### 5. Commands act through an adapter, not the DOM
 
 `window.HostApp` is the app's own actions exposed as functions. Commands call
 those. That's why validation, persistence, and re-render work identically
 whether a human or the model is driving — and why your commands survive a UI
 rewrite.
 
-### 5. Descriptions are the interface
+### 6. Descriptions are the interface
 
 The model decides what to call based entirely on the `description` string.
 Write for a reader who cannot see your UI, and say what a command is _for_, not
@@ -321,7 +353,7 @@ description: 'Set the on-screen filter so the human sees a subset. ' +
 
 The second one prevents a whole class of annoying behaviour.
 
-### 6. Pick the risk tier honestly
+### 7. Pick the risk tier honestly
 
 | tier      | meaning                                         | gated?                 |
 | --------- | ----------------------------------------------- | ---------------------- |

package/examples/web-app-agent/thread-config.visitor.example.json

@@ -33,9 +33,37 @@
   "effort": "medium",
   "alwaysInclude": ["docs/demoapp-system-prompt.md"],
 
+  "_allowedTools": [
+    "THE ONLY TOOLS A VISITOR TURN MAY USE. This is an allowlist, so it is",
+    "deny-by-default: anything not named here is refused, including tools that a",
+    "future cumulus or Claude CLI release adds. That is the point — the alternative",
+    "is a denylist, which silently grants every newly-added tool to every visitor of",
+    "every deployed app until you notice and edit it. One real app needed 47 deny",
+    "entries to get a safe surface; this list is five.",
+    "",
+    "Your app's own MCP shim tools are NOT affected: cumulus does not know their",
+    "names, so it cannot deny them. They stay available, which is what you want —",
+    "they are the tools you deliberately gave this namespace.",
+    "",
+    "Names may be bare ('read_file') or fully qualified",
+    "('mcp__cumulus-history__read_file'). An entry that matches nothing is inert,",
+    "and inertness DENIES — a typo fails closed, so check the journal after a deploy.",
+    "",
+    "Start from this list and add only what your app actually needs. Note what is",
+    "absent and why: Bash/Write/Edit (a visitor must not run shell or write files),",
+    "Task/Workflow (spawning sub-agents on anonymous traffic), send_to_agent (a",
+    "visitor could message your maintainer threads), schedule_trigger (a visitor",
+    "could arm turns that fire long after they leave), forget_content (destructive).",
+    "",
+    "Omit this key entirely to leave a thread unrestricted."
+  ],
+  "allowedTools": ["Read", "read_file", "search_content", "retrieve_content", "search_history"],
+
   "_disallowedTools": [
-    "Visitor-facing threads should not be able to stop and ask the operator a",
-    "question — there is nobody on the other end, and the turn would hang. Strip it:"
+    "Applied ON TOP of the allowlist — it can subtract, never add. Redundant while",
+    "the allowlist above omits AskUserQuestion, and kept as the explicit statement",
+    "of why: there is nobody on the other end of a visitor turn, so a question hangs.",
+    "If you widen allowedTools, this line keeps holding."
   ],
   "disallowedTools": ["AskUserQuestion"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",