refactor(api)!: new format for run/run_new args

As discussed in #84, the previous cmd refactor had broken argument
handling for run/run_new.

The old format had an ambiguity between prompt and context args.

This change is breaking because we no longer support the old format. The
new format is:

:OpencodeRun [agent=<name>] [model=<model>] [context=<overrides>] <prompt>
:OpencodeRunNewSession [agent=<name>] [model=<model>] [context=<overrides>] <prompt>

Author: cameronr

lua/opencode/api.lua

@@ -958,24 +958,24 @@ M.commands = {
   run = {
     desc = 'Run prompt in current session',
     fn = function(args)
-      local prompt = table.concat(args, ' ')
+      local opts, prompt = util.parse_run_args(args)
       if prompt == '' then
         vim.notify('Prompt required', vim.log.levels.ERROR)
         return
       end
-      M.run(prompt)
+      M.run(prompt, opts)
     end,
   },
 
   run_new = {
     desc = 'Run prompt in new session',
     fn = function(args)
-      local prompt = table.concat(args, ' ')
+      local opts, prompt = util.parse_run_args(args)
       if prompt == '' then
         vim.notify('Prompt required', vim.log.levels.ERROR)
         return
       end
-      M.run_new_session(prompt)
+      M.run_new_session(prompt, opts)
     end,
   },
 

lua/opencode/util.lua

@@ -420,4 +420,38 @@ function M.strdisplaywidth(str)
   return vim.fn.strdisplaywidth(str)
 end
 
+--- Parse run command arguments with optional agent, model, and context prefixes.
+--- Returns opts table and remaining prompt string.
+--- Format: [agent=<name>] [model=<model>] [context=<key=value,...>] <prompt>
+--- @param args string[]
+--- @return table opts, string prompt
+function M.parse_run_args(args)
+  local opts = {}
+  local prompt_start_idx = 1
+
+  for i, token in ipairs(args) do
+    local agent = token:match('^agent=(.+)$')
+    local model = token:match('^model=(.+)$')
+    local context = token:match('^context=(.+)$')
+
+    if agent then
+      opts.agent = agent
+      prompt_start_idx = i + 1
+    elseif model then
+      opts.model = model
+      prompt_start_idx = i + 1
+    elseif context then
+      opts.context = M.parse_dot_args(context:gsub(',', ' '))
+      prompt_start_idx = i + 1
+    else
+      break
+    end
+  end
+
+  local prompt_tokens = vim.list_slice(args, prompt_start_idx)
+  local prompt = table.concat(prompt_tokens, ' ')
+
+  return opts, prompt
+end
+
 return M

tests/unit/api_spec.lua

@@ -141,4 +141,77 @@ describe('opencode.api', function()
       })
     end)
   end)
+
+  describe('run command argument parsing', function()
+    it('parses agent prefix and passes to send_message', function()
+      api.commands.run.fn({ 'agent=plan', 'analyze', 'this', 'code' })
+      assert.stub(core.send_message).was_called()
+      assert.stub(core.send_message).was_called_with('analyze this code', {
+        new_session = false,
+        focus = 'output',
+        agent = 'plan',
+      })
+    end)
+
+    it('parses model prefix and passes to send_message', function()
+      api.commands.run.fn({ 'model=openai/gpt-4', 'test', 'prompt' })
+      assert.stub(core.send_message).was_called()
+      assert.stub(core.send_message).was_called_with('test prompt', {
+        new_session = false,
+        focus = 'output',
+        model = 'openai/gpt-4',
+      })
+    end)
+
+    it('parses context prefix and passes to send_message', function()
+      api.commands.run.fn({ 'context=current_file.enabled=false', 'test' })
+      assert.stub(core.send_message).was_called()
+      assert.stub(core.send_message).was_called_with('test', {
+        new_session = false,
+        focus = 'output',
+        context = { current_file = { enabled = false } },
+      })
+    end)
+
+    it('parses multiple prefixes and passes all to send_message', function()
+      api.commands.run.fn({ 'agent=plan', 'model=openai/gpt-4', 'context=current_file.enabled=false', 'analyze', 'code' })
+      assert.stub(core.send_message).was_called()
+      assert.stub(core.send_message).was_called_with('analyze code', {
+        new_session = false,
+        focus = 'output',
+        agent = 'plan',
+        model = 'openai/gpt-4',
+        context = { current_file = { enabled = false } },
+      })
+    end)
+
+    it('works with run_new command', function()
+      api.commands.run_new.fn({ 'agent=plan', 'model=openai/gpt-4', 'new', 'session', 'prompt' })
+      assert.stub(core.send_message).was_called()
+      assert.stub(core.send_message).was_called_with('new session prompt', {
+        new_session = true,
+        focus = 'output',
+        agent = 'plan',
+        model = 'openai/gpt-4',
+      })
+    end)
+
+    it('requires a prompt after prefixes', function()
+      local notify_stub = stub(vim, 'notify')
+      api.commands.run.fn({ 'agent=plan' })
+      assert.stub(notify_stub).was_called_with('Prompt required', vim.log.levels.ERROR)
+      notify_stub:revert()
+    end)
+
+    it('Lua API accepts opts directly without parsing', function()
+      api.run('test prompt', { agent = 'plan', model = 'openai/gpt-4' })
+      assert.stub(core.send_message).was_called()
+      assert.stub(core.send_message).was_called_with('test prompt', {
+        new_session = false,
+        focus = 'output',
+        agent = 'plan',
+        model = 'openai/gpt-4',
+      })
+    end)
+  end)
 end)

