@hasna/hook-knowledge-context 0.1.4 → 0.1.6

package/README.md

@@ -27,12 +27,26 @@ 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. Items that mark themselves as
+historical/reference-only or not suitable for auto-loading are filtered out by
+default, because they are not useful ambient context for normal agent work.
+
+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.
@@ -43,12 +57,20 @@ bad stdin, or empty packs return `{"continue":true}` without context.
 export HOOKS_KNOWLEDGE_CONTEXT_DISABLE=1    # Kill switch
 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_ITEMS=3          # Rendered item budget
+export HOOKS_KNOWLEDGE_CANDIDATE_ITEMS=12   # Internal candidate budget before filtering
 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

@@ -31,9 +31,13 @@ export interface KnowledgeContextConfig {
     command: string;
     timeoutMs: number;
     maxItems: number;
+    candidateItems: number;
     maxTokens: number;
+    minPromptChars: number;
+    minSignalScore: number;
     maxQueryChars: number;
     maxOutputChars: number;
+    requireHighSignal: boolean;
 }
 export interface KnowledgeExecResult {
     ok: boolean;
@@ -45,11 +49,17 @@ 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>;
 export declare function truncate(text: string, max: number): string;
-export declare function extractContextText(pack: unknown): string | null;
+interface ExtractContextOptions {
+    maxItems?: number;
+    includeHistorical?: boolean;
+}
+export declare function extractContextText(pack: unknown, options?: ExtractContextOptions): string | null;
 export declare function formatAdditionalContext(event: KnowledgeContextEvent, context: string, config: KnowledgeContextConfig): string;
 export declare function buildHookOutput(input: HookInput | null, executor?: KnowledgeExecutor, env?: NodeJS.ProcessEnv): Promise<HookOutput>;
 export declare function run(): Promise<void>;

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([
@@ -39,13 +41,18 @@ function commandFromEnv(raw) {
   return "knowledge";
 }
 function getConfig(env = process.env) {
+  const maxItems = boundedNumber(env.HOOKS_KNOWLEDGE_MAX_ITEMS, DEFAULT_MAX_ITEMS, 1, 20);
   return {
     command: commandFromEnv(env.HOOKS_KNOWLEDGE_COMMAND),
     timeoutMs: boundedNumber(env.HOOKS_KNOWLEDGE_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100, 1e4),
-    maxItems: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_ITEMS, DEFAULT_MAX_ITEMS, 1, 20),
+    maxItems,
+    candidateItems: boundedNumber(env.HOOKS_KNOWLEDGE_CANDIDATE_ITEMS, Math.min(20, Math.max(maxItems, maxItems * 4)), maxItems, 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 +78,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");
@@ -98,7 +149,7 @@ function buildKnowledgeArgs(query, config) {
     "--from",
     "search",
     "--max-items",
-    String(config.maxItems),
+    String(config.candidateItems),
     "--max-tokens",
     String(config.maxTokens),
     "--json"
@@ -177,14 +228,31 @@ 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;
+}
+var NON_AUTOLOADABLE_HISTORY_RE = /\b(historical\/reference only|historical reference only|should not be auto-?loaded|do not auto-?load|not an active startup instruction|brain orchestration startup files)\b/i;
+var ARCHIVED_STARTUP_RE = /^Archived on \d{4}-\d{2}-\d{2}\b.*\b(startup context|startup files|CLAUDE\.md)\b/i;
+function shouldSuppressKnowledgeItem(text, options) {
+  if (options.includeHistorical)
+    return false;
+  const compact = compactText(text);
+  return NON_AUTOLOADABLE_HISTORY_RE.test(compact) || ARCHIVED_STARTUP_RE.test(compact);
 }
-function formatPackItems(items) {
+function formatPackItems(items, options = {}) {
   const lines = [];
+  let hasKnowledgeItems = false;
+  const maxItems = options.maxItems ?? DEFAULT_MAX_ITEMS;
   for (const [index, item] of items.entries()) {
+    if (lines.length >= maxItems)
+      break;
     if (typeof item === "string" && item.trim()) {
-      lines.push(`- ${truncate(item.trim(), 900)}`);
+      const text = cleanStringItem(item);
+      if (text && !shouldSuppressKnowledgeItem(text, options))
+        lines.push(`- ${truncate(text, 900)}`);
       continue;
     }
     if (!item || typeof item !== "object")
@@ -208,25 +276,50 @@ 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)}` : ""}`);
+    const itemText = [title, body, source].filter(Boolean).join(" ");
+    if (shouldSuppressKnowledgeItem(itemText, options))
+      continue;
     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) {
+function shouldIncludeHistoricalItems(input) {
+  const prompt = `${stringField(input, "prompt")} ${stringField(input, "user_prompt")}`;
+  return /\b(archive|archived|historical|history|reference-only|reference only|old startup|startup files|CLAUDE\.md)\b/i.test(prompt);
+}
+function extractContextText(pack, options = {}) {
   if (typeof pack === "string") {
-    return pack.trim() || null;
+    const text = cleanLegacyEmptyBullet(pack.trim());
+    if (!text || shouldSuppressKnowledgeItem(text, options))
+      return null;
+    return text;
   }
   if (Array.isArray(pack)) {
-    return formatPackItems(pack);
+    return formatPackItems(pack, options);
   }
   if (!pack || typeof pack !== "object") {
     return null;
@@ -234,18 +327,18 @@ function extractContextText(pack) {
   const obj = pack;
   const direct = firstString(obj, ["additionalContext", "context", "markdown", "content", "text", "summary"]);
   if (direct)
-    return direct;
+    return shouldSuppressKnowledgeItem(direct, options) ? null : direct;
   for (const key of ["pack", "contextPack", "context_pack", "data", "result"]) {
     const nested = obj[key];
-    const text = extractContextText(nested);
+    const text = extractContextText(nested, options);
     if (text)
       return text;
   }
   const items = firstArray(obj, ["items", "results", "sources", "citations"]);
-  return items ? formatPackItems(items) : null;
+  return items ? formatPackItems(items, options) : 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 +356,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 };
@@ -273,7 +369,10 @@ async function buildHookOutput(input, executor = spawnKnowledgeContextPack, env
       return { continue: true };
     }
     const parsed = JSON.parse(result.stdout);
-    const context = extractContextText(parsed);
+    const context = extractContextText(parsed, {
+      maxItems: config.maxItems,
+      includeHistorical: shouldIncludeHistoricalItems(input)
+    });
     if (!context) {
       return { continue: true };
     }
@@ -297,9 +396,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.6",
   "description": "Codewith hook that injects deterministic Knowledge context packs into lifecycle events",
   "type": "module",
   "main": "./dist/hook.js",