oh-my-opencode-slim/docs/subtask.md

Subtask

/subtask lets the current agent spin up a separate, bounded worker session for one specific piece of work. The worker runs as an orchestrator in a real child session, completes the requested task, and sends a structured summary back to the original conversation.

Use it when a bounded, context-heavy task only needs to return a compact result to the main thread.

Usage

/subtask <focused task for the worker>

Examples:

/subtask update the subtask docs and run the relevant checks
/subtask investigate why the auth retry test is flaky and report findings
/subtask implement the small button spacing polish in the settings panel

Keep the request narrow. A good subtask has a clear finish line.

What happens

1. The /subtask command asks the current agent to prepare a self-contained worker prompt.
2. The agent calls the subtask tool with that prompt and any clearly relevant files.
3. Slim creates a real child session with parentID pointing at the current session.
4. The child session runs as orchestrator, so it can use normal tools and specialist delegation when useful.
5. Referenced files are injected as synthetic Read-tool context before the worker starts.
6. If the worker needs missing conversation details, it can call read_session to inspect only the source session that spawned it.
7. When finished, the worker returns a <subtask_summary> with status, changes, files touched, validation, and follow-up notes.
8. Slim extracts the summary, returns it to the original session, and aborts the child session for cleanup.

In tmux or zellij, the subtask appears like other child-agent work because it is a real child session. Existing depth limits and pane cleanup handling apply.

If the parent session has an active Session Goal, the worker inherits it as context. The explicit subtask request still defines the worker's scope.

Worker scope

The worker prompt is intentionally bounded:

• complete only the requested task,
• do not broaden scope,
• do not spawn another subtask,
• use read_session only when needed context is missing,
• run the most relevant validation checks when practical,
• stop when the requested task is done.

This keeps subtasks useful for focused execution rather than turning them into a second open-ended conversation.

Tools

Tool	Purpose
subtask	Creates a child worker session and returns its summary
read_session	Lets a subtask worker read the source session that spawned it

read_session is restricted to subtask workers and only allows reading the source session. It is not a general transcript-reading tool.

File context

Files can be passed explicitly with the files argument or referenced in the worker prompt with @path syntax. Slim resolves those paths inside the current workspace and injects readable text files as synthetic context.

Safety rules:

• paths must stay inside the workspace real path,
• symlinks that resolve outside the workspace are skipped,
• binary files are skipped,
• large files are capped before injection,
• unreadable or missing files are skipped.

Timeout

Each subtask worker has a timeout. If the worker has not returned a summary before the timeout elapses, Slim aborts the child session and the subtask tool call fails with Prompt timed out after <ms>ms.

The default timeout is 5 minutes (300000 ms). Override it via subtask.timeoutMs in your plugin config:

{
  // Give workers up to 30 minutes before timing out
  "subtask": {
    "timeoutMs": 1800000
  }
}

Set timeoutMs to 0 to disable the timeout entirely. The maximum accepted value is 86400000 (24 hours).

Summary format

The worker is instructed to finish with:

<subtask_summary>
Status: completed | blocked | partial

What changed:
- ...

Files touched:
- ...

Validation:
- ...

Risks / follow-up:
- ...
</subtask_summary>

The parent session receives that summary as normal tool output.