v1.9.4: visible knowledge hooks, L0-only SessionStart, identity onboarding

Hooks now visible in the terminal:
- first-prompt-inject emits `knowledge: injected N hits (...)` systemMessage
- session-start always appends `| identity: ...` status suffix

SessionStart auto-wakeup drops L1 (first-prompt-inject covers it better
with query-targeted search). AGENT_KNOWLEDGE_WAKEUP_BUDGET default 800 → 200.
~600-750 fewer tokens pre-loaded per session, no loss of context quality.

Fix: session-start clears the first-prompt-inject marker on every
SessionStart event so /exit+resume re-arms injection (was silently
skipping on resume because the prior run's marker stayed on disk).

Add: identity onboarding. When identity.md is missing and no
.identity-declined opt-out exists, session-start injects an instruction
telling the agent to ask the user 3 short questions and save via the
host's Write tool. No manual file creation.

563/563 tests passing; prettier/typecheck/lint clean.

Author: keshrath

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.9.4 (2026-04-19) — visible knowledge-hook feedback + L0-only SessionStart
+
+### Changed
+
+- **`scripts/hooks/first-prompt-inject.mjs` now emits a user-visible `systemMessage`** alongside the silent `additionalContext`. When the session's first real prompt triggers injection, the host renders a one-line summary like `knowledge: injected 4 hits (decisions/database-choice.md, sessions/odoo-sh/...md, +2 more)` in the transcript, so the user can see which entries the model received without having to diff context.
+- **`scripts/hooks/session-start.js` now auto-loads L0 identity only**, not the full L0+L1 wakeup pack. L1 top-weighted facts are covered by `first-prompt-inject.mjs`, which runs query-targeted search against the KB on the session's first real prompt — a better-matched slice than any query-agnostic pre-load. Effect: ~600 fewer tokens pre-loaded per session on average, no loss of context quality because `first-prompt-inject.mjs` fills the same budget one turn later with relevance-ranked content.
+- **`AGENT_KNOWLEDGE_WAKEUP_BUDGET` default changed from 800 → 200 tokens.** L0 identity is small; the legacy 800-token ceiling existed to accommodate the now-removed L1 pack. Users who want the full legacy L0+L1 injection can still call `knowledge(action="wakeup")` manually — the MCP tool is unchanged.
+- **SessionStart `systemMessage`** now always appends a status suffix so the user can tell the hook ran: `identity: 312 chars` when an `identity.md` is loaded, `identity: placeholder (no identity.md)` when only the default placeholder was emitted, or `autowake off · <source>` when disabled. Previously the suffix was suppressed on the "no identity.md" path, which was visually indistinguishable from the pre-v1.9.4 URL-only line.
+
+### Fixed
+
+- **`session-start.js` clears the `first-prompt-inject.mjs` marker on every SessionStart event.** Resumed sessions reuse the same `session_id`, so the marker from the prior run stayed on disk and the inject hook silently skipped the next user prompt. Now every `/exit`+resume (or `/clear`) re-arms query-targeted injection. When the marker is cleared, the SessionStart `systemMessage` appends `· inject rearmed`.
+
+### Added
+
+- **Identity onboarding.** When no `identity.md` (or `IDENTITY.md`) exists in the memory dir AND no `.identity-declined` opt-out marker is present, `session-start.js` injects a short instruction into `additionalContext` telling the agent to ask the user three questions (name/role, stack, projects) and save the answers via the host's `Write` tool directly into `~/agent-knowledge/identity.md`. No manual file creation; the agent drives the flow. If the user says "skip" / "not now", the agent writes `~/agent-knowledge/.identity-declined` and the nag stops. Delete that file to re-enable. The SessionStart `systemMessage` reports `identity: onboarding pending` or `identity: declined` accordingly.
+
+Neither change alters the model-facing MCP API. Fail-open behaviour unchanged: errors still produce a valid empty JSON response.
+
+### Tests
+
+563/563 passing. New assertions cover: `first-prompt-inject.mjs` `systemMessage` shape, `session-start.js` dashboard-URL line, identity-onboarding instruction when neither `identity.md` nor `.identity-declined` exist, opt-out path via `.identity-declined`, happy-path with an existing `identity.md`, and first-prompt-inject marker clear on resume. Existing hook tests only asserted `hookSpecificOutput`, which stays the same shape; the new `systemMessage` field is additive.
+
 ## 1.9.3 (2026-04-19) — README showcase rewrite
 
 ### Changed

README.md

@@ -2,7 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node >= 20](https://img.shields.io/badge/Node-%3E%3D%2020-brightgreen.svg)](https://nodejs.org)
-[![Tests: 558 passing](https://img.shields.io/badge/Tests-558%20passing-brightgreen.svg)]()
+[![Tests: 563 passing](https://img.shields.io/badge/Tests-563%20passing-brightgreen.svg)]()
 [![MCP Tools: 6](https://img.shields.io/badge/MCP%20Tools-6-blueviolet.svg)]()
 [![LongMemEval R@5: 98.8%](https://img.shields.io/badge/LongMemEval%20R%405-98.8%25-brightgreen.svg)]()
 
@@ -383,7 +383,7 @@ This enables HTTP-based writes from other services without an MCP connection.
 ## Testing
 
 ```bash
-npm test              # 558 tests across 35 files
+npm test              # 563 tests across 35 files
 npm run test:watch    # Watch mode
 npm run lint          # ESLint on src/ and tests/
 npm run typecheck     # tsc --noEmit

agent-desk-plugin.json

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

docs/HOOKS.md

@@ -18,22 +18,61 @@ returns an empty JSON object so the user is never blocked.
 
 ## session-start.js
 
-Two jobs:
+Four jobs:
 
 1. Prints the dashboard URL (`http://localhost:3423` by default, override via
    `AGENT_KNOWLEDGE_PORT`) and injects it into SessionStart `additionalContext`.
-2. Auto-loads a token-budgeted **wakeup** payload (L0 identity + L1 top-weighted
-   entries) into the same `additionalContext`, so the agent starts every session
-   with a small world-model already in the prompt — no manual
-   `knowledge(action="wakeup")` call required.
+2. Auto-loads the **L0 identity** section (who the user is — query-agnostic
+   facts from `~/agent-knowledge/identity.md`) into the same
+   `additionalContext`, so every session starts with that context without a
+   manual `knowledge(action="wakeup")` call.
+3. Clears the `first-prompt-inject.mjs` marker file for this `session_id` on
+   every SessionStart event (startup / resume / clear). Resumed sessions
+   reuse the same `session_id`, so without this the inject hook silently
+   skips on the next prompt because the prior run's marker is still on disk.
+4. **Identity onboarding**: if neither `identity.md` nor `IDENTITY.md` exists
+   in the memory dir AND there is no `.identity-declined` opt-out marker,
+   appends a short instruction to `additionalContext` telling the agent to
+   ask the user three questions (name/role, stack, projects) and save the
+   answers via the host's `Write` tool. The agent drives the conversation;
+   the user never has to manually create the file. If the user says "skip"
+   or "not now", the agent creates `~/agent-knowledge/.identity-declined` and
+   the onboarding prompt stops firing. Delete that file to re-enable.
+
+L1 top-weighted facts are **not** auto-loaded here. The companion
+`first-prompt-inject.mjs` runs a query-targeted KB search on the session's
+first real prompt and injects a better-matched slice than any
+query-agnostic pre-load would. Users who want the full legacy L0+L1 pack can
+still call `knowledge(action="wakeup")` manually, or flip
+`AGENT_KNOWLEDGE_WAKEUP_BUDGET` up to re-enable larger identity sections.
+
+Also emits a user-visible `systemMessage` on every session start with a
+status suffix so the user can always tell the hook ran:
+
+- `agent-knowledge: http://localhost:3423 | identity: 312 chars` — when a
+  user-authored `identity.md` was loaded.
+- `agent-knowledge: http://localhost:3423 | identity: onboarding pending` —
+  when no identity file exists and onboarding is queued (agent will ask
+  the user on the next prompt).
+- `agent-knowledge: http://localhost:3423 | identity: declined (delete ~/agent-knowledge/.identity-declined to redo)` —
+  when the user previously opted out.
+- `agent-knowledge: http://localhost:3423 | identity: placeholder (no identity.md) · inject rearmed` —
+  fallback for edge cases (e.g. stat errors), with `· inject rearmed` when
+  the first-prompt-inject marker was cleared.
+- `agent-knowledge: http://localhost:3423 | autowake off · resume` — when
+  `AGENT_KNOWLEDGE_AUTOWAKE=0` disables auto-injection.
+
+The model-facing context and the user-facing line are separate channels —
+the `systemMessage` is purely a UX signal so the user can see what got
+pre-loaded and whether the next prompt will trigger query-targeted injection.
 
 ### Environment variables
 
-| Variable                        | Default | Description                                         |
-| ------------------------------- | ------- | --------------------------------------------------- |
-| `AGENT_KNOWLEDGE_PORT`          | `3423`  | Dashboard port announced in the context line        |
-| `AGENT_KNOWLEDGE_AUTOWAKE`      | `1`     | Set `0` / `false` to skip the wakeup auto-injection |
-| `AGENT_KNOWLEDGE_WAKEUP_BUDGET` | `800`   | Max tokens (chars/4 estimate) for the L0+L1 blob    |
+| Variable                        | Default | Description                                             |
+| ------------------------------- | ------- | ------------------------------------------------------- |
+| `AGENT_KNOWLEDGE_PORT`          | `3423`  | Dashboard port announced in the context line            |
+| `AGENT_KNOWLEDGE_AUTOWAKE`      | `1`     | Set `0` / `false` to skip the identity auto-injection   |
+| `AGENT_KNOWLEDGE_WAKEUP_BUDGET` | `200`   | Max tokens (chars/4 estimate) for the L0 identity slice |
 
 Requires `npm run build` to have succeeded — if `dist/wakeup.js` is missing,
 only the dashboard-URL line is emitted (fail-open).
@@ -67,6 +106,11 @@ The marker file (`{dataDir}/.first-prompt-seen/<session_id>`) is only written
 AFTER a real search has run — skip-gates like `/clear` do NOT burn the shot,
 so the user's next real question still gets injection.
 
+When injection fires, the hook also emits a user-visible `systemMessage`:
+`knowledge: injected 4 hits (decisions/database-choice.md, sessions/foo.md, +2 more)`.
+This is separate from the model-facing `additionalContext` — the user sees a
+one-line summary in the transcript, the model sees the full rendered hit list.
+
 ### Environment variables
 
 | Variable                               | Default             | Description                                             |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-knowledge",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "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/first-prompt-inject.mjs

@@ -38,7 +38,7 @@ import { homedir } from 'os';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-function emit(additionalContext) {
+function emit(additionalContext, systemMessage) {
   const payload = additionalContext
     ? {
         hookSpecificOutput: {
@@ -47,10 +47,22 @@ function emit(additionalContext) {
         },
       }
     : {};
+  if (systemMessage) payload.systemMessage = systemMessage;
   process.stdout.write(JSON.stringify(payload) + '\n');
   process.exit(0);
 }
 
+function summarizeHits(hits) {
+  if (!hits || hits.length === 0) return null;
+  const paths = hits
+    .map((h) => h.entry?.path)
+    .filter(Boolean)
+    .slice(0, 2);
+  const suffix = hits.length > paths.length ? `, +${hits.length - paths.length} more` : '';
+  const list = paths.length ? ` (${paths.join(', ')}${suffix})` : '';
+  return `knowledge: injected ${hits.length} hit${hits.length === 1 ? '' : 's'}${list}`;
+}
+
 function warn(msg) {
   process.stderr.write(`[knowledge firstprompt] ${msg}\n`);
 }
@@ -221,7 +233,7 @@ async function main() {
   const budgetChars = tokenBudget() * 4;
   const rendered = renderHits(hits, budgetChars);
   if (!rendered) return emit(null);
-  emit(rendered);
+  emit(rendered, summarizeHits(hits));
 }
 
 main().catch((err) => {