[FEATURE]: Improve Subagent Invocation Documentation

[mossbergmaverick]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

The current documentation explains that subagents can be invoked automatically or manually, but doesn't clearly explain how to write agent prompts for automatic invocation when creating agents via markdown files.

From the docs:

Subagents can be invoked:

• Automatically by primary agents for specialized tasks based on their descriptions.
• Manually by @ mentioning a subagent in your message.

What's unclear for users creating agents via .md files:

• Should primary agents use @subagent-name or just subagent-name in their system prompts?
• What syntax should be written in the markdown body of primary agent files?
• How does the automatic invocation mechanism work?

Context

This issue specifically concerns users who create agents using markdown files in:

• ~/.config/opencode/agent/
• .opencode/agent/

The confusion is about what to write in the markdown body (system prompt), not the frontmatter configuration.

Expected vs Actual Behavior

User possible expectation based on docs:

# .opencode/agent/test-agent.md
---
description: Test agent
mode: primary
---
Example: "@test-subagent create a test file"

What actually works:

# .opencode/agent/test-agent.md
---
description: Test agent
mode: primary
---
Example: "test-subagent create a test file"

The @ prefix is only for manual user invocation, not for automatic agent-to-agent invocation in system prompts.

Suggested Documentation Improvement

Add a clear example in the Agents section showing the difference:

Proposed addition:

Subagent Invocation

Subagents can be invoked in two ways:

1. Automatic Invocation (by primary agents)

When creating agents via markdown files, primary agents invoke subagents by mentioning their name without @ in the system prompt:

Primary agent file (~/.config/opencode/agent/delegator.md):

---
description: Main development agent that delegates tasks
mode: primary
tools:
  write: false
---

You delegate file creation to the file-writer subagent.
When user requests file creation, invoke it like this:
"file-writer create the requested file"

NOT like this: "@file-writer create file"  # @ is only for manual user invocation

Subagent file (~/.config/opencode/agent/file-writer.md):

---
description: Creates and manages files
mode: subagent
tools:
  write: true
---

You create files as requested.

2. Manual Invocation (by users)

Users invoke subagents directly in the TUI using @:

@file-writer create test.txt with content "hello"

Technical Note

Subagents appear as available tools to primary agents based on their description. The primary agent decides when to invoke them based on the task context. In the agent's system prompt (markdown body), reference subagents by name only, without the @ prefix.

Additional Examples for Markdown Agent Files

Example 1: Testing Agent

# .opencode/agent/developer.md

---
description: Main development agent
mode: primary
tools:
  write: false
---
Delegate test creation to test-writer subagent:
"test-writer generate tests for this code"

# .opencode/agent/test-writer.md

---
description: Writes unit and integration tests
mode: subagent
tools:
  write: true
---
You write comprehensive tests for the code provided.

Example 2: Security Review

# Primary agent markdown body
When security review is requested, invoke the subagent:
"security-auditor analyze this code for vulnerabilities"

# Correct ✅
"security-auditor analyze code"

# Incorrect ❌ (@ is for manual user invocation only)
"@security-auditor analyze code"

Related Documentation Files

• /docs/agents/
• Specifically the "Usage" and "Markdown" sections

Impact

This clarification would help users who create agents via markdown files:

• Understand the difference between automatic and manual invocation syntax
• Write correct agent system prompts in markdown files
• Avoid confusion with @ syntax when writing agent instructions

[JayGhiya]

post upgrade to v1 i am not able to invoke them manually is this expected @mossbergmaverick ?

[rekram1-node]

@JayGhiya we are gonna update that

[johnr14]

I would like to know how the the sub-agent communicates back with the agent that called it.

Does the subagent return the last message, the whole context or nothing ?
Could that be customizable with a return: all|last|compact|validator config ?

Example :

• plan agent calls plan-drafter subagent with instructions on what to plan
  • plan-drafter will :
    • decide to investigate current code using plan-code or plan-doc to plan what files need modifications
    • receive the plan produced by the subagent and decide if more investigation is needed
    • call subagent plan-project with the previous produced plan to enhance and correct the plan with any specific instructions related to the project instructions. Returns a plan that is coherent with the project's convention
    • review plan draft and check if any refactoring is needed before passing it back to plan agent
• plan will ask user if the plan-draft is ok or if there are any changes requiring calling back plan-drafter
• plan will send the plan to sub-agent plan-manager that will write the plan to a file

