@ghilteras/opencode-agent-memory 0.5.2 → 1.0.0

package/README.md

@@ -24,7 +24,7 @@ Think of it as a searchable sidecar to `AGENTS.md`. OpenCode supports [rules](ht
 
 ## Requirements
 
-- [OpenCode](https://opencode.ai/) v1.0.115 or later
+- [OpenCode](https://opencode.ai/) **v2** — this version uses the OpenCode v2 plugin API and does **not** run on v1
 
 ## Installation
 
@@ -32,32 +32,33 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugin": ["@ghilteras/opencode-agent-memory@0.5.2"]
+  "plugins": ["@ghilteras/opencode-agent-memory@1.0.0"]
 }
 ```
 
-OpenCode fetches unpinned plugins from npm on each startup; pinned versions are cached and require a manual version bump to update.
+Note OpenCode **v2** reads the `plugins` key (v1 used `plugin`). OpenCode fetches unpinned plugins from npm on each startup; pinned versions are cached and require a manual version bump to update.
 
 ## Journal
 
-The journal is **opt-in**. Enable it in `~/.config/opencode/agent-memory.json`:
+The journal is **on by default** — the three tools are registered with no configuration required.
+
+To turn it off, set `enabled: false` in `~/.config/opencode/agent-memory.json`:
 
 ```json
 {
   "journal": {
-    "enabled": true
+    "enabled": false
   }
 }
 ```
 
-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**.
+- An explicit disable (`"enabled": false`) is silent by design and registers **no tools**.
+- A config that exists but is unreadable, malformed, or schema-invalid **fails closed**: it logs `[agent-memory] journal config <resolved path>: <reason>; journal tools will NOT be registered` and registers **no tools**.
+- An **absent** config means the default: the tools register. (This changed in 1.0.0 — an absent config used to disable the journal.)
 
 ### Tools
 
-When the journal is enabled, the agent gets 3 tools:
+The agent gets 3 tools:
 
 | Tool | Description |
 |------|-------------|
@@ -119,6 +120,15 @@ By default the transformers.js model cache lives in the default location (`~/.ca
 }
 ```
 
+## Upgrading to 1.0.0
+
+**This release requires OpenCode v2.** The plugin was ported from the v1 plugin API to the v2 plugin API and will not load on v1. The config key is now `plugins` (v1 used `plugin`).
+
+Two behaviour changes:
+
+- **The journal tools are registered by default.** Previously you had to opt in through `agent-memory.json`; now an absent config means the tools are on, and you turn them off with `"enabled": false`.
+- **Storage is unchanged.** Existing entries under `~/.config/opencode/journal/` and their `.embedding` sidecars stay readable; nothing is migrated or rewritten.
+
 ## Upgrading from 0.4.x
 
 Memory blocks and their tools (`memory_list`, `memory_set`, `memory_replace`) are **removed**. Blocks are no longer read, written, or injected into the system prompt; the plugin ships only the journal.
@@ -127,9 +137,9 @@ Existing `~/.config/opencode/memory/` and `.opencode/memory/` directories are **
 
 ## Compatibility & Troubleshooting
 
-- **Requires OpenCode v1.0.115+.**
+- **Requires OpenCode v2.** This release uses the OpenCode v2 plugin API and does not run on v1.
 - **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`; intentional disablement is silent, while a missing, unreadable, malformed, or schema-invalid config logs a warning and registers no tools.
+- **Journal is on by default.** Turn it off with `"enabled": false`; an explicit disable is silent, while a config that exists but is unreadable, malformed, or schema-invalid logs a warning and registers no tools (fail-closed).
 - **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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "0.5.2",
+  "version": "1.0.0",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",
@@ -22,7 +22,7 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
-    "@opencode-ai/plugin": "^1.0.115",
+    "@opencode/plugin": "^2.0.18",
     "js-yaml": "^4.1.0",
     "zod": "^4.1.13"
   },

