claude-slack-channel-bots 0.6.6 → 0.7.0

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) **installed system-wide** as a prerequisite — like `git` or `docker`. CSCB no longer vendors the AD binary. The npm `agent-director` package CSCB depends on is now a thin TypeScript shim that locates the system-installed binary at startup via `resolveSystemBinary()` / `Client.create()` and refuses to start when the binary is missing, too old, or unreachable. The startup gate enforces AD's required version (declared by AD in `dist/version-floor.json`) and reports the required version on mismatch. 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.
 
@@ -52,9 +52,74 @@ See the sections below for manual configuration details if you prefer not to use
 | `darwin-x64` (Intel Mac) | **Not supported** by agent-director |
 | Windows | **Not supported** by agent-director |
 
-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.
+If the host is unsupported, the system-installed `agent-director` itself will refuse to install or run; CSCB's startup gate then exits non-zero with one of the `ad-system-install-*` class labels (see [Startup errors](#startup-errors)) and writes the failure to `~/.claude/channels/slack/startup-errors.log` and stderr. Consult [agent-director's documentation](https://github.com/gabemahoney/agent-director) for the canonical platform support list.
 
-> **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. From v0.7.0 onward, AD ships as a thin npm shim around a system-installed binary, and CSCB defers the minimum-AD-version decision to AD itself via `dist/version-floor.json` (AD's library-side `Client.create()` reads it). CSCB's `package.json` caret-pin on `agent-director` governs npm resolution of AD's TypeScript shim only — not the runtime floor, which is owned by the AD release the system binary belongs to.
+
+### Checking your agent-director install
+
+Before starting the server, you can confirm `agent-director` is installed system-wide and meets the declared minimum with:
+
+```sh
+bun run install-check
+```
+
+The script calls the same discovery + floor-comparison pipeline the startup gate uses (it reads AD's `dist/version-floor.json`, calls `resolveSystemBinary()`, and compares versions via `semver.gte`). It exits 0 on success with a single-line block naming `agent-director`, the absolute resolved binary path, the detected version, and the floor. On failure it writes one of the canonical class labels to stderr and exits non-zero:
+
+- `ad-system-install-not-found` — no agent-director on PATH or at the standard install path. Install AD and retry. The stderr also points at the install-cscb skill for interactive remediation.
+- `ad-system-install-too-old` — AD binary is below the floor. Upgrade AD and retry. The stderr points at the skill.
+- `ad-system-install-unreachable` — AD discovered but the probe could not invoke it (eight `.reason` values exposed verbatim). The stderr points at the skill.
+- `ad-version-floor-unreadable` — `dist/version-floor.json` is missing, malformed, or lacks `min_binary_version`. The remediation is to reinstall `agent-director` from npm; the install-cscb skill cannot fix a corrupt AD package, so this case does NOT append the skill instructions block.
+
+The script is purely diagnostic — it never prompts, never runs an install command, never fetches the skill. The startup gate enforces the same floor automatically at server boot via AD's `Client.create()`; `install-check` is for operators who want to confirm their setup ahead of time.
+
+### Installing the install-cscb skill
+
+If `bun run install-check` (or the startup gate) reports one of the
+`ad-system-install-*` failure classes, you can install the `install-cscb`
+Claude skill for an interactive walkthrough. The skill drives the same
+shared check module but walks you through install/upgrade and a
+per-reason remediation flow for each of the eight
+`ErrSystemInstallUnreachable.reason` values.
+
+The skill is NOT auto-installed by `bun install` — fetch it manually
+from CSCB's GitHub repo and place it in your local Claude skills
+folder:
+
+1. **Fetch** `SKILL.md` from:
+
+   ```
+   https://github.com/gabemahoney/claude-slack-channel-bots/blob/main/skills/install-cscb/SKILL.md
+   ```
+
+   (The startup gate's `ad-system-install-*` error log line includes
+   this URL automatically.)
+
+2. **Place** it at:
+
+   ```
+   ~/.claude/skills/install-cscb/SKILL.md
+   ```
+
+3. **Invoke** the skill from Claude Code:
+
+   ```
+   /install-cscb
+   ```
+
+The skill calls `bun run install-check` on each iteration, surfaces
+`agent-director`'s published install/upgrade command verbatim (no
+CSCB-owned install command — AD's documentation is the source of
+truth), prompts before running, and loops until the check passes or
+you decline. The `ad-version-floor-unreadable` class is handled
+separately: the skill prints reinstall-from-npm guidance and does NOT
+loop on it (the skill cannot fix a corrupt AD npm package).
+
+The published CSCB npm tarball includes `skills/install-cscb/SKILL.md`
+under its `files` array, so the skill source is also available via
+`node_modules/claude-slack-channel-bots/skills/install-cscb/SKILL.md`
+after `bun install`. The manual GitHub-fetch step above is for users
+who haven't yet installed CSCB at all.
 
 ---
 
@@ -433,12 +498,15 @@ CSCB writes fatal startup errors to `~/.claude/channels/slack/startup-errors.log
 
 Classes you may see:
 
-- `ad-platform-package-missing` — agent-director's platform-native peer dependency is absent. The host is unsupported by agent-director.
-- `ad-unsupported-platform` — agent-director's runtime check rejected the host's `process.platform`/`process.arch` tuple.
+- `ad-system-install-not-found` — `Client.create()` could not locate an `agent-director` binary on PATH or at the standard install path. Install agent-director system-wide and retry. The log line appends a manual-skill-install instructions block pointing at `skills/install-cscb/SKILL.md` (URL, target path under `~/.claude/skills/`, and invocation command `/install-cscb`) for the interactive install/upgrade flow.
+- `ad-system-install-too-old` — the system-installed agent-director binary is below the floor declared in `dist/version-floor.json`. The log line names the detected and required versions, and appends the manual-skill-install instructions block.
+- `ad-system-install-unreachable` — agent-director was discovered but the probe could not execute it (e.g. permission bits, broken symlink, runtime crash). The log line surfaces AD's supplied `err.reason` value verbatim (one of `not-executable`, `not-a-regular-file`, `probe-timeout`, `probe-nonzero-exit`, `probe-killed-by-signal`, `unparseable-version`, `spawn-failed`, `other`) and appends the manual-skill-install instructions block.
 - `ad-bun-version-too-old` — agent-director needs Bun `>= 1.0.21`. Upgrade Bun.
-- `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 the system-installed binary. Reinstall a matching `agent-director` version and confirm the resolved package 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 a matching `agent-director` version and confirm `buildDecide` carries the flag.
+- `ad-version-floor-unreadable` — `node_modules/agent-director/dist/version-floor.json` could not be read, parsed, or is missing `.min_binary_version`. This is a packaging defect — reinstall `agent-director` from npm. Surfaced by `bun run install-check`; the startup gate itself does not emit this label (it relies on `Client.create()`, which fails differently when the AD package is corrupt).
 - `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 +569,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 +582,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.6",
+  "version": "0.7.0",
   "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",
@@ -23,6 +22,7 @@
     "start": "bun install --no-summary && bun src/server.ts",
     "pretest": "bun scripts/fixup-bun-cache.ts && bun scripts/check-no-toplevel-mock-module.ts",
     "check:mocks": "bun scripts/check-no-toplevel-mock-module.ts",
+    "install-check": "bun scripts/install-check.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
@@ -30,11 +30,12 @@
     "@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.7.0",
+    "semver": "^7.6.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
-    "semver": "^7.6.0",
+    "@types/semver": "^7.7.1",
     "typescript": "^5.4.0"
   },
   "license": "MIT",

package/skills/install-cscb/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: install-cscb
+description: Interactive walkthrough that installs or upgrades the system-installed `agent-director` so claude-slack-channel-bots can boot. Drives Epic 2's bun run install-check and per-reason remediation.
+version: 1.0.0
+author: Gabe Mahoney
+license: MIT
+user-invocable: true
+argument-hint: "(no arguments)"
+allowed-tools: [Bash, Read]
+---
+
+# /install-cscb
+
+Diagnose and fix a broken or missing `agent-director` system install so
+`claude-slack-channel-bots` (CSCB) can boot. This skill is the interactive
+counterpart to the diagnostic `bun run install-check` script — same shared
+check module, but with a guided remediation loop for each failure class.
+
+## When to invoke
+
+Invoke this skill when CSCB's startup gate emits one of these class labels
+in `~/.claude/channels/slack/startup-errors.log`:
+
+- `ad-system-install-not-found`
+- `ad-system-install-too-old`
+- `ad-system-install-unreachable`
+
+The gate appends a pointer to this skill on those three classes. Other
+failure classes (`ad-bun-version-too-old`, `ad-shim-*`, `ad-same-user`,
+`ad-version-floor-unreadable`) are NOT remediated by this skill — see
+the README's Startup-errors section for those.
+
+## Step 1 — Run the shared check
+
+From the CSCB project root, run:
+
+```sh
+bun run install-check
+```
+
+This is the same command you can run directly from the shell. It calls
+the shared check module (`src/install-check.ts`) which is also what this
+skill drives internally on every iteration.
+
+Read the output carefully:
+
+- **Exit 0 + "OK"**: agent-director is satisfied. Print the resolved
+  binary path, detected version, and floor from the success output, then
+  exit cleanly. No further action required.
+
+- **Exit non-zero**: identify the class label on stderr (one of
+  `ad-system-install-not-found`, `ad-system-install-too-old`,
+  `ad-system-install-unreachable`, `ad-version-floor-unreadable`) and
+  branch on it as documented below.
+
+## Step 2 — Identify the user's platform
+
+Detect the platform via `uname -sm`. CSCB supports two platforms:
+
+- **linux-x64** — `Linux x86_64`
+- **darwin-arm64** — `Darwin arm64` (Apple Silicon Mac)
+
+Any other platform is unsupported by `agent-director` itself and the
+skill cannot proceed; surface the platform mismatch to the user and
+exit non-zero.
+
+## Step 3 — Branch on the class label
+
+### `ad-system-install-not-found` — agent-director missing
+
+Surface the install command published by `agent-director` verbatim for
+the detected platform. Do NOT invent or maintain a CSCB-owned command —
+consult agent-director's documentation
+(<https://github.com/gabemahoney/agent-director>) for the canonical
+install procedure. The current installer is `install.sh` from
+agent-director's repo; recommend running it.
+
+Prompt the user (using AskUserQuestion or an equivalent) — the literal
+command must be visible:
+
+> agent-director is not installed system-wide. Run the AD-published install
+> command? `<command>`
+>
+> - **Yes** — run the command via Bash and continue.
+> - **No** — install manually then continue.
+
+- **Yes**: run the command via Bash. Capture stdout/stderr for the user
+  to see. Return to Step 1.
+- **No**: instruct the user to install manually. Wait for confirmation.
+  Return to Step 1.
+
+If the user declines to proceed at any point, exit non-zero with a
+one-line summary: "Aborted by user — agent-director still not installed."
+
+### `ad-system-install-too-old` — agent-director below floor
+
+Same flow as `ad-system-install-not-found` but with the upgrade command
+instead of the install command. Surface the detected version and the
+required floor from the stderr block so the user understands what they
+are upgrading from and to.
+
+Prompt:
+
+> agent-director is installed but at version `<detected>`, below the
+> required floor `<required>`. Run the AD-published upgrade command?
+> `<command>`
+>
+> - **Yes** — run the command via Bash and continue.
+> - **No** — upgrade manually then continue.
+
+- **Yes**: run via Bash. Return to Step 1.
+- **No**: wait for manual upgrade. Return to Step 1.
+
+### `ad-system-install-unreachable` — exhaustive reason switch
+
+The stderr block carries an `err.reason` value verbatim. Branch on it
+explicitly — every reason has a named branch, no `default:`-only
+fallthrough.
+
+1. **`not-executable`** — the agent-director file exists but lacks the
+   executable bit. Show the user the binary path from the stderr block
+   and suggest:
+   ```sh
+   chmod +x <binary_path>
+   ```
+   Re-run Step 1.
+
+2. **`not-a-regular-file`** — the path resolved by `resolveSystemBinary()`
+   is a directory, broken symlink, or other non-file. Recommend
+   inspection (`ls -la <binary_path>`) and removal of the bad entry,
+   then re-installation via the AD install command. Re-run Step 1.
+
+3. **`probe-timeout`** — `agent-director --version` did not return within
+   the probe window. Likely the binary is hanging on startup
+   (corrupted, mismatched architecture, missing shared library).
+   Recommend a manual `<binary_path> --version` invocation to confirm,
+   then reinstall via the AD install command. Re-run Step 1.
+
+4. **`probe-nonzero-exit`** — `agent-director --version` exited with a
+   non-zero code. The stderr block surfaces `exitCode` and any
+   `diagnostic` from AD. Show the user the values and recommend a
+   manual reproduction (`<binary_path> --version`), then reinstall.
+   Re-run Step 1.
+
+5. **`probe-killed-by-signal`** — `agent-director --version` was killed
+   by a signal (SIGSEGV, SIGBUS, etc.). The stderr block surfaces
+   `signal`. The binary is likely corrupted or built for a different
+   architecture. Recommend a full reinstall via the AD install command.
+   Re-run Step 1.
+
+6. **`unparseable-version`** — `agent-director --version` returned but
+   the output could not be parsed as semver. The stderr's `diagnostic`
+   field carries the raw output. Likely the installed binary is from
+   a pre-release line that uses non-semver tags (e.g. `v0.6.3-dev`
+   without sentinel handling). Recommend upgrading to a release AD
+   version via the AD install command. Re-run Step 1.
+
+7. **`spawn-failed`** — the OS rejected the spawn before the subprocess
+   ran (ENOENT after stat succeeded, EACCES, EPERM, etc.). The stderr's
+   `diagnostic` field carries the underlying OS error. Recommend
+   checking filesystem permissions, then reinstalling. Re-run Step 1.
+
+8. **`other`** — an unexpected failure mode AD's `resolveSystemBinary()`
+   could not classify. Print the raw underlying error message from
+   `detail.underlying` (or `diagnostic`) and direct the user to file
+   a bug against `agent-director`:
+   <https://github.com/gabemahoney/agent-director/issues>
+
+   This is the only branch that recommends bug-filing rather than a
+   local remediation step.
+
+After rendering the per-reason remediation, ask the user to confirm
+they have applied it, then return to Step 1.
+
+### `ad-version-floor-unreadable` — corrupt agent-director npm package
+
+This class is NOT a system-install problem — it indicates the
+`node_modules/agent-director/dist/version-floor.json` file is missing,
+malformed, or lacks `.min_binary_version`. The skill cannot walk the
+user through fixing a corrupt AD npm package.
+
+Print the reinstall guidance:
+
+> The agent-director npm package appears corrupted. Reinstall it from
+> npm in CSCB's project root:
+>
+> ```sh
+> bun add agent-director@latest
+> ```
+
+Then exit. Do NOT loop on this class — the user must manually verify
+the AD package is intact before re-invoking the skill.
+
+## Step 4 — Loop or exit
+
+After each remediation step, re-run Step 1. The skill keeps looping
+until the check passes (exit cleanly with the success output) or the
+user declines to proceed (exit non-zero with the abort summary).
+
+## Notes
+
+- This skill does not maintain its own list of agent-director install
+  commands. AD's documentation is the source of truth; the skill
+  surfaces AD's published command verbatim.
+- This skill does not touch `~/.claude/channels/slack/` or CSCB's
+  routing configuration. It only acts on the system-wide
+  `agent-director` install.
+- The skill is callable repeatedly; each invocation re-runs Step 1
+  from a clean state.

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: