@vkmikc/create-vkm-kit 4.2.0

package/src/hooks/guard-effort-gate.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Claude Code `PreToolUse` hook — deterministically DENIES a session's 2nd+ substantive
+ * Write/Edit/MultiEdit/NotebookEdit call until the model has proposed an effort level
+ * (`/effort low|medium|high|xhigh|max`) AND gotten a real reply from the user.
+ *
+ * Why a hook and not just a CLAUDE.md sentence: a model that announces "pausing for your
+ * confirmation" and then immediately keeps calling tools in the same turn is a common
+ * failure mode — the announcement is prose, and prose doesn't stop a tool call. Same root
+ * cause ADR-0029/ADR-0030 already named: relying on the model to *honor* a rule against an
+ * always-available tool is exactly what fails in practice. This hook makes the pause real
+ * by denying the call until a genuine user turn happened after the proposal. See ADR-0031.
+ *
+ * Anti-nagging, mirroring the ADR-0030 `Stop` hook's threshold: the FIRST substantive call
+ * of a session is always free (a one-line fix shouldn't need a ritual). Gating starts at
+ * the 2nd. Once the gate is satisfied once, it stays open for the rest of the session — this
+ * is a one-time checkpoint per session, not a per-task interrogation.
+ *
+ * Main agent only — never a sub-agent (ADR-0031 addendum): a Task-tool sub-agent (a fanned-out
+ * `vkm-implementer`, `Explore`, etc.) cannot ever satisfy this gate — a coordinator's relayed
+ * `SendMessage` confirmation and an `AskUserQuestion` answer both land in the transcript as
+ * content `isRealUserTurn()` deliberately excludes (see its own doc comment), so a sub-agent
+ * would be denied forever, wedging any multi-agent workflow. Claude Code populates `agent_id`
+ * on the hook's stdin payload only when the hook fires inside a sub-agent — its presence is
+ * the signal to defer immediately, no scan needed. The gate still applies in full to the main
+ * agent's own direct edits; this makes it neutral toward delegation, neither encouraging nor
+ * blocking it, rather than an obstacle a workflow has to route around.
+ *
+ * Installed by create-obsidian-memory — the vkm-kit installer — into `~/.claude/hooks/` next
+ * to the other managed hooks, registered in `~/.claude/settings.json` as:
+ *   node "<this file>" [lang]
+ * with matcher `"Write|Edit|MultiEdit|NotebookEdit"`. Reads `transcript_path` from the
+ * hook's stdin payload (like the `Stop` hook), not from argv — there's no file path to
+ * check here, just conversation history.
+ *
+ * Contract (Claude Code `PreToolUse` hooks):
+ *  - Read the hook's JSON payload from stdin (`tool_name`, `transcript_path`, `agent_id`, …
+ *    — `agent_id` is populated only inside a sub-agent call, see the main-agent-only note above).
+ *  - To deny the call, print ONE JSON object to stdout:
+ *      { "hookSpecificOutput": { "hookEventName": "PreToolUse",
+ *          "permissionDecision": "deny", "permissionDecisionReason": "<text>" } }
+ *  - To defer to the normal permission flow, print nothing and exit 0.
+ *  - Never throw: a malformed payload or unreadable transcript must fall through to the
+ *    normal permission flow (fail OPEN — this hook must never hang or break a session).
+ *
+ * Performance: re-parsing the WHOLE transcript on every gated call gets slower as a session
+ * grows (measured ~75ms on a real 25.8MB transcript) — see `_transcript-cache.mjs` (installed
+ * alongside this file) for the sidecar-cache fix that makes each call only read the NEW
+ * suffix appended since the last one. Purely a performance change: `scanTranscript` below
+ * returns the identical shape/values a full rescan always did.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getIncrementalState } from "./_transcript-cache.mjs";
+
+const SUBSTANTIVE_TOOLS = /^(Write|Edit|MultiEdit|NotebookEdit)$/;
+/** Below this many PRIOR substantive calls, the gate stays out of the way entirely. */
+const MIN_SUBSTANTIVE_CALLS = 2;
+/** Matches ONLY the literal marker the model is told to print — see reason() below. */
+const MARKER_RE = /\[!\]\s*(recomendaci[oó]n de esfuerzo|effort recommendation)/i;
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * True if a transcript entry is a REAL user turn — as opposed to a tool result, which
+ * Claude Code also encodes as a `type:"user"` message (`content: [{type:"tool_result",…}]`).
+ * A turn only counts as a genuine reply if it carries the user's own text.
+ */
+function isRealUserTurn(entry) {
+  if (!entry || entry.type !== "user") return false;
+  const content = entry?.message?.content;
+  if (typeof content === "string") return content.trim().length > 0;
+  if (!Array.isArray(content)) return false;
+  return content.some((block) => block && block.type !== "tool_result");
+}
+
+function initialScanState() {
+  return { substantiveBefore: 0, pending: false, satisfied: false };
+}
+
+/**
+ * Fold ONE raw JSONL line into `state` (mutate-and-return). Same per-line logic the old
+ * always-full-rescan version used, factored out so it can run over just the transcript's
+ * NEW suffix (see `_transcript-cache.mjs`) with an identical result to scanning from byte 0:
+ * each line's effect depends only on itself and the accumulator so far (`pending` gates
+ * whether a later user turn sets `satisfied`), never on lines further ahead.
+ */
+function foldTranscriptLine(state, line) {
+  const trimmed = line.trim();
+  if (!trimmed) return state;
+  let entry;
+  try {
+    entry = JSON.parse(trimmed);
+  } catch {
+    return state;
+  }
+  if (entry?.type === "assistant") {
+    const content = entry?.message?.content;
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (!block) continue;
+        if (block.type === "text" && typeof block.text === "string" && MARKER_RE.test(block.text)) {
+          state.pending = true;
+        } else if (block.type === "tool_use" && SUBSTANTIVE_TOOLS.test(block.name || "")) {
+          state.substantiveBefore++;
+        }
+      }
+    }
+  } else if (state.pending && isRealUserTurn(entry)) {
+    state.satisfied = true;
+    state.pending = false;
+  }
+  return state;
+}
+
+/**
+ * Scan the JSONL transcript in order (walks each assistant turn's content blocks in array
+ * order — text marker before any later tool_use in the SAME prior turn still counts, since
+ * the call currently being gated is by definition not yet in this file; `satisfied` is
+ * monotonic, staying set for the rest of the scan once a real user turn follows a proposal).
+ * Computed incrementally via the shared sidecar cache (`_transcript-cache.mjs`) — resumes
+ * from the last-consumed byte offset when safe, full rescan otherwise. Never throws; returns
+ * the SAME shape a full rescan from byte 0 always did.
+ */
+export function scanTranscript(transcriptPath) {
+  return getIncrementalState(transcriptPath, "effort-gate", initialScanState, foldTranscriptLine);
+}
+
+function reason(lang, alreadyProposed) {
+  if (lang === "en") {
+    return alreadyProposed
+      ? "Paused: you already proposed an effort level but there's no reply from the user " +
+          "yet in this conversation. Do not call any more tools this turn — wait for the " +
+          "user's next message before retrying."
+      : "Paused: this session is about to make its 2nd+ substantive edit without an effort " +
+          "estimate. Before calling any more tools, reply with ONLY this block (no tool " +
+          "calls in this turn), then stop and wait for the user's next message:\n\n" +
+          "[!] EFFORT RECOMMENDATION\n" +
+          "- Task: <short description>\n" +
+          "- Suggested level: /effort <low|medium|high|xhigh|max>\n" +
+          "- Reason: <why>\n\n" +
+          "Retry only after the user replies (confirming or naming a different level). See ADR-0031.";
+  }
+  return alreadyProposed
+    ? "Pausa: ya propusiste un nivel de esfuerzo pero todavía no hay respuesta del usuario " +
+        "en esta conversación. No llames más herramientas en este turno — esperá el próximo " +
+        "mensaje del usuario antes de reintentar."
+    : "Pausa: esta sesión va a hacer su 2.º+ edit sustantivo sin haber propuesto un nivel " +
+        "de esfuerzo. Antes de llamar más herramientas, respondé SOLO con este bloque (nada " +
+        "de tool calls en este turno), después parate y esperá el próximo mensaje del usuario:\n\n" +
+        "[!] RECOMENDACIÓN DE ESFUERZO\n" +
+        "- Tarea: <descripción breve>\n" +
+        "- Nivel sugerido: /effort <low|medium|high|xhigh|max>\n" +
+        "- Razón: <por qué>\n\n" +
+        "Reintentá solo después de que el usuario responda (confirmando u otro nivel). Ver ADR-0031.";
+}
+
+function main() {
+  const lang = (process.argv[2] || "es").toLowerCase() === "en" ? "en" : "es";
+
+  let input;
+  try {
+    input = JSON.parse(readStdin() || "{}");
+  } catch {
+    return; // unparseable payload — defer to the normal permission flow
+  }
+
+  const toolName = typeof input?.tool_name === "string" ? input.tool_name : "";
+  if (!SUBSTANTIVE_TOOLS.test(toolName)) return;
+
+  // Sub-agent call — see the file header for why this can never be satisfied from in here.
+  if (typeof input?.agent_id === "string" && input.agent_id) return;
+
+  const transcriptPath = typeof input?.transcript_path === "string" ? input.transcript_path : "";
+  if (!transcriptPath) return; // no transcript to check against — fail open
+
+  const { substantiveBefore, pending, satisfied } = scanTranscript(transcriptPath);
+  if (substantiveBefore === 0) return; // first substantive edit of the session is free
+  if (satisfied) return; // gated once already this session — stay out of the way
+
+  const payload = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason(lang, pending)
+    }
+  };
+  process.stdout.write(JSON.stringify(payload));
+}
+
+// Only auto-run when executed directly (`node guard-effort-gate.mjs ...`), not when imported
+// — `scanTranscript` is exported above so tests can unit-test the caching behavior directly
+// (call counts, resumed-vs-full-scan byte counts) without a stdin read as an import side effect.
+const isMainModule =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (isMainModule) {
+  try {
+    main();
+  } catch {
+    // Never let a bug in this hook block a legitimate tool call.
+  }
+}

