switchroom 0.14.76 → 0.14.78

package/bin/user-profile-refresh-hook.sh

@@ -18,21 +18,45 @@ if [ -f "$MARKER" ]; then
 fi
 # Fire-and-forget refresh via MCP. Timeout bounded by Claude Code hook.
 # Output nothing on success or failure; errors are surfaced via doctor.
+#
+# Two bugs this fixes (2026-06-07):
+#  1. The Hindsight server is STATELESS (HINDSIGHT_API_MCP_STATELESS=true) and
+#     returns NO mcp-session-id header, so the old code's `[ -n "$SESSION" ]`
+#     gate was ALWAYS false → the refresh NEVER fired. Stateless MCP needs no
+#     session — drop the gate (mirrors src/memory/hindsight.ts, which tolerates
+#     a missing session id).
+#  2. refresh_mental_model takes `mental_model_id` (a UUID), NOT `name`. Passing
+#     `name` returns isError "Missing required argument: mental_model_id". So we
+#     list_mental_models, resolve the `user-profile` model's id, then refresh
+#     by id.
 {
-  # JSON-RPC flow: initialize → tools/call refresh_mental_model
-  SESSION=$(curl -sS -X POST "$API_URL/mcp/" \
+  # initialize (no session id needed on the stateless server).
+  curl -sS -X POST "$API_URL/mcp/" \
     -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-    -H "X-Bank-Id: $BANK_ID" -D /tmp/mm-refresh-$$.headers \
+    -H "X-Bank-Id: $BANK_ID" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"mm-refresh","version":"0.1"}}}' \
-    -m 3 -o /dev/null 2>/dev/null && grep -i mcp-session-id /tmp/mm-refresh-$$.headers | cut -d' ' -f2 | tr -d '\r\n')
-  if [ -n "$SESSION" ]; then
+    -m 3 -o /dev/null 2>/dev/null || true
+
+  # Resolve the user-profile mental model's id (refresh is by id, not name).
+  # list_mental_models returns the items as a JSON STRING nested in
+  # .result.structuredContent.result, so parse with jq (fromjson). The agent
+  # image ships jq; if it's somehow absent, MM_ID stays empty → skip (the next
+  # Stop fires it again; fire-and-forget, no wedge).
+  MM_ID=$(curl -sS -X POST "$API_URL/mcp/" \
+    -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
+    -H "X-Bank-Id: $BANK_ID" \
+    -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_mental_models","arguments":{}}}' \
+    -m 5 2>/dev/null \
+    | grep '^data:' | sed 's/^data: //' \
+    | jq -r '.result.structuredContent.result | fromjson | .items[] | select(.name=="user-profile") | .id' 2>/dev/null | head -1)
+
+  if [ -n "$MM_ID" ]; then
     curl -sS -X POST "$API_URL/mcp/" \
       -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-      -H "X-Bank-Id: $BANK_ID" -H "mcp-session-id: $SESSION" \
-      -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"refresh_mental_model","arguments":{"name":"user-profile"}}}' \
+      -H "X-Bank-Id: $BANK_ID" \
+      -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"refresh_mental_model\",\"arguments\":{\"mental_model_id\":\"$MM_ID\"}}}" \
       -m 5 -o /dev/null 2>/dev/null || true
   fi
-  rm -f /tmp/mm-refresh-$$.headers 2>/dev/null || true
   date +%s > "$MARKER"
 } &
 exit 0

package/dist/cli/switchroom.js

@@ -14987,7 +14987,7 @@ async function ensureUserProfileMentalModel(apiUrl, bankId, opts) {
           name: "create_mental_model",
           arguments: {
             name: "user-profile",
-            query: "What are the key facts, preferences, context, and communication style about the user I talk to? Summarize what matters for making the agent feel like it knows them.",
+            source_query: "What are the key facts, preferences, context, and communication style about the user I talk to? Summarize what matters for making the agent feel like it knows them.",
             types: ["world", "experience"]
           }
         }
