fix: align @microsoft/agent-governance-opencode plugin with the actual OpenCode plugin contract

[Alexander Wiedemann (ax0l0tl)]

Description

Aligns the @microsoft/agent-governance-opencode plugin with the OpenCode plugin contract as shipped in the current OpenCode release (1.17.4).

The hook and tool registration shapes are corrected to match the real OpenCode plugin contract (flat string keys, singular tool:, plain string returns from custom tools). The prompt event filter is narrowed to message.part.updated with part.type === "text", which is the only event type that carries user-submitted text (smoked tested via live event log). The other event types handled, do not exist.

The plugin is not really working well, because, if user or agent prompt messages are denied, the exception thrown in the event handler causes the OpenCode user interaction to hang (cursor blinking, never returns), but at least now it does anything.

Type of Change

• Bug fix

Package(s) Affected

• agent-governance-opencode (@microsoft/agent-governance-opencode)

Checklist

• My code follows the project style guidelines (node --check passes on all .mjs files)
• All new and existing tests pass (npm run check: 25/25)
• [] I have signed the Microsoft CLA

Attribution & Prior Art

• This contribution does not contain code copied or derived from other projects without attribution

AI Assistance

• I can explain every meaningful change in this PR: what it does, why, and what tradeoffs were considered
• I have run tests and verification appropriate for this change
• No part of this PR was autonomously submitted by an AI agent without my review

OpenCode (AI coding agent) was used to investigate the real OpenCode plugin contract, identify the mismatches, implement the fixes, and verify via in-session smoke tests of both agt_policy_status and agt_policy_check_text.

IP, Patents, and Licensing

• This contribution does not implement patent-pending or patent-encumbered techniques
• This contribution does not require an NDA or licensing agreement to understand or use
• Any AI tools used have terms compatible with the MIT License

Related Issues

Related: #2658 (original plugin PR)

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[github-actions]

❔ Contributor Check: UNKNOWN

Check	Result
Profile	LOW
Credential	NONE
Overall	UNKNOWN

Automated check by AGT Contributor Check.

[github-actions]

🤖 AI Agent: contributor-guide — Actionable Items:

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Welcome, and thank you for contributing! Great job on aligning the plugin with the OpenCode contract and providing detailed explanations in the PR description.

Actionable Items:

1. The package name has been changed from @`microsoft/agent-governance-opencode` to @ax0l0tl/agent-governance-opencode. Please confirm if this change is intentional and aligns with project guidelines.
2. Ensure the Microsoft CLA is signed before merging.

For guidance, please refer to CONTRIBUTING.md.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

[Alexander Wiedemann (ax0l0tl)]

Alexander Wiedemann (@ax0l0tl) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

Alexander Wiedemann (@ax0l0tl) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

@microsoft-github-policy-service agree company="bluehands"

[Imran Siddique (imran-siddique)]

The core contract realignment is correct and well-reasoned. I verified the claims against the official OpenCode plugin contract (the `@opencode-ai/plugin` Hooks type): hooks are flat string keys (`session.created`, `event`, `tool.execute.before`/`after`), `session.start` and `tool.execute.error` are not real, custom tools belong under the singular `tool` key returning a plain value (not an MCP envelope), and `message.part.updated` with `part.type === "text"` is the correct text-bearing event. The old broad `chat|message|prompt|user` regex matched event types that do not exist. Fail-closed deny/redaction logic is preserved, and the tests are updated to the new shape with good new coverage. Nice work.

Two must-fix items before merge:

1. package-lock.json leaks fork identity. `agent-governance-opencode/package-lock.json` lines 2 and 8 now read `"name": "@ax0l0tl/agent-governance-opencode"` / `"version": "4.0.4"`, while package.json is `@microsoft/agent-governance-opencode` v4.1.0. This looks like an accidental commit of a local `npm install` under your fork name. Please regenerate the lockfile so it reads `@microsoft/agent-governance-opencode` at 4.1.0.

2. Docs describe removed hooks. README.md (around lines 50, 56), docs/packages/opencode-governance.md (around 31, 35), and the JSDoc at src/index.mjs:20 (`event (chat.params/start)`) still document `session.start` / `tool.execute.error` and the old event description. Update them to the new hook set so the docs match the code.

Should-address (non-blocking, can be follow-ups):

• The OpenCode `tool()` contract expects `args` to be a Zod schema, but src/index.mjs:145,154 pass a raw object. Your live smoke test suggests OpenCode tolerates it, but please confirm and ideally add a test exercising registration.
• The removed `tool.execute.error` hook was dead code (never fired), but it was the documented audit path for failed tool calls; that audit coverage is now simply gone. Worth a note or a real replacement.
• Deny currently throws inside the `event` handler which hangs the TUI rather than surfacing the block. The contract's `permission.ask` hook is the correct mechanism for review/deny; consider a follow-up so prompt-level governance is cleanly usable.

Happy to re-review quickly once the lockfile and docs are fixed.

[Imran Siddique (imran-siddique)]

Thanks for the update, but both original blockers are still open:

1. package-lock.json fork identity -- "name": "@ax0l0tl/agent-governance-opencode" and "version": "4.0.4" remain in the lockfile. This needs to be regenerated with the @microsoft scope and version 4.1.0 to match package.json.

To fix: delete package-lock.json, run npm install from the agent-governance-opencode/ directory, then commit the regenerated lockfile.

2. Docs for removed hooks -- session.start, tool.execute.error, tools.agt_policy_status, and tools.agt_policy_check_text were removed or renamed, but no documentation was updated. A brief changelog section in the README or relevant doc file is needed so consumers know what changed.

The inline comment added in the latest commit is a good code note but doesn't address either blocker.

[Imran Siddique (imran-siddique)]

Contract alignment with OpenCode 1.17.4 looks correct. Approving.

[Imran Siddique (imran-siddique)]

/ok-to-test

[Kerberosmansour (kerberosmansour)]

Validated follow-up work from the contract alignment in this PR:

• [Bug]: OpenCode workspace install uses an undiscoverable .mjs shim and stale hook documentation #3707 — the workspace README still uses an auto-discovery extension OpenCode 1.18.16 does not scan, and the README/package reference retain the removed hook names discussed in review here;
• [Feature]: add out-of-band activation evidence for OpenCode governance #3708 — model-independent evidence that the plugin was discovered, initialized, and activated; and
• [Bug]: duplicate OpenCode plugin shims register governance hooks more than once #3709 — duplicate registration when multiple valid workspace shims are present.

Linking these here so the runtime correction, remaining documentation drift, and operational follow-ups stay connected without reopening this merged PR.