claude-slack-channel-bots 0.6.5 → 0.6.7

package/README.md

@@ -38,7 +38,7 @@ See the sections below for manual configuration details if you prefer not to use
 
 - [Bun](https://bun.sh) `>= 1.0.21` (agent-director minimum)
 - [Claude Code](https://claude.ai/code) installed and authenticated
-- [`agent-director`](https://github.com/gabemahoney/agent-director) **runtime dependency** — pulled in transitively when you install this package. Hard required at server boot: CSCB refuses to start if the library is missing, the host platform is unsupported, Bun is too old, or the installed version is below `MIN_AD_VERSION` (`^0.5.5`). agent-director itself requires [tmux](https://github.com/tmux/tmux) on the operator's PATH; CSCB no longer probes for it directly.
+- [`agent-director`](https://github.com/gabemahoney/agent-director) **runtime dependency** — pulled in transitively when you install this package. Hard required at server boot: CSCB refuses to start if the library is missing, the host platform is unsupported, Bun is too old, or the installed version is below `MIN_AD_VERSION` (`^0.6.3`). agent-director itself requires [tmux](https://github.com/tmux/tmux) on the operator's PATH; CSCB no longer probes for it directly.
 - Slack workspace admin access (to create and configure the Slack app)
 - **cozempic** (optional) — Python 3.10+ and `pip install cozempic` — used by JSONL path resolution helpers retained for downstream callers.
 
@@ -54,7 +54,7 @@ See the sections below for manual configuration details if you prefer not to use
 
 If the host is unsupported, the SR-5.1 startup gate exits non-zero at server boot with a typed error from agent-director (`ErrPlatformPackageMissing` or `ErrUnsupportedPlatform`) and writes the failure to `~/.claude/channels/slack/startup-errors.log` and stderr. See [Startup errors](#startup-errors) below.
 
-> **Note on agent-director versions.** v0.4.1 is a zombie release (the published tarball is missing `dist/` and cannot be imported). v0.4.2 lacks the `MakeTemplateParams.overwrite` field CSCB needs for the boot-time template refresh. v0.5.4 and earlier lack `allow_pending` on `readPane`/`sendKeys`, causing `ErrSpawnNotInteractive` during dev-channels dialog approval on freshly-spawned bots. CSCB pins `^0.5.5` to get past all three.
+> **Note on agent-director versions.** v0.4.1 is a zombie release (the published tarball is missing `dist/` and cannot be imported). v0.4.2 lacks the `MakeTemplateParams.overwrite` field CSCB needs for the boot-time template refresh. v0.5.4 and earlier lack `allow_pending` on `readPane`/`sendKeys`, causing `ErrSpawnNotInteractive` during dev-channels dialog approval on freshly-spawned bots. v0.6.0 shipped a stale TS shim whose `Client` dropped `getPermission`, whose `buildDecide()` dropped `--request-token`, and whose error catalog omitted `ErrInvalidFlags` / `ErrPermissionRequestNotFound` / `ErrAmbiguousRequest` — each silently breaks the disambiguation relay. v0.6.1–0.6.2 still lack the full `permission_requests` plural projection + composite-key disambiguation surface CSCB depends on for concurrent open requests. CSCB pins `^0.6.3` to get past all of these.
 
 ---
 
@@ -439,6 +439,9 @@ Classes you may see:
 - `ad-cli-not-executable` — the resolved agent-director CLI binary exists but is not executable. Run `chmod +x` on the binary referenced in the log line.
 - `ad-version-probe` — `agent-director` was loaded but the `version()` probe failed (subprocess invocation, platform binary, etc.).
 - `ad-version-stale` — installed `agent-director` is below the minimum version this CSCB requires. Run `bun add agent-director@^<minimum>`.
+- `ad-shim-missing-get-permission` — the installed `agent-director` TS shim's `Client` does not expose `getPermission`. The npm-published package is out of sync with its bundled binary. Reinstall and confirm the resolved version actually ships the method.
+- `ad-shim-catalog-incomplete` — the installed `agent-director` TS error catalog is missing one or more of `ErrInvalidFlags`, `ErrPermissionRequestNotFound`, `ErrAmbiguousRequest`. The log line lists the missing names. Same remediation as `ad-shim-missing-get-permission`.
+- `ad-shim-decide-drops-token` — the installed `agent-director` dist does not include `--request-token` in its bundled JS, meaning `buildDecide()` would resolve permission clicks against the wrong row. Reinstall and confirm `buildDecide` carries the flag.
 - `ad-call-timeout` — an agent-director verb call exceeded the configured `callTimeoutMs` (default 30 s). Investigate the subprocess or increase the timeout.
 - `ad-same-user` — `~/.agent-director/state.db` is owned by a different UID than the CSCB process. Reinstall agent-director as the correct user or remove the mismatched file.
 - `ad-same-user-stat` — Non-ENOENT stat error on the state DB (permissions, I/O). Investigate the file before re-launching.
@@ -501,11 +504,7 @@ This gracefully exits the managed Claude Code sessions, stops and restarts the s
 For operators upgrading from a pre-`agent-director` install:
 
 1. **Install the new CSCB**: `bun remove claude-director` (if present) and `bun install -g claude-slack-channel-bots@^<new>`. The `agent-director` library is pulled in transitively — no separate install step.
-2. **Delete any old relay hooks** (CSCB no longer ships them — agent-director's relay machinery owns the tool-permission flow):
-   ```sh
-   rm -f ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh
-   ```
-   Also remove their entries from `~/.claude/settings.json` if you wired them in by hand previously.
+2. **Delete any old relay hooks** — see [Upgrading from pre-Epic-2 (v0.5.x → v0.6.x)](#upgrading-from-pre-epic-2-v05x--v06x) for the cleanup commands.
 3. **Configure agent-director's `find-missing` sweep**. CSCB does NOT call `client.findMissing(...)`; reconciling stuck rows is the operator's responsibility. Add a cron entry (or systemd timer) that runs `agent-director find-missing` on a cadence that matches your tolerance — e.g. every minute on a busy host:
    ```cron
    * * * * * /usr/local/bin/agent-director find-missing --timeout 30s
@@ -518,5 +517,41 @@ For operators upgrading from a pre-`agent-director` install:
 6. **Optional cleanup**: `~/.claude/channels/slack/sessions.json` and `sessions.json.last` are no longer read or written. CSCB ignores them; you can safely `rm` them after a successful boot.
 7. **`tmux` is no longer a CSCB-direct prereq** but is still required transitively via agent-director — keep it installed.
 
-After step 1, every CSCB bot is spawned through `client.spawn(...)` with `relay_mode='on'`. The green/red Slack button UX is byte-identical to the pre-migration behavior; the action_id shape changes from `perm_(allow|deny)_<uuid>` to `perm_(allow|deny)_cscb_<channelId>_<request_id>` but this is invisible to end users.
+After step 1, every CSCB bot is spawned through `client.spawn(...)` with `relay_mode='on'`. The green/red Slack button UX is byte-identical to the pre-migration behavior; the action_id shape changes from `perm_(allow|deny)_<uuid>` to `perm_(allow|deny)_cscb_<channelId>_<request_token>` (where `<request_token>` is a UUIDv4 minted by agent-director) but this is invisible to end users.
+
+---
+
+## Upgrading from pre-Epic-2 (v0.5.x → v0.6.x)
+
+If you installed CSCB before v0.6.0 you may have legacy artifacts on disk that are no longer needed. Clean them up manually — automatic postinstall migration is tracked under idea b.irf and not yet implemented.
+
+### 1. Remove old relay hook files
+
+The `.sh` relay hooks are no longer shipped by CSCB. Delete them if present:
+
+```sh
+rm -f ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh
+```
+
+### 2. Remove orphan settings.json hook entries
+
+If you wired the hooks into `~/.claude/settings.json` by hand, remove the stale entries. Use this `jq` filter to check whether any are present:
+
+```sh
+jq '
+  (.hooks.PermissionRequest // [] | map(select(.hooks[]?.command | strings | test("\\.sh$")))),
+  (.hooks.PreToolUse // [] | map(select(.matcher == "AskUserQuestion" and (.hooks[]?.command | strings | test("\\.sh$")))))
+' ~/.claude/settings.json 2>/dev/null
+```
+
+Any non-empty arrays in the output are orphan entries. Remove:
+
+- Any object inside `hooks.PermissionRequest` whose `hooks[].command` ends in `permission-relay.sh`.
+- Any object inside `hooks.PreToolUse` with `"matcher": "AskUserQuestion"` whose `hooks[].command` ends in `ask-relay.sh`.
+
+The modern permission relay runs automatically via agent-director — no `PermissionRequest` or `PreToolUse` hook entries for `.sh` files are needed.
+
+### 3. Note on automated migration
+
+A postinstall step that performs this cleanup automatically is tracked under idea b.irf. Until that lands, the steps above are manual.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Multi-session Slack-to-Claude bridge — run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {
@@ -9,7 +9,6 @@
   "files": [
     "src/*.ts",
     "!src/*.test.ts",
-    "hooks/",
     "scripts/fixup-bun-cache.ts",
     "slack-app-manifest.yml",
     "README.md",
@@ -30,7 +29,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@slack/socket-mode": "^2.0.0",
     "@slack/web-api": "^7.0.0",
-    "agent-director": "^0.5.5"
+    "agent-director": "^0.6.3"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",

package/skills/setup-slack-channel-bots/SKILL.md

@@ -343,104 +343,53 @@ Do not modify `access.json` during setup unless the user asks to.
 
 ---
 
-### Step 7 — Check hooks
+### Step 7 — Verify agent-director is installed
 
-Check whether the relay hooks exist and are executable:
+The modern permission relay runs automatically via agent-director — no
+operator action is required for permission-relay or ask-handling.
+`AskUserQuestion` is denied at the agent-director template level (SR-3.1).
 
-```bash
-ls -la ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh 2>/dev/null || echo "NOT_FOUND"
-```
-
-**If either hook is missing:**
-
-Provide the copy and chmod commands. The source path depends on how the
-package was installed. Try to detect it:
-
-```bash
-# Attempt to find the package hooks directory
-bun pm ls -g 2>/dev/null | grep -o "claude-slack-channel-bots.*" | head -1 || true
-```
-
-Show the user the exact commands:
-
-```bash
-mkdir -p ~/.claude/hooks
-
-# Copy from the installed package (adjust path if needed):
-cp "$(npm root -g)/claude-slack-channel-bots/hooks/permission-relay.sh" ~/.claude/hooks/
-cp "$(npm root -g)/claude-slack-channel-bots/hooks/ask-relay.sh" ~/.claude/hooks/
-chmod +x ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh
-```
-
-Or, to keep them in sync with future package updates, symlink instead:
+Check that agent-director is installed and the `slack-channel-bot` template
+is registered:
 
 ```bash
-HOOKS_DIR="$(npm root -g)/claude-slack-channel-bots/hooks"
-ln -sf "$HOOKS_DIR/permission-relay.sh" ~/.claude/hooks/permission-relay.sh
-ln -sf "$HOOKS_DIR/ask-relay.sh" ~/.claude/hooks/ask-relay.sh
+agent-director --version
 ```
 
-Also remind the user that `curl` and `jq` must be on `PATH` for the hooks to
-work.
+The `slack-channel-bot` template is registered automatically at CSCB startup
+via `client.makeTemplate(...)`. Confirm the template exists after a successful
+`claude-slack-channel-bots start` by checking the agent-director template
+registry. If the startup log shows `ad-template-install` in
+`$STATE_DIR/startup-errors.log`, the template registration
+failed — investigate that error before proceeding.
 
-**If both hooks exist**, confirm they are executable (`-x`). If not, show:
-
-```bash
-chmod +x ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh
-```
+If `agent-director` is not on `PATH`, postinstall did not complete successfully.
+Re-run `bun postinstall.ts` from the installed package directory, or reinstall
+CSCB with `bun install -g claude-slack-channel-bots`.
 
 ---
 
-### Step 8 — Check Claude Code settings.json for hook entries
-
-Read `~/.claude/settings.json` and check whether the `PermissionRequest` and
-`PreToolUse` hook entries for the relay scripts are present.
+### Step 8 — Check settings.json for orphan legacy hook entries
 
-**Check for `PermissionRequest` entry:**
-
-Look for an entry inside `hooks.PermissionRequest` with:
-```json
-{ "type": "command", "command": "~/.claude/hooks/permission-relay.sh" }
-```
+Operators upgrading from pre-Epic-2 (v0.5.x) may have `PermissionRequest` or
+`PreToolUse` `AskUserQuestion` entries in `~/.claude/settings.json` that point
+at the old `.sh` files. These are harmless but stale — the `.sh` files no
+longer exist and agent-director owns the relay machinery now.
 
-**Check for `PreToolUse` entry:**
+Check for orphan entries:
 
-Look for an entry inside `hooks.PreToolUse` with:
-```json
-{ "matcher": "AskUserQuestion", "hooks": [{ "type": "command", "command": "~/.claude/hooks/ask-relay.sh" }] }
-```
-
-**If either entry is missing OR exists but is missing `"timeout": 2000000`**,
-show the user the exact JSON to add or fix. The timeout is critical — without
-it Claude Code uses a short default timeout, kills the hook before the
-long-poll completes, and falls back to TUI approval. This is the complete
-block for both entries:
-
-```jsonc
-"PermissionRequest": [
-  {
-    "matcher": ".*",
-    "timeout": 2000000,
-    "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-relay.sh" }]
-  }
-],
-"PreToolUse": [
-  {
-    "matcher": "AskUserQuestion",
-    "timeout": 2000000,
-    "hooks": [{ "type": "command", "command": "~/.claude/hooks/ask-relay.sh" }]
-  }
-]
+```bash
+jq '
+  (.hooks.PermissionRequest // [] | map(select(.hooks[]?.command | strings | test("\\.sh$")))),
+  (.hooks.PreToolUse // [] | map(select(.matcher == "AskUserQuestion" and (.hooks[]?.command | strings | test("\\.sh$")))))
+' ~/.claude/settings.json 2>/dev/null
 ```
 
-Add these under the top-level `"hooks"` key in `settings.json`. Existing
-entries in those arrays should be preserved — append, do not replace.
-
-If `settings.json` does not exist or does not have a `"hooks"` key, show the
-user the full minimal structure to add.
-
-Offer to write the missing entries automatically to `~/.claude/settings.json`.
-If the user agrees, make the targeted edits, preserving all existing content.
+If either output array is non-empty, orphan entries are present. Show the user
+the relevant block from `settings.json` and advise manual removal of any
+`PermissionRequest` entries whose `hooks[].command` ends in `permission-relay.sh`,
+and any `PreToolUse` entries with `matcher: "AskUserQuestion"` whose
+`hooks[].command` ends in `ask-relay.sh`.
 
 ---
 
@@ -450,13 +399,13 @@ Print a final summary of what was checked and configured:
 
 - Environment variables: set / missing
 - Token format: valid / invalid
-- config.json: populated (N routes) / skeleton
+- ~/.claude/channels/slack/config.json: present and valid (N routes) / missing or skeleton
 - append_system_prompt_file: configured / skipped
 - access.json: present / missing
-- permission-relay.sh hook: present and executable / missing
-- ask-relay.sh hook: present and executable / missing
-- settings.json PermissionRequest hook: present / missing
-- settings.json PreToolUse hook: present / missing
+- agent-director: installed (version X) / missing
+- slack-channel-bot template: registered (confirmed at startup) / unconfirmed
+- settings.json orphan PermissionRequest (.sh) hooks: none / found (needs cleanup)
+- settings.json orphan PreToolUse AskUserQuestion (.sh) hooks: none / found (needs cleanup)
 
 Remind the user:
 

package/src/agent-director-client.ts

@@ -27,7 +27,13 @@
 import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { Client } from 'agent-director'
+import { AgentDirectorError, Client } from 'agent-director'
+import type {
+  DecideParams as ADDecideParams,
+  DecideResult,
+  GetPermissionParams as ADGetPermissionParams,
+  GetPermissionResult as ADGetPermissionResult,
+} from 'agent-director'
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -131,3 +137,87 @@ export function resetClientForTests(): void {
 export function setClientForTests(client: Client): void {
   singleton = client
 }
+
+// ---------------------------------------------------------------------------
+// decide-wire wrapper (SR-4.1, SR-7.2)
+// ---------------------------------------------------------------------------
+
+/**
+ * CSCB decide params — extends `DecideParams` with the `request_token` field
+ * (SR-7.2). The snake-case JSON field flows through the subprocess-CLI
+ * transport without further marshaling on this side.
+ *
+ * Typing `request_token` as a required field at the wrapper boundary is how
+ * SR-4.1 (unconditional pass-through) is enforced statically — every CSCB
+ * decide call site must construct one of these.
+ */
+export interface DecideParamsWithToken extends ADDecideParams {
+  request_token: string
+}
+
+/**
+ * Always-include-token decide wrapper. MIN_AD_VERSION is now pinned at
+ * `^0.6.0`, which carries `request_token` on `DecideParams` natively. The
+ * structural cast is retained because, until the lockfile is refreshed to
+ * resolve the bumped pin, the imported `DecideParams` type still comes from
+ * the locked `0.5.6` package — same lockfile-lag pattern as
+ * `GetResultWithPermissionRequests`.
+ *
+ * Routing the single CSCB decide call site through this function gives the
+ * codebase one definitive serializer for the decide wire shape (SR-7.2).
+ */
+export async function decideWithToken(
+  client: Pick<Client, 'decide'>,
+  params: DecideParamsWithToken,
+): Promise<DecideResult> {
+  return client.decide(params as unknown as ADDecideParams)
+}
+
+// ---------------------------------------------------------------------------
+// get-permission wrapper (SR-7.1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Params + result for AD's `get-permission` verb (shipped in `^0.6.1`+).
+ * Re-exported from `agent-director` so the local consumers
+ * (`permission-poller`, `permission-click-handler`, tests) reference one
+ * source of truth. `decision` / `decision_reason` / `decided_at` are
+ * optional + nullable on AD's type because the same row shape covers both
+ * open and closed states; `classifyVerdict` collapses any non-canonical
+ * combination into the SR-5.2 fail-closed generic-deny path.
+ */
+export type GetPermissionParams = ADGetPermissionParams
+export type GetPermissionResult = ADGetPermissionResult
+
+/**
+ * Local sentinel matcher for AD's `ErrPermissionRequestNotFound`. Matches on
+ * `errName` so both the typed class (`^0.6.0`+ exposes it) and the stub's
+ * AgentDirectorError-shape resolve cleanly. The errName-based predicate keeps
+ * working with the typed class when the lockfile catches up to the bumped
+ * pin (same pattern as `ErrInvalidFlags`).
+ */
+export function isErrPermissionRequestNotFound(err: unknown): boolean {
+  return err instanceof AgentDirectorError && err.errName === 'ErrPermissionRequestNotFound'
+}
+
+/**
+ * `get-permission` wrapper (SR-7.1). MIN_AD_VERSION is pinned at `^0.6.0`,
+ * which carries the verb; the SR-6.1 startup gate is the compatibility
+ * boundary that keeps stale-version installs from reaching this path. The
+ * wrapper takes a structural client (rather than `Pick<Client, 'getPermission'>`)
+ * because the locked `0.5.6` types do not yet expose the method shape, and
+ * fails loudly at runtime when the verb is missing as defense-in-depth for
+ * the dev/test edge (e.g. stub clients that omit it on purpose).
+ */
+export async function getPermission(
+  client: { getPermission?: (params: GetPermissionParams) => Promise<GetPermissionResult> },
+  params: GetPermissionParams,
+): Promise<GetPermissionResult> {
+  if (typeof client.getPermission !== 'function') {
+    throw new Error(
+      'agent-director-client: getPermission verb unavailable — ' +
+        'confirm installed agent-director version meets the MIN_AD_VERSION pin',
+    )
+  }
+  return client.getPermission(params)
+}

package/src/agent-director-startup.ts

@@ -2,8 +2,7 @@
  * agent-director-startup.ts — SR-5.1 startup gate for the agent-director
  * library dependency.
  *
- * Runs the four-step boot sequence the SRD requires before any other CSCB
- * work:
+ * Runs the boot sequence the SRD requires before any other CSCB work:
  *
  *   1. import { Client } from 'agent-director'   — covered at module load
  *      time; module-not-found surfaces as a top-level import error caught
@@ -14,6 +13,12 @@
  *      ErrBunVersionTooOld; other throws surface verbatim.
  *   3. await client.version({})                  — strip leading 'v',
  *      compare to MIN_AD_VERSION via semverGte.
+ *   3.5. API surface probes (SR-6.1 publish-skew defense)  — short-circuit,
+ *      run in order: probeGetPermission (ad-shim-missing-get-permission) →
+ *      probeErrorCatalog (ad-shim-catalog-incomplete) → probeDecideArgv
+ *      (ad-shim-decide-drops-token). These exist because a passing version
+ *      check does not prove the npm-shipped TS shim matches the bundled Go
+ *      binary; each missing surface silently breaks the permission relay.
  *   4. stat ~/.agent-director/state.db           — compare st_uid to
  *      geteuid(). ENOENT passes (the row is created on first verb call);
  *      other stat errors are fatal.
@@ -27,6 +32,7 @@
 
 import * as fs from 'node:fs'
 import * as os from 'node:os'
+import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
 
 import {
@@ -57,6 +63,54 @@ const AD_STATE_DB_PATH = join(os.homedir(), '.agent-director', 'state.db')
 /** Supported platforms surfaced in operator-facing remediation text. */
 const SUPPORTED_PLATFORMS = ['linux-x64', 'darwin-arm64'] as const
 
+/**
+ * err_names CSCB's runtime branches on. The structural-drift indicator we
+ * guard against is whether the `agent-director` dist file ships a class
+ * declaration for each — i.e. matches `class <Name> extends ...`. The class
+ * declaration is the defining symptom of a shim that's caught up to the
+ * bundled Go binary: when one is missing, `instanceof Err<Name>` predicates
+ * silently downgrade and the runtime `errorFromEnvelope` falls back to a
+ * base `AgentDirectorError` instead of the typed subclass. A bare-identifier
+ * match in the dist source is too loose because the shipped shim also
+ * carries a metadata array (`{ name: "ErrPermissionRequestNotFound", ... }`)
+ * that mentions the names even when the class is absent — so the regex
+ * must anchor on `class <Name>\s`.
+ */
+const REQUIRED_ERR_NAMES = [
+  'ErrInvalidFlags',
+  'ErrPermissionRequestNotFound',
+  'ErrAmbiguousRequest',
+] as const
+
+// ---------------------------------------------------------------------------
+// Private helper: resolve + read the agent-director dist source (memoized)
+// ---------------------------------------------------------------------------
+
+/**
+ * Source-text cache for the resolved `agent-director` dist entry. Probes 2
+ * and 3 both grep the same file; reading it once keeps boot fast and avoids
+ * surprising operators with duplicate I/O failures.
+ */
+let cachedAdDistSource: string | Error | null = null
+
+/**
+ * Resolve `agent-director` via `import.meta.resolve`, convert the file:// URL
+ * to a filesystem path, and read the bundled JS as UTF-8. Memoized for the
+ * life of the process. Returns the cached `Error` on a previous failure so
+ * each probe can surface a uniform `detail` field.
+ */
+function readAdDistSource(): string | Error {
+  if (cachedAdDistSource !== null) return cachedAdDistSource
+  try {
+    const resolved = import.meta.resolve('agent-director')
+    const distPath = fileURLToPath(resolved)
+    cachedAdDistSource = fs.readFileSync(distPath, 'utf-8')
+  } catch (err) {
+    cachedAdDistSource = err instanceof Error ? err : new Error(String(err))
+  }
+  return cachedAdDistSource
+}
+
 // ---------------------------------------------------------------------------
 // Pure helper: semver-gte for the three-segment versions AD ships
 // ---------------------------------------------------------------------------
@@ -114,6 +168,33 @@ export interface StartupGateDeps {
   recordStartupError: typeof recordStartupError
   /** Process exit hook (terminates by default). */
   exit: (code: number) => never
+  /**
+   * Probe 1 — verify the wrapper Client exposes the `getPermission` method.
+   * Production default checks `typeof client.getPermission === 'function'`.
+   * Tests inject a constant boolean.
+   */
+  probeGetPermission: (client: unknown) => boolean
+  /**
+   * Probe 2 — verify the AD error catalog includes the err_names CSCB
+   * branches on. Production default reads the resolved `agent-director`
+   * dist file and matches `class <Name>\s` for each required name — the
+   * class-declaration site is the structural symptom of a shim that's
+   * caught up to the bundled Go binary. A behavioral `errorFromEnvelope`
+   * round-trip is unusable (the helper falls back to a base
+   * `AgentDirectorError` with `.errName` copied verbatim from the input),
+   * and a bare-identifier match false-positives on the dist's metadata
+   * array that names err_names even when the class is missing.
+   */
+  probeErrorCatalog: () => { ok: true } | { ok: false; missing: string[] }
+  /**
+   * Probe 3 — verify the wrapper Client's `decide()` argv carries
+   * `--request-token`. Production default reads the resolved
+   * `agent-director` dist file and greps for the literal `request-token` —
+   * a static-file probe (no subprocess, no DB write) chosen over the
+   * subprocess fallback per the bug requirements. See the production
+   * defaults block for the resolution + read.
+   */
+  probeDecideArgv: (client: unknown) => Promise<{ ok: true } | { ok: false; detail: string }>
 }
 
 // ---------------------------------------------------------------------------
@@ -138,6 +219,55 @@ const prodDeps: StartupGateDeps = {
   geteuid: () => process.geteuid?.(),
   recordStartupError,
   exit: (code) => process.exit(code),
+  probeGetPermission: (client) =>
+    typeof (client as { getPermission?: unknown }).getPermission === 'function',
+  probeErrorCatalog: () => {
+    // Static-file probe: the runtime `errorFromEnvelope` helper falls back
+    // to constructing a base `AgentDirectorError` (with `.errName` copied
+    // verbatim from the input) when err_name is absent from `ERROR_TABLE`,
+    // so a behavioral round-trip cannot tell catalog-present from
+    // catalog-absent. A bare-identifier regex is also too loose: the shim
+    // carries a metadata array whose `name: "Err..."` literals match every
+    // err_name regardless of whether the class is declared. Anchor instead
+    // on `class <Name>\s` — the class declaration site is emitted once per
+    // typed error and is the defining symptom of a caught-up shim.
+    const src = readAdDistSource()
+    if (src instanceof Error) {
+      // Surface this as "all required names missing" with a diagnostic
+      // detail in the first slot, so the operator sees a complete picture.
+      return { ok: false, missing: [`<read-failed: ${src.message}>`, ...REQUIRED_ERR_NAMES] }
+    }
+    const missing: string[] = []
+    for (const name of REQUIRED_ERR_NAMES) {
+      const re = new RegExp(`class\\s+${name}\\s`)
+      if (!re.test(src)) {
+        missing.push(name)
+      }
+    }
+    return missing.length === 0 ? { ok: true } : { ok: false, missing }
+  },
+  probeDecideArgv: async (_client) => {
+    // Static-file probe: grep the resolved agent-director dist for the
+    // literal `--request-token` flag. Chosen over the subprocess fallback
+    // because it's faster, touches no AD state, and a stale shipped shim
+    // is exactly the file-content condition we're detecting.
+    const src = readAdDistSource()
+    if (src instanceof Error) {
+      return {
+        ok: false,
+        detail: `failed to read agent-director dist for argv probe: ${src.message}`,
+      }
+    }
+    if (src.includes('--request-token')) {
+      return { ok: true }
+    }
+    return {
+      ok: false,
+      detail:
+        `agent-director dist does not include the literal '--request-token' — ` +
+        `buildDecide() is dropping the field.`,
+    }
+  },
 }
 
 function mergeDeps(overrides?: Partial<StartupGateDeps>): StartupGateDeps {
@@ -154,7 +284,7 @@ function mergeDeps(overrides?: Partial<StartupGateDeps>): StartupGateDeps {
  */
 export type StartupGateOutcome =
   | { ok: true; client: unknown; adVersion: string }
-  | { ok: false; phase: 'construct' | 'version' | 'same-user' | 'unexpected'; classLabel: string; message: string }
+  | { ok: false; phase: 'construct' | 'version' | 'api-surface' | 'same-user' | 'unexpected'; classLabel: string; message: string }
 
 /**
  * Run the SR-5.1 startup sequence without exiting. The dispatcher
@@ -280,6 +410,56 @@ export async function runStartupGate(
     }
   }
 
+  // Step 3.5: API surface probes. The version gate above confirms the AD
+  // binary meets MIN_AD_VERSION, but published agent-director npm packages
+  // have shipped a stale TS shim that drops methods (getPermission), drops
+  // CLI flags (--request-token in buildDecide), and misses err_names in the
+  // catalog. Each of those silently breaks CSCB at click-handling time. The
+  // probes run 1 → 2 → 3 and short-circuit on first failure so one operator
+  // message corresponds to one fix.
+  if (!d.probeGetPermission(client)) {
+    d.closeClient(client)
+    return {
+      ok: false,
+      phase: 'api-surface',
+      classLabel: 'ad-shim-missing-get-permission',
+      message:
+        `agent-director Client is missing the 'getPermission' method. ` +
+        `The installed shim is stale relative to the AD binary (${adVersion}). ` +
+        `Run: bun add agent-director@^${MIN_AD_VERSION} (and confirm the resolved version actually ships getPermission).`,
+    }
+  }
+
+  const catalogProbe = d.probeErrorCatalog()
+  if (!catalogProbe.ok) {
+    d.closeClient(client)
+    return {
+      ok: false,
+      phase: 'api-surface',
+      classLabel: 'ad-shim-catalog-incomplete',
+      message:
+        `agent-director TS error catalog is missing required err_names: ` +
+        `${catalogProbe.missing.join(', ')}. ` +
+        `Envelopes with these names would surface as the base AgentDirectorError ` +
+        `instead of typed subclasses, breaking CSCB's instanceof Err<Name> branches. ` +
+        `Run: bun add agent-director@^${MIN_AD_VERSION} (confirm the resolved package ships the full catalog).`,
+    }
+  }
+
+  const argvProbe = await d.probeDecideArgv(client)
+  if (!argvProbe.ok) {
+    d.closeClient(client)
+    return {
+      ok: false,
+      phase: 'api-surface',
+      classLabel: 'ad-shim-decide-drops-token',
+      message:
+        `agent-director shim's decide() does not pass --request-token to the CLI: ${argvProbe.detail} ` +
+        `Permission clicks would resolve against the wrong row. ` +
+        `Run: bun add agent-director@^${MIN_AD_VERSION} (confirm the resolved package's buildDecide includes the flag).`,
+    }
+  }
+
   // Step 4: same-user check on ~/.agent-director/state.db.
   let expectedUid = d.geteuid()
   if (expectedUid === undefined || expectedUid === -1) {

package/src/lib.ts

@@ -14,6 +14,14 @@ import { resolve } from 'path'
 // Constants (re-exported so server.ts and tests share the same values)
 // ---------------------------------------------------------------------------
 
+// True iff the standalone GET SSE stream entry "_GET_stream" is present in the
+// MCP SDK transport's internal _streamMapping — used by handleMessage to detect
+// silent-drop conditions before forwarding a Slack message.
+export function hasGetStreamKey(transport: unknown): boolean {
+  const mapping = (transport as any)?._streamMapping
+  return typeof mapping?.has === 'function' && mapping.has('_GET_stream')
+}
+
 export const MAX_PENDING = 3
 export const MAX_PAIRING_REPLIES = 2
 export const PAIRING_EXPIRY_MS = 60 * 60 * 1000 // 1 hour