tests/unit/util_spec.lua

@@ -26,3 +26,68 @@ describe('util.parse_dot_args', function()
     assert.are.same({}, args)
   end)
 end)
+
+describe('util.parse_run_args', function()
+  it('parses no prefixes', function()
+    local opts, prompt = util.parse_run_args({ 'just', 'a', 'regular', 'prompt' })
+    assert.are.same({}, opts)
+    assert.equals('just a regular prompt', prompt)
+  end)
+
+  it('parses single agent prefix', function()
+    local opts, prompt = util.parse_run_args({ 'agent=plan', 'hello', 'world' })
+    assert.are.same({ agent = 'plan' }, opts)
+    assert.equals('hello world', prompt)
+  end)
+
+  it('parses single model prefix', function()
+    local opts, prompt = util.parse_run_args({ 'model=openai/gpt-4', 'analyze', 'this' })
+    assert.are.same({ model = 'openai/gpt-4' }, opts)
+    assert.equals('analyze this', prompt)
+  end)
+
+  it('parses single context prefix', function()
+    local opts, prompt = util.parse_run_args({ 'context=current_file.enabled=false', 'test' })
+    assert.are.same({ context = { current_file = { enabled = false } } }, opts)
+    assert.equals('test', prompt)
+  end)
+
+  it('parses multiple prefixes in order', function()
+    local opts, prompt = util.parse_run_args({ 'agent=plan', 'model=openai/gpt-4', 'context=current_file.enabled=false', 'prompt', 'here' })
+    assert.are.same({
+      agent = 'plan',
+      model = 'openai/gpt-4',
+      context = { current_file = { enabled = false } }
+    }, opts)
+    assert.equals('prompt here', prompt)
+  end)
+
+  it('parses context with multiple comma-delimited values', function()
+    local opts, prompt = util.parse_run_args({ 'context=current_file.enabled=false,selection.enabled=true', 'test' })
+    assert.are.same({
+      context = {
+        current_file = { enabled = false },
+        selection = { enabled = true }
+      }
+    }, opts)
+    assert.equals('test', prompt)
+  end)
+
+  it('handles empty prompt after prefixes', function()
+    local opts, prompt = util.parse_run_args({ 'agent=plan' })
+    assert.are.same({ agent = 'plan' }, opts)
+    assert.equals('', prompt)
+  end)
+
+  it('handles empty string', function()
+    local opts, prompt = util.parse_run_args({})
+    assert.are.same({}, opts)
+    assert.equals('', prompt)
+  end)
+
+  it('stops parsing at first non-prefix token', function()
+    local opts, prompt = util.parse_run_args({ 'agent=plan', 'some', 'prompt', 'model=openai/gpt-4' })
+    assert.are.same({ agent = 'plan' }, opts)
+    assert.equals('some prompt model=openai/gpt-4', prompt)
+  end)
+end)