@huynle/hub 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Hub: a harness-agnostic central hub your AI agent harnesses connect to (OpenCode first). Follow, steer and stop sessions from your phone or browser, with notifications, optional hands-free Voice and a self-hostable server.",
   "license": "MIT",
   "author": "Huy Le",
@@ -45,16 +45,57 @@
     "tui.ts",
     "rpc.ts",
     "src",
+    "packages/protocol/src",
+    "packages/protocol/package.json",
+    "packages/sdk/src",
+    "packages/sdk/package.json",
+    "packages/cli/dist/hub-cli.js",
+    "packages/runtime-sdk/src",
+    "packages/runtime-sdk/package.json",
+    "packages/node/src",
+    "packages/node/package.json",
+    "packages/runtime-openshell/src",
+    "packages/runtime-openshell/package.json",
+    "packages/runtime-openshell/image",
+    "packages/spoke-sdk/src",
+    "packages/spoke-sdk/package.json",
+    "packages/claude-code/src",
+    "packages/claude-code/package.json",
+    "packages/preset/src",
+    "packages/preset/presets",
+    "packages/preset/package.json",
+    "packages/codex/src",
+    "packages/codex/package.json",
     "bin",
     "web/dist",
     "docker",
     "Dockerfile",
     "scripts/hub-local.sh",
     "scripts/io.github.huynle.hub.plist",
+    "scripts/io.github.huynle.hub-node.plist",
+    "scripts/hub-node.service",
+    "scripts/io.github.huynle.hub-claude-code.plist",
+    "scripts/hub-claude-code.service",
+    "scripts/io.github.huynle.hub-codex-spoke.plist",
+    "scripts/hub-codex-spoke.service",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
+  "workspaces": [
+    "packages/protocol",
+    "packages/sdk",
+    "packages/cli",
+    "packages/runtime-sdk",
+    "packages/node",
+    "packages/runtime-openshell",
+    "packages/spoke-sdk",
+    "packages/testkit",
+    "packages/claude-code",
+    "packages/conformance",
+    "packages/preset",
+    "packages/codex"
+  ],
   "engines": {
     "bun": ">=1.3"
   },
@@ -65,9 +106,10 @@
     "test": "bun test",
     "typecheck": "tsc --noEmit && tsc --noEmit -p web",
     "build:web": "vite build --config web/vite.config.ts",
+    "build:cli": "bun build packages/cli/src/main.ts --target=node --outfile=packages/cli/dist/hub-cli.js",
     "dev:web": "vite --config web/vite.config.ts",
     "test:e2e": "bun web/e2e/smoke.ts",
