@hasna/hooks 0.3.4 → 0.3.6

package/bin/index.js

@@ -2089,7 +2089,7 @@ var init_registry = __esm(() => {
       name: "knowledge-context",
       displayName: "Knowledge Context",
       description: "Injects deterministic Knowledge context packs into Codewith SessionStart, UserPromptSubmit, and SubagentStart",
-      version: "0.1.3",
+      version: "0.1.5",
       category: "Context Management",
       event: "SessionStart",
       events: ["SessionStart", "UserPromptSubmit", "SubagentStart"],

package/dist/index.js

@@ -1010,7 +1010,7 @@ var HOOKS = [
     name: "knowledge-context",
     displayName: "Knowledge Context",
     description: "Injects deterministic Knowledge context packs into Codewith SessionStart, UserPromptSubmit, and SubagentStart",
-    version: "0.1.3",
+    version: "0.1.5",
     category: "Context Management",
     event: "SessionStart",
     events: ["SessionStart", "UserPromptSubmit", "SubagentStart"],

package/hooks/hook-knowledge-context/README.md

@@ -27,12 +27,24 @@ knowledge context pack <query> --from search --max-items <n> --max-tokens <n> --
 
 The hook intentionally does not pass `--semantic`, does not call web search,
 does not call ask/build/generate flows, and does not crawl raw stores directly.
+For `UserPromptSubmit`, the hook first applies a deterministic high-signal gate
+so short acknowledgements and casual follow-ups do not inject Knowledge context.
 When Knowledge returns a nonempty context pack, the hook redacts credential-like
 text from that pack and emits Codewith-native
 `hookSpecificOutput.additionalContext` with the same event name. Citation-only
-packs are expanded into progressive context lines with a bounded preview and a
-`knowledge get --id ... --json` read hint so agents can decide which full items
-are worth opening.
+packs are expanded into progressive context lines with bounded previews and a
+single `knowledge get --id <item_id> --json` hint so agents can decide which
+full items are worth opening.
+
+Example injected context:
+
+```text
+[hook-knowledge-context] Knowledge matches (UserPromptSubmit; top 3, deterministic search):
+
+If a match looks relevant, read it with: knowledge get --id <item_id> --json
+
+- item_id=k_example cite=cite_123: Bounded preview text...
+```
 
 All failures are fail-open: missing CLI, timeout, nonzero exit, malformed JSON,
 bad stdin, or empty packs return `{"continue":true}` without context.
@@ -45,10 +57,17 @@ export HOOKS_KNOWLEDGE_COMMAND=knowledge    # CLI command/path
 export HOOKS_KNOWLEDGE_TIMEOUT_MS=5000      # Per-call timeout
 export HOOKS_KNOWLEDGE_MAX_ITEMS=3          # Context pack item budget
 export HOOKS_KNOWLEDGE_MAX_TOKENS=1200      # Context pack token budget
+export HOOKS_KNOWLEDGE_REQUIRE_HIGH_SIGNAL=1
+export HOOKS_KNOWLEDGE_MIN_PROMPT_CHARS=6
+export HOOKS_KNOWLEDGE_MIN_SIGNAL_SCORE=3
 export HOOKS_KNOWLEDGE_MAX_QUERY_CHARS=1200 # Redacted query bound
 export HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS=8000
 ```
 
+All numeric env overrides are bounded. `HOOKS_KNOWLEDGE_COMMAND` accepts only a
+single command/path token; unsafe values with whitespace fall back to
+`knowledge`.
+
 ## Events
 
 - `SessionStart`

package/hooks/hook-knowledge-context/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hook-knowledge-context",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Codewith hook that injects deterministic Knowledge context packs into lifecycle events",
   "type": "module",
   "main": "./dist/hook.js",
@@ -16,7 +16,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build ./src/hook.ts --outdir ./dist --target node && tsc -p tsconfig.json --emitDeclarationOnly --declaration --declarationMap false --noEmit false",
+    "build": "rm -rf dist && bun build ./src/hook.ts --outdir ./dist --target bun && tsc -p tsconfig.json --emitDeclarationOnly --declaration --declarationMap false --noEmit false",
     "prepublishOnly": "bun run build",
     "typecheck": "tsc --noEmit"
   },

package/hooks/hook-knowledge-context/src/hook.test.ts

@@ -5,6 +5,7 @@ import {
   buildQuery,
   extractContextText,
   getConfig,
+  promptSignalScore,
   redactSecrets,
   sanitizeQuery,
   type KnowledgeContextConfig,
@@ -16,15 +17,44 @@ const baseConfig: KnowledgeContextConfig = {
   timeoutMs: 5000,
   maxItems: 3,
   maxTokens: 1200,
+  minPromptChars: 6,
+  minSignalScore: 3,
   maxQueryChars: 1200,
   maxOutputChars: 8000,
+  requireHighSignal: true,
 };
 
 describe("hook-knowledge-context", () => {
   test("defaults Knowledge CLI timeout to 5000ms and keeps env override", () => {
     expect(getConfig({}).timeoutMs).toBe(5000);
     expect(getConfig({}).maxItems).toBe(3);
+    expect(getConfig({}).minPromptChars).toBe(6);
+    expect(getConfig({}).minSignalScore).toBe(3);
+    expect(getConfig({}).requireHighSignal).toBe(true);
     expect(getConfig({ HOOKS_KNOWLEDGE_TIMEOUT_MS: "2345" }).timeoutMs).toBe(2345);
+    expect(getConfig({ HOOKS_KNOWLEDGE_REQUIRE_HIGH_SIGNAL: "0" }).requireHighSignal).toBe(false);
+  });
+
+  test("applies bounded env overrides and rejects unsafe command override", () => {
+    const config = getConfig({
+      HOOKS_KNOWLEDGE_COMMAND: "/tmp/knowledge",
+      HOOKS_KNOWLEDGE_MAX_ITEMS: "9",
+      HOOKS_KNOWLEDGE_MAX_TOKENS: "2345",
+      HOOKS_KNOWLEDGE_MIN_PROMPT_CHARS: "12",
+      HOOKS_KNOWLEDGE_MIN_SIGNAL_SCORE: "4",
+      HOOKS_KNOWLEDGE_MAX_QUERY_CHARS: "200",
+      HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS: "9999",
+    });
+
+    expect(config.command).toBe("/tmp/knowledge");
+    expect(config.maxItems).toBe(9);
+    expect(config.maxTokens).toBe(2345);
+    expect(config.minPromptChars).toBe(12);
+    expect(config.minSignalScore).toBe(4);
+    expect(config.maxQueryChars).toBe(200);
+    expect(config.maxOutputChars).toBe(9999);
+    expect(buildKnowledgeArgs("q", config)).toContain("9");
+    expect(getConfig({ HOOKS_KNOWLEDGE_COMMAND: "bad command" }).command).toBe("knowledge");
   });
 
   test("builds deterministic knowledge context pack args without semantic, web, or generation flags", () => {
@@ -67,7 +97,7 @@ describe("hook-knowledge-context", () => {
 
     expect(output.continue).toBe(true);
     expect(output.hookSpecificOutput?.hookEventName).toBe("SessionStart");
-    expect(output.hookSpecificOutput?.additionalContext).toContain("knowledge context pack --from search");
+    expect(output.hookSpecificOutput?.additionalContext).toContain("Knowledge matches");
     expect(output.hookSpecificOutput?.additionalContext).toContain("Use hooks.json");
   });
 
@@ -87,7 +117,7 @@ describe("hook-knowledge-context", () => {
       {
         hook_event_name: "UserPromptSubmit",
         cwd: "/repo",
-        prompt: "implement this with token=demo",
+        prompt: "implement the knowledge hook context output with token=demo",
       },
       executor
     );
@@ -151,6 +181,46 @@ describe("hook-knowledge-context", () => {
     ).toEqual({ continue: true });
   });
 
+  test("fails open for low-signal UserPromptSubmit prompts before calling Knowledge", async () => {
+    let executorCalls = 0;
+    const executor: KnowledgeExecutor = async () => {
+      executorCalls += 1;
+      throw new Error("executor should not run for low-signal prompts");
+    };
+
+    for (const prompt of ["", "ok", "thanks", "?", "continue", "tell me again"]) {
+      expect(
+        await buildHookOutput({ hook_event_name: "UserPromptSubmit", cwd: "/repo", prompt }, executor)
+      ).toEqual({ continue: true });
+    }
+    expect(executorCalls).toBe(0);
+    for (const prompt of [
+      "fix authz",
+      "release",
+      "publish npm",
+      "check src/hook.ts",
+      "@hasna/hooks",
+      "merge PR 12",
+      "review staged diff",
+      "rerun tests",
+    ]) {
+      expect(promptSignalScore(prompt, "/home/hasna/workspace/hasna/opensource/open-hooks")).toBeGreaterThanOrEqual(3);
+    }
+  });
+
+  test("can opt out of high-signal gating for UserPromptSubmit", async () => {
+    const output = await buildHookOutput(
+      { hook_event_name: "UserPromptSubmit", cwd: "/repo", prompt: "ok" },
+      async () => ({
+        ok: true,
+        stdout: JSON.stringify({ context: "Forced low-signal context." }),
+      }),
+      { HOOKS_KNOWLEDGE_REQUIRE_HIGH_SIGNAL: "0" }
+    );
+
+    expect(output.hookSpecificOutput?.additionalContext).toContain("Forced low-signal context");
+  });
+
   test("sanitizes and bounds queries", () => {
     expect(redactSecrets("password=hunter2 token=demo")).toBe(
       "password=<redacted> token=<redacted>"
@@ -172,21 +242,65 @@ describe("hook-knowledge-context", () => {
     expect(extractContextText([{ title: "One", text: "Body", uri: "knowledge://item/one" }])).toContain("Body");
   });
 
-  test("formats citation previews as useful progressive blurbs with compact open commands", () => {
+  test("formats citation-only packs as item_id/cite bullets with one read hint", () => {
     const text = extractContextText({
       citations: [
         {
-          id: "cite_123",
-          source_ref: "knowledge://item/k_example",
-          quote_preview: "A short preview that tells the agent why this Knowledge item might matter.",
+          id: "cite_1",
+          source_ref: "knowledge://item/k_one",
+          quote_preview: "First preview that tells the agent why this Knowledge item might matter.",
+        },
+        {
+          id: "cite_2",
+          source_ref: "knowledge://item/k_two",
+          quote_preview: "Second preview that tells the agent why this Knowledge item might matter.",
         },
       ],
     });
 
-    expect(text).toContain("- k_example (cite_123): A short preview");
-    expect(text).toContain("cite_123");
-    expect(text).toContain("A short preview");
-    expect(text).toContain("open: knowledge get --id k_example --json");
-    expect(text).not.toContain("source: knowledge://item/k_example");
+    expect(text).toContain("If a match looks relevant, read it with: knowledge get --id <item_id> --json");
+    expect(text?.match(/knowledge get --id/g) ?? []).toHaveLength(1);
+    expect(text).toContain("- item_id=k_one cite=cite_1: First preview");
+    expect(text).toContain("- item_id=k_two cite=cite_2: Second preview");
+    expect(text).not.toContain("open: knowledge get --id k_one --json");
+    expect(text).not.toContain("(cite_1)");
+    expect(text).not.toContain("source: knowledge://item/k_one");
+  });
+
+  test("extracts item_id from legacy Knowledge source paths", () => {
+    const text = extractContextText({
+      citations: [
+        {
+          id: "cite_abc",
+          source_ref: "open-files://source/legacy-json/path/k_mqyrz7gt_olq82e",
+          quote_preview: "Legacy file source preview.",
+        },
+      ],
+    });
+
+    expect(text).toContain("item_id=k_mqyrz7gt_olq82e");
+    expect(text).toContain("cite=cite_abc");
+    expect(text).not.toContain("source=open-files://source/legacy-json/path/k_mqyrz7gt_olq82e");
+  });
+
+  test("keeps source fallback for non-Knowledge citations without item ids", () => {
+    const text = extractContextText({
+      citations: [
+        {
+          id: "cite_url",
+          source_ref: "https://example.test/doc",
+          quote_preview: "External preview.",
+        },
+      ],
+    });
+
+    expect(text).toContain("- cite=cite_url source=https://example.test/doc: External preview.");
+    expect(text).not.toContain("item_id=");
+    expect(text).not.toContain("knowledge get --id");
+  });
+
+  test("cleans legacy empty-title bullet artifacts in item text", () => {
+    expect(extractContextText(["- : legacy empty title preview"])).toBe("- legacy empty title preview");
+    expect(extractContextText("- : legacy direct context")).toBe("- legacy direct context");
   });
 });

package/hooks/hook-knowledge-context/src/hook.ts

@@ -40,8 +40,11 @@ export interface KnowledgeContextConfig {
   timeoutMs: number;
   maxItems: number;
   maxTokens: number;
+  minPromptChars: number;
+  minSignalScore: number;
   maxQueryChars: number;
   maxOutputChars: number;
+  requireHighSignal: boolean;
 }
 
 export interface KnowledgeExecResult {
@@ -58,6 +61,8 @@ export type KnowledgeExecutor = (
 const DEFAULT_TIMEOUT_MS = 5000;
 const DEFAULT_MAX_ITEMS = 3;
 const DEFAULT_MAX_TOKENS = 1200;
+const DEFAULT_MIN_PROMPT_CHARS = 6;
+const DEFAULT_MIN_SIGNAL_SCORE = 3;
 const DEFAULT_MAX_QUERY_CHARS = 1200;
 const DEFAULT_MAX_OUTPUT_CHARS = 8000;
 const SUPPORTED_EVENTS = new Set<KnowledgeContextEvent>([
@@ -97,8 +102,11 @@ export function getConfig(env: NodeJS.ProcessEnv = process.env): KnowledgeContex
     timeoutMs: boundedNumber(env.HOOKS_KNOWLEDGE_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100, 10_000),
     maxItems: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_ITEMS, DEFAULT_MAX_ITEMS, 1, 20),
     maxTokens: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_TOKENS, DEFAULT_MAX_TOKENS, 100, 8_000),
+    minPromptChars: boundedNumber(env.HOOKS_KNOWLEDGE_MIN_PROMPT_CHARS, DEFAULT_MIN_PROMPT_CHARS, 0, 4_000),
+    minSignalScore: boundedNumber(env.HOOKS_KNOWLEDGE_MIN_SIGNAL_SCORE, DEFAULT_MIN_SIGNAL_SCORE, 1, 10),
     maxQueryChars: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_QUERY_CHARS, DEFAULT_MAX_QUERY_CHARS, 80, 4_000),
     maxOutputChars: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS, DEFAULT_MAX_OUTPUT_CHARS, 500, 20_000),
+    requireHighSignal: env.HOOKS_KNOWLEDGE_REQUIRE_HIGH_SIGNAL !== "0",
   };
 }
 
@@ -135,6 +143,52 @@ export function sanitizeQuery(text: string, maxChars: number): string {
   return redacted.length > maxChars ? redacted.slice(0, maxChars).trim() : redacted;
 }
 
+function cleanLegacyEmptyBullet(text: string): string {
+  return text.replace(/^(\s*[-*])\s*:\s*/gm, "$1 ");
+}
+
+function cleanStringItem(text: string): string {
+  return cleanLegacyEmptyBullet(text).replace(/^[-*]\s*/, "").trim();
+}
+
+const DOMAIN_SIGNAL_RE =
+  /\b(auth|authz|rls|tenant|deploy|release|publish|rollback|merge|pr|staged|diff|security|secret|credential|prod|incident|migration|billing|stripe|oauth|webhook|connector|loop|workflow|agent|subagent|knowledge|hook|hooks|codewith|worktree|repo|repository|project|task|todo|todos|memento|mementos|conversation|conversations|context|config|configuration|npm|bun|package|cli|install|global|station|spark|machine|file|path|markdown|docs?|ci|tests?|build|typecheck|verify|debug|error|failing|failure|bug|regression)\b/i;
+const ACTION_SIGNAL_RE =
+  /\b(add|build|change|check|configure|create|debug|fix|implement|improve|inspect|install|merge|patch|publish|refactor|release|rerun|review|rollback|test|update|verify)\b/i;
+const STRUCTURAL_SIGNAL_RE =
+  /(`[^`]+`|(?:^|\s)(?:\.{1,2}\/)?[\w.-]+\/[\w./-]+|\/[\w./-]+|@hasna\/[a-z0-9-]+|\b(?:open|platform|iapp)-[a-z0-9-]+\b|[\w.-]+\.(ts|tsx|js|jsx|json|toml|md|yml|yaml|rs|py|go|sh|sql))/i;
+const PROJECT_CWD_SIGNAL_RE = /\/(?:open|platform|iapp)-[a-z0-9-]+(?:\/|$)|\/hasna\/(?:opensource|infra|community)\//i;
+
+export function promptSignalScore(prompt: string, cwd = ""): number {
+  const text = compactText(prompt);
+  if (!text) return 0;
+
+  let score = 0;
+  if (text.length >= 80) score += 3;
+  else if (text.length >= 40) score += 1;
+
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+  if (wordCount >= 12) score += 3;
+  if (DOMAIN_SIGNAL_RE.test(text)) score += 3;
+  if (ACTION_SIGNAL_RE.test(text)) score += 2;
+  if (STRUCTURAL_SIGNAL_RE.test(text)) score += 3;
+  if (cwd && PROJECT_CWD_SIGNAL_RE.test(cwd) && text.length >= 20) score += 2;
+  if (/\b(error|exception|failed|failure|regression|stack trace|traceback)\b/i.test(text)) score += 2;
+
+  return score;
+}
+
+export function shouldSearchKnowledge(input: HookInput, config: KnowledgeContextConfig): boolean {
+  if (!config.requireHighSignal) return true;
+  if (input.hook_event_name !== "UserPromptSubmit") return true;
+
+  const prompt = stringField(input, "prompt") || stringField(input, "user_prompt");
+  const score = promptSignalScore(prompt, stringField(input, "cwd"));
+  const promptChars = compactText(prompt).length;
+
+  return promptChars >= config.minPromptChars && score >= config.minSignalScore;
+}
+
 export function buildQuery(input: HookInput, config: KnowledgeContextConfig): string | null {
   const cwd = stringField(input, "cwd");
   const event = stringField(input, "hook_event_name");
@@ -258,16 +312,21 @@ function compactText(text: string): string {
 }
 
 function knowledgeItemId(source: string | null): string | null {
-  const match = source?.match(/^knowledge:\/\/item\/([^/?#\s]+)$/);
-  return match?.[1] ?? null;
+  const direct = source?.match(/^knowledge:\/\/item\/([^/?#\s]+)$/);
+  if (direct) return direct[1];
+
+  const legacyPath = source?.match(/(?:^|\/)(k_[A-Za-z0-9]+_[A-Za-z0-9]+)(?:[?#].*)?$/);
+  return legacyPath?.[1] ?? null;
 }
 
 function formatPackItems(items: unknown[]): string | null {
   const lines: string[] = [];
+  let hasKnowledgeItems = false;
 
   for (const [index, item] of items.entries()) {
     if (typeof item === "string" && item.trim()) {
-      lines.push(`- ${truncate(item.trim(), 900)}`);
+      const text = cleanStringItem(item);
+      if (text) lines.push(`- ${truncate(text, 900)}`);
       continue;
     }
     if (!item || typeof item !== "object") continue;
@@ -295,23 +354,35 @@ function formatPackItems(items: unknown[]): string | null {
     ]);
     if (!body && !source) continue;
 
-    const suffixParts = [
-      citationId && citationId !== title ? citationId : null,
-      source && !itemId ? `source: ${truncate(source, 180)}` : null,
-    ].filter(Boolean);
-    const suffix = suffixParts.length > 0 ? ` (${suffixParts.join("; ")})` : "";
-    lines.push(`- ${truncate(title, 160)}${suffix}${body ? `: ${truncate(compactText(body), 520)}` : ""}`);
     if (itemId) {
-      lines.push(`  open: knowledge get --id ${itemId} --json`);
+      hasKnowledgeItems = true;
+      const labelParts = [`item_id=${itemId}`];
+      if (citationId) labelParts.push(`cite=${citationId}`);
+      const preview = body ? compactText(body) : title !== itemId ? title : "";
+      lines.push(`- ${labelParts.join(" ")}${preview ? `: ${truncate(preview, 520)}` : ""}`);
+      continue;
     }
+
+    const suffixParts = [
+      citationId ? `cite=${citationId}` : null,
+      source ? `source=${truncate(source, 180)}` : null,
+    ].filter(Boolean);
+    const label = suffixParts.length > 0 ? suffixParts.join(" ") : truncate(title, 160);
+    lines.push(`- ${label}${body ? `: ${truncate(compactText(body), 520)}` : ""}`);
   }
 
-  return lines.length > 0 ? lines.join("\n") : null;
+  if (lines.length === 0) return null;
+  if (!hasKnowledgeItems) return lines.join("\n");
+  return [
+    "If a match looks relevant, read it with: knowledge get --id <item_id> --json",
+    "",
+    ...lines,
+  ].join("\n");
 }
 
 export function extractContextText(pack: unknown): string | null {
   if (typeof pack === "string") {
-    return pack.trim() || null;
+    return cleanLegacyEmptyBullet(pack.trim()) || null;
   }
   if (Array.isArray(pack)) {
     return formatPackItems(pack);
@@ -339,7 +410,7 @@ export function formatAdditionalContext(
   context: string,
   config: KnowledgeContextConfig
 ): string {
-  const header = `[hook-knowledge-context] Deterministic Knowledge context (${event}; knowledge context pack --from search):`;
+  const header = `[hook-knowledge-context] Knowledge matches (${event}; top ${config.maxItems}, deterministic search):`;
   const safeContext = redactSecrets(context.trim());
   return `${header}\n\n${truncate(safeContext, Math.max(0, config.maxOutputChars - header.length - 2))}`;
 }
@@ -363,6 +434,10 @@ export async function buildHookOutput(
   }
 
   const config = getConfig(env);
+  if (!shouldSearchKnowledge(input, config)) {
+    return { continue: true };
+  }
+
   const query = buildQuery(input, config);
   if (!query) {
     return { continue: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -73,6 +73,7 @@
     "bin/",
     "dist/",
     "hooks/",
+    "!hooks/*/dist/",
     "README.md",
     "LICENSE"
   ],