@ghilteras/opencode-agent-memory 0.5.1 → 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,29 +32,33 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugin": ["@ghilteras/opencode-agent-memory@0.5.0"]
+  "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
   }
 }
 ```
 
-With the journal disabled the plugin 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 |
 |------|-------------|
@@ -116,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.
@@ -124,11 +137,11 @@ 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`; with it disabled the plugin 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 (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.
+- **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.1",
+  "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

@@ -41,27 +41,68 @@ 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("rejects an unrecognized journal key instead of silently enabling", 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("invalid");
+    expect(loaded.config).toEqual({});
+  });
+
+  test("classifies valid disabled config without changing it", 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("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 +119,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

@@ -16,28 +16,81 @@ 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(),
 });
 
 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 {
+    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 {
-    const raw = await fs.readFile(configPath, "utf-8");
-    const parsed = ConfigSchema.safeParse(JSON.parse(raw));
-    if (!parsed.success) return {};
-    return parsed.data;
+    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,4 +504,3 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
     },
   };
 }
-

package/src/plugin-disabled.test.ts

@@ -1,53 +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 () => ({
-    journal: { enabled: false },
-  }),
+  loadConfig: async () => ({ config: { journal: { enabled: false } }, status: "ok", configPath: "/tmp/disabled/agent-memory.json" }),
   createJournalStore: () => ({}),
 }));
+mock.module("./embeddings", () => ({ warmupEmbedder: async () => {} }));
+import plugin from "./plugin";
 
-// 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);
-      }
-    }
-  });
+afterEach(() => mock.restore());
 
-  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("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,41 +1,124 @@
-import { describe, expect, mock, test } from "bun:test";
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import type { LoadedConfig, JournalEntry } from "./journal";
 
-// 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 () => ({
-    journal: { enabled: true },
+  loadConfig: async () => loadedConfig,
+  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: [] }),
   }),
-  createJournalStore: () => ({}),
 }));
+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;
+});
 
-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");
+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"]);
   });
 
-  test("does NOT return experimental.chat.system.transform hook", async () => {
-    const plugin = await MemoryPlugin(stubInput);
-    expect(plugin["experimental.chat.system.transform"]).toBeUndefined();
+  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 h = harness();
+    await h.start();
+    const description = h.definitions.get("journal_write").description as string;
+
+    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.");
+  });
+
+  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("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([]);
+  });
+
+  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 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; }
+    });
+  }
+
+  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; }
   });
 
-  test("registers journal tools when enabled", async () => {
-    const plugin = await MemoryPlugin(stubInput);
-    expect(plugin.tool).toBeDefined();
-    expect(plugin.tool!["journal_write"]).toBeDefined();
-    expect(plugin.tool!["journal_read"]).toBeDefined();
-    expect(plugin.tool!["journal_search"]).toBeDefined();
+  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,53 +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 config = await loadConfig();
-  const journalEnabled = config.journal?.enabled === true;
-
-  // Mutable state updated by chat.message hook
-  const journalCtx: JournalContext = {
-    directory,
-    model: "",
-    provider: "",
-  };
+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;
+    }
 
-  let journalTools: Record<string, ToolDefinition> = {};
+    if (config.journal?.enabled === false) return;
 
-  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,167 +1,115 @@
 import { describe, expect, test } from "bun:test";
-
 import { JournalRead, JournalSearch, JournalWrite } from "./tools";
 import type { JournalContext } from "./tools";
-import type { JournalStore, JournalTag } from "./journal";
-
-// Minimal mock store — tests only check description strings, not execute.
-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",
+import type { JournalEntry, JournalStore } from "./journal";
+
+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"] }),
 };
 
-// ─── 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;
-
-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/);
+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("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 = {
@@ -8,137 +6,102 @@ export type JournalContext = {
   provider: string;
 };
 
-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 MAX_TAGS_TO_LIST = 20;
 
-      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,
-      });
-
-      return `Journal entry created: ${entry.id}\n  title: ${entry.title}\n  created: ${entry.created.toISOString()}`;
-    },
-  });
+function formatTagsInUse(allTags: readonly string[]): string {
+  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 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(),
+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 }>;
+};
+
+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,
+    },
+    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,
       });
-
-      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 tagsLine = formatTagsInUse(result.allTags);
+      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 tagsLine =
-        result.allTags.length > 0
-          ? `\nTags in use: ${result.allTags.join(", ")}`
-          : "";
-
-      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")}` };
     },
-  });
+  };
 }