fix(server): discover commands registered by Claude mods

apps/server/src/provider/ClaudeCapabilitiesProbe.test.ts

@@ -1,11 +1,19 @@
 // @effect-diagnostics nodeBuiltinImport:off - cleanup uses Node's retrying rm, which the FileSystem service does not expose.
+import * as NodeOS from "node:os";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { ClaudeSettings, type ServerProvider } from "@t3tools/contracts";
+import {
+  ClaudeSettings,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { buildServerProvider } from "@t3tools/provider-core/server/snapshotProbe";
 import { vi } from "vite-plus/test";
 import * as ClaudeSdk from "@anthropic-ai/claude-agent-sdk";
 import { assert, it } from "@effect/vitest";
 import * as HostProcess from "@t3tools/shared/HostProcess";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as FileSystem from "effect/FileSystem";
 import * as Schema from "effect/Schema";
 import * as TestClock from "effect/testing/TestClock";
@@ -42,6 +50,7 @@ it.effect("reports a deleted worktree's scan as finished, not pending", () =>
       { skills: [], slashCommands: [] } as unknown as ServerProvider,
       "/nonexistent/t3-deleted-worktree",
       { HOME: "/nonexistent/t3-home" },
+      false,
     );
     assert.strictEqual(snapshot.slashCommandsPending, false);
   }).pipe(Effect.provide(NodeServices.layer)),