package/src/journal.test.ts

@@ -75,6 +75,14 @@ describe("loadConfig", () => {
     expect(loaded.config).toEqual({});
   });
 
+  test("rejects an unrecognized journal key instead of silently enabling", async () => {
+    const dir = await mkTmpDir();
+    await fs.writeFile(path.join(dir, "agent-memory.json"), JSON.stringify({ journal: { enabled_: false } }));
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("invalid");
+    expect(loaded.config).toEqual({});
+  });
+
   test("classifies valid disabled config without changing it", async () => {
     const dir = await mkTmpDir();
     await fs.writeFile(

package/src/journal.ts

@@ -16,10 +16,10 @@ const TagSchema = z.looseObject({
 const ConfigSchema = z.looseObject({
   cacheDir: z.string().optional(),
   journal: z
-    .looseObject({
+    .object({
       enabled: z.boolean().optional(),
       tags: z.array(TagSchema).optional(),
-    })
+    }).strict()
     .optional(),
 });
 

package/src/plugin-disabled.test.ts

@@ -1,70 +1,26 @@
-import { describe, expect, mock, test } from "bun:test";
+import { afterEach, 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",
-  }),
+  loadConfig: async () => ({ config: { journal: { enabled: false } }, status: "ok", configPath: "/tmp/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;
-    }
-  });
+mock.module("./embeddings", () => ({ warmupEmbedder: async () => {} }));
+import plugin from "./plugin";
+
+afterEach(() => mock.restore());
+
+test("explicit opt-out registers no tools and emits no warning", async () => {
+  const definitions: unknown[] = [];
+  const warn = console.warn;
+  let warnings = 0;
+  console.warn = () => { warnings++; };
+  try {
+    await plugin.setup({
+      location: { directory: "/tmp" },
+      session: { hook: async () => {} },
+      tool: { transform: async (callback: (editor: { add: (tool: unknown) => void }) => void) => callback({ add: (tool) => definitions.push(tool) }) },
+    } as any);
+    expect(definitions).toEqual([]);
+    expect(warnings).toBe(0);
+  } finally { console.warn = warn; }
 });

package/src/plugin.test.ts

@@ -1,129 +1,124 @@
-import { describe, expect, mock, test } from "bun:test";
-import type { LoadedConfig } from "./journal";
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import type { LoadedConfig, JournalEntry } from "./journal";
 
-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
+let loadedConfig: LoadedConfig = { config: {}, status: "missing", configPath: "/tmp/test/agent-memory.json", reason: "file is missing" };
+const writes: Array<Record<string, unknown>> = [];
 mock.module("./journal", () => ({
   loadConfig: async () => loadedConfig,
-  createJournalStore: () => ({}),
+  createJournalStore: () => ({
+    write: async (entry: Record<string, unknown>) => {
+      writes.push(entry);
+      return { id: "id-1", title: entry.title, created: new Date("2026-01-01T00:00:00.000Z") } as JournalEntry;
+    },
+    read: async () => { throw new Error("unused"); },
+    search: async () => ({ entries: [], total: 0, allTags: [] }),
+  }),
 }));
+mock.module("./embeddings", () => ({ warmupEmbedder: async () => {} }));
 
-// Mock embeddings to avoid model download
-mock.module("./embeddings", () => ({
-  warmupEmbedder: async () => {},
-}));
+import plugin from "./plugin";
 
-import { MemoryPlugin } from "./plugin";
-import type { PluginInput } from "@opencode-ai/plugin";
+function harness() {
+  const definitions = new Map<string, any>();
+  let contextHook: ((event: any) => void) | undefined;
+  let transform: ((editor: { add: (definition: any) => void; list: () => any[] }) => void) | undefined;
+  const context = {
+    location: { directory: "/tmp/project" },
+    session: { hook: async (name: string, callback: (event: any) => void) => { expect(name).toBe("context"); contextHook = callback; } },
+    tool: { transform: async (callback: typeof transform) => { transform = callback; callback!({ add: (definition) => definitions.set(definition.name, definition), list: () => [...definitions.values()] }); } },
+  } as any;
+  return { definitions, contextHook: () => contextHook, replay: () => transform!({ add: (definition) => definitions.set(definition.name, definition), list: () => [...definitions.values()] }), start: () => plugin.setup(context) };
+}
 
-// Minimal stub: the plugin only reads `directory` from the input.
-const stubInput = { directory: "/tmp/test-plugin-regression" } as unknown as PluginInput;
+afterEach(() => {
+  loadedConfig = { config: {}, status: "missing", configPath: "/tmp/test/agent-memory.json", reason: "file is missing" };
+  writes.length = 0;
+});
 
-type FaultStatus = Exclude<LoadedConfig["status"], "ok">;
+describe("v2 plugin registration", () => {
+  test("has a stable id and default-registers exactly the three journal tools", async () => {
+    expect(plugin.id).toBe("opencode-agent-memory");
+    const h = harness();
+    await h.start();
+    expect([...h.definitions.keys()].sort()).toEqual(["journal_read", "journal_search", "journal_write"]);
+  });
 
-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 } },
-  },
-];
+  test("registered write description suggests configured tag names without their descriptions", async () => {
+    loadedConfig = {
+      config: {
+        journal: {
+          tags: [
+            { name: "owner_approved", description: "Use for a choice made and its rationale." },
+            { name: "incident_followup", description: "Use for investigation notes and findings." },
+          ],
+        },
+      },
+      status: "ok",
+      configPath: "/tmp/test/agent-memory.json",
+    };
 
-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,
-  },
-];
+    const h = harness();
+    await h.start();
+    const description = h.definitions.get("journal_write").description as string;
 
-function resetLoadedConfig(): void {
-  loadedConfig = {
-    config: { journal: { enabled: true } },
-    status: "ok",
-    configPath: "/tmp/test-plugin/agent-memory.json",
-  };
-}
+    expect(description).toContain("Suggested tags: owner_approved, incident_followup.");
+    expect(description).not.toContain("Use for a choice made and its rationale.");
+    expect(description).not.toContain("Use for investigation notes and findings.");
+  });
 
