v1.9.5: precompact-flush nudge moves from hookSpecificOutput.additionalContext to top-level systemMessage (PreCompact schema rejects the former)

Author: keshrath

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.9.5 (2026-04-20) — PreCompact nudge schema fix
+
+### Fixed
+
+- **`scripts/hooks/precompact-flush.mjs` now emits the memory-flush nudge as top-level `systemMessage` instead of `hookSpecificOutput.additionalContext`.** Claude Code's PreCompact hook schema only accepts `additionalContext` under `hookSpecificOutput` for `UserPromptSubmit` and `PostToolUse` events — PreCompact has no `additionalContext` shape, so the host was rejecting every response with `Hook JSON output validation failed — (root): Invalid input` and dropping the nudge on the floor. The disk-dump side-effect still ran (that's why the companion `precompact-distill.mjs` reported success), but the pre-compaction "save your context" reminder never reached the transcript. Switched to `systemMessage`, which is accepted for all event types and lands in the transcript ahead of the compacted summary, so the reminder still survives compaction.
+
+### Tests
+
+New assertions cover: (a) PreCompact nudge lands in `systemMessage` and nothing is emitted under `hookSpecificOutput`, (b) `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE=0` suppresses the nudge entirely. Guards against regressing to the broken `hookSpecificOutput.additionalContext` shape.
+
 ## 1.9.4 (2026-04-19) — visible knowledge-hook feedback + L0-only SessionStart
 
 ### Changed

agent-desk-plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-knowledge",
   "name": "Knowledge",
   "icon": "psychology",
-  "version": "1.9.4",
+  "version": "1.9.5",
   "description": "Knowledge base — entries, sessions, search, graph relationships",
   "ui": "./dist/ui/app.js",
   "css": "./dist/ui/styles.css",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-knowledge",
-  "version": "1.9.4",
+  "version": "1.9.5",
   "description": "Cross-session memory and recall for AI agents — git-synced knowledge base, knowledge graph, confidence scoring, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing",
   "type": "module",
   "main": "dist/index.js",

scripts/hooks/precompact-flush.mjs

@@ -9,11 +9,14 @@
 //      later distillation/promotion has a durable anchor even if the host
 //      garbage-collects the transcript.
 //
-//   2. Inject a short "save-your-context" nudge into the host's PreCompact
-//      response (`hookSpecificOutput.additionalContext`). The compaction pass
-//      is about to summarize — anything important and unsaved should be
-//      written to the knowledge base NOW via `knowledge(action="write", …)`.
-//      Pre-compaction memory-flush primitive.
+//   2. Emit a short "save-your-context" nudge as a top-level `systemMessage`.
+//      The compaction pass is about to summarize — anything important and
+//      unsaved should be written to the knowledge base NOW via
+//      `knowledge(action="write", …)`. Pre-compaction memory-flush primitive.
+//      (PreCompact rejects `hookSpecificOutput.additionalContext` — only
+//      UserPromptSubmit/PostToolUse accept that shape — so the nudge rides
+//      in `systemMessage`, which lands in the transcript and survives
+//      compaction.)
 //
 // Disable the nudge by exporting AGENT_KNOWLEDGE_PRECOMPACT_NUDGE=0 (the disk
 // dump still runs). Set AGENT_KNOWLEDGE_PRECOMPACT_NUDGE=off to suppress both.
@@ -38,28 +41,14 @@ const nudgeEnabled = NUDGE_MODE !== '0' && NUDGE_MODE !== 'false' && NUDGE_MODE
 const diskDumpEnabled = NUDGE_MODE !== 'off';
 
 const NUDGE_TEXT = [
-  '## PreCompact — memory-flush nudge',
-  '',
-  'The host is about to compact the conversation. Anything you learned this',
-  'turn that the next session will need MUST be written to the knowledge base',
-  'before the summary replaces the transcript. Use:',
-  '',
-  '  `knowledge(action="write", category="decisions"|"notes"|"workflows", filename=..., content=...)`',
-  '',
-  'Candidates worth a write: architectural decisions, non-obvious gotchas,',
-  'hard-won commands, people/ownership facts, project state. Skip transient',
-  'things (file diffs, TODO lists, in-flight plans — plan/task systems own those).',
-].join('\n');
-
-function emitResult(additionalContext) {
-  const payload = additionalContext
-    ? {
-        hookSpecificOutput: {
-          hookEventName: 'PreCompact',
-          additionalContext,
-        },
-      }
-    : {};
+  'knowledge: PreCompact — flush durable facts to the KB before summary replaces the transcript.',
+  'Write architectural decisions, non-obvious gotchas, hard-won commands, people/ownership facts, project state via',
+  '`knowledge(action="write", category="decisions"|"notes"|"workflows", filename=..., content=...)`.',
+  'Skip transient things (file diffs, TODO lists, in-flight plans — plan/task systems own those).',
+].join(' ');
+
+function emitResult(nudge) {
+  const payload = nudge ? { systemMessage: nudge } : {};
   process.stdout.write(JSON.stringify(payload) + '\n');
   process.exit(0);
 }

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/keshrath/agent-knowledge",
     "source": "github"
   },
-  "version": "1.9.4",
+  "version": "1.9.5",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-knowledge",
-      "version": "1.9.4",
+      "version": "1.9.5",
       "transport": {
         "type": "stdio"
       }

tests/hooks/hooks.test.ts

@@ -192,6 +192,34 @@ describe('precompact-flush.mjs', () => {
     const { code } = await runHook('precompact-flush.mjs', 'junk');
     expect(code).toBe(0);
   });
+
+  it('emits nudge as top-level systemMessage, not hookSpecificOutput.additionalContext', async () => {
+    // Claude Code's PreCompact schema only accepts systemMessage at the top
+    // level; hookSpecificOutput.additionalContext is UserPromptSubmit /
+    // PostToolUse only. Emitting the latter produces a validation error and
+    // the nudge is dropped. Guard against regression.
+    const { json } = await runHook('precompact-flush.mjs', {
+      session_id: 'sess-precompact-nudge',
+      hook_event_name: 'PreCompact',
+    });
+    const obj = json as {
+      systemMessage?: string;
+      hookSpecificOutput?: { additionalContext?: string };
+    };
+    expect(obj.systemMessage).toBeTruthy();
+    expect(obj.systemMessage).toContain('knowledge:');
+    expect(obj.hookSpecificOutput).toBeUndefined();
+  });
+
+  it('suppresses nudge when AGENT_KNOWLEDGE_PRECOMPACT_NUDGE=0', async () => {
+    const { json } = await runHook(
+      'precompact-flush.mjs',
+      { session_id: 'sess-nudge-off', hook_event_name: 'PreCompact' },
+      { env: { AGENT_KNOWLEDGE_PRECOMPACT_NUDGE: '0' } },
+    );
+    const obj = json as { systemMessage?: string };
+    expect(obj.systemMessage).toBeUndefined();
+  });
 });
 
 // ---------------------------------------------------------------------------