@hasna/hooks 0.3.6 → 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.5",
+      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.5",
+    version: "0.1.6",
     category: "Context Management",
     event: "SessionStart",
     events: ["SessionStart", "UserPromptSubmit", "SubagentStart"],

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

@@ -34,7 +34,9 @@ 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 bounded previews and a
 single `knowledge get --id <item_id> --json` hint so agents can decide which
-full items are worth opening.
+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:
 
@@ -55,7 +57,8 @@ 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

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

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hook-knowledge-context",
-  "version": "0.1.5",
+  "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

@@ -16,6 +16,7 @@ const baseConfig: KnowledgeContextConfig = {
   command: "knowledge",
   timeoutMs: 5000,
   maxItems: 3,
+  candidateItems: 12,
   maxTokens: 1200,
   minPromptChars: 6,
   minSignalScore: 3,
@@ -28,6 +29,7 @@ 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);
@@ -39,6 +41,7 @@ describe("hook-knowledge-context", () => {
     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",
@@ -48,12 +51,13 @@ describe("hook-knowledge-context", () => {
 
     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("9");
+    expect(buildKnowledgeArgs("q", config)).toContain("15");
     expect(getConfig({ HOOKS_KNOWLEDGE_COMMAND: "bad command" }).command).toBe("knowledge");
   });
 
@@ -67,7 +71,7 @@ describe("hook-knowledge-context", () => {
       "--from",
       "search",
       "--max-items",
-      "3",
+      "12",
       "--max-tokens",
       "1200",
       "--json",
@@ -303,4 +307,73 @@ describe("hook-knowledge-context", () => {
     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,6 +39,7 @@ export interface KnowledgeContextConfig {
   command: string;
   timeoutMs: number;
   maxItems: number;
+  candidateItems: number;
   maxTokens: number;
   minPromptChars: number;
   minSignalScore: number;
@@ -97,10 +98,17 @@ 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),
@@ -224,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",
@@ -319,14 +327,31 @@ function knowledgeItemId(source: string | null): string | null {
   return legacyPath?.[1] ?? null;
 }
 
-function formatPackItems(items: unknown[]): string | 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[], 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()) {
       const text = cleanStringItem(item);
-      if (text) lines.push(`- ${truncate(text, 900)}`);
+      if (text && !shouldSuppressKnowledgeItem(text, options)) lines.push(`- ${truncate(text, 900)}`);
       continue;
     }
     if (!item || typeof item !== "object") continue;
@@ -353,6 +378,8 @@ function formatPackItems(items: unknown[]): string | null {
       "description",
     ]);
     if (!body && !source) continue;
+    const itemText = [title, body, source].filter(Boolean).join(" ");
+    if (shouldSuppressKnowledgeItem(itemText, options)) continue;
 
     if (itemId) {
       hasKnowledgeItems = true;
@@ -380,12 +407,19 @@ function formatPackItems(items: unknown[]): string | null {
   ].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 cleanLegacyEmptyBullet(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;
@@ -393,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(
@@ -450,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.6",
+  "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": {