-describe("plugin structure", () => {
-  test("returns chat.message hook", async () => {
-    const plugin = await MemoryPlugin(stubInput);
-    expect(plugin["chat.message"]).toBeDefined();
-    expect(typeof plugin["chat.message"]).toBe("function");
+  test("transform replay does not duplicate tool registration", async () => {
+    const h = harness(); await h.start();
+    h.replay();
+    expect([...h.definitions.keys()].sort()).toEqual(["journal_read", "journal_search", "journal_write"]);
   });
 
-  test("does NOT return experimental.chat.system.transform hook", async () => {
-    const plugin = await MemoryPlugin(stubInput);
-    expect(plugin["experimental.chat.system.transform"]).toBeUndefined();
+  test("explicit false opts out without tools", async () => {
+    loadedConfig = { config: { journal: { enabled: false } }, status: "ok", configPath: "/tmp/test/agent-memory.json" };
+    const h = harness(); await h.start();
+    expect([...h.definitions.keys()]).toEqual([]);
   });
 
-  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);
+  test("invalid journal typo fails closed and warns", async () => {
+    loadedConfig = { config: {}, status: "invalid", configPath: "/tmp/test/agent-memory.json", reason: "schema validation failed" };
+    const warnings: unknown[][] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args) => warnings.push(args);
+    try {
+      const h = harness(); await h.start();
+      expect([...h.definitions.keys()]).toEqual([]);
+      expect(warnings).toEqual([["[agent-memory] journal config /tmp/test/agent-memory.json: schema validation failed; journal tools will NOT be registered"]]);
+    } finally { console.warn = originalWarn; }
+  });
 
+  for (const status of ["unreadable", "malformed", "invalid"] as const) {
+    test(`fails closed on ${status} config`, async () => {
+      loadedConfig = { config: { journal: { enabled: true } }, status, configPath: "/tmp/test/agent-memory.json", reason: "bad config" };
+      const warnings: unknown[][] = [];
+      const originalWarn = console.warn;
+      console.warn = (...args) => warnings.push(args);
       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();
-      }
+        const h = harness(); await h.start();
+        expect([...h.definitions.keys()]).toEqual([]);
+        expect(warnings).toEqual([["[agent-memory] journal config /tmp/test/agent-memory.json: bad config; journal tools will NOT be registered"]]);
+      } finally { console.warn = originalWarn; }
     });
   }
 
-  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);
+  test("default absent config emits no warning", async () => {
+    const warnings: unknown[][] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args) => warnings.push(args);
+    try { const h = harness(); await h.start(); expect(warnings).toEqual([]); }
+    finally { console.warn = originalWarn; }
+  });
 
