@hasna/hooks 0.3.5 → 0.3.7

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.4",
+      version: "0.1.6",
       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.4",
+    version: "0.1.6",
     category: "Context Management",
     event: "SessionStart",
     events: ["SessionStart", "UserPromptSubmit", "SubagentStart"],

package/hooks/hook-knowledge-context/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/hooks/hook-knowledge-context/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",

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

@@ -5,6 +5,7 @@ import {
   buildQuery,
   extractContextText,
   getConfig,
+  promptSignalScore,
   redactSecrets,
   sanitizeQuery,
   type KnowledgeContextConfig,
@@ -15,16 +16,49 @@ const baseConfig: KnowledgeContextConfig = {
   command: "knowledge",
   timeoutMs: 5000,
   maxItems: 3,
+  candidateItems: 12,
   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({}).candidateItems).toBe(12);
+    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_CANDIDATE_ITEMS: "15",
+      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.candidateItems).toBe(15);
+    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("15");
+    expect(getConfig({ HOOKS_KNOWLEDGE_COMMAND: "bad command" }).command).toBe("knowledge");
   });
 
   test("builds deterministic knowledge context pack args without semantic, web, or generation flags", () => {
@@ -37,7 +71,7 @@ describe("hook-knowledge-context", () => {
       "--from",
       "search",
       "--max-items",
-      "3",
+      "12",
       "--max-tokens",
       "1200",
       "--json",
@@ -67,7 +101,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 +121,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 +185,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 +246,134 @@ 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_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("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_123",
-          source_ref: "knowledge://item/k_example",
-          quote_preview: "A short preview that tells the agent why this Knowledge item might matter.",
+          id: "cite_url",
+          source_ref: "https://example.test/doc",
+          quote_preview: "External preview.",
         },
       ],
     });
 
-    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("- 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");
+  });
+
+  test("filters historical reference-only archive items from injected context", () => {
+    const text = extractContextText(
+      {
+        citations: [
+          {
+            id: "cite_archived",
+            source_ref: "knowledge://item/k_archived",
+            quote_preview:
+              "Archived on 2026-06-25 before removing brain orchestration startup files from spark01. Historical/reference only; not an active startup instruction.",
+          },
+          {
+            id: "cite_active",
+            source_ref: "knowledge://item/k_active",
+            quote_preview: "Current npm publish convention: use scoped granular tokens through the secrets CLI.",
+          },
+        ],
+      },
+      { maxItems: 3 }
+    );
+
+    expect(text).toContain("item_id=k_active cite=cite_active");
+    expect(text).toContain("Current npm publish convention");
+    expect(text).not.toContain("k_archived");
+    expect(text).not.toContain("Archived on 2026-06-25");
+  });
+
+  test("fails open when all citation candidates are non-autoloadable archive items", () => {
+    expect(
+      extractContextText(
+        {
+          citations: [
+            {
+              id: "cite_archived",
+              source_ref: "knowledge://item/k_archived",
+              quote_preview:
+                "Archived on 2026-06-25 from local Claude startup context. These instructions are historical/reference only and should not be auto-loaded for normal agents.",
+            },
+          ],
+        },
+        { maxItems: 3 }
+      )
+    ).toBeNull();
+  });
+
+  test("caps emitted items after filtering extra search candidates", () => {
+    const text = extractContextText(
+      {
+        citations: [
+          {
+            id: "cite_archived",
+            source_ref: "knowledge://item/k_archived",
+            quote_preview:
+              "Archived on 2026-06-25 before removing brain orchestration startup files. Historical/reference only; not an active startup instruction.",
+          },
+          { id: "cite_one", source_ref: "knowledge://item/k_one", quote_preview: "First active item." },
+          { id: "cite_two", source_ref: "knowledge://item/k_two", quote_preview: "Second active item." },
+          { id: "cite_three", source_ref: "knowledge://item/k_three", quote_preview: "Third active item." },
+        ],
+      },
+      { maxItems: 2 }
+    );
+
+    expect(text?.match(/^- item_id=/gm) ?? []).toHaveLength(2);
+    expect(text).toContain("item_id=k_one");
+    expect(text).toContain("item_id=k_two");
+    expect(text).not.toContain("item_id=k_three");
+    expect(text).not.toContain("item_id=k_archived");
   });
 });

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

@@ -39,9 +39,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 {
@@ -58,6 +62,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>([
@@ -92,13 +98,23 @@ function commandFromEnv(raw: string | undefined): string {
 }
 
 export function getConfig(env: NodeJS.ProcessEnv = process.env): KnowledgeContextConfig {
+  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, 10_000),
-    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, 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 +151,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");
@@ -170,7 +232,7 @@ export function buildKnowledgeArgs(query: string, config: KnowledgeContextConfig
     "--from",
     "search",
     "--max-items",
-    String(config.maxItems),
+    String(config.candidateItems),
     "--max-tokens",
     String(config.maxTokens),
     "--json",
@@ -258,16 +320,38 @@ 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;
+}
+
+interface ExtractContextOptions {
+  maxItems?: number;
+  includeHistorical?: boolean;
+}
+
+const 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;
+const ARCHIVED_STARTUP_RE = /^Archived on \d{4}-\d{2}-\d{2}\b.*\b(startup context|startup files|CLAUDE\.md)\b/i;
+
+function shouldSuppressKnowledgeItem(text: string, options: ExtractContextOptions): boolean {
+  if (options.includeHistorical) return false;
+  const compact = compactText(text);
+  return NON_AUTOLOADABLE_HISTORY_RE.test(compact) || ARCHIVED_STARTUP_RE.test(compact);
 }
 
-function formatPackItems(items: unknown[]): string | null {
+function formatPackItems(items: unknown[], options: ExtractContextOptions = {}): string | null {
   const lines: string[] = [];
+  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") continue;
@@ -294,27 +378,48 @@ function formatPackItems(items: unknown[]): string | null {
       "description",
     ]);
     if (!body && !source) continue;
+    const itemText = [title, body, source].filter(Boolean).join(" ");
+    if (shouldSuppressKnowledgeItem(itemText, options)) 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 {
+function shouldIncludeHistoricalItems(input: HookInput): boolean {
+  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);
+}
+
+export function extractContextText(pack: unknown, options: ExtractContextOptions = {}): string | null {
   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;
@@ -322,16 +427,16 @@ export function extractContextText(pack: unknown): string | null {
 
   const obj = pack as Record<string, unknown>;
   const direct = firstString(obj, ["additionalContext", "context", "markdown", "content", "text", "summary"]);
-  if (direct) return direct;
+  if (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;
 }
 
 export function formatAdditionalContext(
@@ -339,7 +444,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 +468,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 };
@@ -375,7 +484,10 @@ export async function buildHookOutput(
     }
 
     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 };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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"
   ],