Subagent Example

Delegate tasks to specialized subagents with isolated context windows.

Features

• Isolated context: Each subagent runs in a separate omk process
• Session model inheritance: Agents without model use the parent session's currently selected model; an explicit model pins the child
• Streaming output: See tool calls and progress as they happen
• Parallel streaming: All parallel tasks stream updates simultaneously
• Validated task graphs: Dependency DAGs fail closed on duplicate/unknown/cyclic nodes and execute in deterministic parallel waves
• Explicit handoffs: Graph nodes receive only declared dependency output and only when their task includes {dependencies}
• Markdown rendering: Final output rendered with proper formatting (expanded view)
• Usage tracking: Shows turns, tokens, cost, and context usage per agent
• Abort support: Ctrl+C propagates to the entire detached subagent process tree
• Dual-budget planning: Predictive sharding uses both estimated tokens and learned wall-clock demand
• Checkpoint resume: A cutoff resumes only the unfinished shard with bounded prior evidence
• Cutoff learning: Completion/cutoff history is persisted per provider and model under the agent state directory
• Bounded cost: At most 3 semantic shards and 1 resume across the whole logical task by default
• Ultra execution: Removes task-count, concurrency, internal deadline, and outer tool-timeout caps; Ctrl+C cancellation still propagates

Structure

subagent/
├── README.md            # This file
├── index.ts                    # The extension entry point
├── adaptive-agent-runtime.ts   # Shard/checkpoint/resume coordinator
├── checkpoint-runtime.ts       # Bounded checkpoint protocol
├── deadline-budget.ts          # Token + wall-clock planning and cutoff learning
├── deadline-profile-store.ts   # Persistent provider/model profiles
├── managed-process.ts          # Process-tree termination and cleanup
├── subagent-runtime-types.ts   # Typed result/deadline metadata
├── agents.ts                   # Agent discovery logic
├── agents/              # Sample agent definitions
│   ├── scout.md         # Fast recon, returns compressed context
│   ├── planner.md       # Creates implementation plans
│   ├── reviewer.md      # Code review
│   └── worker.md        # General-purpose (full capabilities)
└── prompts/             # Workflow presets (prompt templates)
    ├── implement.md     # scout -> planner -> worker
    ├── scout-and-plan.md    # scout -> planner (no implementation)
    └── implement-and-review.md  # worker -> reviewer -> worker

Installation

From the repository root, symlink the files:

# Symlink the extension (must be in a subdirectory with index.ts)
mkdir -p ~/.omk/agent/extensions/subagent
src="$(pwd)/packages/coding-agent/examples/extensions/subagent"
for f in index.ts agents.ts agent-capability-router.ts capabilities.ts domain-profiles.ts \
  adaptive-agent-runtime.ts adaptive-result.ts checkpoint-runtime.ts deadline-budget.ts \
  deadline-profile-store.ts managed-process.ts subagent-runtime-types.ts workflow-graph.ts; do
  ln -sf "$src/$f" ~/.omk/agent/extensions/subagent/$f
done

# Symlink agents
mkdir -p ~/.omk/agent/agents
for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do
  ln -sf "$(pwd)/$f" ~/.omk/agent/agents/$(basename "$f")
done

# Symlink workflow prompts
mkdir -p ~/.omk/agent/prompts
for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do
  ln -sf "$(pwd)/$f" ~/.omk/agent/prompts/$(basename "$f")
done

Security Model

This tool executes a separate omk subprocess with a delegated system prompt and tool/model configuration.

