Repository navigation
Description
🤖 Kelos Strategist Agent @gjkim42
Latest verdict
- Status:
VALID - Checked at:
2026-11-21T12:02:19Z - Evidence: The gap still reproduces on Kanon's default branch. Since the
2026-11-21T00:04:00Zcheck, no stable Codex or OpenCode release has shipped, and no upstream change touches a contract this design depends on. The body below is unchanged.- Kanon: the default branch is still
d37d7e6. There are no new commits, PRs, or hook issues, and every anchor in "Current product gap" still matches. I ran a freshmake buildwith Go 1.27.4, then ran the Reproduction config plus atargets: [codex]hook withtype: http, using an emptyHOMEand--home <source>:kanon validateprintedkanon.yaml is valid.and exited 0, with no warning.kanon render --agent codexandkanon apply --agent codex --yesboth exited 0 and wroteNotification,"args": ["--deny", "rm -rf"], and a bare{"type": "http"}handler into~/.codex/hooks.json. Claude still receivedargsnatively.kanon render --agent opencodeprintedNo target files.in user scope and with--project <dir>, even for thetargets: [opencode]hook.kanon apply --agent opencode --yesprintedNo changes.and created no~/.config/opencode.
- Codex: the latest stable release is still
rust-v0.171.0. The prereleaserust-v0.173.0-alpha.4(2026-11-21T00:35:19Z) andmainat1145028change no file undercodex-rs/hooks,hooks.rs,hook_config.rs, orcommand_runner.rs. The onlydiscoverymatches are the TUI'sagents_overview_discovery.rsand an MCP test. TheonFailurenote in "External contracts" still applies as written. - OpenCode: no new releases. npm
latestis still1.19.6foropencode-aiand2.3.2for@opencode/cliand@opencode/plugin. Homebrew Core'sopencodeformula is still at52478b1(v2.3.2).devmoved toba5bbefwith 32 new commits. Seven of the eight cited files are unchanged.tool/plugin/shell.tschanged only in #65346, which names the machine in missing-workdir errors, and #65365, which adds akilledfield to the structured result. The tool is stillexport const name = "shell".- Changes to
plugin/supervisor.tsand the plugins doc affect only auto-updates of package plugins (ranges and Git branches now self-update). Auto-discovered localplugins/files, which this design uses, are unaffected.
- Claude Code: the hooks reference still says that with
args,command"is resolved as an executable and spawned directly withargsas the argument vector, with no shell involved". It still lists thecommand,http,mcp_tool,prompt, andagenthandler types. - Maintainer config: gjkim42/kanon-repo is still at
76faf46.kanon.yamlis still blob538e558, with the same five untargeted hooks. - Overlap and alternatives:
- #7, #33, #85, #22, and #68 have had no activity. #101 (updated
2026-11-21T09:00:38Z) covers only a missingkanon.yaml. No other open issue or PR covers hooks. - This is still the only strategist proposal left open with
triage-acceptedafter the maintainer closed the rest as not planned on2026-08-08(for example #94, #98, and #99). Kanon's code hasn't changed, so no stronger candidate emerged.
- #7, #33, #85, #22, and #68 have had no activity. #101 (updated
- Kanon: the default branch is still
Area: New Managed-Settings Types & CLI Extensions
Summary
Hooks are the only top-level managed setting that doesn't reach every shipped agent, and they don't render faithfully where they do. Kanon writes every neutral hook into Codex's hooks.json verbatim, and never renders hooks for OpenCode. The result: shared hooks silently behave differently per agent, and validate/render/diff/apply all succeed.
Proposal: give each adapter an explicit hook capability table. Render a hook only where the agent can run it as written, translate faithfully where possible, and report every omission. Use the same table to add OpenCode hook rendering through one generated local plugin that loads on both OpenCode 1 and OpenCode 2. kanon.yaml needs no schema change.
Why this candidate
- It is the maintainer's own workflow. gjkim42/kanon-repo syncs five untargeted tmux-status hooks (
Stop,Notification,PreToolUse,SessionEnd,UserPromptSubmit). Today Codex ignores theNotificationone, and OpenCode gets none of them. - Silent safety degradation. A
PreToolUseguard written withargs(Claude's exec form) runs in Codex without its arguments, because Codex drops the unknownargskey. - One bad entry disables every Codex hook. Kanon passes
typethrough unchecked. Codex parses the whole file with serde, so one unsupported handler type fails the parse, and Codex skips the entire file with a startup warning. - It completes the provider the maintainer just shipped. #89 added OpenCode for instructions, MCP, and skills. Hooks are the remaining managed type, and
targets: [opencode]is already accepted for hooks without producing anything. - Small, backward-compatible, testable. No new YAML, no network, no new command. Existing Claude output is unchanged.
Reproduction (d37d7e6)
version: 1
hooks:
- name: notification-1
event: Notification
type: command
command: bash -c 'tmux set-window-option window-status-style "bg=yellow"'
- name: guard-bash
event: PreToolUse
matcher: Bash
type: command
command: /usr/local/bin/guard
args: ["--deny", "rm -rf"]
- name: opencode-only
event: Stop
targets: [opencode]
type: command
command: notify-send donekanon validate prints kanon.yaml is valid. and kanon render exits 0, but:
~/.codex/hooks.jsoncontainsNotification, which is not a Codex event, so Codex ignores it.~/.codex/hooks.jsoncontains"args": ["--deny", "rm -rf"]. Codex ignores it and runs/usr/local/bin/guardwith no arguments.- Nothing is rendered for OpenCode, including the hook explicitly targeted at
opencode. - A separate
type: httphook (no URL) also validates and is written tohooks.json. Per Codex's parser, that file then fails to parse and every Codex hook in it is dropped.
Current product gap
Hookhas one neutral shape.hooksForAgentemits the same event/handler map for every agent, filtered only bytargets.- The Codex adapter writes that map to
hooks.jsonwith no event, type, or field check. - The OpenCode adapter renders instructions,
opencode.jsonMCP, and skills only. - Hook validation checks only the name and target names.
- A warning channel already exists:
validateprintswarning: …lines for lock state.
External contracts
Codex (pinned at rust-v0.167.2. The hook types live in codex-rs/protocol/src/hooks.rs, and codex-rs/config/src/hook_config.rs re-exports them. Both files are byte-identical through the latest stable release, rust-v0.171.0. The cited discovery.rs and command_runner.rs are byte-identical through rust-v0.170.0. rust-v0.171.0 changes them only for bundled-plugin hooks, model-request lifecycles, and MCP post-hook pricing. The cited parse-failure path (discovery.rs#L411-L419) and shell path (command_runner.rs#L448-L463) are unchanged):
hooks.jsonaccepts exactlyPreModelRequest,PostModelRequest,PreToolUse,PermissionRequest,PostToolUse,PreCompact,PostCompact,SessionStart,SessionEnd,UserPromptSubmit,SubagentStart,SubagentStop,Stop, andInterrupt(HookEventsToml).PreModelRequestandPostModelRequesthooks only observe the request (#55144). On these events, Codex logs a hook's stdout and never treats it as a control directive (model_request.rs#L286). Fromrust-v0.171.0, a successful synchronousmcp_toolPostModelRequesthook can also report a rollout-budget price throughstructuredContent(#61580, model_request.rs#L302-L328). Command hooks never carry structured content (command_runner.rs#L271), so every handler Kanon would write for these events is observe-only. Unknown event keys are ignored because only the top-levelHooksFileusesdeny_unknown_fields.- Handler variants are
command(fieldscommand,commandWindows,timeout,async,statusMessage,additionalContextLimit) andmcp_tool.promptandagentare parsed but skipped. Any othertypeis a parse error (HookHandlerConfig). Prereleaserust-v0.173.0-alpha.3adds an optionalonFailurefield tocommandandmcp_tool, with valuescontinue(the default) orblock(#62831). Kanon doesn't write it, so its handlers keep the defaultcontinue. - Command hooks run through a shell, as
<shell> -lc <command>on Unix (command runner). - Codex asks the user to review and trust non-managed hooks before they run (docs).
Claude Code: command hooks accept args, which switches to exec form with no shell (hooks reference). Kanon's neutral shape mirrors Claude's today.
OpenCode 1 (opencode-ai@1.18.35, tag 4ac0d9c; plugin files byte-identical in npm latest 1.19.6):
- Local plugins are auto-loaded from
{plugin,plugins}/*.{ts,js}under the global and project config directories (loader), i.e.~/.config/opencode/plugins/and.opencode/plugins/(docs). - A default export with
idand aserverfunction is loaded as a module plugin. The loader returns that object without checking for other keys, and path plugins must exportid. serverreturns theHooksobject:event(includingsession.createdandsession.idle),chat.message,tool.execute.before, andtool.execute.after. Throwing fromtool.execute.beforeblocks the tool call.- The shell tool's ID stays
bashin OpenCode 1, for compatibility with existing plugins and saved permissions.
OpenCode 2 (@opencode/cli@2.0.26, default branch since 2026-10-10, pinned at 823ac87 unless noted):
- OpenCode 1 and 2 both install the
opencodecommand and use the same config locations. V1 plugin implementations do not run in V2. - Local plugins are still auto-discovered from
plugin/andplugins/. The default export must decode as{ id, effect }or{ id, setup }. - Discovery and config entries are handled differently (pinned at
v2.1.4):- Auto-discovered
.jsand.tsfiles load as file entrypoints. - A local path listed under the
pluginsconfig key must be a directory. A file path there is skipped with a warning (plugin migration guide).
- Auto-discovered
- Hooks are registered in
setup, per the V1-to-V2 hook map:event→ctx.event.subscribe(), which still carriessession.idleandsession.createdchat.message→ctx.session.hook("prompt")tool.execute.beforeandtool.execute.after→ctx.tool.hook("execute.before")andctx.tool.hook("execute.after"). Onlyexecute.beforemay fail, which rejects the call. From@opencode/cli2.0.29 (#55263), a rejectedexecute.beforecallback in asetupplugin fails only that call, with its own message (adapter.ts#L637-L643). In earlier 2.0.x releases, every call rejected in a parallel batch showed the first hook's message.
- The Bun
$helper is not provided in V2. - The shell tool is named
shellin2.0.32through2.3.0,v2.3.1, andv2.3.2, and theexecute.beforeevent carriestoolandinput. The docs useshellsince #56922.
Proposal
1. Per-adapter hook capability table
Each adapter declares what it can render: supported events, handler types, matcher support, and how args is represented. Rendering and validation both read from this table, so they can't disagree. Claude keeps full passthrough in the MVP.
| Claude | Codex | OpenCode (MVP) | |
|---|---|---|---|
| Events | passthrough | the events of the latest stable Codex release (the 14 listed above) | SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop |
Handler type |
passthrough | command |
command |
matcher |
yes | yes | no (the shell tool is Bash in Claude and Codex, bash in OpenCode 1, and shell in OpenCode 2) |
args |
native exec form | POSIX-quoted into command |
exec form in the plugin |
timeout, async |
native | native | enforced by the plugin |
The Codex row tracks the latest stable Codex release. Codex ignores unknown event keys. So if a newer Codex release adds an event before Kanon's row includes it, an implicit-target hook for that event is left out with a warning, and the rest of hooks.json still loads.
2. Explicit versus implicit targets
- Explicit target (
targetsnames the agent) plus an unsupported capability: a validation error that names the hook, the agent, and the unsupported event, type, or field. Examples:hook "guard" targets opencode but event "Notification" is not supported for opencode, orhook "audit" targets codex but type "http" is not supported for codex.render,diff, andapplyalready run validation, so they fail the same way. - Implicit target (
targetsomitted orall): the hook is left out for that agent.validate,render,diff, andapplyprint a warning to stderr naming the hook, the agent, and the reason. Existing configs, including the maintainer's, stay valid, and nothing is dropped silently. Users silence the warning by statingtargets.
3. Faithful Codex translation
- Never write a handler type Codex can't run, so one entry can't disable the others.
- Never write an event key Codex ignores.
- Render
command+argsas one command line, POSIX single-quoting each element, because Codex runscommandthrough<shell> -lc. This preserves the argument vector on POSIX-compatible shells; document that assumption. - Output for hooks that are already valid (supported event,
commandtype, noargs) stays byte-identical.
4. OpenCode hooks through one generated plugin for OpenCode 1 and 2
OpenCode is mid-transition. opencode-ai@1.19.6 is npm latest and keeps 1.x installs on the 1.x line. Moving to OpenCode 2 is an explicit choice. It happens through the 2.0 offer in the TUI's /update, through opencode upgrade --major, or, from v1.19.6, through the desktop app's upgrade card (#64153). That card warns that plugins made for OpenCode 1 break. OpenCode 2 ships as @opencode/cli and is now the default branch. The OpenCode README's install script, npm, and tap commands now install OpenCode 2 (#56839): opencode.ai/v2/install, @opencode/cli, and anomalyco/tap/opencode-v2. Homebrew Core's opencode formula also installs OpenCode 2 (v2.3.2). npm opencode-ai and opencode.ai/install still install only OpenCode 1. A fleet synced by Kanon will run both, and both read plugins from the same directories. So the rendered file must load on either version, and must not depend on Kanon detecting which one is installed.
When at least one hook renders for OpenCode, write one Kanon-owned file, replaced whole like other non-merged target files:
- user scope:
~/.config/opencode/plugins/kanon-hooks.js - project scope (
--project):<project>/.opencode/plugins/kanon-hooks.js
The file:
- Is loaded only through
plugins/directory auto-discovery. Kanon does not list it under thepluginorpluginsconfig key, because OpenCode 2 skips configured local file paths. - Is a single file, not a plugin directory. OpenCode 1 auto-loads only
*.{ts,js}files directly underplugins/. OpenCode 2 auto-loads both files and directories there, although its plugin guide shows the directory layout and its loader calls single files legacy. - Default-exports one plain object,
{ id: "kanon-hooks", server, setup }. OpenCode 1 seesid+serverand callsserver, which returns the V1Hooksobject. OpenCode 2 decodes the default export as{ id, setup }and callssetup, which registers the same handlers throughctx. Both entrypoints share one dispatch function and one data table. - Returns nothing from
setup, and never returnsserver'sHooksobject there. Throughv2.2.7, OpenCode 2 calls any truthysetup()return value as a cleanup (adapter.ts#L666-L669). On those versions, a returned object throwsTypeErroron every unload, aborts the plugin swap, and leaves custom agents and commands unregistered until restart. #63548 fixed this inv2.3.0, which calls only a function return as a cleanup (adapter.ts#L673-L677) and logs a failing finalizer instead of aborting the swap. A fleet synced by Kanon can still run 2.0.x–2.2.x, so the constraint stays. - Calls
ctx.event.subscribe()with no arguments insetupand filters forsession.createdandsession.idleitself. The{ types }filter exists only from@opencode/cli2.2.0 (#58864), andsubscribe()with no arguments returns every public event both before and after that change. - Imports only Node built-ins (
node:child_processto spawn commands). It does not import@opencode-ai/pluginor@opencode/plugin, because nothing resolves packages from a bare config directory. It does not use Bun$, because V2 doesn't provide it. - Embeds hook commands only as JSON string data, never spliced into JavaScript source.
- Is deterministic, so
kanon renderandkanon diffshow exactly what will run.
| Kanon event | OpenCode 1 (server) |
OpenCode 2 (setup) |
Exit status |
|---|---|---|---|
SessionStart |
event → session.created |
ctx.event.subscribe() → session.created |
observe-only |
UserPromptSubmit |
chat.message |
ctx.session.hook("prompt") |
observe-only |
PreToolUse |
tool.execute.before |
ctx.tool.hook("execute.before") |
exit code 2 blocks by throwing with the hook's stderr |
PostToolUse |
tool.execute.after |
ctx.tool.hook("execute.after") |
observe-only |
Stop |
event → session.idle |
ctx.event.subscribe() → session.idle |
observe-only |
Runtime contract, documented in the README:
- Commands run with
sh -c, or directly as exec form whenargsis set. - The hook receives a JSON object on stdin with these fields:
hook_event_name(the Kanon event),session_id, andcwd- for tool events,
tool_name(the OpenCode tool ID, passed through as is, so the shell tool arrives asbashon OpenCode 1 andshellon OpenCode 2) andtool_input(from V1output.argsor V2event.input)
timeoutis in seconds and kills the process when exceeded.async: trueis not awaited.- Observe-only events are listed as such, so no one expects Claude-style prompt blocking.
The maintainer's config would render Stop, PreToolUse, and UserPromptSubmit for OpenCode, with warnings for Notification and SessionEnd. It would render every hook except Notification for Codex, with a warning.
Smaller first PR, if preferred: land §1–3 with OpenCode declared hook-unsupported. An explicit targets: [opencode] hook then fails validation and implicit hooks warn, which already ends the silent no-op. §4 can then land as a follow-up that adds the OpenCode column above.
5. kanon.yaml compatibility
No schema change. Every existing config still loads. Claude output is unchanged. Codex output changes only where Codex was already ignoring or rejecting what Kanon wrote. New output appears only under the OpenCode plugin path.
Acceptance criteria
- Configs whose hooks are all supported render byte-identically for Claude and Codex.
- An implicit-target
Notificationhook is left out of Codexhooks.json, a warning names the hook,codex, and the event, and Claude still receives the hook. - An explicit target with an unsupported event, handler type, or matcher fails
kanon validate(and thereforerender/diff/apply) with an error naming the hook, the agent, and the capability. - No handler type other than
commandis ever written to Codexhooks.json. - A Codex hook with
argsrenders a single quoted command whose POSIX-shell word splitting reproduces the original argv, tested with arguments containing spaces and single quotes. - User and project scopes render
plugins/kanon-hooks.jsfor the MVP OpenCode events.targets: [opencode]with a supported event renders. No plugin file is rendered when no hook targets OpenCode. - Golden tests pin the generated plugin, including the
export default { id, server, setup }shape, asetupthat returnsundefined, Node-built-in-only imports, and JSON-escaped commands. The PR records manual runs onopencode-ai@1.19.6and@opencode/cli@2.3.2(or the then-current releases of each). Each run shows aStophook firing and aPreToolUsehook blocking with exit code2. The OpenCode 2 run also shows two parallel blocked calls, each reporting its own hook's stderr. - The README documents the per-agent hook support table and the OpenCode stdin/exit-code contract, including that the plugin targets both OpenCode 1 and 2 and that
tool_namefor the shell tool differs between them (bashversusshell). make verifypasses.
Suggested MVP
- Add per-adapter hook capability data and one
hookSupport(hook, agent)check ininternal/core. - Use it in
ValidateConfigfor explicit targets, in aHookRenderWarningshelper for implicit targets, and inhooksForAgentfiltering. - Add Codex handler shaping for
argsquoting. - Add the OpenCode plugin renderer and destinations in
opencode.go. - Print hook warnings from
validate,render,diff, andapplyin the same style as lock warnings. - Add tests for the criteria above.
Non-goals and related work
- New handler types (HTTP, prompt, agent, MCP-tool fields) stay out; #99 was closed. This proposal only stops Kanon from writing handlers an agent can't run.
- Managed hook scripts/assets stay out; #31 was closed.
- Installed-client version probing belongs to #85. The dual-entrypoint plugin avoids needing it for OpenCode 1 versus 2. This table is static per adapter; Add agent compatibility checks for version-gated native settings #85 could later use it as its hook feature source.
- Native OpenCode 2 config shapes (for example
mcp.servers) stay out. OpenCode 2 reads the V1opencode.jsonshape Kanon already writes. - Claude event allowlist or typo detection is out of scope (see closed #15); Claude stays passthrough.
- Codex trust automation is out of scope. Kanon must not write Codex hook trust hashes; each machine still reviews changed hooks in
/hooks. The existingconfig.tomlmerge already preserves unmanaged fields. - Codex managed and environment-scoped hooks (requirements-level
managed_dir, environment attachments) are out of scope. Kanon writes only the user-levelhooks.json. - OpenCode 2 managed plugin policy is out of scope. A managed
plugin.usedeny (fromv2.2.3; before that,integration.usewith aplugin:resource) blocks the generated plugin. Kanon does not read or write managed policy, so the README should say that such a policy disables OpenCode hooks. - Follow-ups once the MVP payload contract is proven: OpenCode matchers,
Notification/SessionEndmappings, importing OpenCode plugins, and aStopmapping that can keep an OpenCode 2 session running through the experimentalexperimental.idlesession hook (added in 2.2.1 by #59437). - Pruning stale files is out of scope. Under the stateless design (README), removing every OpenCode hook leaves the last applied plugin in place, just as Codex
hooks.jsonand the Claudehookssection behave today. - Future adapters (#7, open #22) gain one place to declare hook support instead of inheriting Claude's shape by default. Add Gemini CLI render adapter with explicit agents opt-in #22's Gemini-only
geminiHookItemcheck would become that adapter's row in the table.
Activity
[-]Add rollout channels for staged Git-based Kanon source updates[/-][+]Resolve and lock MCP servers from official and private registries[/+][-]Resolve and lock MCP servers from official and private registries[/-][+][kanon-fake-strategist] Resolve and lock MCP servers from official and private registries[/+][-][kanon-fake-strategist] Resolve and lock MCP servers from official and private registries[/-][+][kanon-fake-strategist] Resolve and lock remote MCP servers from compatible registries[/+][-][kanon-fake-strategist] Resolve and lock remote MCP servers from compatible registries[/-][+][kanon-fake-strategist] Render hooks per agent capability and add OpenCode hook support[/+]