refactor(commands): unify parsed-intent execution axis

- Converge execution flow to parse/build -> bind_action_context -> dispatch.execute
- Keep parse pure by returning ParsedIntent without execute injection
- Route API/keymap/slash through build_parsed_intent + execute_parsed_intent
- Add runtime dispatch hook register/unregister with command filters
- Fix keymap table-arg mutation leak and normalize invalid permission subcommands
- Update type/event annotations and add axis/mapping regression tests

Author: jensenojs

lua/opencode/api.lua

@@ -1,4 +1,4 @@
-local dispatch = require('opencode.commands.dispatch')
+local commands = require('opencode.commands')
 local window = require('opencode.commands.handlers.window').actions
 local session = require('opencode.commands.handlers.session').actions
 local diff = require('opencode.commands.handlers.diff').actions
@@ -7,119 +7,142 @@ local workflow = require('opencode.commands.handlers.workflow').actions
 local permission = require('opencode.commands.handlers.permission').actions
 local agent = require('opencode.commands.handlers.agent').actions
 
--- Routes an action through the dispatch pipeline so lifecycle hooks fire.
--- TODO: hooks (on_command_before/after/error/finally) are not yet in config
--- defaults — activate them when the event unification work lands.
-local function via_dispatch(action_fn, ...)
-  local args = { ... }
-  return dispatch.dispatch_intent({
-    ok = true,
-    intent = { execute = function() return action_fn(unpack(args)) end, args = {}, range = nil },
-  }).result
+-- Route API actions through the same command execution axis.
+---@param hook_key? string
+local function dispatch_action(name, action_fn, hook_key, ...)
+  local parsed = commands.build_parsed_intent(name, vim.deepcopy({ ... }))
+  if hook_key and parsed and parsed.ok and parsed.intent then
+    parsed.intent.hook_key = hook_key
+  end
+
+  return commands.execute_parsed_intent(parsed, function(resolved_args)
+    return action_fn(unpack(resolved_args or {}))
+  end)
 end
 
 ---@type OpencodeCommandApi
 local M = {}
 