package/src/hooks/guard-native-memory-write.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Claude Code `PreToolUse` hook — deterministically DENIES Write/Edit/MultiEdit/
+ * NotebookEdit calls that target Claude's native per-project auto-memory directory
+ * (`~/.claude/projects/<encoded-cwd>/memory/`), redirecting the model to the vault tools.
+ *
+ * Why a hook and not just another CLAUDE.md sentence: ADR-0029 already disables the
+ * native auto-memory at the config level (`autoMemoryEnabled:false`) because relying on
+ * the model to *honor a rule* against an always-available `Write` tool is exactly what
+ * failed in practice on weaker/older models. This hook closes the remaining gap — a model
+ * that still tries to `Write` into that directory out of habit (or because it never
+ * loaded/read the rules) is blocked by the harness itself, independent of which model is
+ * driving. See ADR-0030.
+ *
+ * Installed by create-obsidian-memory — the vkm-kit installer — into `~/.claude/hooks/` next
+ * to the SessionStart hook, registered in `~/.claude/settings.json` as:
+ *   node "<this file>" "<claudeDir>" [lang]
+ * with matcher `"Write|Edit|MultiEdit|NotebookEdit"` so the harness only invokes it for
+ * file-mutating tools. The script re-checks `tool_name` itself too, defensively.
+ *
+ * Contract (Claude Code `PreToolUse` hooks):
+ *  - Read the hook's JSON payload from stdin (`tool_name`, `tool_input`, …).
+ *  - To deny the call, print ONE JSON object to stdout:
+ *      { "hookSpecificOutput": { "hookEventName": "PreToolUse",
+ *          "permissionDecision": "deny", "permissionDecisionReason": "<text>" } }
+ *  - To defer to the normal permission flow, print nothing and exit 0.
+ *  - Never throw: a malformed payload or unreadable input must fall through to the
+ *    normal permission flow, not break the user's tool call.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MUTATING_TOOLS = /^(Write|Edit|MultiEdit|NotebookEdit)$/;
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * True if `filePath` lives under `<claudeDir>/projects/<anything>/memory/...`. Case-folds
+ * the comparison ONLY on platforms whose default filesystem is case-insensitive (`win32`) —
+ * everywhere else (Linux's default; `darwin`'s default APFS is usually case-insensitive too,
+ * but treating it as case-sensitive is the SAFE direction, i.e. never worse than before) an
+ * exact-case comparison is used, so a differently-cased-but-distinct directory that merely
+ * collides case-insensitively with the native-memory path is never over-matched (which would
+ * incorrectly deny a legitimate write on a case-sensitive filesystem).
+ * @param {string} filePath
+ * @param {string} claudeDir
+ * @param {string} [platform] - defaults to `process.platform`; overridable so tests can
+ *   simulate a non-Windows platform without actually running on one.
+ */
+export function isNativeMemoryPath(filePath, claudeDir, platform = process.platform) {
+  if (!filePath || !claudeDir) return false;
+  try {
+    const caseInsensitive = platform === "win32";
+    const fold = (s) => (caseInsensitive ? s.toLowerCase() : s);
+    const norm = fold(path.resolve(filePath).replace(/\\/g, "/"));
+    const dirNorm = fold(path.resolve(claudeDir).replace(/\\/g, "/"));
+    if (!norm.startsWith(`${dirNorm}/`)) return false;
+    const rel = norm.slice(dirNorm.length + 1).split("/");
+    return rel[0] === "projects" && rel.includes("memory");
+  } catch {
+    return false;
+  }
+}
+
+function reason(lang) {
+  if (lang === "en") {
+    return (
+      "Blocked: this path is Claude Code's NATIVE auto-memory, disabled by this kit " +
+      "(autoMemoryEnabled:false, ADR-0029). Write the close ritual to the Obsidian vault " +
+      "instead — mcp__obsidian-memory-hybrid__vault_write_file / vault_edit_file " +
+      "(SESSION_LOG.md + PROJECTS/<project>.md), or basic-memory's write_note/edit_note. " +
+      "See ADR-0030."
+    );
+  }
+  return (
+    "Bloqueado: esa ruta es la auto-memoria NATIVA de Claude Code, desactivada por este kit " +
+    "(autoMemoryEnabled:false, ADR-0029). Escribe el cierre en el vault Obsidian en su lugar " +
+    "— mcp__obsidian-memory-hybrid__vault_write_file / vault_edit_file " +
+    "(SESSION_LOG.md + PROJECTS/<proyecto>.md), o write_note/edit_note de basic-memory. " +
+    "Ver ADR-0030."
+  );
+}
+
+function main() {
+  const claudeDir = process.argv[2] || "";
+  const lang = (process.argv[3] || "es").toLowerCase() === "en" ? "en" : "es";
+
+  let input;
+  try {
+    input = JSON.parse(readStdin() || "{}");
+  } catch {
+    return; // unparseable payload — defer to the normal permission flow
+  }
+
+  const toolName = typeof input?.tool_name === "string" ? input.tool_name : "";
+  if (!MUTATING_TOOLS.test(toolName)) return;
+
+  const filePath = input?.tool_input?.file_path || input?.tool_input?.notebook_path || "";
+  if (!isNativeMemoryPath(filePath, claudeDir)) return;
+
+  const payload = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason(lang)
+    }
+  };
+  process.stdout.write(JSON.stringify(payload));
+}
+
+// Only auto-run when executed directly (`node guard-native-memory-write.mjs ...`), not when
+// imported — `isNativeMemoryPath` is exported above so tests can unit-test it directly
+// (e.g. with a platform override) without triggering a stdin read as a side effect of import.
+const isMainModule =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (isMainModule) {
+  try {
+    main();
+  } catch {
+    // Never let a bug in this hook block a legitimate tool call.
+  }
+}