@@ -88,3 +97,126 @@ it.effect("keeps the probe subprocess alive while gateway model discovery can fi
     assert.equal(abortSignal?.aborted, true);
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
+
+// Mirrors Claude Code 2.1.295 and 2.1.303: initialize answers only after
+// session.start hooks finish, so a mod's registered command is in init unless
+// hooks are disabled, in which case the hook never runs.
+const mockClaudeWithMod = (hook: "registers" | "never-finishes" = "registers") => {
+  const hookRuns = { count: 0 };
+  let markStarted = () => {};
+  const started = new Promise<void>((resolve) => (markStarted = resolve));
+  const query = vi.spyOn(ClaudeSdk, "query").mockImplementation(({ options }) => {
+    const hooksRun =
+      options?.settings === undefined || typeof options.settings === "string"
+        ? true
+        : options.settings.disableAllHooks !== true;
+    if (hooksRun) hookRuns.count += 1;
+    markStarted();
+    const builtin = { name: "project-review", description: "", argumentHint: "" };
+    const modCommand = { name: "handoffs", description: "", argumentHint: "" };
+    // oxlint-disable-next-line require-yield -- the stream stays open until abort, like the real SDK query
+    const messages = (async function* () {
+      await new Promise((resolve) =>
+        options?.abortController?.signal.addEventListener("abort", resolve),
+      );
+    })();
+    return Object.assign(messages, {
+      initializationResult: () =>
+        hooksRun && hook === "never-finishes"
+          ? new Promise<never>(() => {})
+          : Promise.resolve({
+              commands: hooksRun ? [builtin, modCommand] : [builtin],
+              account: {},
+            }),
+      usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET: async () => {
+        throw new Error("usage unavailable");
+      },
+    }) as unknown as ReturnType<typeof ClaudeSdk.query>;
+  });
+  return { query, hookRuns, started };
+};
+
+const MACHINE_SNAPSHOT = {
+  ...buildServerProvider({
+    presentation: { displayName: "Claude" },
+    enabled: true,
+    checkedAt: "2026-10-22T00:00:00.000Z",
+    models: [],
+    slashCommands: [{ name: "machine-only" }],
+    probe: {
+      installed: true,
+      version: "2.1.303",
+      status: "ready",
+      auth: { status: "authenticated" },
+    },
+  }),
+  instanceId: ProviderInstanceId.make("claudeAgent"),
+  driver: ProviderDriverKind.make("claudeAgent"),
+};
+
+const scanWorkspace = (hook: "registers" | "never-finishes", runHooks: boolean) =>
+  Effect.gen(function* () {
+    const { query, hookRuns, started } = mockClaudeWithMod(hook);
+    yield* Effect.addFinalizer(() => Effect.sync(() => query.mockRestore()));
+    const scan = yield* probeClaudeWorkspaceSnapshot(
+      yield* decodeClaudeSettings({}),
+      MACHINE_SNAPSHOT,
+      NodeOS.tmpdir(),
+      {},
+      runHooks,
+    ).pipe(Effect.forkChild);
+    // The probe deadline runs on the test clock, so a hook that never
+    // finishes reaches it without any real waiting.
+    yield* Effect.promise(() => started);
+    yield* TestClock.adjust("30 seconds");
+    const snapshot = yield* Fiber.join(scan);
+    return {
+      commands: snapshot.slashCommands.map((command) => command.name),
+      pending: snapshot.slashCommandsPending,
+      hookRuns: hookRuns.count,
+    };
+  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
+
+it.effect("a scan that may run hooks lists commands that mods register in session.start", () =>
+  Effect.gen(function* () {
+    const scan = yield* scanWorkspace("registers", true);
+    assert.include(scan.commands, "handoffs");
+    assert.equal(scan.pending, false);
+  }),
+);
+
+it.effect("a scan for a read-only caller does not run session.start hooks", () =>
+  Effect.gen(function* () {
+    const scan = yield* scanWorkspace("registers", false);
+    assert.equal(scan.hookRuns, 0);
+    assert.notInclude(scan.commands, "handoffs");
+    assert.include(scan.commands, "project-review");
+  }),
+);
+
+it.effect("a hook that outlasts the probe still lists the project's own commands", () =>
+  Effect.gen(function* () {
+    const scan = yield* scanWorkspace("never-finishes", true);
+    assert.equal(scan.hookRuns, 1);
+    assert.sameMembers(scan.commands, ["compact", "project-review"]);
+    assert.equal(scan.pending, false);
+  }),
+);
+
+it.effect("the periodic health check does not run session.start hooks", () =>
+  Effect.gen(function* () {
+    const { query, hookRuns } = mockClaudeWithMod();
+    yield* Effect.addFinalizer(() => Effect.sync(() => query.mockRestore()));
+    const probe = yield* probeClaudeCapabilities(
+      yield* decodeClaudeSettings({}),
+      {},
+      undefined,
+      true,
+    );
+    assert.equal(hookRuns.count, 0);
+    assert.notInclude(
+      probe.slashCommands.map((command) => command.name),
+      "handoffs",
+    );
+  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+);

apps/server/src/provider/ClaudeProvider.ts

@@ -224,14 +224,16 @@ export function buildClaudeCapabilitiesProbeQueryOptions(input: {
   readonly environment: NodeJS.ProcessEnv;
   readonly cwd: string | undefined;
   readonly managedMcpConfig: boolean;
+  readonly runHooks?: boolean;
 }): ClaudeQueryOptions {
   return {
     persistSession: false,
     pathToClaudeCodeExecutable: input.executablePath,
     abortController: input.abortController,
     settingSources: [...CLAUDE_CAPABILITIES_PROBE_SETTING_SOURCES],
-    // Keep settings for slash-command discovery, but disable hooks so health checks do not run SessionStart repeatedly.
-    settings: { disableAllHooks: true },
+    // Health checks fire every few minutes, so they must not run SessionStart hooks. Workspace
+    // command discovery for operators runs them because mods register commands from one.
+    ...(input.runHooks ? {} : { settings: { disableAllHooks: true } }),
     allowedTools: [],
     // Exclude filesystem MCP servers; omit strict mode when managed-mcp.json already excludes them and forbids the flag.
     mcpServers: {},
@@ -371,6 +373,7 @@ const probeClaudeCapabilities = (
   environment?: NodeJS.ProcessEnv,
   cwd?: string,
   includeUsage = true,
+  runHooks = false,
 ) => {
   const abort = new AbortController();
   const abortProbe = Effect.sync(() => {
@@ -403,8 +406,10 @@ const probeClaudeCapabilities = (
             environment: claudeEnvironment,
             cwd,
             managedMcpConfig,
+            runHooks,
           }),
         });
+        // Claude Code answers initialize after SessionStart hooks finish, so init lists mod commands.
         const init = await q.initializationResult();
         return { q, init, graceMs };
       },
@@ -492,16 +497,20 @@ export const probeClaudeWorkspaceSnapshot = Effect.fn("probeClaudeWorkspaceSnaps
   claudeSettings: ClaudeSettings,
   machineSnapshot: ServerProvider,
   cwd: string,
-  environment?: NodeJS.ProcessEnv,
+  environment: NodeJS.ProcessEnv | undefined,
+  runHooks: boolean,
 ): Effect.fn.Return<ProviderWorkspaceSnapshot, never, FileSystem.FileSystem | Path.Path> {
   if (!claudeSettings.enabled) return machineSnapshot;
   const skills = yield* discoverClaudeSkills(claudeSettings, cwd, environment);
   const fileSystem = yield* FileSystem.FileSystem;
   // A deleted worktree can never answer the probe. Pending would make clients rescan it forever.
   const cwdExists = yield* fileSystem.exists(cwd).pipe(Effect.orElseSucceed(() => true));
-  const probeResult = cwdExists
-    ? yield* probeClaudeCapabilities(claudeSettings, environment, cwd, false).pipe(Effect.result)
-    : undefined;
+  const probe = (hooks: boolean) =>
+    probeClaudeCapabilities(claudeSettings, environment, cwd, false, hooks).pipe(Effect.result);
+  let probeResult = cwdExists ? yield* probe(runHooks) : undefined;
+  // A hook can outlast the probe deadline. Probing again without hooks still lists the
+  // project's own commands; a failure of both stays pending so clients retry.
+  if (runHooks && probeResult && Result.isFailure(probeResult)) probeResult = yield* probe(false);
   const capabilities =
     probeResult && Result.isSuccess(probeResult) ? probeResult.success : undefined;
   return {
@@ -512,6 +521,7 @@ export const probeClaudeWorkspaceSnapshot = Effect.fn("probeClaudeWorkspaceSnaps
       ...(capabilities?.slashCommands ?? []),
     ]),
     slashCommandsPending: cwdExists && !capabilities,
+    hooksSkipped: !runHooks,
   };
 });
 

apps/server/src/provider/Drivers/ClaudeDriver.ts

@@ -56,6 +56,7 @@ import {
 } from "./ClaudeHome.ts";
 import * as HostProcess from "@t3tools/shared/HostProcess";
 import { makeClaudeMaintenanceResolution } from "./ClaudeMaintenance.ts";
+import { WorkspaceScanRunsHooks } from "../WorkspaceScanHooks.ts";
 const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
 
 const DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
@@ -384,9 +385,15 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
       snapshot,
       invalidateCaches: Cache.invalidateAll(capabilitiesProbeCache),
       snapshotForCwd: (cwd: string) =>
-        snapshot.getSnapshot.pipe(
-          Effect.flatMap((machineSnapshot) =>
-            probeClaudeWorkspaceSnapshot(effectiveConfig, machineSnapshot, cwd, processEnv),
+        Effect.all([snapshot.getSnapshot, WorkspaceScanRunsHooks]).pipe(
+          Effect.flatMap(([machineSnapshot, runHooks]) =>
+            probeClaudeWorkspaceSnapshot(
+              effectiveConfig,
+              machineSnapshot,
+              cwd,
+              processEnv,
+              runHooks,
+            ),
           ),
           Effect.provideService(FileSystem.FileSystem, fileSystem),
           Effect.provideService(Path.Path, path),