[FEATURE]: Let plugins register startup CLI flags

Feature has not been suggested before

• I searched open and closed issues for plugin flags, custom CLI options, argument parsing, and startup hooks.

Describe the enhancement you want to request

Problem

OpenCode V2 rejects unknown root flags before plugins load. Plugins can add commands, tools, routes, and slots, but they cannot add startup CLI options.

This limit forces plugins to use wrapper executables for work that must occur before the TUI starts. A Worktrunk integration is one example.

A slash command cannot replace the wrapper. It runs after OpenCode selects the location and starts the TUI.

The current wrapper must:

1. Remove -w or --worktree from the arguments.
2. Call the native worktree list or create API.
3. Start the real OpenCode executable with the returned directory.

The wrapper must also find the real executable without calling itself. It must track changes to core OpenCode arguments.

Requested API

Let plugins declare root CLI flags before OpenCode validates unknown arguments. Give the parsed values to the plugin before session and TUI startup.

An API could have this form:

ctx.cli.option({
  name: "worktree",
  alias: "w",
  type: "string",
  optionalValue: true,
  description: "Create or select a Worktrunk worktree",
})

ctx.cli.beforeStart(async ({ options, directory }) => {
  if (!options.worktree) return
  const worktree = await createOrSelectWorktree(options.worktree, directory)
  return { directory: worktree.directory }
})

The API shape is only an example. A two-stage parser or a plugin manifest could provide the same behavior.

OpenCode does not need to accept undeclared arguments. The core CLI can keep strict validation after plugin flag registration.

Acceptance criteria

• Configured and local plugins can declare root CLI flags before unknown argument validation.
• Flags can use Boolean, string, optional string, and repeated values.
• OpenCode gives typed flag values to the plugin before session and TUI startup.
• A startup handler can change the directory for the new OpenCode instance.
• Plugin flags appear in --help output and shell completions.
• OpenCode rejects conflicts with core flags or other plugin flags with a clear error.
• OpenCode keeps the current behavior when no plugin declares a flag.
• OpenCode still rejects unknown flags that no plugin declares.

Worktree example

opencode2 -w feature-a
opencode2 --worktree feature-b
opencode2 --worktree

The plugin creates or selects the worktree. OpenCode then starts the session in that worktree without a wrapper executable.

This request does not ask the core CLI to know Worktrunk behavior. The plugin owns that behavior through the proposed API.

Related issues

• #48272 requests the specific --worktree and -w flags.
• #36048 requests worktree commands and session movement.
• #38527 requests another plugin hook that must run during startup.

I found no open or closed issue that requests a general API for plugin CLI flags.

Environment

• OpenCode version: 0.0.0-beta-19151
• Channel: beta
• OS: macOS 26, arm64
• Shell: Zsh
• Workaround: https://github.com/pragmaticivan/dotfiles/pull/30