-      try {
-        const plugin = await MemoryPlugin(stubInput);
-        expect(Object.keys(plugin.tool ?? {})).toHaveLength(testCase.expectedToolCount);
-        expect(warnings).toHaveLength(0);
-      } finally {
-        console.warn = originalWarn;
-        resetLoadedConfig();
-      }
-    });
-  }
+  test("captures model/provider per session for interleaved context events", async () => {
+    const h = harness(); await h.start();
+    const hook = h.contextHook()!;
+    hook({ sessionID: "session-a", model: { id: "model-a", providerID: "provider-a" } });
+    hook({ sessionID: "session-b", model: { id: "model-b", providerID: "provider-b" } });
+    hook({ sessionID: "session-a", model: { id: "model-a2", providerID: "provider-a2" } });
+    await h.definitions.get("journal_write").execute({ title: "Title", body: "Body" }, { agent: "agent", sessionID: "session-b" });
+    expect(writes[0]).toMatchObject({ model: "model-b", provider: "provider-b", sessionId: "session-b" });
+  });
 });

package/src/plugin.ts

@@ -1,61 +1,62 @@
-import type { Plugin, ToolDefinition } from "@opencode-ai/plugin";
-
-import {
-  createJournalStore,
-  loadConfig,
-} from "./journal";
-import {
-  JournalRead,
-  JournalSearch,
-  JournalWrite,
-} from "./tools";
+import { Plugin } from "@opencode/plugin";
+import { createJournalStore, loadConfig } from "./journal";
+import { JournalRead, JournalSearch, JournalWrite } from "./tools";
 import type { JournalContext } from "./tools";
 import { warmupEmbedder } from "./embeddings";
 
