feat: add dosu hooks for Claude Code knowledge injection (#74)

* feat: add dosu hooks for Claude Code knowledge injection

Turns the validated prototype into a production 'dosu hooks' command surface that injects Dosu knowledge into Claude Code automatically and non-blockingly.

- user-prompt-submit: create a knowledge ticket (fire-and-forget) + inject a short 'lookup started' note
- post-tool-use: poll (cooldown-throttled) and inject the route map exactly once
- stop (opt-in): non-blocking last-chance delivery
- install/uninstall/doctor for claude-code; writes a bare 'dosu hooks <event>' command into .claude/settings.local.json only (never tracked config)
- in-CLI fake ticket API + unit/integration tests; silent-no-op-on-failure so a hook never disrupts the agent
- save nudge when the server reports a knowledge gap (save_recommended)

* fix: guard Stop against bare save-nudge and tighten installer detection

Review follow-ups on the dosu hooks surface:
- Stop hook only blocks for real knowledge; a knowledge-gap ticket (empty context) is consumed but not blocked on, so the agent is never held open just for a save nudge
- isDosuHookCommand requires 'dosu' to be the command name (optionally path-prefixed), not merely an argument — so a user hook whose argument contains 'dosu hooks' is no longer misidentified and deleted on uninstall
- fake-server: handle mid-stream request errors so a socket error can't crash the dev server

* chore: drop the test-only fake ticket server (not shipped)

fake-server.ts + its two tests were test/dev-only infra: no production code imported them, so they were already tree-shaken out of the published bundle (bin/dosu.js). Removing them slims the changeset with zero behavior change. Unit tests still cover the hook runtime + the §3.6 wire-contract parsing, and coverage stays above the 95/90/80/95 gate (95.23/90.55/98.11/95.23).

* refactor: self-document hooks install/uninstall and validate the agent

Constrain the <agent> positional to the supported set (claude-code) via
commander .choices() so an unknown agent fails fast with a clear message,
and add --help examples for install/uninstall.

* refactor: drop plan/MVP/demo references from hooks comments and messages

Strip 'plan §x' comment references, the 'The MVP supports' wording in
user-facing errors (now 'Supported agents/scopes'), and demo/lineage notes.
Behavior unchanged except the reworded error strings.

---------

Co-authored-by: Caspian Zhao <user.name>

Author: dohooo

src/cli/cli.test.ts

@@ -109,4 +109,24 @@ describe("CLI", () => {
     expect(cmd?.options.find((o) => o.long === "--tail")).toBeDefined();
     expect(cmd?.options.find((o) => o.long === "--clear")).toBeDefined();
   });
+
+  it("has hooks command with entrypoint and lifecycle subcommands", () => {
+    const program = createProgram();
+    const cmd = program.commands.find((c) => c.name() === "hooks");
+    expect(cmd).toBeDefined();
+    const names = cmd?.commands.map((c) => c.name()) ?? [];
+    expect(names).toEqual(
+      expect.arrayContaining([
+        "user-prompt-submit",
+        "post-tool-use",
+        "stop",
+        "status",
+        "install",
+        "uninstall",
+        "doctor",
+      ]),
+    );
+    const install = cmd?.commands.find((c) => c.name() === "install");
+    expect(install?.options.find((o) => o.long === "--with-stop")).toBeDefined();
+  });
 });

src/cli/cli.ts

@@ -8,6 +8,7 @@ import { analyticsCommand } from "../commands/analytics";
 import { askCommand } from "../commands/ask";
 import { deploymentsCommand } from "../commands/deployments";
 import { docsCommand } from "../commands/docs";
+import { hooksCommand } from "../commands/hooks";
 import { insightsCommand } from "../commands/insights";
 import { integrationsCommand } from "../commands/integrations";
 import { knowledgeCommand } from "../commands/knowledge";
@@ -33,6 +34,17 @@ import { checkForSkillUpdates } from "../version/skill-update-check";
 import { checkForUpdates } from "../version/update-check";
 import { getVersionString } from "../version/version";
 
+/**
+ * Hook entrypoints are auto-invoked by Claude Code on every turn and must stay
+ * fast and stdout-clean. Skip the update checks for them (their stderr notices
+ * are noise on the hot path and the background fetch can delay process exit).
+ */
+const HOOK_ENTRYPOINTS = new Set(["user-prompt-submit", "post-tool-use", "stop"]);
+function isHookEntrypointInvocation(argv: string[]): boolean {
+  const i = argv.indexOf("hooks");
+  return i >= 0 && HOOK_ENTRYPOINTS.has(argv[i + 1] ?? "");
+}
+
 export function createProgram(): Command {
   const program = new Command();
 
@@ -44,8 +56,10 @@ export function createProgram(): Command {
     .hook("preAction", (thisCommand) => {
       const opts = thisCommand.optsWithGlobals();
       logger.init({ debug: opts.debug });
-      checkForUpdates();
-      checkForSkillUpdates();
+      if (!isHookEntrypointInvocation(process.argv)) {
+        checkForUpdates();
+        checkForSkillUpdates();
+      }
     })
     .action(async () => {
       // Default: launch TUI when no subcommand given
@@ -242,6 +256,7 @@ export function createProgram(): Command {
   program.addCommand(askCommand());
   program.addCommand(deploymentsCommand());
   program.addCommand(docsCommand());
+  program.addCommand(hooksCommand());
   program.addCommand(insightsCommand());
   program.addCommand(integrationsCommand());
   program.addCommand(knowledgeCommand());