@ghilteras/opencode-agent-memory 0.5.0 → 0.5.2

package/README.md

@@ -19,7 +19,7 @@ Think of it as a searchable sidecar to `AGENTS.md`. OpenCode supports [rules](ht
 - **Append-only journal** - Entries survive across sessions and context compaction
 - **Local semantic search** - Find entries by meaning, not just keywords
 - **Metadata on every entry** - Project, model, provider, agent, session, timestamp, tags
-- **Bounded system prompt note** - A short journal-instructions note is injected while the journal is enabled
+- **Guidance in tool descriptions** - Journal usage guidance lives in the descriptions of the journal tools, so an agent sees it only when it is allowed to call them
 - **No data leaves the machine** - Embeddings run locally
 
 ## Requirements
@@ -32,7 +32,7 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugin": ["@ghilteras/opencode-agent-memory@0.5.0"]
+  "plugin": ["@ghilteras/opencode-agent-memory@0.5.2"]
 }
 ```
 
@@ -50,7 +50,10 @@ The journal is **opt-in**. Enable it in `~/.config/opencode/agent-memory.json`:
 }
 ```
 
-With the journal disabled the plugin registers **no tools** and injects nothing.
+The plugin does **not** regenerate `agent-memory.json` if it is deleted; its loss otherwise silently disables the journal, which is why the fault warning exists.
+
+- Intentional disable (`"enabled": false`) is silent by design and registers **no tools**.
+- A missing, unreadable, malformed, or schema-invalid config logs `[agent-memory] journal config <resolved path>: <reason>; journal tools will NOT be registered` and registers **no tools**.
 
 ### Tools
 