-export const MemoryPlugin: Plugin = async ({ directory }) => {
-  // Journal: opt-in via ~/.config/opencode/agent-memory.json
-  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;
+export default Plugin.define({
+  id: "opencode-agent-memory",
+  async setup(ctx) {
+    const loadedConfig = await loadConfig();
+    const { config } = loadedConfig;
+    const configUsable = loadedConfig.status === "ok" || loadedConfig.status === "missing";
+    if (!configUsable) {
+      console.warn(`[agent-memory] journal config ${loadedConfig.configPath}: ${loadedConfig.reason ?? loadedConfig.status}; journal tools will NOT be registered`);
+      return;
+    }
 
-  // Mutable state updated by chat.message hook
-  const journalCtx: JournalContext = {
-    directory,
-    model: "",
-    provider: "",
-  };
+    if (config.journal?.enabled === false) return;
 
-  let journalTools: Record<string, ToolDefinition> = {};
-
-  if (journalEnabled) {
     const journalStore = createJournalStore(undefined, config.cacheDir);
-    // Warmup the embedder in the background; pass configured cacheDir so the
-    // first-init-wins singleton caches to the correct directory.
     void warmupEmbedder(config.cacheDir).catch(() => {});
-    journalTools = {
-      journal_write: JournalWrite(journalStore, journalCtx, config.journal?.tags),
-      journal_read: JournalRead(journalStore),
-      journal_search: JournalSearch(journalStore),
+    const contexts = new Map<string, JournalContext>();
+    const directory = ctx.location.directory;
+    const tools = [
+      JournalWrite(journalStore, {
+        directory,
+        get model() { return ""; },
+        get provider() { return ""; },
+      }, config.journal?.tags),
+      JournalRead(journalStore),
+      JournalSearch(journalStore),
+    ];
+
+    // Register a per-session capture; a write resolves its own session's model.
+    const writeTool = tools[0]!;
+    writeTool.execute = async (input, toolCtx) => {
+      const sessionContext = contexts.get(toolCtx.sessionID);
+      const modelContext: JournalContext = {
+        directory,
+        model: sessionContext?.model ?? "",
+        provider: sessionContext?.provider ?? "",
+      };
+      const contextual = JournalWrite(journalStore, modelContext, config.journal?.tags);
+      return contextual.execute(input, toolCtx);
     };
-  }
 
-  return {
-    "chat.message": async (input, _output) => {
-      if (input.model) {
-        journalCtx.model = input.model.modelID;
-        journalCtx.provider = input.model.providerID;
+    await ctx.session.hook("context", (input) => {
+      contexts.set(input.sessionID, {
+        directory,
+        model: input.model.id,
+        provider: input.model.providerID,
+      });
+    });
+    await ctx.tool.transform((editor) => {
+      // Transforms may be replayed; avoid duplicate registrations by effective tool name.
+      const registered = new Set(editor.list().map((tool) => tool.name));
+      for (const tool of tools) {
+        if (!registered.has(tool.name)) editor.add(tool as never);
       }
-    },
-
-    tool: {
-      ...journalTools,
-    },
-  };
-};
+    });
+  },
+});

package/src/tools.test.ts

@@ -1,253 +1,115 @@
 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",
-  };
+const context: JournalContext = { directory: "/tmp/project", model: "m", provider: "p" };
+function entry(): JournalEntry {
+  return { id: "20260101-000000-000", title: "Title", project: "/tmp", model: "m", provider: "p", agent: "a", sessionId: "s", created: new Date("2026-01-01T00:00:00.000Z"), tags: ["tag"], body: "Body", filePath: "/tmp/entry.md" };
 }
+const baseStore: JournalStore = {
+  write: async () => entry(),
+  read: async () => entry(),
+  search: async () => ({ entries: [entry()], total: 1, allTags: ["tag"] }),
+};
 
-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);
+function valid(schema: any, value: any): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  if (schema.additionalProperties === false && Object.keys(value).some((key) => !(key in schema.properties))) return false;
+  if (schema.required?.some((key: string) => !(key in value))) return false;
+  for (const [key, field] of Object.entries<any>(schema.properties)) {
+    if (!(key in value)) continue;
+    const actual = value[key];
+    if (field.type === "string" && typeof actual !== "string") return false;
+    if (field.type === "integer" && (!Number.isInteger(actual) || actual < (field.minimum ?? -Infinity))) return false;
+  }
+  return true;
 }
 
