@hasna/hook-knowledge-context 0.1.4 → 0.1.5

package/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/dist/hook.d.ts

@@ -32,8 +32,11 @@ export interface KnowledgeContextConfig {
     timeoutMs: number;
     maxItems: number;
     maxTokens: number;
+    minPromptChars: number;
+    minSignalScore: number;
     maxQueryChars: number;
     maxOutputChars: number;
+    requireHighSignal: boolean;
 }
 export interface KnowledgeExecResult {
     ok: boolean;
@@ -45,6 +48,8 @@ export declare function getConfig(env?: NodeJS.ProcessEnv): KnowledgeContextConf
 export declare function isKnowledgeContextEvent(value: string | undefined): value is KnowledgeContextEvent;
 export declare function redactSecrets(text: string): string;
 export declare function sanitizeQuery(text: string, maxChars: number): string;
+export declare function promptSignalScore(prompt: string, cwd?: string): number;
+export declare function shouldSearchKnowledge(input: HookInput, config: KnowledgeContextConfig): boolean;
 export declare function buildQuery(input: HookInput, config: KnowledgeContextConfig): string | null;
 export declare function buildKnowledgeArgs(query: string, config: KnowledgeContextConfig): string[];
 export declare function spawnKnowledgeContextPack(query: string, config: KnowledgeContextConfig): Promise<KnowledgeExecResult>;

package/dist/hook.js

@@ -7,6 +7,8 @@ import { spawn } from "child_process";
 var DEFAULT_TIMEOUT_MS = 5000;
 var DEFAULT_MAX_ITEMS = 3;
 var DEFAULT_MAX_TOKENS = 1200;
+var DEFAULT_MIN_PROMPT_CHARS = 6;
+var DEFAULT_MIN_SIGNAL_SCORE = 3;
 var DEFAULT_MAX_QUERY_CHARS = 1200;
 var DEFAULT_MAX_OUTPUT_CHARS = 8000;
 var SUPPORTED_EVENTS = new Set([
@@ -44,8 +46,11 @@ function getConfig(env = process.env) {
     timeoutMs: boundedNumber(env.HOOKS_KNOWLEDGE_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100, 1e4),
     maxItems: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_ITEMS, DEFAULT_MAX_ITEMS, 1, 20),
     maxTokens: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_TOKENS, DEFAULT_MAX_TOKENS, 100, 8000),
+    minPromptChars: boundedNumber(env.HOOKS_KNOWLEDGE_MIN_PROMPT_CHARS, DEFAULT_MIN_PROMPT_CHARS, 0, 4000),
+    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, 4000),
-    maxOutputChars: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS, DEFAULT_MAX_OUTPUT_CHARS, 500, 20000)
+    maxOutputChars: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS, DEFAULT_MAX_OUTPUT_CHARS, 500, 20000),
+    requireHighSignal: env.HOOKS_KNOWLEDGE_REQUIRE_HIGH_SIGNAL !== "0"
   };
 }
 function isKnowledgeContextEvent(value) {
@@ -71,6 +76,50 @@ function sanitizeQuery(text, maxChars) {
   const redacted = redactSecrets(normalized);
   return redacted.length > maxChars ? redacted.slice(0, maxChars).trim() : redacted;
 }
+function cleanLegacyEmptyBullet(text) {
+  return text.replace(/^(\s*[-*])\s*:\s*/gm, "$1 ");
+}
+function cleanStringItem(text) {
+  return cleanLegacyEmptyBullet(text).replace(/^[-*]\s*/, "").trim();
+}
+var 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;
+var 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;
+var 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;
+var PROJECT_CWD_SIGNAL_RE = /\/(?:open|platform|iapp)-[a-z0-9-]+(?:\/|$)|\/hasna\/(?:opensource|infra|community)\//i;
+function promptSignalScore(prompt, cwd = "") {
+  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;
+}
+function shouldSearchKnowledge(input, config) {
+  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;
+}
 function buildQuery(input, config) {
   const cwd = stringField(input, "cwd");
   const event = stringField(input, "hook_event_name");
@@ -177,14 +226,20 @@ function compactText(text) {
   return text.replace(/\s+/g, " ").trim();
 }
 function knowledgeItemId(source) {
-  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) {
   const lines = [];
+  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")
@@ -208,22 +263,37 @@ function formatPackItems(items) {
     ]);
     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(`
-`) : null;
+  if (lines.length === 0)
+    return null;
+  if (!hasKnowledgeItems)
+    return lines.join(`
+`);
+  return [
+    "If a match looks relevant, read it with: knowledge get --id <item_id> --json",
+    "",
+    ...lines
+  ].join(`
+`);
 }
 function extractContextText(pack) {
   if (typeof pack === "string") {
-    return pack.trim() || null;
+    return cleanLegacyEmptyBullet(pack.trim()) || null;
   }
   if (Array.isArray(pack)) {
     return formatPackItems(pack);
@@ -245,7 +315,7 @@ function extractContextText(pack) {
   return items ? formatPackItems(items) : null;
 }
 function formatAdditionalContext(event, context, config) {
-  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}
 
@@ -263,6 +333,9 @@ async function buildHookOutput(input, executor = spawnKnowledgeContextPack, env
     return { continue: true };
   }
   const config = getConfig(env);
+  if (!shouldSearchKnowledge(input, config)) {
+    return { continue: true };
+  }
   const query = buildQuery(input, config);
   if (!query) {
     return { continue: true };
@@ -297,9 +370,11 @@ if (import.meta.main) {
 export {
   truncate,
   spawnKnowledgeContextPack,
+  shouldSearchKnowledge,
   sanitizeQuery,
   run,
   redactSecrets,
+  promptSignalScore,
   isKnowledgeContextEvent,
   getConfig,
   formatAdditionalContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hook-knowledge-context",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Codewith hook that injects deterministic Knowledge context packs into lifecycle events",
   "type": "module",
   "main": "./dist/hook.js",