package/src/hooks/session-start-vault-context.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Claude Code `SessionStart` hook — injects the vault map + the "vault is the only
+ * source of truth" reminders as `additionalContext`, so every session starts knowing
+ * the native auto-memory is OFF and recall/close go through the Obsidian vault.
+ *
+ * Installed by create-obsidian-memory — the vkm-kit installer — into `~/.claude/hooks/` and
+ * registered in `~/.claude/settings.json` as: `node "<this file>" "<vault>" [lang]`.
+ *
+ * Cross-platform on purpose (Node, not PowerShell/bash) so ONE script — and ONE copy
+ * of the reminder text — serves Windows, macOS and Linux.
+ *
+ * Contract (Claude Code hooks):
+ *  - Print a single JSON object to stdout.
+ *  - To inject text into the session context, emit:
+ *      { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "<text>" } }
+ *  - A non-zero exit is logged but does NOT abort the session. We never throw: a broken
+ *    vault path must not block the user, so on any error we still emit the reminders.
+ */
+import { pathToFileURL } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
+
+/** Vault path: 1st CLI arg wins, else the MCP env vars the kit sets. */
+function resolveVault() {
+  const fromArg = process.argv[2];
+  if (fromArg && fromArg.trim()) return fromArg.trim();
+  return (
+    process.env.VKM_VAULT ||
+    process.env.BASIC_MEMORY_HOME ||
+    process.env.OBSIDIAN_MEMORY_VAULT ||
+    ""
+  );
+}
+
+function stripBom(text) {
+  return typeof text === "string" && text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/** Backstop cap on the curated index dump injected into EVERY session. A
+ * hand-maintained index that gains one entry per project only grows over time — left
+ * uncapped, this hook's fixed per-session token tax grows right along with the vault
+ * (~10KB / ~2500 tokens on a modest 69-note vault). Compression (below) runs first;
+ * this cap only bites on unusually large or unusually prosy indices. */
+export const MAX_INDEX_CHARS = 3000;
+
+/** Per-entry cap for compressIndex: enough for "name — one-line purpose", not for
+ * the whole multi-sentence history an index entry tends to accrete. */
+export const MAX_ENTRY_CHARS = 100;
+
+/**
+ * Compress the curated index instead of blindly truncating it (ADR-0035). The old
+ * hard cut kept the first N chars — full prose for early entries, and any project
+ * past the cap silently invisible to the session. For a *pointer map* that's
+ * backwards: every entry's NAME is worth more than any entry's third sentence.
+ * So: keep headings and structure, cap each list item at MAX_ENTRY_CHARS (cut at a
+ * word boundary, '…'), drop YAML frontmatter and collapse blank runs. Result: all
+ * pointers visible, prose available on demand via vault_read_file/search.
+ */
+export function compressIndex(index) {
+  const lines = index.split(/\r?\n/);
+  let i = 0;
+  // Drop a leading YAML frontmatter block (--- … ---): metadata, not pointers.
+  if (lines[0]?.trim() === "---") {
+    const end = lines.findIndex((l, j) => j > 0 && l.trim() === "---");
+    if (end > 0) i = end + 1;
+  }
+  const out = [];
+  let blank = false;
+  for (; i < lines.length; i++) {
+    const line = lines[i].trimEnd();
+    if (!line.trim()) {
+      if (!blank && out.length) out.push("");
+      blank = true;
+      continue;
+    }
+    const isHeading = line.startsWith("#");
+    const isBullet = line.trimStart().startsWith("- ");
+    let kept = line;
+    if (!isHeading && line.trim().length > MAX_ENTRY_CHARS) {
+      if (!isBullet) continue; // over-cap prose (incl. bullet overflow wraps): a
+      // mid-sentence fragment reads worse than absence — the full text is one
+      // vault_read_file away. Bullets ARE the pointers, so those get capped instead:
+      const slice = line.slice(0, MAX_ENTRY_CHARS);
+      const cutAt = slice.lastIndexOf(" ");
+      kept = slice.slice(0, cutAt > MAX_ENTRY_CHARS / 2 ? cutAt : MAX_ENTRY_CHARS) + "…";
+    }
+    blank = false;
+    out.push(kept);
+  }
+  // A dropped prose block can leave a dangling blank at the tail.
+  while (out.length && !out[out.length - 1]) out.pop();
+  return out.join("\n").trim();
+}
+
+export function truncateIndex(index, lang) {
+  const compressed = compressIndex(index);
+  if (compressed.length <= MAX_INDEX_CHARS) return compressed;
+  const notice =
+    lang === "en"
+      ? `\n\n[...truncated: index is ${compressed.length} chars compressed, showing the first ${MAX_INDEX_CHARS}. Use vault_read_file("_meta/index.md") for the rest.]`
+      : `\n\n[...truncado: el indice comprimido tiene ${compressed.length} caracteres, mostrando los primeros ${MAX_INDEX_CHARS}. Usa vault_read_file("_meta/index.md") para el resto.]`;
+  return compressed.slice(0, MAX_INDEX_CHARS) + notice;
+}
+
+/** The reinforced precedence reminders. Kept in sync with the CLAUDE.md rules block. */
+export function reminders(lang) {
+  if (lang === "en") {
+    return [
+      "---",
+      "MEMORY — precedence (HARD RULE): the Obsidian vault is the ONLY source of truth. Claude Code's NATIVE auto-memory (~/.claude/projects/*/memory/, the system prompt's \"# Memory\" section) is DISABLED by the installer (autoMemoryEnabled:false) / is a READ-ONLY MIRROR: do NOT write the close ritual there, redirect to the vault.",
+      "- FIRST STEP if the vault_* tools appear as deferred (common with many MCP servers connected): load them with ToolSearch (select:vault_hybrid_search,vault_read_file,vault_edit_file,vault_write_file) BEFORE touching memory. The native Write tool is zero-friction and tempting; resist it.",
+      '- For ANY non-trivial task (or when a project/person/decision/tool is named): BEFORE answering call mcp__obsidian-memory-hybrid__vault_hybrid_search("<topic>") and answer from the returned section (passage-first, cheap). Use read_text_file/vault_read_file only if you need the whole file.',
+      "- If it's the first task of the session, start with START_HERE.md and MEMORY.md.",
+      '- CLOSE (reusable task done): write to the vault with vault_edit_file/vault_write_file -> SESSION_LOG.md (1 line at the end) + PROJECTS/<project>.md (incremental, above "## Related") + STACKS/PRACTICES if it applies. Anchor each vault_edit_file on ONE single line (notes are CRLF). Don\'t commit: the obsidian-memoryd daemon syncs.'
+    ].join("\n");
+  }
+  return [
+    "---",
+    'MEMORIA — precedencia (REGLA DURA): el vault Obsidian es la UNICA fuente de verdad. La auto-memoria nativa de Claude Code (~/.claude/projects/*/memory/, la seccion "# Memory" del system prompt) esta DESACTIVADA por el instalador (autoMemoryEnabled:false) / es ESPEJO READ-ONLY: NO escribas el cierre ahi, redirigi al vault.',
+    "- PRIMER PASO si las tools vault_* aparecen como deferred (frecuente con muchos MCP conectados): cargalas con ToolSearch (select:vault_hybrid_search,vault_read_file,vault_edit_file,vault_write_file) ANTES de tocar memoria. El Write nativo es cero-friccion y tienta; resistilo.",
+    '- Para CUALQUIER tarea no trivial (o si mencionas un proyecto/persona/decision/herramienta): ANTES de responder llama mcp__obsidian-memory-hybrid__vault_hybrid_search("<tema>") y responde con la seccion que devuelve (passage-first, barato). Usa read_text_file/vault_read_file solo si necesitas el archivo entero.',
+    "- Si es la primera tarea de la sesion, empieza por START_HERE.md y MEMORY.md.",
+    '- CIERRE (tarea reusable terminada): escribi al vault con vault_edit_file/vault_write_file -> SESSION_LOG.md (1 linea al final) + PROJECTS/<proyecto>.md (incremental, arriba de "## Relacionado") + STACKS/PRACTICES si aplica. Ancla cada vault_edit_file en UNA sola linea (notas en CRLF). No commitees: el daemon obsidian-memoryd sincroniza.'
+  ].join("\n");
+}
+
+export function buildContext(vault, lang) {
+  const header =
+    lang === "en"
+      ? "## Obsidian vault available (MCP memory)"
+      : "## Vault Obsidian disponible (memoria MCP)";
+  const parts = [header, ""];
+  if (vault) parts.push(`Path: ${vault}`, "");
+
+  // Top-level folder listing — so the agent knows the structure even if the index is stale.
+  if (vault) {
+    try {
+      const entries = fs
+        .readdirSync(vault, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !/^(\.git|\.obsidian)$/.test(e.name))
+        .map((e) => `- ${e.name}/`);
+      if (entries.length) {
+        parts.push(
+          lang === "en" ? "Top-level folders:" : "Carpetas top-level:",
+          entries.join("\n"),
+          ""
+        );
+      }
+    } catch {
+      /* vault unreadable — still emit the reminders below */
+    }
+
+    // Curated index (_meta/index.md), if present — capped (see truncateIndex).
+    try {
+      const indexPath = path.join(vault, "_meta", "index.md");
+      if (fs.existsSync(indexPath)) {
+        const index = truncateIndex(stripBom(fs.readFileSync(indexPath, "utf8")), lang);
+        // A pathological index (all over-cap prose, no pointers) compresses to "" —
+        // emit nothing rather than an empty labelled section.
+        if (index) {
+          parts.push(
+            lang === "en" ? "Curated index (_meta/index.md):" : "Indice curado (_meta/index.md):",
+            "",
+            index,
+            ""
+          );
+        }
+      }
+    } catch {
+      /* index unreadable — still emit the reminders below */
+    }
+  }
+
+  parts.push(reminders(lang));
+  return parts.join("\n");
+}
+
+export function main() {
+  const vault = resolveVault();
+  const lang = (process.argv[3] || "es").toLowerCase() === "en" ? "en" : "es";
+  let additionalContext;
+  try {
+    additionalContext = buildContext(vault, lang);
+  } catch {
+    additionalContext = reminders(lang); // last-resort: never block the session
+  }
+  const payload = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext
+    }
+  };
+  process.stdout.write(JSON.stringify(payload));
+}
+
+// Guard so importing this module (e.g. from a test) does not also run main() as a
+// side effect — mirrors the pattern in hybrid-mcp.mjs / the other managed hooks.
+const isEntryPoint = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntryPoint) main();