-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");
+describe("v2 journal tools", () => {
+  test("preserves the recognizable names and descriptions", () => {
+    expect([JournalWrite(baseStore, context).name, JournalRead(baseStore).name, JournalSearch(baseStore).name]).toEqual(["journal_write", "journal_read", "journal_search"]);
+    expect(JournalWrite(baseStore, context).description).toContain("append-only");
+    expect(JournalRead(baseStore).description).toContain("by its ID");
+    expect(JournalSearch(baseStore).description).toContain("semantic similarity");
+  });
+
+  test("journal_write description preserves its behavioral guidance", () => {
+    const description = JournalWrite(baseStore, context).description;
+    expect(description).toMatch(/insights.*discoveries|discoveries.*decisions/i);
+    expect(description).toMatch(/insights.*technical discoveries.*design decisions.*observations/i);
+    expect(description).toMatch(/never edit old ones/i);
+    expect(description).toMatch(/comma-separated/i);
+    expect(description).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
+    expect(description).not.toContain("Suggested tags:");
+    const tagged = JournalWrite(baseStore, context, [{ name: "focus", description: "private detail" }]).description;
+    expect(tagged).toContain("Suggested tags: focus.");
+    expect(tagged).not.toContain("private detail");
+  });
+
+  test("read and search descriptions retain their distinct contracts", () => {
+    const read = JournalRead(baseStore).description;
+    expect(read).not.toMatch(/append.only|cannot be (edited|modified)/i);
+    expect(read).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
+    const search = JournalSearch(baseStore);
+    expect(search.description).toMatch(/filters are optional/i);
+    expect(search.description).toMatch(/global across all projects/i);
+    expect(search.input.properties).toHaveProperty("project");
+    expect(search.input.properties).toHaveProperty("offset");
+    expect(search.description).toMatch(/paginate/i);
+  });
+
+  test("descriptions are nonempty and do not name sibling tools", () => {
+    const descriptions = [JournalWrite(baseStore, context).description, JournalRead(baseStore).description, JournalSearch(baseStore).description];
+    expect(descriptions.every((description) => description.trim().length > 0)).toBe(true);
+    for (const [index, description] of descriptions.entries()) {
+      for (const [otherIndex, name] of ["journal_write", "journal_read", "journal_search"].entries()) {
+        if (index !== otherIndex) expect(description).not.toContain(name);
+      }
+    }
   });
-});
 
-// ─── 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("uses JSON schemas, rejects malformed and unknown arguments", () => {
+    const write = JournalWrite(baseStore, context).input as any;
+    const read = JournalRead(baseStore).input as any;
+    const search = JournalSearch(baseStore).input as any;
+    expect(write.type).toBe("object");
+    expect(valid(write, { title: "t", body: "b" })).toBe(true);
+    expect(valid(write, { title: 4, body: "b" })).toBe(false);
+    expect(valid(write, { title: "t", body: "b", extra: true })).toBe(false);
+    expect(valid(read, {})).toBe(false);
+    expect(valid(read, { id: "id", extra: 1 })).toBe(false);
+    expect(valid(search, { limit: 0 })).toBe(false);
+    expect(valid(search, { offset: 1.5 })).toBe(false);
+    expect(valid(search, { unexpected: true })).toBe(false);
+    expect(valid(search, { tags: "a,b", limit: 2, offset: 0 })).toBe(true);
+  });
+
+  test("all execute methods return the v2 {content} result", async () => {
+    const writeResult = await JournalWrite(baseStore, context).execute({ title: "t", body: "b" }, { agent: "a", sessionID: "s" });
+    const readResult = await JournalRead(baseStore).execute({ id: "entry" }, {} as any);
+    const searchResult = await JournalSearch(baseStore).execute({}, {} as any);
+    for (const result of [writeResult, readResult, searchResult]) {
+      expect(Object.keys(result)).toEqual(["content"]);
+      expect(typeof result.content).toBe("string");
     }
+    expect(writeResult.content).toContain("Journal entry created:");
+    expect(readResult.content).toContain("Body");
+    expect(searchResult.content).toContain("Found 1 entries");
   });
 