Project-local agents (.omk/agents/*.md) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.

Default behavior: Only loads user-level agents from ~/.omk/agent/agents.

To enable project-local agents, pass agentScope: "both" (or "project"). Only do this for repositories you trust.

When running interactively, the tool prompts for confirmation before running project-local agents. Set confirmProjectAgents: false to disable.

Usage

Single agent

Use scout to find all authentication code

Parallel execution

Run 2 scouts in parallel: one to find models, one to find providers

Chained workflow

Use a chain: first have scout find the read tool, then have planner suggest improvements

Workflow prompts

/implement add Redis caching to the session store
/scout-and-plan refactor auth to support OAuth
/implement-and-review add input validation to API endpoints

Tool Modes

Mode	Parameter	Description
Single	{ agent, task }	One logical task; the runtime may split it into bounded semantic shards
Parallel	{ tasks: [...] }	Multiple logical tasks; non-Ultra allows max 8 and 4 concurrent, while Ultra starts all requested tasks concurrently
Chain	{ chain: [...] }	Sequential with {previous} placeholder and a fair deadline share per remaining step
Graph	{ graph: [{ id, agent, task, dependsOn? }] }	Validated dependency DAG; ready nodes run in parallel waves, and any failed wave blocks downstream nodes

Graph nodes opt in to dependency output by placing {dependencies} in task. The runtime injects only outputs named in that node's dependsOn; without the placeholder, no prior output is appended. Each dependency handoff is capped at 16 KiB. This keeps large or unrelated context from leaking across nodes.

Optional execution controls:

Parameter	Default	Description
executionBudgetMs	840000	Non-Ultra internal hard budget; when explicitly supplied it also bounds Ultra execution, otherwise Ultra is unbounded
maxResumeAttempts	1	Retries only the active unfinished shard; accepted range is 0-2 and ignored by unbounded Ultra execution

Output Display

Collapsed view (default):

• Status icon (✓/✗/⏳) and agent name
• Last 5-10 items (tool calls and text)
• Usage stats: 3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model

Expanded view (Ctrl+O):

• Full task text
• All tool calls with formatted arguments
• Final output rendered as Markdown
• Per-task usage (for chain/parallel)

Parallel mode streaming:

• Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
• Updates as each task makes progress
• Shows "2/3 done, 1 running" status
• Returns each completed task's final output to the parent model, capped at 50 KB per task
• Returns failure diagnostics from stderr/error messages when a child exits before producing output

Tool call formatting (mimics built-in tools):

• $ command for bash
• read ~/path:1-10 for read
• grep /pattern/ in ~/path for grep
• etc.

Agent Definitions

Agents are markdown files with YAML frontmatter:

---
name: my-agent
description: What this agent does
tools: read, grep, find, ls
---

System prompt for the agent goes here.

model is optional. Omit it to inherit the model currently selected in the parent session; set it only when the agent must be pinned to a specific model.

Locations:

• ~/.omk/agent/agents/*.md - User-level (always loaded)
• .omk/agents/*.md - Project-level (only with agentScope: "project" or "both")

Project agents override user agents with the same name when agentScope: "both".

Sample Agents

Agent	Purpose	Model	Tools
scout	Fast codebase recon	Parent session	read, grep, find, ls, bash
planner	Implementation plans	Parent session	read, grep, find, ls
reviewer	Code review	Parent session	read, grep, find, ls, bash
worker	General-purpose	Parent session	(all default)

Workflow Prompts

Prompt	Flow
/implement <query>	scout → planner → worker
/scout-and-plan <query>	scout → planner
/implement-and-review <query>	worker → reviewer → worker

Error Handling

• Exit code != 0: Tool returns error with stderr/output
• stopReason "error": LLM error propagated with error message
• stopReason "aborted": User abort (Ctrl+C) terminates and reaps the subprocess tree
• stopReason "deadline": Outside Ultra, an internal cutoff returns elapsed/deadline/checkpoint/resume metadata instead of reaching the outer tool timeout
• Ultra: No scheduler or attempt deadline is armed; provider, network, OS, and explicit caller cancellation still apply
• Chain mode: Stops at first failing step, reports which step failed, and preserves completed earlier steps
• Graph mode: Rejects malformed graphs before spawn; a failed wave prevents all downstream starts and preserves completed node evidence
• Duplicate prevention: A cutoff with no new checkpoint or streamed evidence is not retried

Limitations

• Output truncated to last 10 items in collapsed view (expand to see all)
• Parallel model-visible output is capped at 50 KB per task; full results remain in tool details
• Agents discovered fresh on each invocation (allows editing mid-session)
• Outside Ultra, parallel mode is limited to 8 tasks and 4 concurrent processes; Ultra has no extension-imposed count or concurrency cap and can consume substantial host/provider resources
• Automatic semantic pre-sharding requires an explicit numbered/checklist action list; indivisible prose is checkpointed and resumed as one shard
• Checkpoints are best-effort child artifacts plus runtime-captured stream evidence; workspace side effects remain the source of truth after a cutoff