-    "prepack": "npm run build:web",
+    "prepack": "npm run build:web && npm run build:cli",
     "hub": "bun bin/hub.ts"
   },
   "dependencies": {
@@ -78,6 +120,7 @@
   "devDependencies": {
     "@types/bun": "^1.4.2",
     "@types/web-push": "^3.6.4",
+    "onnxruntime-web": "1.23.2",
     "playwright-core": "^1.64.1",
     "solid-js": "^1.9.17",
     "typescript": "^5.9.3",

package/packages/claude-code/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@huynle/hub-claude-code",
+  "version": "0.7.1",
+  "private": true,
+  "description": "The Claude Code hooks spoke: per-user daemon, hook bridge, plugin dir, `hub claude` wrapper and daemon-backed MCP server (internal; shipped inside @huynle/hub, not published on its own).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  }
+}

package/packages/claude-code/src/bridge.ts

@@ -0,0 +1,79 @@
+// The hook bridge: the command Claude Code runs for every hook of the plugin (`hub claude-code hook [--rewake]
+// [--wait <seconds>]`, an absolute path in hooks.json). It reads the hook's stdin JSON, sends it to the per-user
+// daemon over its Unix socket, and does what the daemon answers: print the hook output JSON, write the session's
+// env file (SessionStart's CLAUDE_ENV_FILE, mode 0600), print stderr and exit 2 (the asyncRewake Stop hook only:
+// exit 2 from any other hook would block Claude Code; HUB_CLAUDE_REWAKE=off turns that hook into a no-op). It fails open: no daemon, a bad or late reply, any error →
+// exit 0 without output, as if the hook were not there.
+import { chmodSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { parseHookInput } from "./hook-input.ts"
+import { ask, WIRE_VERSION, type BridgeRequest } from "./wire.ts"
+
+export interface HookIo {
+  readonly argv: readonly string[]
+  readonly stdin: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly socketPath: string
+  stdout(s: string): void
+  stderr(s: string): void
+  /** Give up on the daemon after this long (default: never; Claude Code's hook timeout ends the hook). */
+  readonly timeoutMs?: number
+}
+
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/
+/** Hook input fields the daemon never needs (a tool's whole output). */
+const DROPPED = ["tool_response"] as const
+
+const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** The hook's flags: --rewake, --wait <seconds>. */
+function flags(argv: readonly string[]): { rewake: boolean; waitMs?: number } {
+  const rewake = argv.includes("--rewake")
+  const at = argv.indexOf("--wait")
+  const seconds = at >= 0 ? Number(argv[at + 1]) : NaN
+  return { rewake, ...(Number.isFinite(seconds) && seconds >= 0 ? { waitMs: Math.round(seconds * 1000) } : {}) }
+}
+
+/** Writes `export NAME='value'` lines for the valid names to the env file (0600). */
+function writeEnvFile(file: string | undefined, env: Record<string, unknown>): void {
+  if (!file || !path.isAbsolute(file)) return
+  const lines = Object.entries(env)
+    .filter(([name, value]) => ENV_NAME.test(name) && typeof value === "string" && !value.includes("\n"))
+    .map(([name, value]) => `export ${name}=${quote(value as string)}\n`)
+  if (!lines.length) return
+  writeFileSync(file, lines.join(""), { mode: 0o600 })
+  chmodSync(file, 0o600)
+}
+
+/** Runs one hook; resolves with its exit code (0 unless a rewake reply says 2). Never throws. */
+export async function runHook(io: HookIo): Promise<number> {
+  try {
+    let raw: unknown
+    try {
+      raw = JSON.parse(io.stdin)
+    } catch {
+      return 0
+    }
+    const input = parseHookInput(raw)
+    if (!input) return 0
+    const sent: Record<string, unknown> = { ...input }
+    for (const key of DROPPED) delete sent[key]
+    const { rewake, waitMs } = flags(io.argv)
+    // A print run without streaming input (`hub claude -p`) waits on an asyncRewake hook until it ends: nothing to wake.
+    if (rewake && io.env.HUB_CLAUDE_REWAKE === "off") return 0
+    const launch = io.env.HUB_CLAUDE_LAUNCH
+    const req: BridgeRequest = { v: WIRE_VERSION, kind: "hook", input: sent, ...(launch ? { launch } : {}), ...(rewake ? { rewake: true as const } : {}), ...(waitMs !== undefined ? { waitMs } : {}) }
+    const reply = await ask(io.socketPath, req, io.timeoutMs !== undefined ? { timeoutMs: io.timeoutMs } : {})
+    if (!isObject(reply)) return 0
+    if (isObject(reply.env)) writeEnvFile(io.env.CLAUDE_ENV_FILE, reply.env)
+    if (rewake && reply.exit === 2) {
+      if (typeof reply.stderr === "string") io.stderr(reply.stderr)
+      return 2
+    }
+    if (isObject(reply.output)) io.stdout(`${JSON.stringify(reply.output)}\n`)
+    return 0
+  } catch {
+    return 0
+  }
+}

package/packages/claude-code/src/daemon.ts

@@ -0,0 +1,339 @@
+// The per-user Claude Code spoke daemon (decision fx04e42c point 4): one process per user, connected to the hub with
+// the machine token (read-only from the spoke's config.json) as the machine's claude-code hooks service (evidence
+// "hooks", kind "service"), serving the hook bridges, the wrapper and the MCP pipes of every Claude Code session on
+// the machine over a Unix socket in a private directory. ClaudeSessions holds the sessions' state; this file wires
+// it to the hub (HarnessSpoke: ops permission and stop, deliver, prompt messages, reject messages) and to the socket.
+//
+// With `launch` options it also starts Claude Code for hub launches (features create, launch, turn, interrupt):
+// a create's directory must be under the node's workspace roots (node.json); the daemon reports the new session at
+// once and runs its claude headless (launcher.ts) with the hub plugin, so its hooks come back here like any other
+// session's. turn and interrupt reach only those sessions (stdin user messages, control requests); a terminal
+// session refuses them. stop interrupts a launched session's running turn at once, besides the hook-level stop.
+// Stopping the daemon ends the claude processes it started.
+//
+// A `hub claude` run registers its pid ("launch"); the daemon checks it now and then and ends the run's sessions
+// when the process is gone (Claude Code killed without SessionEnd), and at once when the wrapper reports its exit.
+import { randomBytes, randomUUID } from "node:crypto"
+import { chmodSync, lstatSync, unlinkSync } from "node:fs"
+import { createServer, type Server, type Socket } from "node:net"
+import path from "node:path"
+import type { ResultFor, ServerRequest } from "../../protocol/src/index.ts"
+import { HarnessSpoke, type HarnessSpokeOptions, type ModifierFeature, type OpHandlers } from "../../spoke-sdk/src/index.ts"
+import { parseHookInput } from "./hook-input.ts"
+import { ensurePrivateDir, SOCKET_PATH_MAX } from "./paths.ts"
+import { createMcpRouter, MCP_END, type McpRouter } from "./mcp.ts"
+import { ClaudeLauncher, launchAgent, launchDirectory, launchModel } from "./launcher.ts"
+import { hubReferences } from "./references.ts"
+import { ClaudeSessions, type SessionsOptions } from "./sessions.ts"
+import { ask, onLines, WIRE_VERSION } from "./wire.ts"
+
+export const HARNESS = "claude-code"
+const DEFAULT_LIVENESS_MS = 30_000
+const LAUNCHES_MAX = 1000
+
+/** What the daemon needs to start Claude Code for hub launches (features create, launch, turn, interrupt). */
+export interface DaemonLaunchOptions {
+  /** The claude executable. */
+  readonly bin: string
+  /** The hub plugin directory launched sessions load (written on demand). */
+  readonly pluginDir: () => string
+  /** The node's workspace roots (node.json): a create's directory must be under one. */
+  readonly roots: () => readonly string[]
+  /** The environment claude starts with (default the daemon's). */
+  readonly env?: Readonly<Record<string, string | undefined>>
+}
+
+export interface DaemonOptions {
+  readonly socketPath: string
+  readonly server: string
+  /** The machine token (never logged). */
+  readonly token: string
+  readonly harnessVersion: string
+  readonly pluginVersion: string
+  readonly directory: string
+  readonly tokenWaitMs?: number
+  readonly permissionWaitMs?: number
+  /** How often launches' processes are checked (default 30 s). */
+  readonly livenessIntervalMs?: number
+  /** Prompt references (default: looked up at the hub with the session's token). */
+  readonly references?: SessionsOptions["references"]
+  readonly log?: (line: string) => void
+  readonly socket?: HarnessSpokeOptions["socket"]
+  readonly backoff?: HarnessSpokeOptions["backoff"]
+  /** Start Claude Code for hub launches; absent: the daemon only follows sessions started in terminals. */
+  readonly launch?: DaemonLaunchOptions
+}
+
+export interface ClaudeDaemon {
+  readonly state: HarnessSpoke["state"]
+  readonly spoke: HarnessSpoke
+  readonly sessions: ClaudeSessions
+  stop(): Promise<void>
+}
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM"
+  }
+}
+
+const str = (v: unknown) => (typeof v === "string" && v ? v : undefined)
+
+/** Takes the socket path: refuses when a daemon answers there, removes a stale socket file. */
+async function claimSocket(socketPath: string): Promise<void> {
+  if (Buffer.byteLength(socketPath) > SOCKET_PATH_MAX) throw new Error(`The socket path ${socketPath} is too long for a Unix socket (at most ${SOCKET_PATH_MAX} bytes); set HUB_CLAUDE_SOCKET to a shorter one`)
+  ensurePrivateDir(path.dirname(socketPath))
+  let exists = false
+  try {
+    lstatSync(socketPath)
+    exists = true
+  } catch {}
+  if (!exists) return
+  const reply = (await ask(socketPath, { v: WIRE_VERSION, kind: "ping" }, { timeoutMs: 1000 })) as { ok?: unknown } | undefined
+  if (reply?.ok === true) throw new Error(`A Claude Code spoke daemon is already running on ${socketPath}`)
+  unlinkSync(socketPath)
+}
+
+export async function startDaemon(options: DaemonOptions): Promise<ClaudeDaemon> {
+  await claimSocket(options.socketPath)
+  const log = options.log ?? (() => {})
+  let sessions!: ClaudeSessions
+  /** Launch key (HUB_CLAUDE_LAUNCH) of each session the daemon started, by its native ID. */
+  const launchKeys = new Map<string, string>()
+  const launch = options.launch
+  const launcher = launch
+    ? new ClaudeLauncher({
+        bin: launch.bin,
+        env: launch.env ?? process.env,
+        log,
+        onExit: (native) => {
+          const key = launchKeys.get(native)
+          launchKeys.delete(native)
+          if (key) sessions.endLaunch(key)
+        },
+      })
+    : undefined
+
+  /** The native ID of a session the daemon launched (and still runs); throws for any other. */
+  const launchedNative = (sessionID: string): string => {
+    const native = sessions.nativeOf(sessionID)
+    if (native === undefined || !launcher?.has(native)) throw new Error(`Session ${sessionID} runs in a terminal, not launched by the hub: Claude Code takes hub turns and interrupts only in sessions the hub launched (send it a message instead)`)
+    return native
+  }
+
+  async function create(req: Extract<ServerRequest, { op: "create" }>): Promise<ResultFor["create"]> {
+    if (!launch || !launcher) throw new Error("This Claude Code daemon does not start sessions")
+    if (req.herdrWorkspace !== undefined) throw new Error("Claude Code sessions cannot be opened in a Herdr workspace yet")
+    const directory = launchDirectory(req.directory, launch.roots())
+    const agent = launchAgent(req.agent)
+    const model = launchModel(req.model)
+    const native = randomUUID()
+    const key = `cl_${randomBytes(8).toString("hex")}`
+    const sessionID = sessions.launched({ sessionID: native, cwd: directory, launch: key, ...(req.title ? { title: req.title } : {}) })
+    launchKeys.set(native, key)
+    try {
+      await launcher.start({ sessionID: native, directory, launch: key, pluginDir: launch.pluginDir(), socketPath: options.socketPath, ...(model ? { model } : {}), ...(agent ? { agent } : {}) })
+    } catch (cause) {
+      launchKeys.delete(native)
+      sessions.endLaunch(key)
+      throw cause
+    }
+    log(`launched claude for ${sessionID}${req.launchID ? ` (launch ${req.launchID})` : ""} in ${directory}`)
+    return { sessionID }
+  }
+
+  async function turn(req: Extract<ServerRequest, { op: "turn" }>): Promise<ResultFor["turn"]> {
+    const native = launchedNative(req.sessionID)
+    sessions.hubPrompt(native)
+    const result = await launcher!.turn(native, req.text, req.images ?? [])
+    sessions.turnEnded(native, result.outcome, "message" in result ? result.message : undefined)
+    return result
+  }
+
+  async function interrupt(req: Extract<ServerRequest, { op: "interrupt" }>): Promise<ResultFor["interrupt"]> {
+    await launcher!.interrupt(launchedNative(req.sessionID))
+    return {}
+  }
+
+  async function stop(req: Extract<ServerRequest, { op: "stop" }>): Promise<ResultFor["stop"]> {
+    const native = sessions.nativeOf(req.sessionID)
+    const running = native !== undefined && launcher?.running(native) === true
+    const stopped = sessions.stop(req)
+    if (!running) return stopped
+    await launcher!.interrupt(native!)
+    return { stopped: stopped.stopped.length ? stopped.stopped : [req.sessionID] }
+  }
+
+  const handlers: OpHandlers = {
+    permission: (req) => sessions.permission(req),
+    stop,
+    ...(launcher ? { create, turn, interrupt } : {}),
+  }
+  const features: ModifierFeature[] = ["permissionMessage", "hubPrompt", ...(launcher ? (["launch"] as const) : [])]
+  const spoke = new HarnessSpoke({
+    server: options.server,
+    token: options.token,
+    harness: HARNESS,
+    harnessVersion: options.harnessVersion,
+    evidence: "hooks",
+    pluginVersion: options.pluginVersion,
+    directory: options.directory,
+    kind: "service",
+    mode: "always",
+    handlers,
+    deliver: (req) => sessions.deliver(req),
+    features,
+    onState: (state, error) => log(`hub connection ${state}${error ? `: ${error}` : ""}`),
+    ...(options.socket ? { socket: options.socket } : {}),
+    ...(options.backoff ? { backoff: options.backoff } : {}),
+  })
+  sessions = new ClaudeSessions({
+    spoke,
+    ...(options.tokenWaitMs !== undefined ? { tokenWaitMs: options.tokenWaitMs } : {}),
+    ...(options.permissionWaitMs !== undefined ? { permissionWaitMs: options.permissionWaitMs } : {}),
+    references: options.references ?? hubReferences((id) => spoke.sessionToken(id)),
+  })
+
+  const launches = new Map<string, number>()
+  const connections = new Set<Socket>()
+  const reply = (conn: Socket, body: unknown) => {
+    if (!conn.destroyed) conn.end(`${JSON.stringify(body)}\n`)
+  }
+
+  async function request(conn: Socket, req: Record<string, unknown>, signal: AbortSignal): Promise<void> {
+    switch (req.kind) {
+      case "ping":
+        return reply(conn, { ok: true, pid: process.pid, state: spoke.state })
+      case "hook": {
+        const input = parseHookInput(req.input)
+        if (!input) return reply(conn, {})
+        const launch = str(req.launch)
+        const waitMs = typeof req.waitMs === "number" && Number.isFinite(req.waitMs) && req.waitMs >= 0 ? req.waitMs : undefined
+        const answer = await sessions.hook(input, { ...(launch ? { launch } : {}), ...(req.rewake === true ? { rewake: true } : {}), ...(waitMs !== undefined ? { waitMs } : {}), signal })
+        return reply(conn, answer)
+      }
+      case "launch": {
+        const launch = str(req.launch)
+        if (!launch || !Number.isInteger(req.pid) || (req.pid as number) <= 0) return reply(conn, { ok: false, error: "launch needs a launch ID and a pid" })
+        launches.delete(launch)
+        launches.set(launch, req.pid as number)
+        while (launches.size > LAUNCHES_MAX) launches.delete(launches.keys().next().value!)
+        return reply(conn, { ok: true })
+      }
+      case "exit": {
+        const launch = str(req.launch)
+        if (launch) {
+          sessions.endLaunch(launch)
+          launches.delete(launch)
+        }
+        return reply(conn, { ok: true })
+      }
+      default:
+        return reply(conn, { ok: false, error: "unknown request" })
+    }
+  }
+
+  /** An MCP pipe: JSON-RPC lines both ways, as the launch's current session; at the pipe's end line, answers then closes. */
+  function mcp(conn: Socket, launch: string | undefined): (text: string) => void {
+    const router: McpRouter = createMcpRouter({
+      version: options.pluginVersion,
+      sessionID: () => (launch ? sessions.sessionForLaunch(launch) : undefined),
+      sessionToken: (id) => spoke.sessionToken(id),
+      actToken: (id) => spoke.actToken(id),
+    })
+    const pending = new Set<Promise<void>>()
+    conn.on("close", () => router.close())
+    return (text) => {
+      let message: unknown
+      try {
+        message = JSON.parse(text)
+      } catch {
+        if (!conn.destroyed) conn.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error: not JSON" } })}\n`)
+        return
+      }
+      if (typeof message === "object" && message !== null && (message as { hub?: unknown }).hub === MCP_END.hub) {
+        void Promise.allSettled([...pending]).then(() => conn.end())
+        return
+      }
+      const task = router
+        .handle(message)
+        .then((answer) => {
+          if (answer && !conn.destroyed) conn.write(`${JSON.stringify(answer)}\n`)
+        })
+        .catch((cause) => log(`mcp: ${cause instanceof Error ? cause.message : String(cause)}`))
+        .finally(() => pending.delete(task))
+      pending.add(task)
+    }
+  }
+
+  const server: Server = createServer((conn) => {
+    connections.add(conn)
+    const abort = new AbortController()
+    conn.on("close", () => {
+      connections.delete(conn)
+      abort.abort()
+    })
+    conn.on("error", () => {})
+    let first = true
+    let rpc: ((text: string) => void) | undefined
+    onLines(conn, (text) => {
+      if (rpc) return rpc(text)
+      if (!first) return
+      first = false
+      let req: unknown
+      try {
+        req = JSON.parse(text)
+      } catch {
+        return reply(conn, { ok: false, error: "not JSON" })
+      }
+      if (typeof req !== "object" || req === null || (req as { v?: unknown }).v !== WIRE_VERSION) return reply(conn, { ok: false, error: "unsupported request" })
+      if ((req as { kind?: unknown }).kind === "mcp") {
+        rpc = mcp(conn, str((req as { launch?: unknown }).launch))
+        return
+      }
+      request(conn, req as Record<string, unknown>, abort.signal).catch((cause) => {
+        log(`request failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+        reply(conn, {})
+      })
+    })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(options.socketPath, () => {
+      server.off("error", reject)
+      resolve()
+    })
+  })
+  chmodSync(options.socketPath, 0o600)
+
+  // A launch whose process is gone: its sessions end (checked again each round; Claude Code may report late).
+  const liveness = setInterval(() => {
+    for (const [launch, pid] of launches) if (!alive(pid)) sessions.endLaunch(launch)
+  }, options.livenessIntervalMs ?? DEFAULT_LIVENESS_MS)
+  liveness.unref?.()
+
+  spoke.start()
+  let stopped = false
+  return {
+    get state() {
+      return spoke.state
+    },
+    spoke,
+    sessions,
+    async stop() {
+      if (stopped) return
+      stopped = true
+      clearInterval(liveness)
+      await launcher?.stopAll()
+      spoke.stop()
+      for (const conn of connections) conn.destroy()
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+      try {
+        unlinkSync(options.socketPath)
+      } catch {}
+    },
+  }
+}

package/packages/claude-code/src/hook-input.ts

@@ -0,0 +1,44 @@
+// The stdin JSON of a Claude Code hook (shapes recorded by the P7-T0 spike, Brain report v0hsdqhm). Every input
+// carries session_id (a UUID), transcript_path, cwd and hook_event_name; the rest depends on the event. Input that is
+// not a hook input of a Claude Code session is refused before anything uses it.
+
+/** Claude Code hook input: the common fields checked, the event's own fields kept as they came. */
+export interface HookInput {
+  readonly session_id: string
+  readonly hook_event_name: string
+  readonly cwd?: string
+  readonly transcript_path?: string
+  readonly prompt_id?: string
+  readonly prompt?: string
+  readonly source?: string
+  readonly reason?: string
+  readonly tool_name?: string
+  readonly tool_input?: unknown
+  readonly tool_use_id?: string
+  readonly tool_response?: unknown
+  readonly permission_suggestions?: unknown
+  readonly notification_type?: string
+  readonly message?: string
+  readonly stop_hook_active?: boolean
+  readonly last_assistant_message?: string
+  readonly error?: unknown
+  readonly error_details?: unknown
+  readonly agent_id?: string
+  readonly agent_type?: string
+  readonly [key: string]: unknown
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const EVENT = /^[A-Za-z]{1,64}$/
+const OPTIONAL_STRINGS = ["cwd", "transcript_path", "prompt_id", "prompt", "source", "reason", "tool_name", "tool_use_id", "notification_type", "message", "last_assistant_message", "agent_id", "agent_type"] as const
+
+/** The hook input, or undefined when `raw` is not one. */
+export function parseHookInput(raw: unknown): HookInput | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined
+  const r = raw as Record<string, unknown>
+  if (typeof r.session_id !== "string" || !UUID.test(r.session_id)) return undefined
+  if (typeof r.hook_event_name !== "string" || !EVENT.test(r.hook_event_name)) return undefined
+  for (const key of OPTIONAL_STRINGS) if (r[key] !== undefined && typeof r[key] !== "string") return undefined
+  if (r.stop_hook_active !== undefined && typeof r.stop_hook_active !== "boolean") return undefined
+  return r as HookInput
+}

package/packages/claude-code/src/ids.ts

@@ -0,0 +1,27 @@
+// Hub IDs for Claude Code's native IDs (decision fx04e42c point 2). A session's UUID maps to the reversible
+// ses_cc<32 hex> (spoke-sdk hubSessionID, namespace "cc"); a subagent (SubagentStart's agent_id inside a session)
+// gets a child session of its own, stable for (session, agent). Other IDs the hub sees (tool calls, requests) are
+// plain IDs (protocol wire.ts ID).
+import { createHash, randomBytes } from "node:crypto"
+import { MAX_NATIVE_BYTES, hubSessionID } from "../../spoke-sdk/src/index.ts"
+
+/** The session namespace of Claude Code in hub session IDs. */
+export const CLAUDE_NAMESPACE = "cc"
+
+const PLAIN_MAX = 300
+
+/** The hub session ID of a Claude Code session. */
+export const claudeSessionID = (sessionID: string): string => hubSessionID(CLAUDE_NAMESPACE, sessionID)
+
+/** The hub session ID of a subagent of a Claude Code session: `<session>/<agent>`, hashed when that is too long. */
+export function childSessionID(sessionID: string, agentID: string): string {
+  const native = `${sessionID.toLowerCase()}/${agentID}`
+  if (Buffer.byteLength(native, "utf8") <= MAX_NATIVE_BYTES) return hubSessionID(CLAUDE_NAMESPACE, native)
+  return hubSessionID(CLAUDE_NAMESPACE, `${sessionID.toLowerCase()}/#${createHash("sha256").update(agentID).digest("hex").slice(0, 32)}`)
+}
+
+/** `raw` as a plain hub ID (letters, digits and _.:@/+~- only, at most 300 characters); a fresh one when empty. */
+export function plainID(raw: string, prefix = "id"): string {
+  const clean = (typeof raw === "string" ? raw : "").replace(/[^A-Za-z0-9_.:@/+~-]/g, "_").slice(0, PLAIN_MAX)
+  return clean || `${prefix}_${randomBytes(8).toString("hex")}`
+}

package/packages/claude-code/src/index.ts

@@ -0,0 +1,18 @@
+// @huynle/hub-claude-code: the Claude Code hooks spoke (design §1.2, §13.3; decision fx04e42c point 4, report
+// v0hsdqhm). `hub claude` runs Claude Code with the hub plugin (wrapper.ts); the plugin's hooks run the bridge
+// (bridge.ts), which talks to the per-user daemon (daemon.ts: HarnessSpoke + ClaudeSessions) over a private Unix
+// socket; the plugin's MCP server is a pipe to the daemon (mcp.ts).
+export * from "./bridge.ts"
+export * from "./daemon.ts"
+export * from "./hook-input.ts"
+export * from "./ids.ts"
+export * from "./launcher.ts"
+export * from "./main.ts"
+export * from "./mcp.ts"
+export * from "./paths.ts"
+export * from "./plugin.ts"
+export * from "./references.ts"
+export * from "./sessions.ts"
+export * from "./tools.ts"
+export * from "./wire.ts"
+export * from "./wrapper.ts"