@@ -101,7 +104,7 @@ Tags are free-form strings - the agent can use any tag, not just the suggested o
 }
 ```
 
-Suggested tags appear in the system prompt as guidance.
+Suggested tag **names** (not their descriptions) appear in the `journal_write` tool description as guidance.
 
 ### cacheDir
 
@@ -126,8 +129,9 @@ Existing `~/.config/opencode/memory/` and `.opencode/memory/` directories are **
 
 - **Requires OpenCode v1.0.115+.**
 - **Restart after config changes.** Plugin config changes require a full OpenCode restart to take effect; editing the config file alone is not sufficient.
-- **Journal is opt-in.** You must explicitly enable it in `~/.config/opencode/agent-memory.json`; with it disabled the plugin registers no tools and injects nothing.
+- **Journal is opt-in.** You must explicitly enable it in `~/.config/opencode/agent-memory.json`; intentional disablement is silent, while a missing, unreadable, malformed, or schema-invalid config logs a warning and registers no tools.
 - **Local embeddings, no data leaves the machine.** Semantic search uses a locally cached transformers.js model; no external API calls are made for search or embedding.
+- **Known limitation (since 0.5.1): guidance-in-descriptions depends on an unverified premise.** 0.5.1 moved journal guidance from the injected system-prompt note into the three journal tool descriptions, so only agents allowed to call those tools should see it. That relies on opencode omitting a permission-denied tool from the definitions sent to the model. This is **unverified**: a `tool.definition` probe on the isolated instance fires before permission filtering, so it cannot confirm what the model actually receives. If the premise does not hold, an agent denied `journal_*` may still read the description text; `deny` still blocks execution, so there is no capability escalation and no data disclosure — the blast radius is the three tools' description strings.
 
 ## Inspiration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",

package/src/journal.test.ts

@@ -41,27 +41,60 @@ async function mkTmpDir(): Promise<string> {
 }
 
 describe("loadConfig", () => {
-  test("returns empty config when file does not exist", async () => {
+  test("classifies a missing file and returns an empty config", async () => {
     const dir = await mkTmpDir();
-    const config = await loadConfig(dir);
-    expect(config).toEqual({});
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("missing");
+    expect(loaded.config).toEqual({});
   });
 
-  test("returns parsed config when file is valid", async () => {
+  test("classifies an unreadable file and returns an empty config", async () => {
+    const dir = await mkTmpDir();
+    await fs.mkdir(path.join(dir, "agent-memory.json"));
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("unreadable");
+    expect(loaded.config).toEqual({});
+  });
+
+  test("classifies malformed JSON and returns an empty config", async () => {
+    const dir = await mkTmpDir();
+    await fs.writeFile(path.join(dir, "agent-memory.json"), "not json{{{");
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("malformed");
+    expect(loaded.config).toEqual({});
+  });
+
+  test("classifies schema-invalid JSON and returns an empty config", async () => {
     const dir = await mkTmpDir();
     await fs.writeFile(
       path.join(dir, "agent-memory.json"),
-      JSON.stringify({ journal: { enabled: true } }),
+      JSON.stringify({ journal: { enabled: "yes" } }),
     );
-    const config = await loadConfig(dir);
-    expect(config.journal?.enabled).toBe(true);
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("invalid");
+    expect(loaded.config).toEqual({});
   });
 
-  test("returns empty config when file has invalid JSON", async () => {
+  test("classifies valid disabled config without changing it", async () => {
     const dir = await mkTmpDir();
-    await fs.writeFile(path.join(dir, "agent-memory.json"), "not json{{{");
-    const config = await loadConfig(dir);
-    expect(config).toEqual({});
+    await fs.writeFile(
+      path.join(dir, "agent-memory.json"),
+      JSON.stringify({ journal: { enabled: false } }),
+    );
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("ok");
+    expect(loaded.config).toEqual({ journal: { enabled: false } });
+  });
+
+  test("classifies valid enabled config without changing it", async () => {
+    const dir = await mkTmpDir();
+    await fs.writeFile(
+      path.join(dir, "agent-memory.json"),
+      JSON.stringify({ journal: { enabled: true } }),
+    );
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("ok");
+    expect(loaded.config).toEqual({ journal: { enabled: true } });
   });
 
   test("returns custom tags from config", async () => {
@@ -78,22 +111,12 @@ describe("loadConfig", () => {
         },
       }),
     );
-    const config = await loadConfig(dir);
-    expect(config.journal?.tags).toEqual([
+    const loaded = await loadConfig(dir);
+    expect(loaded.config.journal?.tags).toEqual([
       { name: "perf", description: "Performance optimization work" },
       { name: "debug", description: "Debugging sessions" },
     ]);
   });
-
-  test("returns empty config when schema validation fails", async () => {
-    const dir = await mkTmpDir();
-    await fs.writeFile(
-      path.join(dir, "agent-memory.json"),
-      JSON.stringify({ journal: { enabled: "yes" } }),
-    );
-    const config = await loadConfig(dir);
-    expect(config).toEqual({});
-  });
 });
 
 describe("journal store", () => {

package/src/journal.ts

@@ -25,19 +25,72 @@ const ConfigSchema = z.looseObject({
 
 export type AgentMemoryConfig = z.infer<typeof ConfigSchema>;
 
+export type ConfigLoadStatus =
+  | "ok"
+  | "missing"
+  | "unreadable"
+  | "malformed"
+  | "invalid";
+
+export type LoadedConfig = {
+  config: AgentMemoryConfig;
+  status: ConfigLoadStatus;
+  configPath: string;
+  reason?: string;
+};
+
 export async function loadConfig(
   configDir?: string,
-): Promise<AgentMemoryConfig> {
+): Promise<LoadedConfig> {
   const dir = configDir ?? path.join(os.homedir(), ".config", "opencode");
-  const configPath = path.join(dir, "agent-memory.json");
+  const configPath = path.resolve(dir, "agent-memory.json");
+
+  let raw: string;
   try {
-    const raw = await fs.readFile(configPath, "utf-8");
-    const parsed = ConfigSchema.safeParse(JSON.parse(raw));
-    if (!parsed.success) return {};
-    return parsed.data;
+    raw = await fs.readFile(configPath, "utf-8");
+  } catch (error) {
+    const code = error instanceof Error && "code" in error
+      ? String(error.code)
+      : "unknown error";
+    if (code === "ENOENT") {
+      return {
+        config: {},
+        status: "missing",
+        configPath,
+        reason: "file is missing",
+      };
+    }
+    return {
+      config: {},
+      status: "unreadable",
+      configPath,
+      reason: `read failed (${code})`,
+    };
+  }
+
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
   } catch {
-    return {};
+    return {
+      config: {},
+      status: "malformed",
+      configPath,
+      reason: "malformed JSON",
+    };
+  }
+
+  const parsed = ConfigSchema.safeParse(value);
+  if (!parsed.success) {
+    return {
+      config: {},
+      status: "invalid",
+      configPath,
+      reason: "schema validation failed",
+    };
   }
+
+  return { config: parsed.data, status: "ok", configPath };
 }
 
 export type JournalTag = {
@@ -451,22 +504,3 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
     },
   };
 }
-
-export function buildJournalSystemNote(
-  tags?: readonly JournalTag[],
-): string {
-  const tagSection =
-    tags && tags.length > 0
-      ? `\n\nSuggested tags:\n${tags.map((t) => `- ${t.name}: ${t.description}`).join("\n")}`
-      : "";
-
-  return `<journal_instructions>
-You have access to a private journal. Use it to record thoughts, discoveries, and decisions as you work.
-Tags are free-form strings — use them to classify entries however makes sense.${tagSection}
-
-Before starting complex tasks, search the journal for relevant past context.
-Journal entries are append-only: you write new entries but never edit old ones.
-Use journal_search to find past entries semantically, and journal_read to read a specific entry.
-The journal is global across all projects but each entry records which project it was written from.
-</journal_instructions>`;
-}

package/src/plugin-disabled.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// Mock journal module with journal DISABLED — the control path.
+mock.module("./journal", () => ({
+  loadConfig: async () => ({
+    config: { journal: { enabled: false } },
+    status: "ok",
+    configPath: "/tmp/test-plugin-disabled/agent-memory.json",
+  }),
+  createJournalStore: () => ({}),
+}));
+
+// Mock embeddings to avoid model download
+mock.module("./embeddings", () => ({
+  warmupEmbedder: async () => {},
+}));
+
+import { MemoryPlugin } from "./plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+
+const stubInput = { directory: "/tmp/test-plugin-disabled" } as unknown as PluginInput;
+
+describe("plugin disabled path", () => {
+  test("registers zero tools when journal is disabled", async () => {
+    const plugin = await MemoryPlugin(stubInput);
+    // tool should be undefined or an empty object
+    if (plugin.tool) {
+      expect(Object.keys(plugin.tool)).toHaveLength(0);
+    } else {
+      expect(plugin.tool).toBeUndefined();
+    }
+  });
+
+  test("produces no guidance text when disabled", async () => {
+    const plugin = await MemoryPlugin(stubInput);
+    // There should be no system transform hook injecting guidance
+    expect(plugin["experimental.chat.system.transform"]).toBeUndefined();
+    // Tool definitions (if any exist as empty object) must not contain
+    // any description with journal guidance keywords
+    if (plugin.tool) {
+      for (const def of Object.values(plugin.tool)) {
+        const desc = (def as { description?: string }).description ?? "";
+        expect(desc).not.toMatch(/append-only|journal|search.*entry/i);
+      }
+    }
+  });
+
+  test("chat.message hook is still present when disabled", async () => {
+    const plugin = await MemoryPlugin(stubInput);
+    // The chat.message hook updates model/provider context — it should
+    // still be present even when journal is disabled.
+    expect(plugin["chat.message"]).toBeDefined();
+    expect(typeof plugin["chat.message"]).toBe("function");
+  });
+
+  test("does not warn for an intentional disabled configuration", async () => {
+    const originalWarn = console.warn;
+    let warningCount = 0;
+    console.warn = () => {
+      warningCount += 1;
+    };
+
+    try {
+      await MemoryPlugin(stubInput);
+      expect(warningCount).toBe(0);
+    } finally {
+      console.warn = originalWarn;
+    }
+  });
+});

package/src/plugin.test.ts

@@ -1,16 +1,16 @@
 import { describe, expect, mock, test } from "bun:test";
+import type { LoadedConfig } from "./journal";
 
-// Mock journal module so we don't hit the real filesystem for config/journal
-const JOURNAL_NOTE = `<journal_instructions>
-You have access to a private journal.
-</journal_instructions>`;
+let loadedConfig: LoadedConfig = {
+  config: { journal: { enabled: true } },
+  status: "ok" as const,
+  configPath: "/tmp/test-plugin/agent-memory.json",
+};
 
+// Mock journal module so we don't hit the real filesystem for config/journal
 mock.module("./journal", () => ({
-  loadConfig: async () => ({
-    journal: { enabled: true },
-  }),
+  loadConfig: async () => loadedConfig,
   createJournalStore: () => ({}),
-  buildJournalSystemNote: () => JOURNAL_NOTE,
 }));
 
 // Mock embeddings to avoid model download
@@ -24,43 +24,106 @@ import type { PluginInput } from "@opencode-ai/plugin";
 // Minimal stub: the plugin only reads `directory` from the input.
 const stubInput = { directory: "/tmp/test-plugin-regression" } as unknown as PluginInput;
 
-describe("plugin transform hook — journal regression", () => {
-  test("journal system note is injected when enabled and no blocks present", async () => {
-    const plugin = await MemoryPlugin(stubInput);
+type FaultStatus = Exclude<LoadedConfig["status"], "ok">;
 
-    const transform = plugin["experimental.chat.system.transform"];
-    expect(transform).toBeDefined();
+const faultCases: Array<{
+  status: FaultStatus;
+  reason: string;
+  config: LoadedConfig["config"];
+}> = [
+  { status: "missing", reason: "file is missing", config: {} },
+  { status: "unreadable", reason: "read failed (EACCES)", config: {} },
+  { status: "malformed", reason: "malformed JSON", config: {} },
+  {
+    // A non-ok status must win even if the mocked config is truthy.
+    status: "invalid",
+    reason: "schema validation failed",
+    config: { journal: { enabled: true } },
+  },
+];
 
-    const output = { system: [] as string[] };
-    // The chat.message hook expects a model param; the transform hook does not use it.
-    // Pass a minimal mock for the transform signature.
-    await (transform as Function)({}, output);
+const okCases: Array<{
+  name: string;
+  config: LoadedConfig["config"];
+  expectedToolCount: number;
+}> = [
+  {
+    name: "enabled",
+    config: { journal: { enabled: true } },
+    expectedToolCount: 3,
+  },
+  {
+    name: "disabled",
+    config: { journal: { enabled: false } },
+    expectedToolCount: 0,
+  },
+];
 
-    // The journal note MUST be present — this is the core regression check.
-    // With the old early-return (`if (!xml) return;`), when renderMemoryBlocks
-    // returned "" (no blocks), the entire transform returned before pushing
-    // journalSystemNote, silently disabling the journal.
-    expect(output.system).toContain(JOURNAL_NOTE);
-  });
+function resetLoadedConfig(): void {
+  loadedConfig = {
+    config: { journal: { enabled: true } },
+    status: "ok",
+    configPath: "/tmp/test-plugin/agent-memory.json",
+  };
+}
 
-  test("journal system note is pushed exactly once", async () => {
+describe("plugin structure", () => {
+  test("returns chat.message hook", async () => {
     const plugin = await MemoryPlugin(stubInput);
-
-    const transform = plugin["experimental.chat.system.transform"];
-    const output = { system: [] as string[] };
-    await (transform as Function)({}, output);
-
-    const count = output.system.filter((s) => s === JOURNAL_NOTE).length;
-    expect(count).toBe(1);
+    expect(plugin["chat.message"]).toBeDefined();
+    expect(typeof plugin["chat.message"]).toBe("function");
   });
 
-  test("empty system array is populated (not left untouched)", async () => {
+  test("does NOT return experimental.chat.system.transform hook", async () => {
     const plugin = await MemoryPlugin(stubInput);
+    expect(plugin["experimental.chat.system.transform"]).toBeUndefined();
+  });
 
-    const transform = plugin["experimental.chat.system.transform"];
-    const output = { system: [] as string[] };
-    await (transform as Function)({}, output);
+  for (const testCase of faultCases) {
+    test(`warns and disables tools for ${testCase.status} config`, async () => {
+      loadedConfig = {
+        config: testCase.config,
+        status: testCase.status,
+        configPath: "/tmp/test-plugin/agent-memory.json",
+        reason: testCase.reason,
+      };
+      const originalWarn = console.warn;
+      const warnings: unknown[][] = [];
+      console.warn = (...args: unknown[]) => warnings.push(args);
 
-    expect(output.system.length).toBeGreaterThan(0);
-  });
+      try {
+        const plugin = await MemoryPlugin(stubInput);
+        expect(Object.keys(plugin.tool ?? {})).toHaveLength(0);
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]?.[0]).toBe(
+          `[agent-memory] journal config /tmp/test-plugin/agent-memory.json: ${testCase.reason}; journal tools will NOT be registered`,
+        );
+      } finally {
+        console.warn = originalWarn;
+        resetLoadedConfig();
+      }
+    });
+  }
+
+  for (const testCase of okCases) {
+    test(`does not warn for valid ${testCase.name} config`, async () => {
+      loadedConfig = {
+        config: testCase.config,
+        status: "ok",
+        configPath: "/tmp/test-plugin/agent-memory.json",
+      };
+      const originalWarn = console.warn;
+      const warnings: unknown[][] = [];
+      console.warn = (...args: unknown[]) => warnings.push(args);
+
+      try {
+        const plugin = await MemoryPlugin(stubInput);
+        expect(Object.keys(plugin.tool ?? {})).toHaveLength(testCase.expectedToolCount);
+        expect(warnings).toHaveLength(0);
+      } finally {
+        console.warn = originalWarn;
+        resetLoadedConfig();
+      }
+    });
+  }
 });

package/src/plugin.ts

@@ -1,7 +1,6 @@
 import type { Plugin, ToolDefinition } from "@opencode-ai/plugin";
 
 import {
-  buildJournalSystemNote,
   createJournalStore,
   loadConfig,
 } from "./journal";
@@ -15,8 +14,16 @@ import { warmupEmbedder } from "./embeddings";
 
 export const MemoryPlugin: Plugin = async ({ directory }) => {
   // Journal: opt-in via ~/.config/opencode/agent-memory.json
-  const config = await loadConfig();
-  const journalEnabled = config.journal?.enabled === true;
+  const loadedConfig = await loadConfig();
+  const { config } = loadedConfig;
+
+  if (loadedConfig.status !== "ok") {
+    console.warn(
+      `[agent-memory] journal config ${loadedConfig.configPath}: ${loadedConfig.reason ?? loadedConfig.status}; journal tools will NOT be registered`,
+    );
+  }
+
+  const journalEnabled = loadedConfig.status === "ok" && config.journal?.enabled === true;
 
   // Mutable state updated by chat.message hook
   const journalCtx: JournalContext = {
@@ -26,7 +33,6 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
   };
 
   let journalTools: Record<string, ToolDefinition> = {};
-  let journalSystemNote = "";
 
   if (journalEnabled) {
     const journalStore = createJournalStore(undefined, config.cacheDir);
@@ -34,11 +40,10 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
     // first-init-wins singleton caches to the correct directory.
     void warmupEmbedder(config.cacheDir).catch(() => {});
     journalTools = {
-      journal_write: JournalWrite(journalStore, journalCtx),
+      journal_write: JournalWrite(journalStore, journalCtx, config.journal?.tags),
       journal_read: JournalRead(journalStore),
       journal_search: JournalSearch(journalStore),
     };
-    journalSystemNote = buildJournalSystemNote(config.journal?.tags);
   }
 
   return {
@@ -49,16 +54,6 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
       }
     },
 
-    "experimental.chat.system.transform": async (_input, output) => {
-      // Inject journal instructions unconditionally when enabled.
-      // Previous versions returned early when no memory blocks were present,
-      // which also skipped the journal note — a regression-class bug that
-      // silently disabled the journal entirely once blocks were removed.
-      if (journalSystemNote) {
-        output.system.push(journalSystemNote);
-      }
-    },
-
     tool: {
       ...journalTools,
     },

package/src/tools.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, test } from "bun:test";
+
+import { JournalRead, JournalSearch, JournalWrite } from "./tools";
+import type { JournalContext } from "./tools";
+import type { JournalEntry, JournalStore } from "./journal";
+
+// Minimal mock store — description tests use the default stubs, while search
+// output tests replace search with deterministic fixtures.
+const mockStore: JournalStore = {
+  write: async () => {
+    throw new Error("not implemented");
+  },
+  read: async () => {
+    throw new Error("not implemented");
+  },
+  search: async () => {
+    throw new Error("not implemented");
+  },
+};
+
+const mockCtx: JournalContext = {
+  directory: "/tmp/test",
+  model: "test-model",
+  provider: "test-provider",
+};
+
+// ─── Tool description tests ───────────────────────────────────────────────
+// These assert semantic properties of the description strings: that guidance
+// content is present, that stale/hallucinated text is absent, and that structural
+// invariants hold.  They use substring/regex assertions, so intra-sentence
+// rewording is tolerated; only content-level regressions trip them.
+
+const WRITE_DESC_NO_TAGS = JournalWrite(mockStore, mockCtx).description;
+const WRITE_DESC_WITH_TAGS = JournalWrite(mockStore, mockCtx, [
+  { name: "perf", description: "Performance optimization" },
+  { name: "debug", description: "Debugging sessions" },
+]).description;
+const READ_DESC = JournalRead(mockStore).description;
+const SEARCH_TOOL = JournalSearch(mockStore);
+const SEARCH_DESC = SEARCH_TOOL.description;
+
+function makeEntry(tags: string[]): JournalEntry {
+  return {
+    id: "20260101-000000-000",
+    title: "Retrieved entry",
+    project: "/tmp/test",
+    model: "test-model",
+    provider: "test-provider",
+    agent: "test-agent",
+    sessionId: "test-session",
+    created: new Date("2026-01-01T00:00:00.000Z"),
+    tags,
+    body: "Entry body",
+    filePath: "/tmp/test-entry.md",
+  };
+}
+
+async function executeSearch(result: Awaited<ReturnType<JournalStore["search"]>>): Promise<string> {
+  const store: JournalStore = {
+    ...mockStore,
+    search: async () => result,
+  };
+  const output = await JournalSearch(store).execute!({}, {} as never);
+  return String(output);
+}
+
+describe("journal_write description", () => {
+  test("mentions append-only semantics", () => {
+    expect(WRITE_DESC_NO_TAGS).toContain("append-only");
+  });
+
+  test("explains that entries cannot be edited", () => {
+    expect(WRITE_DESC_NO_TAGS).toMatch(/never edit|cannot be (edited|modified)/i);
+  });
+
+  test("documents tag format", () => {
+    expect(WRITE_DESC_NO_TAGS).toMatch(/tags/i);
+    expect(WRITE_DESC_NO_TAGS).toMatch(/comma.separated/i);
+  });
+
+  test("contains no dynamic or timestamped content", () => {
+    // A static description must not embed a date or ISO timestamp
+    expect(WRITE_DESC_NO_TAGS).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
+  });
+
+  test("mentions the journal is for recording insights", () => {
+    expect(WRITE_DESC_NO_TAGS).toMatch(/insight|discovery|decision|observation/i);
+  });
+
+  test("does not include suggested tags when none provided", () => {
+    expect(WRITE_DESC_NO_TAGS).not.toMatch(/suggested tags/i);
+  });
+
+  test("includes suggested tags when provided", () => {
+    expect(WRITE_DESC_WITH_TAGS).toMatch(/suggested tags/i);
+    expect(WRITE_DESC_WITH_TAGS).toContain("perf");
+    expect(WRITE_DESC_WITH_TAGS).toContain("debug");
+  });
+
+  test("suggested tags are tag names only, not descriptions", () => {
+    expect(WRITE_DESC_WITH_TAGS).toContain("perf");
+    expect(WRITE_DESC_WITH_TAGS).toContain("debug");
+    // Tag descriptions should NOT appear in the tool description
+    expect(WRITE_DESC_WITH_TAGS).not.toContain("Performance optimization");
+    expect(WRITE_DESC_WITH_TAGS).not.toContain("Debugging sessions");
+  });
+});
+
+describe("journal_read description", () => {
+  test("mentions reading a specific entry by ID", () => {
+    expect(READ_DESC).toMatch(/by.*ID/i);
+  });
+
+  test("does not contain write-only guidance", () => {
+    // Write-scoping guidance (append-only, cannot be edited) belongs only in
+    // journal_write's description.  An agent with read-but-not-write would
+    // see this guidance without the ability to act on it.
+    expect(READ_DESC).not.toMatch(/append.only|cannot be (edited|modified)/i);
+  });
+
+  test("contains no dynamic or timestamped content", () => {
+    expect(READ_DESC).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
+  });
+});
+
+describe("journal_search description", () => {
+  test("mentions searching semantically", () => {
+    expect(SEARCH_DESC).toMatch(/semantic|similarity|meaning/i);
+  });
+
+  test("mentions that filters can be combined", () => {
+    expect(SEARCH_DESC).toMatch(/filter/i);
+  });
+
+  test("documents the project filter argument", () => {
+    // The project filter is documented via the tool's args schema, not the
+    // description prose.  Assert the arg exists so a schema regression is caught.
+    expect(SEARCH_TOOL.args).toBeDefined();
+    expect(SEARCH_TOOL.args!.project).toBeDefined();
+  });
+
+  test("mentions pagination (offset)", () => {
+    expect(SEARCH_DESC).toMatch(/offset|paginate/i);
+  });
+
+  test("mentions the journal is global across projects", () => {
+    expect(SEARCH_DESC).toMatch(/global.*project|across.*project/i);
+  });
+
+  test("advises searching before complex tasks", () => {
+    expect(SEARCH_DESC).toMatch(/complex task|before start/i);
+  });
+
+  test("contains no dynamic or timestamped content", () => {
+    expect(SEARCH_DESC).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
+  });
+});
+
+describe("journal_search tag inventory output", () => {
+  const manyTags = Array.from({ length: 21 }, (_, index) => `tag-${index + 1}`);
+  const exactlyTwentyTags = Array.from({ length: 20 }, (_, index) => `tag-${index + 1}`);
+
+  test("bounds large tag inventories while reporting their count", async () => {
+    const output = await executeSearch({
+      entries: [makeEntry(["entry-tag"])],
+      total: 1,
+      allTags: manyTags,
+    });
+
+    expect(output.split("\n")[1]).toBe("Tags in use: 21 (filter with tags=...)");
+    expect(output).not.toContain("tag-1");
+    expect(output).not.toContain("tag-21");
+  });
+
+  test("lists small tag inventories", async () => {
+    const output = await executeSearch({
+      entries: [makeEntry(["entry-tag"])],
+      total: 1,
+      allTags: ["perf", "debug"],
+    });
+
+    expect(output).toContain("Tags in use: perf, debug");
+  });
+
+  test("lists exactly 20 tags at the boundary", async () => {
+    const output = await executeSearch({
+      entries: [makeEntry(["entry-tag"])],
+      total: 1,
+      allTags: exactlyTwentyTags,
+    });
+
+    expect(output.split("\n")[1]).toBe(`Tags in use: ${exactlyTwentyTags.join(", ")}`);
+  });
+
+  test("omits the tag inventory line when no tags exist", async () => {
+    const output = await executeSearch({
+      entries: [],
+      total: 0,
+      allTags: [],
+    });
+
+    expect(output).toBe("No journal entries found.");
+  });
+
+  test("bounds large tag inventories for empty results too", async () => {
+    const output = await executeSearch({
+      entries: [],
+      total: 0,
+      allTags: manyTags,
+    });
+
+    expect(output).toContain("No journal entries found.");
+    expect(output.split("\n")[1]).toBe("Tags in use: 21 (filter with tags=...)");
+    expect(output).not.toContain("tag-1");
+    expect(output).not.toContain("tag-21");
+  });
+});
+
+// ─── Cross-tool invariants ───────────────────────────────────────────────────
+
+describe("cross-tool invariants", () => {
+  test("no description mentions another journal tool by name", () => {
+    const toolNames = ["journal_search", "journal_read", "journal_write"];
+    for (const name of toolNames) {
+      const desc =
+        name === "journal_write"
+          ? WRITE_DESC_NO_TAGS
+          : name === "journal_read"
+            ? READ_DESC
+            : SEARCH_DESC;
+      const others = toolNames.filter((n) => n !== name);
+      for (const other of others) {
+        expect(desc).not.toContain(other);
+      }
+    }
+  });
+
+  test("all descriptions are non-empty strings", () => {
+    expect(typeof WRITE_DESC_NO_TAGS).toBe("string");
+    expect(WRITE_DESC_NO_TAGS.length).toBeGreaterThan(0);
+    expect(typeof READ_DESC).toBe("string");
+    expect(READ_DESC.length).toBeGreaterThan(0);
+    expect(typeof SEARCH_DESC).toBe("string");
+    expect(SEARCH_DESC.length).toBeGreaterThan(0);
+  });
+
+  test("no description contains the retired invitation phrase", () => {
+    const retired = "record thoughts, discoveries, and decisions as you work";
+    expect(WRITE_DESC_NO_TAGS).not.toContain(retired);
+    expect(READ_DESC).not.toContain(retired);
+    expect(SEARCH_DESC).not.toContain(retired);
+  });
+});

package/src/tools.ts

@@ -1,6 +1,6 @@
 import { tool } from "@opencode-ai/plugin";
 
-import type { JournalStore } from "./journal";
+import type { JournalStore, JournalTag } from "./journal";
 
 export type JournalContext = {
   directory: string;
@@ -8,15 +8,37 @@ export type JournalContext = {
   provider: string;
 };
 
+const MAX_TAGS_TO_LIST = 20;
+
+function formatTagsInUse(allTags: readonly string[]): string {
+  if (allTags.length === 0) {
+    return "";
+  }
+
+  // Retrieved entries already show their own tags, so avoid repeating the
+  // entire global inventory when it grows beyond a useful size.
+  if (allTags.length > MAX_TAGS_TO_LIST) {
+    return `\nTags in use: ${allTags.length} (filter with tags=...)`;
+  }
+  return `\nTags in use: ${allTags.join(", ")}`;
+}
+
 export function JournalWrite(
   store: JournalStore,
   ctx: JournalContext,
+  tags?: readonly JournalTag[],
 ) {
+  const suggestedTags =
+    tags && tags.length > 0
+      ? ` Suggested tags: ${tags.map((t) => t.name).join(", ")}.`
+      : "";
   return tool({
     description:
-      "Write a new journal entry. Use this to capture insights, technical discoveries, " +
-      "design decisions, observations, or reflections. Entries are append-only and cannot be edited. " +
-      "Tags are optional comma-separated names, e.g. \"perf, debugging\".",
+      "Write a new append-only journal entry. Use this to capture insights, technical discoveries, " +
+      "design decisions, observations, or reflections. " +
+      "Entries are append-only: you write new entries but never edit old ones. " +
+      "Tags are optional comma-separated names, e.g. \"perf, debugging\"." +
+      suggestedTags,
     args: {
       title: tool.schema.string(),
       body: tool.schema.string(),
@@ -82,7 +104,9 @@ export function JournalSearch(store: JournalStore) {
     description:
       "Search journal entries using semantic similarity. Returns matching entries " +
       "sorted by relevance. All filters are optional and combined with AND logic. " +
-      "Use with no arguments to list recent entries. Use offset to paginate.",
+      "Use with no arguments to list recent entries. Use offset to paginate. " +
+      "Before starting complex tasks, search the journal for relevant past context. " +
+      "The journal is global across all projects but each entry records which project it was written from.",
     args: {
       text: tool.schema.string().optional(),
       project: tool.schema.string().optional(),
@@ -106,20 +130,13 @@ export function JournalSearch(store: JournalStore) {
         offset: args.offset,
       });
 
+      const tagsLine = formatTagsInUse(result.allTags);
       if (result.entries.length === 0) {
-        const tagsLine =
-          result.allTags.length > 0
-            ? `\nTags in use: ${result.allTags.join(", ")}`
-            : "";
         return `No journal entries found.${tagsLine}`;
       }
 
       const offset = args.offset ?? 0;
       const header = `Found ${result.total} entries (showing ${offset + 1}–${offset + result.entries.length}):`;
-      const tagsLine =
-        result.allTags.length > 0
-          ? `\nTags in use: ${result.allTags.join(", ")}`
-          : "";
 
       const lines = result.entries.map((e) => {
         const tagStr =