Skip to content

v2: decide command execution and mention semantics #34847

Open
#52929
Open
v2: decide command execution and mention semantics#34847
#52929
Labels
2.0coreAnything pertaining to core functionality of the application (opencode server stuff)

Description

@rekram1-node
rekram1-node
opened on Jul 2, 2026

Context

The v2 command port intentionally keeps slash commands as prompt-template admission only. The old v1 command path could convert commands into subtasks, and there is a related question of whether commands should be able to automatically background work.

The v1 command path also had prompt-like template affordances such as @agent and @file mentions. Those are intentionally deferred in the v2 command port because prompt submit/attachment behavior needs a clearer native design before commands synthesize extra prompt attachments.

Decision needed

  • Should v2 commands support subtask execution at all, or should that stay owned by explicit subagent/tool flows?
  • If command subtasks are supported, should they use the existing subagent child-session mechanism or a separate command-specific primitive?
  • Should commands be able to request automatic backgrounding, or should backgrounding remain a user/tool/session-level action?
  • Should command templates support @agent mentions, or should commands rely on command metadata (agent) and explicit prompt attachments only?
  • Should command templates support @file mentions, and if so should they resolve into prompt file attachments or remain plain text for the model/tools to interpret?

Current behavior

  • Built-in and config commands resolve into normal session prompt input.
  • MCP prompts are exposed as command-shaped entries and resolve into normal prompt input.
  • /review is treated as a normal command for now.
  • Shell interpolation with !...`` is supported for command templates.
  • Command-level subtask/background behavior is intentionally deferred.
  • Command-template @agent and @file mention resolution is intentionally deferred; command text is submitted without synthesizing attachments from those mentions.

Activity

  1. rekram1-node
    changed the title [-]v2: decide command subtask and backgrounding semantics[/-] [+]v2: decide command execution and mention semantics[/+] on Jul 2, 2026

  2. opencode-agent commented on Jul 3, 2026

    @opencode-agent
    opencode-agentBot
    on Jul 3, 2026 – with OpenCode Agent
    Contributor

    Update: #35025 (fix(core): allow resuming subagents) adds subagent_id continuation/resume support and exposes the id in model-facing subagent output. This likely closes part of the follow-up-subagent/command semantics gap, but the broader command mention/subtask/backgrounding decision remains here unless confirmed otherwise.

  3. opencode-agent
    added
    2.0
    coreAnything pertaining to core functionality of the application (opencode server stuff)
    on Jul 5, 2026

  4. opencode-agent commented on Jul 5, 2026

    @opencode-agent
    opencode-agentBot
    on Jul 5, 2026 – with OpenCode Agent
    Contributor

    Tracker update: draft PR #35233 is the active WIP implementation for subagent slash commands that launch child sessions in the background and report status/completion to the parent. Aiden notes the PR still needs more work. Keep this issue open for review of command execution/backgrounding semantics and the remaining @agent / @file mention decisions.

  5. Dante-dan commented on Oct 1, 2026

    @Dante-dan
    Dante-dan
    on Oct 1, 2026
    Contributor

    I traced this against current dev (0112a92) and suggest splitting template admission from execution policy.

    The native API has moved since #34849: SessionV2.Interface admits a Prompt through session.prompt; it has no command method. CommandV2 currently registers/lists templates. Prompt already separates text, file attachments and agent attachments, each attachment optionally retaining source offsets. The native runner lowers files to media and keeps agents as metadata; an agent attachment does not itself launch a child session. Also, the current built-in tool list still lists task as a remaining port. The old child-session path is therefore not yet an interchangeable native primitive.

    Proposed first slice for core design review:

    Input Proposed native behavior
    Ordinary command / MCP prompt Expand into one normal Prompt; retain supplied explicit attachments.
    @file / @agent in template text Preserve text initially; do not copy v1's filesystem-first, agent-fallback name guessing. Resolve only through an explicitly approved attachment resolver that produces the native files / agents structures and source ranges.
    Command agent metadata Treat agent selection separately from an agent attachment. Define whether invocation selects the session's agent or a per-input agent before wiring it; the current prompt contract has no per-input agent override.
    subtask: true or subagent-mode command Defer execution until the native child-session/task contract exists; reuse that contract rather than introduce a command-specific scheduler.
    Automatic backgrounding Keep it separate from template expansion. Require the same durable status, cancellation, recovery and parent completion-delivery contract as explicit background execution.

    One concrete v1 trap worth avoiding: resolvePromptParts / command resolves template files/agents, but the subtask branch then retains only the text prompt. Carrying that conversion forward would silently lose those attachments.

    Could the core team approve this staged boundary, especially explicit attachment resolution and keeping subtask/background lifecycle outside command expansion? The execution and mention decisions would remain open until their respective native contracts are approved; this would give template admission a bounded implementation target.

  6. arin8513 commented on Oct 24, 2026

    @arin8513
    arin8513
    on Oct 24, 2026

    Concrete proposal feeding this discussion, from daily multi-agent use on Windows (v2.1.4).

    The inverse of the @ mention: let # in the main input address the tool space:

    • #read - one tool
    • #context7 - a whole MCP server (all of its tools)
    • #context7.resolve-library-id - one tool of one server

    The mention should reach the agent as a scoped directive on the user message (e.g. "the user pinned these tools for this request"), not only as a UI chip the runtime consumes silently. With 200+ tools in scope, name similarity makes an agent pick the wrong tool or waffle, and pinning is the cheapest correction a user can express.

    Real example: forcing #chrome-devtools.take_screenshot for a visual check instead of letting the model choose among several browser-ish servers in the same toolkit.

    Split out of #58243 (item 5), where the triage bot mapped that item to this discussion - posting it here rather than as a separate issue so the design conversation stays in one place.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    2.0coreAnything pertaining to core functionality of the application (opencode server stuff)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions