@hasna/hooks 0.3.0 → 0.3.1

package/README.md

@@ -28,26 +28,27 @@ hooks --help
 
 ## Codewith-native hooks
 
-@hasna/hooks includes five unprefixed Codewith-native hook names:
+@hasna/hooks includes unprefixed Codewith-native hook names:
 
 - `session-start` — `SessionStart` digest and additional context.
 - `prompt-guard` — `UserPromptSubmit` guard for pasted fake policy/freeze/run-this-now content.
 - `pre-bash` — `PreToolUse` Bash gate for staged secrets scans and risky-op comms checks.
 - `worktree-guard` — `PreToolUse` guard for managed repos worktree boundaries.
 - `stop-sync` — `Stop` turn-end heartbeat/evidence best effort.
+- `knowledge-context` — deterministic Knowledge context packs for `SessionStart`, `UserPromptSubmit`, and `SubagentStart`.
 
 For Codewith, the installer is renderer-safe by default: it emits a TOML
 fragment instead of mutating managed `~/.codewith/config.toml`.
 
 ```bash
-hooks install session-start prompt-guard pre-bash worktree-guard stop-sync --target codewith
+hooks install session-start prompt-guard pre-bash worktree-guard stop-sync knowledge-context --target codewith
 ```
 
 Apply that fragment through `open-configs` or the managed config renderer. A
 direct write path exists only for explicit local/test use:
 
 ```bash
-hooks install session-start --target codewith --apply-codewith --codewith-config /tmp/codewith-config.toml
+hooks install knowledge-context --target codewith --apply-codewith --codewith-config /tmp/codewith-config.toml
 ```
 
 ## Storage

package/bin/index.js

