[BUG] OpenCode plugin registers experimental.* hooks not present in Plugin API — autoRecall silently broken on 1.16.2

[clayleopardlabs]

Bug Description

The @vectorize-io/opencode-hindsight plugin (tested on v0.2.5 and v0.2.7) registers three hooks that are not part of the @opencode-ai/plugin public Plugin API in OpenCode 1.16.2. OpenCode silently ignores unknown hook names — no error, no warning — so the following features are completely non-functional:

• experimental.chat.system.transform → autoRecall never fires
• experimental.session.compacting → memory injection during compaction never fires
• (The event hook for session.idle autoRetain does work, as it's a supported hook)

This is distinct from the execution-ordering issue described in #1758 item #2 (which was about session.created vs system.transform firing order). The code in v0.2.5+ already implements the #1758 fix (it doesn't depend on session.created), but it doesn't matter — the hook itself is never called.

Environment

Component	Version
OpenCode	1.16.2
@vectorize-io/opencode-hindsight	0.2.5 (also confirmed on 0.2.7)
@opencode-ai/plugin	^1.3.13
OS	Windows 11

Root Cause

The plugin registers hooks using the "experimental." prefix namespace in hindsight-integrations/opencode/src/hooks.ts. These hooks (experimental.chat.system.transform, experimental.session.compacting) are not defined in the @opencode-ai/plugin type definitions.

The Hooks type in @opencode-ai/plugin only exposes: tool, auth, event, config, chat.message, chat.params, permission.ask, tool.execute.before, tool.execute.after. There are no experimental.* entries.

The plugin's own HindsightHooks interface defines these names locally (not imported from the Plugin SDK) and returns them in the hooks object. OpenCode silently discards any hook key it doesn't recognize — these hooks are registered but never invoked.

Impact

Feature	Hook	Status
autoRecall — injects relevant memories at session start	experimental.chat.system.transform	Never called
memory injection during compaction	experimental.session.compacting	Never called
autoRetain — saves conversation on idle events	event (session.idle)	Works (supported hook)

Users are not notified that autoRecall is broken. The plugin loads without errors, logs nothing unusual, and appears to be working — but the hindsight_memories context block never appears in the system prompt.

Steps to Reproduce

1. Install @vectorize-io/opencode-hindsight v0.2.5+ in OpenCode 1.16.2
2. Enable autoRecall: true in plugin config
3. Start a session and chat — no <hindsight_memories> context appears in the system prompt
4. Check plugin logs — no errors or warnings about unrecognized hooks
5. Inspect @opencode-ai/plugin type definitions — confirm experimental.* hooks are absent

Evidence

• hooks.ts source (v0.2.7): https://github.com/vectorize-io/hindsight/blob/integrations/opencode/v0.2.7/hindsight-integrations/opencode/src/hooks.ts
• The @opencode-ai/plugin Hooks type defines only: tool, auth, event, config, chat.message, chat.params, permission.ask, tool.execute.before, tool.execute.after
• The plugin's HindsightHooks interface (hooks.ts lines 71-80) is self-defined, not derived from the Plugin SDK
• OpenCode silently ignores unrecognized hook keys — no error is emitted

Related Issues

• Not work for opencode 1.4.0 #941 ("Not work for opencode 1.4.0") — same observable symptom, closed without resolution
• [BUG] Three integration plugin issues across OpenClaw, OpenCode, and Claude Code #1758 item rename to hindsight #2 — describes execution ordering of session.created vs system.transform (assumes hooks exist but fire in wrong order). The hook-absence issue is a distinct and more fundamental problem.

Suggested Fixes

1. Add experimental.chat.system.transform and experimental.session.compacting to the OpenCode Plugin API — these hooks appear to have been designed but never shipped in the public interface
2. Alternative for autoRecall: Use the supported event hook to detect session creation and trigger initial recall from there
3. Fallback: At minimum, the plugin should detect at startup whether the hooks it depends on are actually available and log a clear warning

[benfrank241]

Thanks for the very thorough write-up — but I think the root cause here is off, and I want to save you (and us) from chasing the wrong fix.

I pulled the actual @opencode-ai/plugin tarballs and read the Hooks type directly. Both hooks the plugin relies on are part of the public Plugin API — in the version the plugin pins and in your runtime:

Hook	@opencode-ai/plugin@1.3.13 (plugin's pinned ^1.3.13)	@1.16.2 (your OpenCode)
experimental.chat.system.transform	present	present
experimental.session.compacting	present	present

And the signatures match exactly what the plugin uses, e.g. from 1.16.2:

"experimental.chat.system.transform"?: (input: {
    sessionID?: string;
    model: Model;
}, output: {
    system: string[];
}) => Promise<void>;

The plugin also registers them correctly — src/index.ts returns { tool, ...hooks }, so those keys really are handed to OpenCode. So the "unknown hook / silently ignored" theory doesn't hold for 1.3.13 or 1.16.2; OpenCode should be calling experimental.chat.system.transform.

That means autoRecall is almost certainly breaking for a different reason. Since event/session.idle retain works for you, we know the plugin loads and OpenCode is invoking its hooks — so this is likely one of:

1. bankId mismatch — retain and recall resolving to different banks (so recall queries an empty bank and injects nothing). Can you share the bank value from the Hindsight plugin initialized log line, and confirm it's the same bank you see memories accumulating in?
2. autoRecall not actually enabled in the resolved config (the hook early-returns on if (!config.autoRecall) return;).
3. Recall returned 0 results — the hook fires but there's nothing to inject, so no <hindsight_memories> block appears. This looks identical to "the hook never fired" from the outside.

Could you enable debug logging ("debug": true in the plugin options) and share what you see around a new session? Specifically whether these fire:

• System transform hook error (would show an exception), and
• Injected recall context for session <id> (would confirm the hook ran and had content).

If the hook runs but you never see Injected recall context, it's #1/#3 (empty/mismatched bank) rather than a missing-hook problem. That'll tell us exactly where to look.

(Separately — good callout on observability. Right now we only log on successful injection, not when the hook fires and recall comes back empty, which is exactly why this is hard to tell apart. I'll add a debug line for the empty-recall case so this class of report is self-diagnosing.)

[clayleopardlabs]

I went back and checked the actual @opencode-ai/plugin types again more carefully. The experimental.* hooks really are in the Plugin API at both v1.3.13 and 1.16.2. You're right! I guess my problem must be one of these:

1. Bank ID mismatch (retain writes to bank A, recall reads bank B)
2. autoRecall not actually enabled at runtime
3. Recall returns 0 results (bank is empty or the query finds nothing)

Unfortunately, I already removed the plugin to test some other memory plugin options. If I reinstall and have the same issue with the automatic recall not working, I'll debug as requested.

[nicoloboschi]

Resolved for the Coding Agents plugin, which supersedes @vectorize-io/opencode-hindsight. Those hook names are part of the current @opencode-ai/plugin API — experimental.chat.system.transform and experimental.chat.messages.transform are both in its shipped type definitions — and the new plugin registers against them, so the silent no-op you hit on 1.16.2 no longer applies.

Welcome to migrate: npx @vectorize-io/hindsight-coding-agents install opencode (docs). The old plugin keeps working, but fixes land on the new one.