The thing is that subagents can quickly fill their context up and that's better than the main agent busting it's context.
But they should be able to provide context back like a function would return.
There are no clear information in the documentation about this.

A build in tool like return could also be called when a subagent has finished so it can write it's return message like : `status=COMPLETED|FAILED,message="".

While at it, a validator agent could be specified to validate that the agent was successful. It could be validator: simple-validator config. The validator could read the last message or use a tool call to read last N messages if it isn't sure. The validator would return COMPLETED or FAILED and a description of what went wrong.

---

Is it possible to change/append to the system_prompt for a model in the config ?
I like to force tags on Kimi Linear, seems to help it a bit.

---

Also, is there a way to have a scratch pad for the agents ? Something like the todo list.

Could we get a document that will never be duplicated in the discussion ? Any changes to it would be lost or would require a rollback for the llm. The user could consult it's versions and start a new session with what he considers the best iteration or revert to it in the current session. I think this would help context, might not be for all cases.

---

Also it would be nice to ask the llm about opencode. I would propose the command /opencode ask that would have access to the opencode documentation and answer.

Example:
/opencode how can I limit a agent to generate at most 3000 tokens per interaction
@build I would like to limit agent-somename to 3000 tokens and change context limit to 32000.

---

Session name: Why is is always New session ?
Could it be updated to a short description like [plan] plan the new super feature... the first characters of the first command of the session with the original agent/command ?

Thanks

[rekram1-node]

@johnr14

Does the subagent return the last message

It returns the last text message it had.

Is it possible to change/append to the system_prompt for a model in the config ?
I like to force tags on Kimi Linear, seems to help it a bit.

Not currently , you can use AGENTS.md or a prompt for an agent but we don't really allow this specifically for a model across everything

Also it would be nice to ask the llm about opencode. I would propose the command /opencode ask that would have access to the opencode documentation and answer.

I kinda like this idea because then it is less intruisive and we dont have to throw stuff in the system prompt everywhere

Session name: Why is is always New session ?
Could it be updated to a short description like [plan] plan the new super feature... the first characters of the first command of the session with the original agent/command ?

It's not supposed to be... What model / provider are you using?

[johnr14]

@rekram1-node

Is it possible to change/append to the system_prompt for a model in the config ?
I like to force tags on Kimi Linear, seems to help it a bit.

Not currently , you can use AGENTS.md or a prompt for an agent but we don't really allow this specifically for a model across everything

hmm, could be done with config ?

{
    "$schema": "https://opencode.ai/config.json",
    "provider": {
        "llamacpp": {
            "npm": "@ai-sdk/openai-compatible",
            "name": "llamacpp (local)",
            "options": {
                "baseURL": "http://192.168.1.132:8112/v1"
            },
            "models": {
                "DeepCogito-109b": {
                    "name": "DeepCogito-109b local",
                    "system_prompt": "CUSTOM PROMPT",
                },
            }
        },
        "vllm":{  
            "npm": "@ai-sdk/openai-compatible",
            "name": "vllm (local)",
            "options": {
                "baseURL": "http://192.168.1.132:8111/v1",
                "apiKey": "local"
                },
            "models": {
                "Kimi-Linear-48B-A3B-Instruct": {
                "name": "Kimi-Linear-48B-A3B-Instruct",
                "system_prompt_prepend": "INSTRUCTIONS HERE AT TOP",
                "system_prompt_append": "INSTRUCTIONS HERE AT BOTTOM",
                },
            }
        }
    },
    "model": "Kimi-Linear-48B-A3B-Instruct",
    "small_model": "Kimi-Linear-48B-A3B-Instruct"
}

Also it would be nice to ask the llm about opencode. I would propose the command /opencode ask that would have access to the opencode documentation and answer.

I kinda like this idea because then it is less intruisive and we dont have to throw stuff in the system prompt everywhere

You might add some docs with FAQ, implementation details (tutorial, examples, explanations), release notes. That could save time and be quite useful. I would process all github issues for most asked questions and check that the generated answer is right. Then bundle that in a few FAQ files by component (agents/tools/tui/etc.) in the doc and there you go. Limit file access to .opencode/docs for the command /opencode and provide list of files and a summary of what they contain in a README.md index.

Session name: Why is is always New session ?
Could it be updated to a short description like [plan] plan the new super feature... the first characters of the first command of the session with the original agent/command ?

It's not supposed to be... What model / provider are you using?

Kimi-Linear, only running opencode locally, didn't try API. Sorry then, but a fail-safe would be great when using smaller models.