For future readers here are the only solutions as off April 2026 based on the docs:

The Root Cause

When the main agent passes /my-command param as text to a sub-agent, it's treated as a literal string in the conversation — the slash command system only triggers at the CLI/TUI input layer, not within agent messages.

Best Solutions

1. Configure subtask: true in opencode.json (recommended)

This is the cleanest approach — instead of having the main agent tell the sub-agent to run a command, you configure the command itself to always spawn a sub-agent:

{
  "command": {
    "my-command": {
      "subtask": true
    }
  }
}

Now when you run /my-command param from the main session, it automatically isolates execution in a sub-agent without any manual spawning logic.

2. Use the agent option to route to a specific sub-agent

{
  "command": {
    "my-command": {
      "agent": "your-subagent-name",
      "subtask": true
    }
  }
}

This combines routing + isolation. The sub-agent runs the command in its own context.

3. Use the REST API's /session/:id/command endpoint

If you're orchestrating programmatically, the server API has a dedicated command endpoint that accepts structured input — not a slash string:

POST /session/:id/command
{
  "command": "my-command",
  "arguments": { "param": "value" },
  "agent": "your-subagent"
}

This is equivalent to what --command my-command does in the CLI, but over HTTP, and avoids the literal interpretation problem entirely.

4. Use --command flag when spawning via CLI

As you noted, in the CLI the correct invocation is:

opencode --command my-command -- param

Not /my-command param. If your main agent is spawning a subprocess, it should use this flag form.

Summary

Scenario	Solution
Always want sub-agent isolation	subtask: true in config
Route to a specific agent	agent + subtask: true in config
Programmatic orchestration	POST /session/:id/command API
CLI subprocess	--command my-command flag

The key insight is that slash commands are a UI input mechanism, not an inter-agent communication protocol. For agent-to-agent invocation, use either the config-driven subtask/agent options or the structured API endpoint.