-  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("retains bounded tag inventory output formatting", async () => {
+    const populated: JournalStore = { ...baseStore, search: async () => ({ entries: [entry()], total: 1, allTags: ["alpha", "beta"] }) };
+    expect((await JournalSearch(populated).execute({}, {} as any)).content).toContain("Tags in use: alpha, beta");
+    const empty: JournalStore = { ...baseStore, search: async () => ({ entries: [], total: 0, allTags: [] }) };
+    expect((await JournalSearch(empty).execute({}, {} as any)).content).toBe("No journal entries found.");
+    const store: JournalStore = { ...baseStore, search: async () => ({ entries: [], total: 0, allTags: Array.from({ length: 21 }, (_, i) => `tag-${i}`) }) };
+    const result = await JournalSearch(store).execute({}, {} as any);
+    expect(result.content).toBe("No journal entries found.\nTags in use: 21 (filter with tags=...)");
   });
 
-  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);
+  test("journal_read formats metadata before the body", async () => {
+    const result = await JournalRead(baseStore).execute({ id: "entry" }, {} as any);
+    expect(result.content).toBe("title: Title\ncreated: 2026-01-01T00:00:00.000Z\nproject: /tmp\nmodel: m\nprovider: p\nagent: a\nsession: s\ntags: tag\n\nBody");
   });
 });

package/src/tools.ts

@@ -1,5 +1,3 @@
-import { tool } from "@opencode-ai/plugin";
-
 import type { JournalStore, JournalTag } from "./journal";
 
 export type JournalContext = {
@@ -11,142 +9,99 @@ export type JournalContext = {
 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=...)`;
-  }
+  if (allTags.length === 0) return "";
+  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 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(),
-      tags: tool.schema.string().optional(),
-    },
-    async execute(args, toolCtx) {
-      const tags = args.tags
-        ? args.tags
-            .split(",")
-            .map((t: string) => t.trim())
-            .filter(Boolean)
-        : undefined;
-
-      const entry = await store.write({
-        title: args.title,
-        body: args.body,
-        project: ctx.directory,
-        model: ctx.model,
-        provider: ctx.provider,
-        agent: toolCtx.agent,
-        sessionId: toolCtx.sessionID,
-        tags,
-      });
+type JsonSchema = {
+  type: "object";
+  properties: Record<string, { type: string; description?: string; minimum?: number }>;
+  required?: string[];
+  additionalProperties: false;
+};
+type ToolDefinition = {
+  name: string;
+  description: string;
+  input: JsonSchema;
+  execute(input: Record<string, unknown>, context: { agent: string; sessionID: string }): Promise<{ content: string }>;
+};
 
-      return `Journal entry created: ${entry.id}\n  title: ${entry.title}\n  created: ${entry.created.toISOString()}`;
+export function JournalWrite(store: JournalStore, ctx: JournalContext, tags?: readonly JournalTag[]): ToolDefinition {
+  const suggestedTags = tags?.length ? ` Suggested tags: ${tags.map((tag) => tag.name).join(", ")}.` : "";
+  return {
+    name: "journal_write",
+    description: "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,
+    input: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Entry title" },
+        body: { type: "string", description: "Entry body" },
+        tags: { type: "string", description: "Optional comma-separated tag names" },
+      },
+      required: ["title", "body"],
+      additionalProperties: false,
     },
-  });
-}
-
-export function JournalRead(store: JournalStore) {
-  return tool({
-    description:
-      "Read a specific journal entry by its ID. Returns the full entry " +
-      "including metadata and body.",
-    args: {
-      id: tool.schema.string(),
+    async execute(input, toolCtx) {
+      const title = input.title as string;
+      const body = input.body as string;
+      const tags = typeof input.tags === "string" ? input.tags.split(",").map((tag) => tag.trim()).filter(Boolean) : undefined;
+      const entry = await store.write({ title, body, project: ctx.directory, model: ctx.model, provider: ctx.provider, agent: toolCtx.agent, sessionId: toolCtx.sessionID, tags });
+      return { content: `Journal entry created: ${entry.id}\n  title: ${entry.title}\n  created: ${entry.created.toISOString()}` };
     },
-    async execute(args) {
-      const entry = await store.read(args.id);
+  };
+}
 
+export function JournalRead(store: JournalStore): ToolDefinition {
+  return {
+    name: "journal_read",
+    description: "Read a specific journal entry by its ID. Returns the full entry including metadata and body.",
+    input: { type: "object", properties: { id: { type: "string", description: "Journal entry ID" } }, required: ["id"], additionalProperties: false },
+    async execute(input) {
+      const entry = await store.read(input.id as string);
       const meta = [
-        `title: ${entry.title}`,
-        `created: ${entry.created.toISOString()}`,
+        `title: ${entry.title}`, `created: ${entry.created.toISOString()}`,
         entry.project ? `project: ${entry.project}` : null,
         entry.model ? `model: ${entry.model}` : null,
         entry.provider ? `provider: ${entry.provider}` : null,
         entry.agent ? `agent: ${entry.agent}` : null,
         entry.sessionId ? `session: ${entry.sessionId}` : null,
-        entry.tags.length > 0
-          ? `tags: ${entry.tags.join(", ")}`
-          : null,
-      ]
-        .filter(Boolean)
-        .join("\n");
-
-      return `${meta}\n\n${entry.body}`;
+        entry.tags.length ? `tags: ${entry.tags.join(", ")}` : null,
+      ].filter(Boolean).join("\n");
+      return { content: `${meta}\n\n${entry.body}` };
     },
-  });
+  };
 }
 
-export function JournalSearch(store: JournalStore) {
-  return tool({
-    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. " +
-      "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(),
-      tags: tool.schema.string().optional(),
-      limit: tool.schema.number().int().positive().optional(),
-      offset: tool.schema.number().int().nonnegative().optional(),
+export function JournalSearch(store: JournalStore): ToolDefinition {
+  return {
+    name: "journal_search",
+    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. 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.",
+    input: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Semantic search text" },
+        project: { type: "string", description: "Filter by project directory" },
+        tags: { type: "string", description: "Comma-separated tags; all must match" },
+        limit: { type: "integer", minimum: 1, description: "Maximum entries to return" },
+        offset: { type: "integer", minimum: 0, description: "Number of entries to skip" },
+      },
+      additionalProperties: false,
     },
-    async execute(args) {
-      const tags = args.tags
-        ? args.tags
-            .split(",")
-            .map((t: string) => t.trim())
-            .filter(Boolean)
-        : undefined;
-
+    async execute(input) {
       const result = await store.search({
-        text: args.text,
-        project: args.project,
-        tags,
-        limit: args.limit,
-        offset: args.offset,
+        text: input.text as string | undefined,
+        project: input.project as string | undefined,
+        tags: typeof input.tags === "string" ? input.tags.split(",").map((tag) => tag.trim()).filter(Boolean) : undefined,
+        limit: input.limit as number | undefined,
+        offset: input.offset as number | undefined,
       });
-
       const tagsLine = formatTagsInUse(result.allTags);
-      if (result.entries.length === 0) {
-        return `No journal entries found.${tagsLine}`;
-      }
-
-      const offset = args.offset ?? 0;
+      if (!result.entries.length) return { content: `No journal entries found.${tagsLine}` };
+      const offset = (input.offset as number | undefined) ?? 0;
       const header = `Found ${result.total} entries (showing ${offset + 1}–${offset + result.entries.length}):`;
-
-      const lines = result.entries.map((e) => {
-        const tagStr =
-          e.tags.length > 0
-            ? ` [${e.tags.join(", ")}]`
-            : "";
-        return `${e.id}\n  ${e.title}${tagStr}\n  ${e.created.toISOString()}`;
-      });
-
-      return `${header}${tagsLine}\n\n${lines.join("\n\n")}`;
+      const lines = result.entries.map((entry) => `${entry.id}\n  ${entry.title}${entry.tags.length ? ` [${entry.tags.join(", ")}]` : ""}\n  ${entry.created.toISOString()}`);
+      return { content: `${header}${tagsLine}\n\n${lines.join("\n\n")}` };
     },
-  });
+  };
 }