--- All dispatch-wrapped actions. Generated into M via the loop below.
--- Read-only queries (get_window_state, with_header, current_model) are defined after.
--- stylua: ignore
-local actions = {
-  -- window
-  swap_position              = window.swap_position,
-  toggle_zoom                = window.toggle_zoom,
-  toggle_input               = window.toggle_input,
-  open_input                 = window.open_input,
-  open_output                = window.open_output,
-  close                      = window.close,
-  hide                       = window.hide,
-  toggle_pane                = window.toggle_pane,
-  focus_input                = window.focus_input,
-  cancel                     = window.cancel,
-  toggle_focus               = window.toggle_focus,    -- (new_sess)
-  toggle                     = window.toggle,          -- (new_sess)
-  -- session
-  open_input_new_session              = session.open_input_new_session,
-  select_child_session                = session.select_child_session,
-  share                               = session.share,
-  unshare                             = session.unshare,
-  initialize                          = session.initialize,
-  timeline                            = session.timeline,
-  redo                                = session.redo,
-  select_session                      = session.select_session,              -- (parent_id)
-  compact_session                     = session.compact_session,             -- (s)
-  open_input_new_session_with_title   = session.open_input_new_session_with_title, -- (title)
-  rename_session                      = session.rename_session,              -- (s, title)
-  undo                                = session.undo,                        -- (msg_id)
-  fork_session                        = session.fork_session,                -- (msg_id)
-  -- diff
-  diff_next                      = diff.diff_next,
-  diff_prev                      = diff.diff_prev,
-  diff_close                     = diff.diff_close,
-  diff_revert_all_last_prompt    = diff.diff_revert_all_last_prompt,
-  diff_revert_this_last_prompt   = diff.diff_revert_this_last_prompt,
-  set_review_breakpoint          = diff.set_review_breakpoint,
-  diff_open                      = diff.diff_open,                   -- (from, to)
-  diff_revert_all                = diff.diff_revert_all,             -- (snap)
-  diff_revert_selected_file      = diff.diff_revert_selected_file,   -- (s, t)
-  diff_restore_snapshot_file     = diff.diff_restore_snapshot_file,  -- (id)
-  diff_restore_snapshot_all      = diff.diff_restore_snapshot_all,   -- (id)
-  diff_revert_this               = diff.diff_revert_this,            -- (snap)
-  -- workflow
-  paste_image             = workflow.paste_image,
-  select_history          = workflow.select_history,
-  prev_history            = workflow.prev_history,
-  next_history            = workflow.next_history,
-  prev_prompt_history     = workflow.prev_prompt_history,
-  next_prompt_history     = workflow.next_prompt_history,
-  next_message            = workflow.next_message,
-  prev_message            = workflow.prev_message,
-  mention_file            = workflow.mention_file,
-  mention                 = workflow.mention,
-  context_items           = workflow.context_items,
-  slash_commands          = workflow.slash_commands,
-  references              = workflow.references,
-  debug_output            = workflow.debug_output,
-  debug_message           = workflow.debug_message,
-  debug_session           = workflow.debug_session,
-  toggle_tool_output      = workflow.toggle_tool_output,
-  toggle_reasoning_output = workflow.toggle_reasoning_output,
-  submit_input_prompt     = workflow.submit_input_prompt,
-  run                     = workflow.run,              -- (prompt, opts)
-  run_new_session         = workflow.run_new_session,  -- (prompt, opts)
-  quick_chat              = workflow.quick_chat,       -- (msg, range)
-  run_user_command        = workflow.run_user_command, -- (name, args)
-  review                  = workflow.review,           -- (args, range)
-  add_visual_selection        = workflow.add_visual_selection,        -- (opts, range)
-  add_visual_selection_inline = workflow.add_visual_selection_inline, -- (o, r)
-  -- surface
-  help          = surface.help,
-  mcp           = surface.mcp,
-  commands_list = surface.commands_list,
-  -- permission
-  question_answer       = permission.question_answer,
-  question_other        = permission.question_other,
-  respond_to_permission = permission.respond_to_permission, -- (answer, perm)
-  permission_accept     = permission.permission_accept,     -- (perm)
-  permission_accept_all = permission.permission_accept_all, -- (perm)
-  permission_deny       = permission.permission_deny,       -- (perm)
-  -- agent
-  configure_provider = agent.configure_provider,
-  configure_variant  = agent.configure_variant,
-  cycle_variant      = agent.cycle_variant,
-  agent_plan         = agent.agent_plan,
-  agent_build        = agent.agent_build,
-  select_agent       = agent.select_agent,
-  switch_mode        = agent.switch_mode,
+local action_groups = {
+  window = {
+    swap_position = window.swap_position,
+    toggle_zoom = window.toggle_zoom,
+    toggle_input = window.toggle_input,
+    open_input = window.open_input,
+    open_output = window.open_output,
+    close = window.close,
+    hide = window.hide,
+    toggle_pane = window.toggle_pane,
+    focus_input = window.focus_input,
+    cancel = window.cancel,
+    toggle_focus = window.toggle_focus,
+    toggle = window.toggle,
+  },
+
+  session = {
+    open_input_new_session = session.open_input_new_session,
+    select_child_session = session.select_child_session,
+    share = session.share,
+    unshare = session.unshare,
+    initialize = session.initialize,
+    timeline = session.timeline,
+    redo = session.redo,
+    select_session = session.select_session,
+    compact_session = session.compact_session,
+    open_input_new_session_with_title = session.open_input_new_session_with_title,
+    rename_session = session.rename_session,
+    undo = session.undo,
+    fork_session = session.fork_session,
+  },
+
+  diff = {
+    diff_next = diff.diff_next,
+    diff_prev = diff.diff_prev,
+    diff_close = diff.diff_close,
+    diff_revert_all_last_prompt = diff.diff_revert_all_last_prompt,
+    diff_revert_this_last_prompt = diff.diff_revert_this_last_prompt,
+    set_review_breakpoint = diff.set_review_breakpoint,
+    diff_open = diff.diff_open,
+    diff_revert_all = diff.diff_revert_all,
+    diff_revert_selected_file = diff.diff_revert_selected_file,
+    diff_restore_snapshot_file = diff.diff_restore_snapshot_file,
+    diff_restore_snapshot_all = diff.diff_restore_snapshot_all,
+    diff_revert_this = diff.diff_revert_this,
+  },
+
+  workflow = {
+    paste_image = workflow.paste_image,
+    select_history = workflow.select_history,
+    prev_history = workflow.prev_history,
+    next_history = workflow.next_history,
+    prev_prompt_history = workflow.prev_prompt_history,
+    next_prompt_history = workflow.next_prompt_history,
+    next_message = workflow.next_message,
+    prev_message = workflow.prev_message,
+    mention_file = workflow.mention_file,
+    mention = workflow.mention,
+    context_items = workflow.context_items,
+    slash_commands = workflow.slash_commands,
+    references = workflow.references,
+    debug_output = workflow.debug_output,
+    debug_message = workflow.debug_message,
+    debug_session = workflow.debug_session,
+    toggle_tool_output = workflow.toggle_tool_output,
+    toggle_reasoning_output = workflow.toggle_reasoning_output,
+    submit_input_prompt = workflow.submit_input_prompt,
+    run = workflow.run,
+    run_new_session = workflow.run_new_session,
+    quick_chat = workflow.quick_chat,
+    run_user_command = workflow.run_user_command,
+    review = workflow.review,
+    add_visual_selection = workflow.add_visual_selection,
+    add_visual_selection_inline = workflow.add_visual_selection_inline,
+  },
+
+  surface = {
+    help = surface.help,
+    mcp = surface.mcp,
+    commands_list = surface.commands_list,
+  },
+
+  permission = {
+    question_answer = permission.question_answer,
+    question_other = permission.question_other,
+    respond_to_permission = permission.respond_to_permission,
+    permission_accept = permission.permission_accept,
+    permission_accept_all = permission.permission_accept_all,
+    permission_deny = permission.permission_deny,
+  },
+
+  agent = {
+    configure_provider = agent.configure_provider,
+    configure_variant = agent.configure_variant,
+    cycle_variant = agent.cycle_variant,
+    agent_plan = agent.agent_plan,
+    agent_build = agent.agent_build,
+    select_agent = agent.select_agent,
+    switch_mode = agent.switch_mode,
+  },
+
+  query = {
+    get_window_state = window.get_window_state,
+    current_model = agent.current_model,
+    with_header = surface.with_header,
+  },
 }
 
-for name, fn in pairs(actions) do
-  M[name] = function(...) return via_dispatch(fn, ...) end
+---@param group_name string
+---@param exports table<string, function>
+local function register_exports(group_name, exports)
+  for name, fn in pairs(exports) do
+    M[name] = function(...)
+      return dispatch_action(name, fn, group_name, ...)
+    end
+  end
 end
 
--- Read-only queries: bypass dispatch, no side effects
-function M.get_window_state() return window.get_window_state() end
-function M.current_model() return agent.current_model() end
-function M.with_header(lines, show_welcome) return surface.with_header(lines, show_welcome) end
+for group_name, exports in pairs(action_groups) do
+  register_exports(group_name, exports)
+end
 
 return M

lua/opencode/commands/AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md (commands)
+
+This directory defines the command execution pipeline.
+
+## Scope
+
+- Parse command input into structured intent (`parse.lua`)
+- Bind intent to executable action (`init.lua`)
+- Execute lifecycle (`dispatch.lua`)
+- Wire slash/keymap/API into the same axis
+
+## Hard Invariants
+
+- Single execution entry: `dispatch.execute(ctx)`
+- Single bind point: `commands.bind_action_context(...)`
+- `parse.lua` does not bind execute functions
+- No `dispatch.run`, no `route.execute`, no fake parse wrapper
+
+## Hook Model
+
+- Stage hooks: `before`, `after`, `error`, `finally`
+- Global hook: no command filter (`command = '*'` or omitted)
+- Command-scoped hook: `command = 'run'` or `{'run','review'}`
+- Keep hook handlers side-effect aware and idempotent
+
+## Expected Execution Shape
+
+```text
+entry (:Opencode | keymap | API | slash)
+  -> parse/build intent
+  -> bind_action_context (single bind point)
+  -> dispatch.execute (single execute point)
+  -> hooks(before/after/error/finally)
+```
+
+## Editing Rules
+
+- Prefer deleting duplicated glue code over adding adapters
+- Keep error normalization in `dispatch.lua`
+- Keep notify behavior unchanged unless explicitly requested
+- Do not split semantics by entry (`:Opencode` / keymap / API / slash)
+
+## Allow / Disallow Examples
+
+- Allowed:
+  - entry adapters call `commands.build_parsed_intent(...)` + `commands.execute_parsed_intent(...)`
+  - infra changes that keep `dispatch.execute(ctx)` as the single execute entry
+- Disallowed:
+  - fallback branches such as `if commands.execute_parsed_intent then ... else ...`
+  - building action context outside `commands.bind_action_context(...)`
+  - adding per-entry behavior forks (`if source == 'keymap' then ...`)
+
+## Quick Review Checklist
+
+- Does new code bypass `dispatch.execute`?
+- Does new code create a second bind path?
+- Does parse start carrying execute logic again?
+- Are hook semantics consistent for all entries?
+
+## Reject Conditions
+
+- Any new execute entry besides `dispatch.execute`
+- Any new bind path besides `bind_action_context`
+- Parse starts binding execute functions again
+
+## Minimal Regression Commands
+
+- `./run_tests.sh -t tests/unit/commands_dispatch_spec.lua`
+- `./run_tests.sh -t tests/unit/commands_parse_spec.lua`
+- `./run_tests.sh -t tests/unit/commands/command_axis_spec.lua`
+- `./run_tests.sh -t tests/unit/keymap_spec.lua`
+- `./run_tests.sh -t tests/unit/api_spec.lua -f "command routing"`
+
+## Entry Notes For New Agents
+
+- Read `parse.lua`, `init.lua`, `dispatch.lua` in this order before editing.
+- Treat this directory as **execution infrastructure**, not feature surface.
+- If a change needs new behavior, prefer changing handlers first; only touch command infrastructure when all entries must change together.
+- Keep edits local and reversible: no new execution entry, no new bind path, no per-entry semantic split.