@@ -1890,6 +1890,9 @@ var require_commander = __commonJS((exports) => {
 function getHooksByCategory(category) {
   return HOOKS.filter((h) => h.category === category);
 }
+function getHookEvents(hook) {
+  return hook.events && hook.events.length > 0 ? hook.events : [hook.event];
+}
 function searchHooks(query) {
   const q = query.toLowerCase();
   return HOOKS.filter((h) => h.name.toLowerCase().includes(q) || h.displayName.toLowerCase().includes(q) || h.description.toLowerCase().includes(q) || h.tags.some((t) => t.includes(q)));
@@ -2082,6 +2085,17 @@ var init_registry = __esm(() => {
       matcher: "",
       tags: ["context", "compaction", "state", "backup"]
     },
+    {
+      name: "knowledge-context",
+      displayName: "Knowledge Context",
+      description: "Injects deterministic Knowledge context packs into Codewith SessionStart, UserPromptSubmit, and SubagentStart",
+      version: "0.1.0",
+      category: "Context Management",
+      event: "SessionStart",
+      events: ["SessionStart", "UserPromptSubmit", "SubagentStart"],
+      matcher: "",
+      tags: ["knowledge", "context", "codewith", "deterministic", "session-start", "prompt", "subagent"]
+    },
     {
       name: "autoformat",
       displayName: "Auto Format",
@@ -4111,6 +4125,8 @@ function codewithMatcher(matcher) {
 }
 function codewithTimeout(name) {
   switch (name) {
+    case "knowledge-context":
+      return 2;
     case "session-start":
       return 8;
     case "pre-bash":
@@ -4126,6 +4142,8 @@ function codewithTimeout(name) {
 }
 function codewithStatusMessage(name) {
   switch (name) {
+    case "knowledge-context":
+      return "Loading Knowledge context";
     case "session-start":
       return "Checking Hasna session context";
     case "pre-bash":
@@ -4145,19 +4163,25 @@ function buildCodewithTomlFragment(name, profile) {
   const meta = getHook(shortName);
   if (!meta)
     throw new Error(`Hook '${shortName}' not found`);
-  const eventKey = getTargetEventName(meta.event, "codewith");
-  if (!eventKey) {
-    throw new Error(`Hook '${shortName}' uses event '${meta.event}', which is not supported by the Codewith target`);
-  }
   const command = profile ? `hooks run ${shortName} --profile ${profile}` : `hooks run ${shortName}`;
   const matcher = codewithMatcher(meta.matcher);
-  const lines = [
-    `[[hooks.${eventKey}]]`
-  ];
-  if (matcher)
-    lines.push(`matcher = ${tomlString(matcher)}`);
-  lines.push("", `[[hooks.${eventKey}.hooks]]`, `type = "command"`, `command = ${tomlString(command)}`, `timeout = ${codewithTimeout(shortName)}`, `statusMessage = ${tomlString(codewithStatusMessage(shortName))}`);
-  return `${lines.join(`
+  const fragments = [];
+  for (const event of getHookEvents(meta)) {
+    const eventKey = getTargetEventName(event, "codewith");
+    if (!eventKey) {
+      throw new Error(`Hook '${shortName}' uses event '${event}', which is not supported by the Codewith target`);
+    }
+    const lines = [
+      `[[hooks.${eventKey}]]`
+    ];
+    if (matcher)
+      lines.push(`matcher = ${tomlString(matcher)}`);
+    lines.push("", `[[hooks.${eventKey}.hooks]]`, `type = "command"`, `command = ${tomlString(command)}`, `timeout = ${codewithTimeout(shortName)}`, `statusMessage = ${tomlString(codewithStatusMessage(shortName))}`);
+    fragments.push(lines.join(`
+`));
+  }
+  return `${fragments.join(`
+
 `)}
 `;
 }
@@ -4185,12 +4209,15 @@ function detectConflict(name, scope, target) {
   const meta = getHook(name);
   if (!meta || !meta.matcher)
     return;
+  const events = new Set(getHookEvents(meta));
   const registered = getRegisteredHooksForTarget(scope, target);
   for (const existingName of registered) {
     if (existingName === name)
       continue;
     const existing = getHook(existingName);
-    if (!existing || existing.event !== meta.event || !existing.matcher)
+    if (!existing || !existing.matcher)
+      continue;
+    if (!getHookEvents(existing).some((event) => events.has(event)))
       continue;
     const a = meta.matcher.toLowerCase();
     const b = existing.matcher.toLowerCase();
@@ -4277,12 +4304,12 @@ function installHook(name, options = {}) {
     const shortName = shortHookName(name);
     const meta = getHook(shortName);
     if (meta) {
-      const unsupportedTargets = ["claude", "gemini", "codewith"].filter((agentTarget) => !isEventSupported(meta.event, agentTarget));
+      const unsupportedTargets = ["claude", "gemini", "codewith"].filter((agentTarget) => getHookEvents(meta).some((event) => !isEventSupported(event, agentTarget)));
       if (unsupportedTargets.length > 0) {
         return {
           hook: shortName,
           success: false,
-          error: `Event '${meta.event}' is not supported by target(s): ${unsupportedTargets.join(", ")}`,
+          error: `Event(s) '${getHookEvents(meta).join(", ")}' are not supported by target(s): ${unsupportedTargets.join(", ")}`,
           target: "all"
         };
       }
@@ -4319,24 +4346,33 @@ function registerHook(name, scope = "global", target = "claude", profile) {
   const meta = getHook(name);
   if (!meta)
     return;
-  const eventKey = getTargetEventName(meta.event, target);
-  if (eventKey === null) {
-    throw new Error(`Event '${meta.event}' is not supported by target '${target}'`);
+  const eventKeys = getHookEvents(meta).map((event) => {
+    const eventKey = getTargetEventName(event, target);
+    if (eventKey === null) {
+      throw new Error(`Event '${event}' is not supported by target '${target}'`);
+    }
+    return eventKey;
+  });
+  const uniqueEventKeys = [...new Set(eventKeys)];
+  if (uniqueEventKeys.length === 0) {
+    throw new Error(`Hook '${name}' has no installable events for target '${target}'`);
   }
   const settings = readSettings(scope, target);
   if (!settings.hooks)
     settings.hooks = {};
   removeHookFromAllEvents(settings, name);
-  if (!settings.hooks[eventKey])
-    settings.hooks[eventKey] = [];
   const hookCommand = profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`;
-  const entry = {
-    hooks: [{ type: "command", command: hookCommand }]
-  };
-  if (meta.matcher) {
-    entry.matcher = meta.matcher;
+  for (const eventKey of uniqueEventKeys) {
+    if (!settings.hooks[eventKey])
+      settings.hooks[eventKey] = [];
+    const entry = {
+      hooks: [{ type: "command", command: hookCommand }]
+    };
+    if (meta.matcher) {
+      entry.matcher = meta.matcher;
+    }
+    settings.hooks[eventKey].push(entry);
   }
-  settings.hooks[eventKey].push(entry);
   writeSettings(settings, scope, target);
 }
 function removeHookFromAllEvents(settings, name) {
@@ -4427,7 +4463,8 @@ var init_installer = __esm(() => {
       Notification: "Notification",
       SessionStart: "SessionStart",
       SessionEnd: "SessionEnd",
-      UserPromptSubmit: null
+      UserPromptSubmit: null,
+      SubagentStart: null
     },
     gemini: {
       PreToolUse: "BeforeTool",
@@ -4436,7 +4473,8 @@ var init_installer = __esm(() => {
       Notification: "Notification",
       SessionStart: null,
       SessionEnd: null,
-      UserPromptSubmit: null
+      UserPromptSubmit: null,
+      SubagentStart: null
     },
     codewith: {
       PreToolUse: "PreToolUse",
@@ -4445,7 +4483,8 @@ var init_installer = __esm(() => {
       Notification: null,
       SessionStart: "SessionStart",
       SessionEnd: null,
-      UserPromptSubmit: "UserPromptSubmit"
+      UserPromptSubmit: "UserPromptSubmit",
+      SubagentStart: "SubagentStart"
     }
   };
   getInstalledHooks = getRegisteredHooks;

package/dist/index.d.ts

@@ -7,9 +7,9 @@
  * Or use the interactive CLI:
  *   npx @hasna/hooks
  */
-export { HOOKS, HOOK_EVENTS, CATEGORIES, getHook, getHooksByCategory, searchHooks, type HookMeta, type HookEvent, type Category, } from "./lib/registry.js";
+export { HOOKS, HOOK_EVENTS, CATEGORIES, getHook, getHookEvents, getHooksByCategory, searchHooks, type HookMeta, type HookEvent, type Category, } from "./lib/registry.js";
 import type { HookEvent as HookEventType } from "./lib/registry.js";
-export { installHook, installHooks, getInstalledHooks, getRegisteredHooks, getRegisteredHooksForTarget, removeHook, hookExists, buildCodewithTomlFragment, getHookPath, getSettingsPath, isEventSupported, type InstallResult, type InstallOptions, type Scope, type Target, type CodewithInstallMode, } from "./lib/installer.js";
+export { installHook, installHooks, getInstalledHooks, getRegisteredHooks, getRegisteredHooksForTarget, removeHook, hookExists, buildCodewithTomlFragment, getHookPath, getSettingsPath, isEventSupported, type InstallResult, type InstallOptions, type Scope, type ConcreteTarget, type Target, type CodewithInstallMode, } from "./lib/installer.js";
 export interface HookAgentInfo {
     agent_id: string;
     agent_type: "claude" | "gemini" | "codewith" | "custom";
@@ -33,7 +33,7 @@ export interface HookOutput {
     reason?: string;
     continue?: boolean;
     hookSpecificOutput?: {
-        hookEventName: "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "Stop" | "Notification" | "SessionEnd";
+        hookEventName: "SessionStart" | "UserPromptSubmit" | "SubagentStart" | "PreToolUse" | "PostToolUse" | "Stop" | "Notification" | "SessionEnd";
         additionalContext?: string;
         permissionDecision?: "allow" | "deny" | "ask";
         permissionDecisionReason?: string;

package/dist/index.js

@@ -820,7 +820,8 @@ var HOOK_EVENTS = [
   "Notification",
   "SessionStart",
   "SessionEnd",
-  "UserPromptSubmit"
+  "UserPromptSubmit",
+  "SubagentStart"
 ];
 var CATEGORIES = [
   "Git Safety",
@@ -1005,6 +1006,17 @@ var HOOKS = [
     matcher: "",
     tags: ["context", "compaction", "state", "backup"]
   },
+  {
+    name: "knowledge-context",
+    displayName: "Knowledge Context",
+    description: "Injects deterministic Knowledge context packs into Codewith SessionStart, UserPromptSubmit, and SubagentStart",
+    version: "0.1.0",
+    category: "Context Management",
+    event: "SessionStart",
+    events: ["SessionStart", "UserPromptSubmit", "SubagentStart"],
+    matcher: "",
+    tags: ["knowledge", "context", "codewith", "deterministic", "session-start", "prompt", "subagent"]
+  },
   {
     name: "autoformat",
     displayName: "Auto Format",
@@ -1309,6 +1321,9 @@ var HOOKS = [
 function getHooksByCategory(category) {
   return HOOKS.filter((h) => h.category === category);
 }
+function getHookEvents(hook) {
+  return hook.events && hook.events.length > 0 ? hook.events : [hook.event];
+}
 function searchHooks(query) {
   const q = query.toLowerCase();
   return HOOKS.filter((h) => h.name.toLowerCase().includes(q) || h.displayName.toLowerCase().includes(q) || h.description.toLowerCase().includes(q) || h.tags.some((t) => t.includes(q)));
@@ -1343,7 +1358,8 @@ var EVENT_MAP = {
     Notification: "Notification",
     SessionStart: "SessionStart",
     SessionEnd: "SessionEnd",
-    UserPromptSubmit: null
+    UserPromptSubmit: null,
+    SubagentStart: null
   },
   gemini: {
     PreToolUse: "BeforeTool",
@@ -1352,7 +1368,8 @@ var EVENT_MAP = {
     Notification: "Notification",
     SessionStart: null,
     SessionEnd: null,
-    UserPromptSubmit: null
+    UserPromptSubmit: null,
+    SubagentStart: null
   },
   codewith: {
     PreToolUse: "PreToolUse",
@@ -1361,7 +1378,8 @@ var EVENT_MAP = {
     Notification: null,
     SessionStart: "SessionStart",
     SessionEnd: null,
-    UserPromptSubmit: "UserPromptSubmit"
+    UserPromptSubmit: "UserPromptSubmit",
+    SubagentStart: "SubagentStart"
   }
 };
 function getTargetSettingsDir(target) {
@@ -1433,6 +1451,8 @@ function codewithMatcher(matcher) {
 }
 function codewithTimeout(name) {
   switch (name) {
+    case "knowledge-context":
+      return 2;
     case "session-start":
       return 8;
     case "pre-bash":
@@ -1448,6 +1468,8 @@ function codewithTimeout(name) {
 }
 function codewithStatusMessage(name) {
   switch (name) {
+    case "knowledge-context":
+      return "Loading Knowledge context";
     case "session-start":
       return "Checking Hasna session context";
     case "pre-bash":
@@ -1467,19 +1489,25 @@ function buildCodewithTomlFragment(name, profile) {
   const meta = getHook(shortName);
   if (!meta)
     throw new Error(`Hook '${shortName}' not found`);
-  const eventKey = getTargetEventName(meta.event, "codewith");
-  if (!eventKey) {
-    throw new Error(`Hook '${shortName}' uses event '${meta.event}', which is not supported by the Codewith target`);
-  }
   const command = profile ? `hooks run ${shortName} --profile ${profile}` : `hooks run ${shortName}`;
   const matcher = codewithMatcher(meta.matcher);
-  const lines = [
-    `[[hooks.${eventKey}]]`
-  ];
-  if (matcher)
-    lines.push(`matcher = ${tomlString(matcher)}`);
-  lines.push("", `[[hooks.${eventKey}.hooks]]`, `type = "command"`, `command = ${tomlString(command)}`, `timeout = ${codewithTimeout(shortName)}`, `statusMessage = ${tomlString(codewithStatusMessage(shortName))}`);
-  return `${lines.join(`
+  const fragments = [];
+  for (const event of getHookEvents(meta)) {
+    const eventKey = getTargetEventName(event, "codewith");
+    if (!eventKey) {
+      throw new Error(`Hook '${shortName}' uses event '${event}', which is not supported by the Codewith target`);
+    }
+    const lines = [
+      `[[hooks.${eventKey}]]`
+    ];
+    if (matcher)
+      lines.push(`matcher = ${tomlString(matcher)}`);
+    lines.push("", `[[hooks.${eventKey}.hooks]]`, `type = "command"`, `command = ${tomlString(command)}`, `timeout = ${codewithTimeout(shortName)}`, `statusMessage = ${tomlString(codewithStatusMessage(shortName))}`);
+    fragments.push(lines.join(`
+`));
+  }
+  return `${fragments.join(`
+
 `)}
 `;
 }
@@ -1507,12 +1535,15 @@ function detectConflict(name, scope, target) {
   const meta = getHook(name);
   if (!meta || !meta.matcher)
     return;
+  const events = new Set(getHookEvents(meta));
   const registered = getRegisteredHooksForTarget(scope, target);
   for (const existingName of registered) {
     if (existingName === name)
       continue;
     const existing = getHook(existingName);
-    if (!existing || existing.event !== meta.event || !existing.matcher)
+    if (!existing || !existing.matcher)
+      continue;
+    if (!getHookEvents(existing).some((event) => events.has(event)))
       continue;
     const a = meta.matcher.toLowerCase();
     const b = existing.matcher.toLowerCase();
@@ -1599,12 +1630,12 @@ function installHook(name, options = {}) {
     const shortName = shortHookName(name);
     const meta = getHook(shortName);
     if (meta) {
-      const unsupportedTargets = ["claude", "gemini", "codewith"].filter((agentTarget) => !isEventSupported(meta.event, agentTarget));
+      const unsupportedTargets = ["claude", "gemini", "codewith"].filter((agentTarget) => getHookEvents(meta).some((event) => !isEventSupported(event, agentTarget)));
       if (unsupportedTargets.length > 0) {
         return {
           hook: shortName,
           success: false,
-          error: `Event '${meta.event}' is not supported by target(s): ${unsupportedTargets.join(", ")}`,
+          error: `Event(s) '${getHookEvents(meta).join(", ")}' are not supported by target(s): ${unsupportedTargets.join(", ")}`,
           target: "all"
         };
       }
@@ -1641,24 +1672,33 @@ function registerHook(name, scope = "global", target = "claude", profile) {
   const meta = getHook(name);
   if (!meta)
     return;
-  const eventKey = getTargetEventName(meta.event, target);
-  if (eventKey === null) {
-    throw new Error(`Event '${meta.event}' is not supported by target '${target}'`);
+  const eventKeys = getHookEvents(meta).map((event) => {
+    const eventKey = getTargetEventName(event, target);
+    if (eventKey === null) {
+      throw new Error(`Event '${event}' is not supported by target '${target}'`);
+    }
+    return eventKey;
+  });
+  const uniqueEventKeys = [...new Set(eventKeys)];
+  if (uniqueEventKeys.length === 0) {
+    throw new Error(`Hook '${name}' has no installable events for target '${target}'`);
   }
   const settings = readSettings(scope, target);
   if (!settings.hooks)
     settings.hooks = {};
   removeHookFromAllEvents(settings, name);
-  if (!settings.hooks[eventKey])
-    settings.hooks[eventKey] = [];
   const hookCommand = profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`;
-  const entry = {
-    hooks: [{ type: "command", command: hookCommand }]
-  };
-  if (meta.matcher) {
-    entry.matcher = meta.matcher;
+  for (const eventKey of uniqueEventKeys) {
+    if (!settings.hooks[eventKey])
+      settings.hooks[eventKey] = [];
+    const entry = {
+      hooks: [{ type: "command", command: hookCommand }]
+    };
+    if (meta.matcher) {
+      entry.matcher = meta.matcher;
+    }
+    settings.hooks[eventKey].push(entry);
   }
-  settings.hooks[eventKey].push(entry);
   writeSettings(settings, scope, target);
 }
 function removeHookFromAllEvents(settings, name) {
@@ -1833,6 +1873,7 @@ export {
   getInstalledHooks,
   getHooksByCategory,
   getHookPath,
+  getHookEvents,
   getHook,
   exportProfiles,
   deleteProfile,

package/dist/lib/installer.d.ts

@@ -9,10 +9,11 @@
  * Hooks run directly from the globally installed @hasna/hooks package.
  * No files are copied. The settings entry points to `hooks run <name>`.
  */
-import type { HookEvent } from "./registry.js";
+import { type HookEvent } from "./registry.js";
 export type Scope = "global" | "project";
 export type Target = "claude" | "gemini" | "codewith" | "all";
 type SingleTarget = Exclude<Target, "all">;
+export type ConcreteTarget = SingleTarget;
 export type CodewithInstallMode = "fragment" | "write";
 export interface InstallResult {
     hook: string;

package/dist/lib/registry.d.ts

@@ -1,7 +1,7 @@
 /**
  * Hook registry - metadata about all available hooks
  */
-export type HookEvent = "PreToolUse" | "PostToolUse" | "Stop" | "Notification" | "SessionStart" | "SessionEnd" | "UserPromptSubmit";
+export type HookEvent = "PreToolUse" | "PostToolUse" | "Stop" | "Notification" | "SessionStart" | "SessionEnd" | "UserPromptSubmit" | "SubagentStart";
 export declare const HOOK_EVENTS: HookEvent[];
 export interface HookMeta {
     name: string;
@@ -10,6 +10,7 @@ export interface HookMeta {
     version: string;
     category: string;
     event: HookEvent;
+    events?: HookEvent[];
     matcher: string;
     tags: string[];
 }
@@ -17,5 +18,6 @@ export declare const CATEGORIES: readonly ["Git Safety", "Code Quality", "Securi
 export type Category = (typeof CATEGORIES)[number];
 export declare const HOOKS: HookMeta[];
 export declare function getHooksByCategory(category: Category): HookMeta[];
+export declare function getHookEvents(hook: HookMeta): HookEvent[];
 export declare function searchHooks(query: string): HookMeta[];
 export declare function getHook(name: string): HookMeta | undefined;

package/hooks/codewith-native-common.ts

@@ -31,7 +31,7 @@ export interface CodewithHookOutput {
   suppressOutput?: boolean;
   systemMessage?: string;
   hookSpecificOutput?: {
-    hookEventName: "SessionStart" | "UserPromptSubmit" | "PreToolUse";
+    hookEventName: "SessionStart" | "UserPromptSubmit" | "SubagentStart" | "PreToolUse";
     additionalContext?: string;
     permissionDecision?: "allow" | "deny" | "ask";
     permissionDecisionReason?: string;

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

@@ -0,0 +1,53 @@
+# hook-knowledge-context
+
+Codewith lifecycle hook that injects deterministic Knowledge context packs.
+
+## Installation
+
+```bash
+hooks install knowledge-context --target codewith
+```
+
+By default this prints a Codewith TOML fragment and does not mutate managed
+Codewith config. Apply that fragment through `open-configs` or the managed
+config renderer. For explicit local testing only:
+
+```bash
+hooks install knowledge-context --target codewith --apply-codewith --codewith-config /tmp/codewith-config.toml
+```
+
+## How it works
+
+On `SessionStart`, `UserPromptSubmit`, and `SubagentStart`, the hook builds a
+small redacted query from the hook input and runs:
+
+```bash
+knowledge context pack <query> --from search --max-items <n> --max-tokens <n> --json
+```
+
+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.
+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.
+
+All failures are fail-open: missing CLI, timeout, nonzero exit, malformed JSON,
+bad stdin, or empty packs return `{"continue":true}` without context.
+
+## Configuration
+
+```bash
+export HOOKS_KNOWLEDGE_CONTEXT_DISABLE=1    # Kill switch
+export HOOKS_KNOWLEDGE_COMMAND=knowledge    # CLI command/path
+export HOOKS_KNOWLEDGE_TIMEOUT_MS=1500      # Per-call timeout
+export HOOKS_KNOWLEDGE_MAX_ITEMS=6          # Context pack item budget
+export HOOKS_KNOWLEDGE_MAX_TOKENS=1200      # Context pack token budget
+export HOOKS_KNOWLEDGE_MAX_QUERY_CHARS=1200 # Redacted query bound
+export HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS=8000
+```
+
+## Events
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `SubagentStart`

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

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/hook-knowledge-context",
+  "version": "0.1.0",
+  "description": "Codewith hook that injects deterministic Knowledge context packs into lifecycle events",
+  "type": "module",
+  "main": "./dist/hook.js",
+  "exports": {
+    ".": {
+      "import": "./dist/hook.js",
+      "types": "./dist/hook.d.ts"
+    }
+  },
+  "files": [
+    "dist/hook.js",
+    "dist/hook.d.ts",
+    "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",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "codewith",
+    "hook",
+    "knowledge",
+    "context",
+    "deterministic",
+    "session-start",
+    "user-prompt-submit",
+    "subagent-start"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasna/hooks.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "@types/node": "^20",
+    "typescript": "^5.0.0"
+  }
+}

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

@@ -0,0 +1,168 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildHookOutput,
+  buildKnowledgeArgs,
+  buildQuery,
+  extractContextText,
+  getConfig,
+  redactSecrets,
+  sanitizeQuery,
+  type KnowledgeContextConfig,
+  type KnowledgeExecutor,
+} from "./hook";
+
+const baseConfig: KnowledgeContextConfig = {
+  command: "knowledge",
+  timeoutMs: 1500,
+  maxItems: 6,
+  maxTokens: 1200,
+  maxQueryChars: 1200,
+  maxOutputChars: 8000,
+};
+
+describe("hook-knowledge-context", () => {
+  test("builds deterministic knowledge context pack args without semantic, web, or generation flags", () => {
+    const args = buildKnowledgeArgs("repo hook context", baseConfig);
+
+    expect(args).toEqual([
+      "context",
+      "pack",
+      "repo hook context",
+      "--from",
+      "search",
+      "--max-items",
+      "6",
+      "--max-tokens",
+      "1200",
+      "--json",
+    ]);
+    expect(args).not.toContain("--semantic");
+    expect(args).not.toContain("--generate");
+    expect(args).not.toContain("web");
+    expect(args).not.toContain("ask");
+    expect(args).not.toContain("build");
+  });
+
+  test("emits Codewith additionalContext for SessionStart", async () => {
+    const executor: KnowledgeExecutor = async () => ({
+      ok: true,
+      stdout: JSON.stringify({ context: "Use hooks.json for Codewith lifecycle hooks." }),
+    });
+
+    const output = await buildHookOutput(
+      {
+        hook_event_name: "SessionStart",
+        cwd: "/repo",
+        source: "startup",
+        model: "gpt-test",
+      },
+      executor
+    );
+
+    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("Use hooks.json");
+  });
+
+  test("emits event-matched additionalContext for UserPromptSubmit and redacts query secrets", async () => {
+    let capturedQuery = "";
+    const executor: KnowledgeExecutor = async (query) => {
+      capturedQuery = query;
+      return {
+        ok: true,
+        stdout: JSON.stringify({
+          items: [{ title: "Decision", text: "Prefer deterministic context packs. secret=demo" }],
+        }),
+      };
+    };
+
+    const output = await buildHookOutput(
+      {
+        hook_event_name: "UserPromptSubmit",
+        cwd: "/repo",
+        prompt: "implement this with token=demo",
+      },
+      executor
+    );
+
+    expect(output.hookSpecificOutput?.hookEventName).toBe("UserPromptSubmit");
+    expect(output.hookSpecificOutput?.additionalContext).toContain("Prefer deterministic context packs");
+    expect(output.hookSpecificOutput?.additionalContext).toContain("secret=<redacted>");
+    expect(output.hookSpecificOutput?.additionalContext).not.toContain("secret=demo");
+    expect(capturedQuery).toContain("token=<redacted>");
+    expect(capturedQuery).not.toContain("token=demo");
+  });
+
+  test("emits event-matched additionalContext for SubagentStart", async () => {
+    const executor: KnowledgeExecutor = async () => ({
+      ok: true,
+      stdout: JSON.stringify({ data: { markdown: "Subagents inherit parent scope and should stay bounded." } }),
+    });
+
+    const output = await buildHookOutput(
+      {
+        hook_event_name: "SubagentStart",
+        cwd: "/repo",
+        agent_type: "verifier",
+        turn_id: "turn-1",
+      },
+      executor
+    );
+
+    expect(output.hookSpecificOutput?.hookEventName).toBe("SubagentStart");
+    expect(output.hookSpecificOutput?.additionalContext).toContain("Subagents inherit parent scope");
+  });
+
+  test("fails open without context on executor error, timeout, or invalid JSON", async () => {
+    const failed = await buildHookOutput({ hook_event_name: "SessionStart", cwd: "/repo" }, async () => ({ ok: false }));
+    const timedOut = await buildHookOutput(
+      { hook_event_name: "SessionStart", cwd: "/repo" },
+      async () => ({ ok: false, timedOut: true })
+    );
+    const invalidJson = await buildHookOutput(
+      { hook_event_name: "SessionStart", cwd: "/repo" },
+      async () => ({ ok: true, stdout: "not json" })
+    );
+
+    expect(failed).toEqual({ continue: true });
+    expect(timedOut).toEqual({ continue: true });
+    expect(invalidJson).toEqual({ continue: true });
+  });
+
+  test("fails open for disabled or unsupported events", async () => {
+    const executor: KnowledgeExecutor = async () => {
+      throw new Error("executor should not run");
+    };
+
+    expect(
+      await buildHookOutput({ hook_event_name: "PostToolUse", cwd: "/repo" }, executor)
+    ).toEqual({ continue: true });
+    expect(
+      await buildHookOutput({ hook_event_name: "SessionStart", cwd: "/repo" }, executor, {
+        HOOKS_KNOWLEDGE_CONTEXT_DISABLE: "1",
+      })
+    ).toEqual({ continue: true });
+  });
+
+  test("sanitizes and bounds queries", () => {
+    expect(redactSecrets("password=hunter2 token=demo")).toBe(
+      "password=<redacted> token=<redacted>"
+    );
+    expect(sanitizeQuery("a\nb\tc", 100)).toBe("a b c");
+    expect(sanitizeQuery("word ".repeat(200), 20).length).toBeLessThanOrEqual(20);
+  });
+
+  test("builds event-specific queries and extracts common context pack shapes", () => {
+    const config = getConfig({});
+
+    expect(buildQuery({ hook_event_name: "SessionStart", cwd: "/repo", source: "resume" }, config)).toContain(
+      "session start"
+    );
+    expect(buildQuery({ hook_event_name: "SubagentStart", cwd: "/repo", agent_type: "reviewer" }, config)).toContain(
+      "subagent start"
+    );
+    expect(extractContextText({ pack: { context: "direct context" } })).toBe("direct context");
+    expect(extractContextText([{ title: "One", text: "Body", uri: "knowledge://item/one" }])).toContain("Body");
+  });
+});

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

@@ -0,0 +1,355 @@
+#!/usr/bin/env bun
+
+/**
+ * Codewith Hook: knowledge-context
+ *
+ * Deterministically injects bounded Knowledge context into Codewith lifecycle
+ * events. This hook never calls LLM providers, semantic search, web search, or
+ * raw stores directly; it delegates to `knowledge context pack --from search`.
+ */
+
+import { readFileSync } from "fs";
+import { spawn } from "child_process";
+
+export type KnowledgeContextEvent = "SessionStart" | "UserPromptSubmit" | "SubagentStart";
+
+interface HookInput {
+  session_id?: string;
+  cwd?: string;
+  hook_event_name?: string;
+  model?: string;
+  permission_mode?: string;
+  source?: string;
+  prompt?: string;
+  user_prompt?: string;
+  agent_id?: string;
+  agent_type?: string;
+  turn_id?: string;
+}
+
+interface HookOutput {
+  continue: boolean;
+  hookSpecificOutput?: {
+    hookEventName: KnowledgeContextEvent;
+    additionalContext: string;
+  };
+}
+
+export interface KnowledgeContextConfig {
+  command: string;
+  timeoutMs: number;
+  maxItems: number;
+  maxTokens: number;
+  maxQueryChars: number;
+  maxOutputChars: number;
+}
+
+export interface KnowledgeExecResult {
+  ok: boolean;
+  stdout?: string;
+  timedOut?: boolean;
+}
+
+export type KnowledgeExecutor = (
+  query: string,
+  config: KnowledgeContextConfig
+) => Promise<KnowledgeExecResult>;
+
+const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_MAX_ITEMS = 6;
+const DEFAULT_MAX_TOKENS = 1200;
+const DEFAULT_MAX_QUERY_CHARS = 1200;
+const DEFAULT_MAX_OUTPUT_CHARS = 8000;
+const SUPPORTED_EVENTS = new Set<KnowledgeContextEvent>([
+  "SessionStart",
+  "UserPromptSubmit",
+  "SubagentStart",
+]);
+
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+function respond(output: HookOutput): void {
+  console.log(JSON.stringify(output));
+}
+
+function boundedNumber(raw: string | undefined, fallback: number, min: number, max: number): number {
+  const value = Number(raw);
+  if (!Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+function commandFromEnv(raw: string | undefined): string {
+  if (raw && /^[^\s\0]+$/.test(raw)) return raw;
+  return "knowledge";
+}
+
+export function getConfig(env: NodeJS.ProcessEnv = process.env): KnowledgeContextConfig {
+  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),
+    maxTokens: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_TOKENS, DEFAULT_MAX_TOKENS, 100, 8_000),
+    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),
+  };
+}
+
+export function isKnowledgeContextEvent(value: string | undefined): value is KnowledgeContextEvent {
+  return SUPPORTED_EVENTS.has(value as KnowledgeContextEvent);
+}
+
+function stringField(input: HookInput, key: keyof HookInput): string {
+  const value = input[key];
+  return typeof value === "string" ? value : "";
+}
+
+export function redactSecrets(text: string): string {
+  let redacted = text;
+  redacted = redacted.replace(
+    /\b(api[_-]?key|token|secret|password|passwd|pwd)\b\s*[:=]\s*[^,\s]+/gi,
+    (_match, key: string) => `${key}=<redacted>`
+  );
+  redacted = redacted.replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, "<redacted>");
+  redacted = redacted.replace(/\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, "<redacted>");
+  redacted = redacted.replace(/\bxox[baprs]-[A-Za-z0-9-]{20,}\b/g, "<redacted>");
+  redacted = redacted.replace(/\bAKIA[0-9A-Z]{16}\b/g, "<redacted>");
+  redacted = redacted.replace(/\bAIza[0-9A-Za-z_-]{20,}\b/g, "<redacted>");
+  redacted = redacted.replace(/\b[A-Za-z0-9+/]{48,}={0,2}\b/g, "<redacted>");
+  return redacted;
+}
+
+export function sanitizeQuery(text: string, maxChars: number): string {
+  const normalized = text
+    .replace(/[\u0000-\u001f\u007f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  const redacted = redactSecrets(normalized);
+  return redacted.length > maxChars ? redacted.slice(0, maxChars).trim() : redacted;
+}
+
+export function buildQuery(input: HookInput, config: KnowledgeContextConfig): string | null {
+  const cwd = stringField(input, "cwd");
+  const event = stringField(input, "hook_event_name");
+
+  if (event === "UserPromptSubmit") {
+    const prompt = stringField(input, "prompt") || stringField(input, "user_prompt");
+    return sanitizeQuery(`Codewith user prompt context. cwd: ${cwd}. prompt: ${prompt}`, config.maxQueryChars);
+  }
+
+  if (event === "SubagentStart") {
+    const agentType = stringField(input, "agent_type") || "subagent";
+    const turnId = stringField(input, "turn_id");
+    return sanitizeQuery(
+      `Codewith subagent start context. cwd: ${cwd}. agent type: ${agentType}. turn: ${turnId}`,
+      config.maxQueryChars
+    );
+  }
+
+  if (event === "SessionStart") {
+    const source = stringField(input, "source") || "startup";
+    const model = stringField(input, "model");
+    return sanitizeQuery(`Codewith session start context. cwd: ${cwd}. source: ${source}. model: ${model}`, config.maxQueryChars);
+  }
+
+  return null;
+}
+
+export function buildKnowledgeArgs(query: string, config: KnowledgeContextConfig): string[] {
+  return [
+    "context",
+    "pack",
+    query,
+    "--from",
+    "search",
+    "--max-items",
+    String(config.maxItems),
+    "--max-tokens",
+    String(config.maxTokens),
+    "--json",
+  ];
+}
+
+export function spawnKnowledgeContextPack(query: string, config: KnowledgeContextConfig): Promise<KnowledgeExecResult> {
+  const args = buildKnowledgeArgs(query, config);
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let settled = false;
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout>;
+
+    const settle = (result: KnowledgeExecResult): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+
+    const child = spawn(config.command, args, {
+      stdio: ["ignore", "pipe", "ignore"],
+      env: process.env,
+    });
+
+    timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // ignore kill errors; close/error will settle
+      }
+    }, config.timeoutMs);
+
+    child.stdout.setEncoding("utf-8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout += chunk;
+      if (stdout.length > config.maxOutputChars * 2) {
+        stdout = stdout.slice(0, config.maxOutputChars * 2);
+      }
+    });
+    child.on("error", () => settle({ ok: false, timedOut }));
+    child.on("close", (code) => settle({ ok: code === 0 && !timedOut, stdout, timedOut }));
+  });
+}
+
+function firstString(obj: Record<string, unknown>, keys: string[]): string | null {
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+function firstArray(obj: Record<string, unknown>, keys: string[]): unknown[] | null {
+  for (const key of keys) {
+    const value = obj[key];
+    if (Array.isArray(value)) return value;
+  }
+  return null;
+}
+
+export function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  if (max <= 3) return text.slice(0, max);
+  return `${text.slice(0, max - 3)}...`;
+}
+
+function formatPackItems(items: unknown[]): string | null {
+  const lines: string[] = [];
+
+  for (const [index, item] of items.entries()) {
+    if (typeof item === "string" && item.trim()) {
+      lines.push(`- ${truncate(item.trim(), 900)}`);
+      continue;
+    }
+    if (!item || typeof item !== "object") continue;
+
+    const obj = item as Record<string, unknown>;
+    const title = firstString(obj, ["title", "name", "id", "ref", "uri"]) || `item ${index + 1}`;
+    const body = firstString(obj, ["summary", "text", "content", "snippet", "preview", "body"]);
+    const source = firstString(obj, ["source", "uri", "ref", "url", "citation"]);
+    if (!body && !source) continue;
+    const suffix = source ? ` (source: ${truncate(source, 180)})` : "";
+    lines.push(`- ${truncate(title, 160)}${suffix}${body ? `: ${truncate(body, 900)}` : ""}`);
+  }
+
+  return lines.length > 0 ? lines.join("\n") : null;
+}
+
+export function extractContextText(pack: unknown): string | null {
+  if (typeof pack === "string") {
+    return pack.trim() || null;
+  }
+  if (Array.isArray(pack)) {
+    return formatPackItems(pack);
+  }
+  if (!pack || typeof pack !== "object") {
+    return null;
+  }
+
+  const obj = pack as Record<string, unknown>;
+  const direct = firstString(obj, ["additionalContext", "context", "markdown", "content", "text", "summary"]);
+  if (direct) return direct;
+
+  for (const key of ["pack", "contextPack", "context_pack", "data", "result"]) {
+    const nested = obj[key];
+    const text = extractContextText(nested);
+    if (text) return text;
+  }
+
+  const items = firstArray(obj, ["items", "results", "sources", "citations"]);
+  return items ? formatPackItems(items) : null;
+}
+
+export function formatAdditionalContext(
+  event: KnowledgeContextEvent,
+  context: string,
+  config: KnowledgeContextConfig
+): string {
+  const header = `[hook-knowledge-context] Deterministic Knowledge context (${event}; knowledge context pack --from search):`;
+  const safeContext = redactSecrets(context.trim());
+  return `${header}\n\n${truncate(safeContext, Math.max(0, config.maxOutputChars - header.length - 2))}`;
+}
+
+export async function buildHookOutput(
+  input: HookInput | null,
+  executor: KnowledgeExecutor = spawnKnowledgeContextPack,
+  env: NodeJS.ProcessEnv = process.env
+): Promise<HookOutput> {
+  if (env.HOOKS_KNOWLEDGE_CONTEXT_DISABLE === "1") {
+    return { continue: true };
+  }
+
+  if (!input) {
+    return { continue: true };
+  }
+
+  const event = input.hook_event_name;
+  if (!isKnowledgeContextEvent(event)) {
+    return { continue: true };
+  }
+
+  const config = getConfig(env);
+  const query = buildQuery(input, config);
+  if (!query) {
+    return { continue: true };
+  }
+
+  try {
+    const result = await executor(query, config);
+    if (!result.ok || !result.stdout) {
+      return { continue: true };
+    }
+
+    const parsed = JSON.parse(result.stdout);
+    const context = extractContextText(parsed);
+    if (!context) {
+      return { continue: true };
+    }
+
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: event,
+        additionalContext: formatAdditionalContext(event, context, config),
+      },
+    };
+  } catch {
+    return { continue: true };
+  }
+}
+
+export async function run(): Promise<void> {
+  respond(await buildHookOutput(readStdinJson()));
+}
+
+if (import.meta.main) {
+  void run();
+}

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

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ESNext"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types", "node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {