feat(bridge): add asyncRewake hooks for idle-Claude delivery

Replace the in-memory pendingBuffer in the Claude Code bridge with a
file-backed queue at ~/.agents/bus/pending/claude-code--<slug>.jsonl.
Both the in-process tool-call drain and the new out-of-process hook
drain script use atomic rename as the synchronisation primitive, so
concurrent drains never duplicate or lose events.

Add hooks/drain.sh and hooks/hooks.json. The hooks declare PostToolUse,
Stop, and UserPromptSubmit entries that invoke drain.sh via asyncRewake.
When pending events exist, drain.sh exits 2 with the content on stderr;
Claude Code wraps it in a <system-reminder> and wakes idle Claude via
the enqueuePendingNotification / useQueueProcessor path.

This removes the dependency on notifications/claude/channel (gated by
tengu_harbor_ledger) for delivery to idle Claude sessions.

Author: Mearman

.claude-plugin/plugin.json

@@ -8,6 +8,7 @@
   "homepage": "https://github.com/ExaDev/agent-comms#readme",
   "repository": "https://github.com/ExaDev/agent-comms",
   "license": "MIT",
+  "hooks": "./hooks/hooks.json",
   "mcpServers": {
     "agent-comms": {
       "command": "npx",

README.md

@@ -217,7 +217,7 @@ agent_comms({ action: "update", visibility: "hidden" })
 
 When `streamingBehavior` is absent, each bridge falls back to its existing heuristic: actionable events (DMs, room messages, invites) are treated as `steer`; status changes and membership events are treated as `info`.
 
-**Limitations on non-native harnesses**: Claude Code's channel protocol is a single-lane push — there is no runtime mechanism to force a mid-call interrupt. The `[STEER]` and `[FOLLOWUP]` markers are visible in the session and structured `meta.streamingBehavior` carries the intent, but acting on them is down to the receiving agent. The pi bridge honours the hint natively.
+**Claude Code delivery mechanism**: Events are written to `~/.agents/bus/pending/claude-code--<cwd-slug>.jsonl`. Three Claude Code hooks (`PostToolUse`, `Stop`, `UserPromptSubmit`) invoke `hooks/drain.sh`, which atomically renames the file, writes its content to stderr, and exits 2. Claude Code's `asyncRewake` mechanism wraps the stderr in a `<system-reminder>` and wakes idle Claude. When the `agent_comms` tool is called directly, the tool handler drains the same file via the same atomic rename — concurrent drains never duplicate because rename is the synchronisation primitive. The `[STEER]` and `[FOLLOWUP]` markers and `meta.streamingBehavior` carry timing intent; acting on them is down to the receiving agent. The pi bridge honours the hint natively via `deliverAs`.
 
 ## Room types
 

hooks/drain.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Drain pending agent-comms events and exit 2 to wake idle Claude via asyncRewake.
+#
+# Called by Claude Code hooks (PostToolUse, Stop). If there are pending events,
+# writes them to stderr and exits 2 — Claude Code wraps the stderr in a
+# <system-reminder> and enqueues it as a task-notification, waking idle Claude.
+#
+# Uses atomic rename to drain so concurrent drains (in-process tool drain vs
+# this out-of-process hook) never duplicate or lose events.
+
+set -euo pipefail
+
+SLUG="${PWD//[^a-zA-Z0-9]/_}"
+PENDING="$HOME/.agents/bus/pending/claude-code--${SLUG}.jsonl"
+DRAINING="${PENDING}.draining-$$-$(date +%s%N 2>/dev/null || date +%s)"
+
+# Atomic drain — if rename fails (file absent), nothing to surface.
+if ! mv "$PENDING" "$DRAINING" 2>/dev/null; then
+  exit 0
+fi
+
+CONTENT=$(cat "$DRAINING")
+rm -f "$DRAINING"
+
+if [ -z "$CONTENT" ]; then
+  exit 0
+fi
+
+echo "Pending agent-comms messages:" >&2
+while IFS= read -r line; do
+  [ -n "$line" ] && echo "  📬 $line" >&2
+done <<< "$CONTENT"
+
+exit 2

hooks/hooks.json

@@ -0,0 +1,40 @@
+{
+  "PostToolUse": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/drain.sh",
+          "asyncRewake": true,
+          "timeout": 5
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/drain.sh",
+          "asyncRewake": true,
+          "timeout": 5
+        }
+      ]
+    }
+  ],
+  "UserPromptSubmit": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/drain.sh",
+          "timeout": 5
+        }
+      ]
+    }
+  ]
+}

package.json

@@ -34,7 +34,8 @@
   },
   "files": [
     "dist",
-    ".claude-plugin/"
+    ".claude-plugin/",
+    "hooks/"
   ],
   "bin": {
     "agent-comms": "dist/cli.js"

src/bridges/claude-code/channel.ts

@@ -2,13 +2,20 @@
  * Agent Comms — Claude Code channel bridge.
  *
  * MCP channel server that provides the "agent_comms" tool and pushes
- * incoming messages into Claude's context via <channel> events.
+ * incoming messages into Claude's context via <channel> events and hooks.
  * Uses TCP mesh for real-time delivery — no filesystem polling.
  *
  * Run via: npx agent-comms bridge claude-code
- * Requires: claude --dangerously-load-development-channels
+ *
+ * Pending events are persisted to ~/.agents/bus/pending/claude-code--<slug>.jsonl
+ * so the asyncRewake hook scripts (hooks/drain.sh) can drain them out-of-process
+ * and wake idle Claude via exit code 2.
  */
 
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -31,14 +38,51 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
+  return typeof err === "object" && err !== null && "code" in err;
+}
+
+function pendingFilePath(cwd: string): string {
+  const slug = cwd.replace(/[^a-zA-Z0-9]/g, "_");
+  return path.join(
+    os.homedir(),
+    ".agents",
+    "bus",
+    "pending",
+    `claude-code--${slug}.jsonl`,
+  );
+}
+
+function appendPending(filePath: string, line: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, line + "\n");
+}
+
+function drainPending(filePath: string): string[] {
+  const drainPath = `${filePath}.draining-${String(process.pid)}-${String(Date.now())}`;
+  try {
+    fs.renameSync(filePath, drainPath);
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") return [];
+    throw err;
+  }
+  const content = fs.readFileSync(drainPath, "utf-8");
+  fs.unlinkSync(drainPath);
+  return content
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
 export async function run(): Promise<void> {
   const identity = generateIdentity();
   const store = new MeshStore();
   store.peerId = identity.fingerprint;
   store.setTransport(new TlsTransport(store.events, identity));
   const tool = new CommsTool(store, store.discovery);
   let agentId: string | undefined;
-  const pendingBuffer: string[] = [];
+
+  const pendingFile = pendingFilePath(process.cwd());
 
   const mcp = new McpServer(
     { name: "agent-comms", version: "0.2.0" },
@@ -49,16 +93,16 @@ export async function run(): Promise<void> {
     },
   );
 
-  // All events land in the drain buffer so idle-Claude never silently misses
-  // a message. Actionable events also get an eager channel push for mid-turn
-  // delivery. If the push fired and Claude caught it, the drain will echo it
-  // on the next tool call — acceptable duplication, far better than loss.
+  // All events are written to the pending file so the out-of-process hook
+  // drain script can surface them to idle Claude via asyncRewake exit 2.
+  // Actionable events also get an eager channel push for mid-turn delivery
+  // when channels are enabled (--dangerously-load-development-channels).
   store.onDelivery = async (_targetId: string, event) => {
     const line = formatDeliveryEvent(event);
     const hint = extractStreamingBehavior(event);
     const shouldPush = isActionableEvent(event) && hint !== "info";
 
-    pendingBuffer.push(line);
+    appendPending(pendingFile, line);
 
     if (shouldPush) {
       await mcp.server.notification({
@@ -82,7 +126,7 @@ export async function run(): Promise<void> {
         "Cross-harness agent communication mesh. Actions:",
         "register, update, whoami, create_room, list_rooms, join_room, leave_room,",
         "send, dm, list_agents, read_room, invite, decline_invite, kick, destroy_room.",
-        'Incoming messages appear as <channel source="agent-comms"> events.',
+        'Incoming messages appear as <channel source="agent-comms"> events or [comms] Pending prefix.',
         "Use streamingBehavior on send/dm: steer (act now), followUp (act when idle), info (whenever, default).",
       ].join(" "),
       inputSchema: MCP_TOOL_PARAMS,
@@ -115,7 +159,7 @@ export async function run(): Promise<void> {
         action,
       );
 
-      const pending = pendingBuffer.splice(0);
+      const pending = drainPending(pendingFile);
       const prefix =
         pending.length > 0
           ? `[comms] Pending:\n${pending.map((l) => `  📬 ${l}`).join("\n")}\n\n`