@@ -14998,6 +14998,13 @@ async function ensureUserProfileMentalModel(apiUrl, bankId, opts) {
     if (!createResponse.ok) {
       return { ok: false, reason: `Create MM HTTP ${createResponse.status}` };
     }
+    try {
+      const created = await parseSseOrJson(createResponse);
+      if (created.result?.isError === true) {
+        const msg = created.result.content?.[0]?.text ?? "create returned isError";
+        return { ok: false, reason: msg };
+      }
+    } catch {}
     return { ok: true };
   } catch (err) {
     if (err.name === "AbortError") {
@@ -15204,6 +15211,13 @@ async function addMemoryTag(apiUrl, bankId, memoryId, tag, opts) {
     if (!toolResponse.ok) {
       return { ok: false, reason: `Tool call HTTP ${toolResponse.status}` };
     }
+    try {
+      const parsed = await parseSseOrJson(toolResponse);
+      if (parsed.result?.isError === true) {
+        const msg = parsed.result.content?.[0]?.text ?? "tool returned isError";
+        return { ok: false, reason: msg };
+      }
+    } catch {}
     return { ok: true };
   } catch (err) {
     if (err.name === "AbortError") {
@@ -20876,7 +20890,7 @@ function getHindsightSettingsEntry(agentName, config) {
   }
   const collection = getCollectionForAgent(agentName, config);
   const mcpConfig = generateHindsightMcpConfig(collection, memoryConfig);
-  return { key: "hindsight", value: mcpConfig };
+  return { key: "hindsight", value: { ...mcpConfig, alwaysLoad: true } };
 }
 function getPlaywrightMcpSettingsEntry() {
   return {
@@ -49681,8 +49695,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.76";
-var COMMIT_SHA = "e7ab9ec6";
+var VERSION = "0.14.78";
+var COMMIT_SHA = "ac0dae98";
 
 // src/cli/agent.ts
 init_source();
@@ -50534,16 +50548,16 @@ Every turn that answers a user message ends with a user-visible
 sees; your terminal output never reaches them.`;
 var MEMORY_GUIDANCE = `## Memory \u2014 proactive, conversational
 
-You have Hindsight tools: \`mcp__hindsight__sync_retain\`, \`mcp__hindsight__delete_memory\`, \`mcp__hindsight__recall\`, \`mcp__hindsight__reflect\`. Use them without being asked.
+You have Hindsight tools: \`mcp__hindsight__sync_retain\`, \`mcp__hindsight__delete_document\`, \`mcp__hindsight__recall\`, \`mcp__hindsight__reflect\`. Use them without being asked.
 
 ### Retain proactively
 When the user shares a fact, preference, decision, or plan worth keeping across sessions, call \`sync_retain\` in the same turn. Briefly acknowledge in your reply ("got it, April 2nd anniversary"). Don't narrate the tool call. Skip small talk and transient tool output, the auto-retain hook handles conversation-level signal.
 
 ### Correct proactively
-When the user corrects you or contradicts a prior memory, call \`delete_memory\` on the wrong entry, then \`sync_retain\` the correction. Acknowledge the correction in one line ("noted, Alice not Bob").
+When the user corrects you or contradicts a prior memory, call \`delete_document\` on the wrong entry, then \`sync_retain\` the correction. Acknowledge the correction in one line ("noted, Alice not Bob").
 
 ### Forget proactively
-When the user asks you to forget something ("forget that", "delete X", "drop what I said about Y"), call \`delete_memory\` for matching entries and confirm what was removed.
+When the user asks you to forget something ("forget that", "delete X", "drop what I said about Y"), call \`delete_document\` for matching entries and confirm what was removed.
 
 ### Inspect proactively
 When the user asks "what do you know about X / me", "what do you remember about Y", or any memory audit, use \`reflect\` to synthesize an answer across the bank. Return it as honest prose, not a raw dump. If the bank has little on the topic, say so.
@@ -50600,7 +50614,18 @@ name from that list.
 Only call the \`vault_request_access\` MCP tool \u2014 which pings the
 operator for a Telegram approval \u2014 for a key you've **confirmed via
 \`vault list\` you don't already have.** Requesting access to a guessed
-or already-held key wastes the operator's tap and fails.`;
+or already-held key wastes the operator's tap and fails.
+
+**Never put a secret's value \u2014 or a \`vault:<key>\` placeholder \u2014 in a
+tool call.** Tool arguments are sent to the underlying API verbatim;
+nothing resolves a \`vault:\` reference for them. A real secret never
+needs to appear in a tool call \u2014 the launcher injects it into the
+tool's environment for you. A value you genuinely must pass literally
+(an account or customer ID) is a public identifier, not a secret, and
+belongs in plain config, not the vault. If a tool call is **blocked for
+containing a vaulted secret**, report that exact block message to the
+operator and stop \u2014 don't theorise about auth or tokens; it just means
+a stored value reached a tool argument.`;
 function renderFleetInvariants() {
   return [
     "<!--",
@@ -51111,6 +51136,11 @@ function buildHumanizerEnvVars(agentDir, agent) {
   const resolved = expanded.startsWith("/") ? expanded : resolve11(agentDir, expanded);
   return { HUMANIZER_VOICE_FILE: resolved };
 }
+function buildToolSearchEnvVars() {
+  if (process.env.SWITCHROOM_DISABLE_TOOL_SEARCH === "1")
+    return {};
+  return { ENABLE_TOOL_SEARCH: process.env.SWITCHROOM_TOOL_SEARCH_MODE ?? "auto" };
+}
 var SWITCHROOM_OWNED_SETTINGS_KEYS = new Set([
   "permissions",
   "mcpServers",
@@ -51440,6 +51470,7 @@ function buildWorkspaceContext(args) {
     fallbackModelQ: agentConfig.fallback_model ? shellSingleQuote(agentConfig.fallback_model) : undefined,
     userEnvQuoted: (() => {
       const combined = {
+        ...buildToolSearchEnvVars(),
         ...channelsToEnv(agentConfig),
         ...agentConfig.env ?? {},
         ...buildRepoEnvVars(name, agentDir, agentConfig),
@@ -51750,7 +51781,8 @@ function scaffoldAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchro
           TELEGRAM_STATE_DIR: telegramStateDir,
           SWITCHROOM_CONFIG: resolvedConfigPath,
           SWITCHROOM_CLI_PATH: switchroomCliPath
-        }
+        },
+        alwaysLoad: true
       },
       "agent-config": {
         command: switchroomCliPath,
@@ -51758,7 +51790,8 @@ function scaffoldAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchro
         env: {
           SWITCHROOM_AGENT_NAME: name,
           SWITCHROOM_CONFIG: resolvedConfigPath
-        }
+        },
+        alwaysLoad: true
       }
     };
     if (agentConfig.admin === true) {
@@ -52503,6 +52536,7 @@ function reconcileAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchr
       fallbackModelQ: agentConfig.fallback_model ? shellSingleQuote(agentConfig.fallback_model) : undefined,
       userEnvQuoted: (() => {
         const combined = {
+          ...buildToolSearchEnvVars(),
           ...channelsToEnv(agentConfig),
           ...agentConfig.env ?? {},
           ...buildRepoEnvVars(name, agentDir, agentConfig)
@@ -52785,7 +52819,8 @@ ${body}
           TELEGRAM_STATE_DIR: telegramStateDir,
           SWITCHROOM_CONFIG: resolvedConfigPath,
           SWITCHROOM_CLI_PATH: switchroomCliPath
-        }
+        },
+        alwaysLoad: true
       },
       "agent-config": {
         command: switchroomCliPath,
@@ -52793,7 +52828,8 @@ ${body}
         env: {
           SWITCHROOM_AGENT_NAME: name,
           SWITCHROOM_CONFIG: resolvedConfigPath
-        }
+        },
+        alwaysLoad: true
       }
     };
     if (agentConfig.admin === true) {
@@ -59152,9 +59188,8 @@ function makeHttpHindsightClient(apiUrl, opts) {
       });
       return { items: res.items ?? [], total: res.total ?? 0 };
     },
-    async deleteMemory(bankId, memoryId) {
-      const sid = await initSession(bankId);
-      await callTool(bankId, sid, "delete_memory", { bank_id: bankId, memory_id: memoryId });
+    async deleteMemory(_bankId, _memoryId) {
+      throw new Error("hindsight exposes no single-memory delete API (delete_memory is not a " + "real tool; a memory id is not a document_id) \u2014 matched secrets cannot " + "be auto-scrubbed; redact manually via the bank UI");
     }
   };
 }
@@ -59184,11 +59219,18 @@ ${mem.context ?? ""}`;
   }
   let deleted = 0;
   if (!opts.dryRun) {
+    let warnedOnce = false;
     for (const m of matched) {
       try {
         await client.deleteMemory(bankId, m.id);
         deleted++;
-      } catch {}
+      } catch (err) {
+        if (!warnedOnce) {
+          warnedOnce = true;
+          process.stderr.write(`vault-sweep: ${matched.length} secret(s) matched in bank '${bankId}' but ` + `could NOT be auto-deleted: ${err.message}
+`);
+        }
+      }
     }
   }
   return { matched, deleted };
@@ -64069,6 +64111,15 @@ import { existsSync as existsSync37 } from "node:fs";
 
 // src/vault/doctor.ts
 var SENSITIVE_KEY_RE = /oauth(?![a-zA-Z])|token(?![a-zA-Z])|secret(?![a-zA-Z])|api[-_]?key(?![a-zA-Z])|password(?![a-zA-Z])/i;
+function looksLikeIdentifierValue(value) {
+  const v = value.trim();
+  if (v.length < 8 || v.length > 24)
+    return false;
+  if (!/^[0-9][0-9 -]*[0-9]$/.test(v))
+    return false;
+  const digitCount = v.replace(/[^0-9]/g, "").length;
+  return digitCount >= 8;
+}
 function analyseVaultHealth(input) {
   const diagnostics = [];
   if (input.brokerConfigured && input.brokerRunning === false) {
@@ -64124,6 +64175,23 @@ ${keyList}`,
         fix: "Consider `switchroom vault set <key> --allow <agent>` to restrict access"
       });
     }
+    const identifierKeys = [];
+    for (const [keyName, entry] of Object.entries(input.vaultKeys)) {
+      if (entry.looksLikeIdentifier)
+        identifierKeys.push(keyName);
+    }
+    if (identifierKeys.length > 0) {
+      const keyList = identifierKeys.map((k) => `  ${k}`).join(`
+`);
+      diagnostics.push({
+        level: "warn",
+        check: "identifier-stored-as-secret",
+        message: `${identifierKeys.length} vault key(s) hold an identifier-like value (digits only):
+${keyList}
+` + `If an agent must pass one of these in a tool call, the secret-guard hook will block it \u2014 it cannot tell a public ID from a secret.`,
+        fix: "If the value is a public identifier (account/customer ID), remove it from the vault and pass it as plain config (e.g. hardcode it in the MCP launcher). If it is genuinely secret, ignore this."
+      });
+    }
     const unreferencedKeys = [];
     for (const keyName of Object.keys(input.vaultKeys)) {
       if (!referencedKeys.has(keyName)) {
@@ -64215,7 +64283,8 @@ function registerVaultDoctorCommand(vault, program3) {
         vaultKeys = {};
         for (const [name, entry] of Object.entries(entries)) {
           vaultKeys[name] = {
-            scope: "scope" in entry && entry.scope ? entry.scope : undefined
+            scope: "scope" in entry && entry.scope ? entry.scope : undefined,
+            looksLikeIdentifier: entry.kind === "string" ? looksLikeIdentifierValue(entry.value) : false
           };
         }
       } catch (err) {
@@ -77207,7 +77276,18 @@ function formatBytes(bytes) {
   return `${bytes.toLocaleString()} bytes`;
 }
 function estimateTokens(bytes) {
-  return Math.round(bytes / 4);
+  return Math.round(bytes / 3.7);
+}
+function readMcpServerNames(agentDir) {
+  const mcpPath = join64(agentDir, ".mcp.json");
+  if (!existsSync64(mcpPath))
+    return [];
+  try {
+    const parsed = JSON.parse(readFileSync56(mcpPath, "utf-8"));
+    return Object.keys(parsed.mcpServers ?? {});
+  } catch {
+    return null;
+  }
 }
 function sha256(content) {
   return createHash13("sha256").update(content).digest("hex").slice(0, 16);
@@ -77425,14 +77505,31 @@ function registerDebugCommand(program3) {
     const soulMdBytes = soulMdContent.length;
     const perTurnBytes = dynamicResult.concatenated.length;
     const userBytes = userMessage?.text.length ?? 0;
-    const totalBytes = stableBytes + perSessionBytes + claudeMdBytes + soulMdBytes + perTurnBytes + userBytes;
-    console.log(`Stable prefix:     ${formatBytes(stableBytes).padEnd(20)} (cache-hot)`);
+    const fleetDir = join64(agentsDir, "..", "fleet");
+    const fleetInvPath = join64(fleetDir, "switchroom-invariants.md");
+    const fleetClaudePath = join64(fleetDir, "CLAUDE.md");
+    const fleetInvBytes = existsSync64(fleetInvPath) ? readFileSync56(fleetInvPath, "utf-8").length : 0;
+    const fleetClaudeBytes = existsSync64(fleetClaudePath) ? readFileSync56(fleetClaudePath, "utf-8").length : 0;
+    const fleetBytes = fleetInvBytes + fleetClaudeBytes;
+    const totalBytes = stableBytes + perSessionBytes + claudeMdBytes + fleetBytes + perTurnBytes + userBytes;
+    console.log(`Stable prefix:     ${formatBytes(stableBytes).padEnd(20)} (cache-hot; includes SOUL.md ${soulMdBytes.toLocaleString()}B)`);
     console.log(`Per-session:       ${formatBytes(perSessionBytes).padEnd(20)} (cache-warm until next session)`);
-    console.log(`CLAUDE.md:         ${formatBytes(claudeMdBytes).padEnd(20)}`);
-    console.log(`SOUL.md:           ${formatBytes(soulMdBytes).padEnd(20)}`);
-    console.log(`Per-turn:          ${formatBytes(perTurnBytes).padEnd(20)} (never cached)`);
+    console.log(`CLAUDE.md (cwd):   ${formatBytes(claudeMdBytes).padEnd(20)} (cache-hot)`);
+    console.log(`Fleet invariants:  ${formatBytes(fleetBytes).padEnd(20)} (--add-dir, cache-hot)`);
+    console.log(`Per-turn:          ${formatBytes(perTurnBytes).padEnd(20)} (never cached \u2014 the real per-turn $ cost)`);
     console.log(`User message:      ${formatBytes(userBytes).padEnd(20)}`);
-    console.log(`Total:             ${formatBytes(totalBytes).padEnd(20)} (~${estimateTokens(totalBytes).toLocaleString()} tokens est.)`);
+    console.log(`Authored text:     ${formatBytes(totalBytes).padEnd(20)} (~${estimateTokens(totalBytes).toLocaleString()} tokens est.)`);
+    const mcpServers = readMcpServerNames(agentDir);
+    const mcpCount = mcpServers?.length ?? null;
+    const mcpEstK = mcpCount != null ? mcpCount * 3 : null;
+    const mcpLabel = mcpCount != null ? `${mcpCount} servers` : "(unreadable \u2014 agent-private .mcp.json)";
+    const mcpEstLabel = mcpEstK != null ? `~${mcpEstK.toLocaleString()}k tok` : "~30k tok (audit est.)";
+    console.log(`MCP tool surface:  ${mcpLabel.padEnd(20)} (NOT counted above; ~3k tok/server \u2248 ${mcpEstLabel} \u2014 deferred under tool search)`);
+    if (mcpServers && mcpServers.length > 0) {
+      console.log(`                   [${mcpServers.join(", ")}]`);
+    }
+    const floorMcp = mcpEstK != null ? `~${mcpEstK.toLocaleString()}k` : "~30k";
+    console.log(`Per-turn FLOOR:    ${`~${estimateTokens(totalBytes).toLocaleString()} + ${floorMcp} MCP + ~13k CLI-base`.padEnd(20)} tokens est. (before the user msg, recall, or tool results)`);
     const stableCacheInput = stableResult.concatenated + progressGuidance + baseSystemPromptAppend;
     const stableHash = sha256(stableCacheInput);
     console.log(`Cache stable hash: sha256:${stableHash}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.14.76",
+  "version": "0.14.78",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/default/workspace/CLAUDE.md.hbs

@@ -11,23 +11,21 @@ Before answering anything non-trivial:
 
 1. Confirm who you are (see `IDENTITY.md` if present).
 2. Confirm who you're talking to (see `USER.md` if present).
-3. Remember what matters — `MEMORY.md` is your long-term memory; the
-   `memory/` subdirectory has daily notes (`memory/YYYY-MM-DD.md`) with
-   recent context.
+3. Recall what matters — your memory is **Hindsight**: call
+   `mcp__hindsight__recall` when you need prior context, decisions, or who
+   someone is. (Full memory protocol is in your `CLAUDE.md`.)
 4. If tools are configured, `TOOLS.md` captures setup-specific notes
    (host paths, credentials, endpoints) that save you discovery work.
 
 Don't ask permission to read these files. They exist so you can use them.
 
-## Memory discipline
+## Memory
 
-- **Short-term / recent context** → `memory/YYYY-MM-DD.md` — raw log-style
-  notes of what happened today. Create the day's file when you need it.
-- **Long-term / curated** → `MEMORY.md` — distilled learnings, decisions,
-  preferences, identity of people you interact with.
-- **Lessons** → When you make a mistake or learn something worth keeping,
-  write it down. Future-you is fresh every session. Files are your
-  continuity.
+Memory is **Hindsight**, not files — `recall` to read, `sync_retain` to keep a
+fact across sessions, `delete_document` to forget. Claude Code's built-in
+file-based auto-memory is disabled for this agent; do not maintain a `MEMORY.md`
+index or a `memory/` daily-notes directory. Your `CLAUDE.md` has the full
+protocol.
 
 ## Safety defaults
 
@@ -55,8 +53,8 @@ Failed edits burn your own context and the user's patience. Verify first.
   tool exists.
 - Long-running commands: use the background flag and poll, rather than
   blocking.
-- `memory_search` and `memory_get` (when available) are your primary
-  interface to workspace knowledge; use them before asking the user.
+- `mcp__hindsight__recall` is your interface to past context and decisions;
+  recall before asking the user something you may already know.
 
 ## Working on code repositories
 

package/telegram-plugin/dist/gateway/gateway.js

@@ -52821,11 +52821,11 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.76";
-var COMMIT_SHA = "e7ab9ec6";
-var COMMIT_DATE = "2026-06-06T08:50:42Z";
-var LATEST_PR = 2196;
-var COMMITS_AHEAD_OF_TAG = 0;
+var VERSION = "0.14.78";
+var COMMIT_SHA = "ac0dae98";
+var COMMIT_DATE = "2026-06-07T09:07:56+10:00";
+var LATEST_PR = null;
+var COMMITS_AHEAD_OF_TAG = 3;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {

package/telegram-plugin/hooks/secret-guard-pretool.mjs

@@ -194,10 +194,19 @@ async function main() {
   }
   const hit = scanToolInput(toolInput, vaultValues)
   if (hit) {
+    // The reason is read by the model. It must be CORRECT and actionable:
+    // earlier versions said "reference it as vault:<key> instead", which
+    // suggested a `vault:` resolver that does not exist for tool arguments
+    // — sending agents (and operators) chasing a phantom mechanism. State
+    // the two real resolutions instead, and do NOT imply a resolver.
     process.stdout.write(
       JSON.stringify({
         decision: 'block',
-        reason: `tool_input contains a vaulted secret — reference it as vault:${hit.key} instead`,
+        reason:
+          `Blocked: this tool input contains the value of vault secret '${hit.key}'. ` +
+          `Secrets must never appear in a tool call. ` +
+          `If '${hit.key}' is a real secret, do not pass it as an argument — the launcher injects it into the tool's environment, so you never type it. ` +
+          `If '${hit.key}' is actually a public identifier (e.g. an account or customer ID that must appear in the call), it should not be in the vault — ask the operator to move it to plain config.`,
       }),
     )
     process.exit(0)

package/telegram-plugin/tests/secret-guard-pretool.test.ts

@@ -132,7 +132,13 @@ describe('secret-guard-pretool.mjs (broker-direct)', () => {
     })
     expect(r.status).toBe(0)
     expect(r.stdout).toContain('"decision":"block"')
-    expect(r.stdout).toContain('vault:gh-token')
+    // The reason must name the offending key and explain the real fix.
+    expect(r.stdout).toContain('gh-token')
+    expect(r.stdout).toContain('Secrets must never appear in a tool call')
+    // It must NOT resurrect the old, misleading "reference it as vault:<key>"
+    // suggestion — there is no vault: resolver for tool arguments, and that
+    // advice sent agents down a dead end (see the hook's block-reason note).
+    expect(r.stdout).not.toContain('reference it as vault:')
   })
 
   it('allows when tool_input contains no vaulted value', async () => {