---

name: delegating-work

description: Choose between running a command yourself, fanning work out to child coding agents with delegate, and handing a whole task to another agent such as the Devin CLI. Use it before reaching for delegate, and whenever work looks like it needs more than one worker.

---

# Handing work to something else

Three ways, in order of what they cost. Pick the cheapest that does the job.

## Do it yourself

The `shell` tool runs a command here. Reading a file, listing a directory,

searching, `git`, a build, a test run: all of it is one call and one process.

This is almost always the right answer for a single command. Starting an agent

to run `pwd` costs minutes and real money and hands back an answer nobody

watched being produced.

## `delegate`, for work that splits

The `delegate` tool starts child coding agents that all run the same prompt in

parallel, in this repository, each with its own file and shell tools. It earns

its cost when the work genuinely splits into parts that do not depend on each

other: several files to change the same way, several hypotheses to check at

once, several test suites to run down.

Each child starts with no context from this conversation and cannot ask

questions, so the prompt has to carry everything. Every child gets the same

prompt and is told its own number separately — write for whichever child is

reading, rather than naming one.

## `delegate --child-model devin`, for a Devin fan-out

If `devin` is on `PATH`, `delegate` can run its children on it instead of on

opencode: pass `--child-model devin`, or `devin:<mode>` for a permission mode

other than the default `dangerous`.

Prefer this over running `devin` yourself through `shell`. A child started this

way is a fleet child like any other — it reports through the registry the

interface renders, it can be stopped with `ctrl+x`, it does not block the turn

that started it, and several run at once. Run through `shell`, the same work is

one call that freezes the session and shows nothing until it ends.

A Devin child brings its own credentials and its own model rather than spending

this session's grant, which is a different trust and billing boundary from an

opencode child. That is why the fleet names the agent.

Its print mode has no structured output, so a Devin child reports its answer

once at the end rather than streaming its tool calls the way an opencode child

does.

## The Devin CLI directly, for one task you will wait on

If `devin` is on `PATH`, it is another coding agent on this machine, and it can

take a task end to end rather than one prompt in parallel. Check with

`command -v devin`.

Run it non-interactively through `shell`:

```sh

devin -p "<a complete, self-contained task>"                        # read-only

devin -p "<a complete, self-contained task>" --permission-mode dangerous  # unattended

```

`-p` means one prompt, print the answer, exit. What it may do is the permission

mode, and the default is already the read-only one:

| `--permission-mode` | Auto-approves |

| --- | --- |

| `auto` (default, no flag needed) | read-only tools only |

| `accept-edits` | and edits inside the workspace |

| `smart` | and anything a fast model judges safe |

| `dangerous` | everything, including writes and shell |

For a read-only run, pass no flag. In `-p` mode there is nobody to answer a

prompt, so anything not auto-approved simply does not happen — the mode is the

whole of the boundary. Run `devin --help` if this disagrees with the build in

front of you; the values it lists are the values it takes.

Three things are worth knowing before an unattended run.

**`dangerous` is the mode name on this build.** The published documentation

calls the equivalent mode "bypass". Passing `--permission-mode bypass` is not

rejected — it is accepted and ignored, so the session silently falls back to

prompting, and a prompt nobody can answer is a task that does nothing.

**It refuses a workspace nobody has opened it in**, exiting at once with

`Refusing to run in an untrusted workspace`. Print mode cannot show the trust

prompt, so it fails rather than asking. Pass `--respect-workspace-trust false`

to skip the check, which is what print mode is for; the alternative is someone

starting `devin` interactively in that directory once. Only that exact message

means trust — do not read other failures as a trust problem.

**`dangerous` auto-approves every tool it has.** That is the point of using it

unattended, and it is the reason to say what you are handing over before you

hand it over. Give it a bounded task in this repository, not an open-ended one.

There is also `devin acp`, an Agent Client Protocol server over stdio, for a

caller that speaks ACP. `-p` is the simpler route from here and needs no

protocol on this side.

## Which one

| The work | Use |

| --- | --- |

| One command, one answer | `shell` |

| The same thing to N independent parts, at once | `delegate` |

| A whole task you would otherwise do yourself, run by another agent | `devin -p` |

Whatever runs it, the result is yours to check. An agent reporting that it

finished is not evidence that it did; read the diff, run the test, look at the

output.

---

name: superdelegate

description: How to hand work to something else, and how to burn through a backlog of open issues with maximum safe parallelism across Devin and opencode. Loaded into every session.

auto: true

---

# Handing work out

## Which lane

| The work | Use |

| --- | --- |

| One command, one answer | `shell` |

| The same thing to N independent parts | `delegate` |

| A backlog of issues | the method below |

Run a single command yourself. Starting an agent to run `pwd` costs minutes and

real money and hands back an answer nobody watched being produced.

`delegate` starts child coding agents that run the same prompt in parallel, each

with its own file and shell tools. Children start with no context from this

conversation and cannot ask questions, so the prompt carries everything. Every

child gets the same prompt and is told its own number separately — write for

whichever child is reading rather than naming one.

`--child-model devin` runs the children on the Devin CLI instead, and

`devin:<mode>` picks a permission mode other than the default `dangerous`. A

Devin child brings its own credentials and model rather than spending this

session's grant. Prefer this over running `devin` yourself through `shell`: a

fleet child renders, stops with `ctrl+x`, and does not block the turn, while a

shell child is one opaque call that freezes the session until it ends.

## Burning through a backlog

When the task is "work the issues" rather than one named thing, this is the

method. It is opinionated on purpose: the decisions below are the ones that go

wrong when they are made ad hoc.

### 1. Read the board before touching it

List open issues in every repository the account can reach —

`OpenAgentsInc/openagents` and `OpenAgentsInc/openagents.com` at least. Use the

`openagents` tool, read the plain output, and use `--json` only to take a field.

### 2. Workable means unblocked

`openagents issue view <n>` reports `Blocked` and `Blocked by`. **A blocked issue

is not workable**, however ready it looks, and starting one wastes a child and

produces a change that cannot land. Name the blocked ones as blocked, say what

they wait on, and leave them.

Prefer `agent-ready`. An issue whose shape is still a question is not ready for

a child that cannot ask one.

### 3. One child per surface

Two children editing the same files is a merge conflict nobody asked for. Group

the workable issues by the surface they touch — a package, a directory, a

module — and keep **one child in flight per surface**. Issues on different

surfaces run together freely.

If two issues must touch the same surface, run them in sequence, or give each

child its own git worktree so their edits cannot meet.

### 4. Route by the kind of thinking

- **Devin** for straightforward engineering: a named fix, a test to write, a

  migration, a rename, a documented change with a clear shape.

- **opencode on Ox Alpha** (`--child-model ox-alpha`) for high-concept and

  strategic work: design, architecture, anything where the shape of the answer

  is the question.

If you cannot tell which, it is the second kind.

### 5. Find the width, do not pick it

**Never choose a number and hope.** Start at about four and climb:

1. Run a round of four.

2. Before widening, look: system load and free memory

   (`uptime`, `vm_stat` or `free`), `openagents auth status` for the account,

   and whether any child came back with a rate limit, a quota refusal, or a

   provider error.

3. If all three are clean, raise the width — four, six, eight — and go again.

4. At the **first** sign of a limit, stop raising and hold at the last width

   that was clean. Do not push past it to confirm; the confirmation costs a

   round of failed children.

The width is a measurement, not a setting. A machine with sixteen idle cores and

a healthy account should be running far more than four; one that is swapping

should be running fewer. Report the width you reached and what stopped it.

### 6. Report as you go

After each round, say which issues were selected, which were skipped and why,

what each child returned, and where the width stands. A backlog run that reports

only at the end is one nobody can steer.

## What is not yours to decide

Closing an issue, pushing, and commenting are visible to other people at once.

Do the work and report it; ask before the first write that leaves the machine.

An agent reporting that it finished is not evidence that it did. Read the diff,

run the test, look at the output.

import { spawnSync } from "node:child_process";

import { rebuild, RELOAD_EXIT_CODE, sourceCheckout } from "./coder-reload.js";

import { loadSkillSelection } from "./coder-skills.js";

import { loadSkillSelection, standingContext } from "./coder-skills.js";

import { describeWorkspace } from "./coder-workspace.js";

import { ComputerClient } from "./computer-client.js";

import { ComputerUp } from "./computer-up.js";

        }),

      );

      const skills = loadSkillSelection();

      const session = new CoderSession(

        source,

        workspace.repository,

        workspace.branch,

        setup?.delegation,

        standingContext(skills.active(), process.cwd()),

      );

      // The model is told what it can do rather than the reader being asked to

      // Skills do not depend on delegation: a session with no credential still

      // reads this repository's conventions, it just cannot hand work to a

      // child. A session with neither declares no tools at all.

      const skills = loadSkillSelection();

      // Re-declared rather than declared once: switching a skill off in

      // `/skills` has to change what the next turn carries, and the tool

      // holding the catalog is the thing that changes.

const DEFAULT_HOST = "http://127.0.0.1:11434";

/**

 * How many times one turn may call tools before it has to answer.

 * How many rounds of tool calls one turn may take before it has to answer.

 *

 * The same ceiling the thread lane uses, for the same reason: a model that

 * keeps delegating never reports to the reader. A local model spends no metered

 * budget, but it does spend the reader's wall clock and the children's.

 * High, because the ceiling is a backstop against a model that loops forever,

 * not a budget. It was six, and six is a number real work passes: a session

 * reading a package hit it after twenty steps and eighty thousand tokens and

 * ended with `Stopped after 6 rounds of tool calls without an answer` — every

 * one of those reads thrown away. A reader can stop a turn with escape at any

 * time, and that is the control that should decide when enough is enough.

 */

const MAX_TOOL_STEPS = 6;

const MAX_TOOL_STEPS = 100;

export interface OllamaOptions {

  /** The Ollama model name, without the `ollama:` prefix. */

      const calls: OllamaToolCall[] = [];

      let assistant = "";

      // The last round is answered without tools. Reaching the ceiling with the

      // tools still on the table produced a turn that stopped mid-work and said

      // so, throwing away everything it had read; taking them away instead

      // leaves the model one thing it can do, which is report what it found.

      const finalRound = step === MAX_TOOL_STEPS - 1;

      if (finalRound && this.tools.length > 0) {

        this.transcript.push({

          role: "user",

          content:

            "You have reached this turn's limit on tool calls. Do not call another tool. " +

            "Answer now with what you have found, and say plainly what is still unfinished.",

        });

      }

      const stream = await this.client.chat({

        model: this.modelName,

        // A snapshot, not the live array: the transcript grows while the round

        // request nobody can reason about.

        messages: [...this.transcript],

        stream: true,

        ...(this.tools.length === 0

        ...(this.tools.length === 0 || finalRound

          ? {}

          : {

              tools: this.tools.map((tool) => ({

      }

    }

    // The ceiling was reached. Say so rather than ending on a tool result the

    // reader has to interpret as an answer.

    yield {

      type: "text",

      value: `\n\nStopped after ${String(MAX_TOOL_STEPS)} rounds of tool calls without an answer.`,

    };

    yield { type: "usage", promptTokens, completionTokens, calls: llmCalls };

  }

    private readonly repository: string,

    private readonly branch: string,

    private readonly delegation?: CoderDelegation,

    /**

     * Put in front of the first prompt, and nowhere else.

     *

     * A session told how to approach its work needs that before its first

     * decision. It goes ahead of the first turn rather than into every one:

     * after that it is in the transcript, and paying for it again each turn

     * buys nothing.

     */

    private readonly standing?: string,

  ) {

    // A child reporting progress has to reach the renderer, and the renderer

    // subscribes to the session rather than to the registry, so the session

    this.emit();

    try {

      for await (const chunk of this.source.reply(prompt, controller.signal)) {

      // The reader's entry above keeps what they typed; the model receives the

      // standing context ahead of it on the first turn only.

      const sent =

        this.standing === undefined || this.turnCount > 1

          ? prompt

          : `${this.standing}\n\n---\n\n${prompt}`;

      for await (const chunk of this.source.reply(sent, controller.signal)) {

        if (controller.signal.aborted) break;

        if (chunk.type === "text") {

export interface CoderSkill {

  /** The name the model asks for, from the front matter. */

  readonly name: string;

  /**

   * Whether the body is put in front of the model without being asked for.

   *

   * The catalog exists so a body is read only when it is wanted. A skill that

   * says how to approach the work is the exception: a session told to burn

   * through a backlog needs the method before its first decision, and a skill

   * it has to think to ask for is one it will not ask for.

   *

   * Set with `auto: true` in the front matter. Use it sparingly — every

   * auto-loaded body is paid for on every turn.

   */

  readonly auto: boolean;

  /** When to use it, from the front matter. One sentence, shown in the catalog. */

  readonly description: string;

  /** The instructions, front matter removed. */

 * is a dependency that can also do something surprising with a file anyone may

 * drop in a skills directory.

 */

const frontMatter = (source: string): { name?: string; description?: string } => {

const frontMatter = (source: string): { name?: string; description?: string; auto?: boolean } => {

  if (!source.startsWith("---")) return {};

  const end = source.indexOf("\n---", 3);

  if (end < 0) return {};

  const fields: { name?: string; description?: string } = {};

  const fields: { name?: string; description?: string; auto?: boolean } = {};

  const lines = source.slice(3, end).split("\n");

  for (const [at, line] of lines.entries()) {

    const auto = /^auto:\s*(true|false)\s*$/.exec(line);

    if (auto !== null) {

      fields.auto = auto[1] === "true";

      continue;

    }

    const match = /^(name|description):\s*(.*)$/.exec(line);

    if (match === null) continue;

    const key = match[1] as "name" | "description";

        continue;

      }

      const { name, description } = frontMatter(source);

      const { name, description, auto } = frontMatter(source);

      // A skill with no name cannot be asked for, and one with no description

      // gives the model nothing to choose on. Both are required.

      if (name === undefined || description === undefined) continue;

      if (found.has(name)) continue;

      found.set(name, { name, description, body: withoutFrontMatter(source), path });

      found.set(name, {

        name,

        description,

        auto: auto ?? false,

        body: withoutFrontMatter(source),

        path,

      });

    }

  }

    active: () => all.filter((skill) => !disabled.has(skill.name)),

  };

}

/**

 * The standing context for a session: every auto-loaded skill, in one block.

 *

 * Returns undefined when there is none, so a caller adds nothing rather than an

 * empty heading.

 */

export const standingContext = (

  skills: ReadonlyArray<CoderSkill>,

  cwd: string = process.cwd(),

): string | undefined => {

  const parts: string[] = [];

  const workspace = openAgentsWorkspace(cwd);

  if (workspace !== undefined) parts.push(workspace);

  for (const skill of skills) {

    if (!skill.auto) continue;

    parts.push(`The \`${skill.name}\` skill, which applies to this session:\n\n${skill.body}`);

  }

  return parts.length === 0 ? undefined : parts.join("\n\n");

};

/**

 * What the two OpenAgents repositories are, when the session is in one.

 *

 * A session in `openagents.com` spent turns working out that it was in the

 * Phoenix application, and one in `openagents` that the CLI lives under

 * `packages/`. Both are facts about the workspace rather than about the work,

 * and neither is discoverable without reading around.

 *

 * Keyed on the path because that is what is true at the time: a directory named

 * for one of them is one of them, and a directory that is not gets nothing

 * rather than a guess.

 */

const openAgentsWorkspace = (cwd: string): string | undefined => {

  if (!/openagents/i.test(cwd)) return undefined;

  return [

    `This session is working in ${cwd}, which is part of OpenAgents. Two repositories carry`,

    "most of the work, and they are easy to confuse:",

    "",

    "- **`openagents.com`** is the web application: a Phoenix and Elixir codebase serving the",

    "  site, the forge, and the `/api/v3` API. Its issues are the site's issues.",

    "- **`openagents`** is the monorepo: the `openagents` CLI lives in",

    "  `packages/openagents-cli`, alongside the other packages. Its issues are the CLI's and the",

    "  monorepo's.",

    "",

    "They are separate repositories with separate issue lists, so name the one you mean when you",

    "read or write issues, and do not assume the current directory is the one being asked about.",

  ].join("\n");

};

const THREADS_PATH = "/api/v3/threads";

/**

 * How many times one turn may call tools before it has to answer.

 * How many rounds of tool calls one turn may take before it has to answer.

 *

 * A ceiling rather than a preference: a model that keeps delegating is a model

 * spending the thread's budget without ever reporting to the reader.

 * A backstop against a model that loops forever, not a budget. It was six, and

 * six is a number real work passes: a session reading a package hit it after

 * twenty steps and ended saying it had stopped, throwing away everything it had

 * read. Escape stops a turn at any time, and that is the control that should

 * decide when enough is enough.

 */

const MAX_TOOL_STEPS = 6;

const MAX_TOOL_STEPS = 100;

/** What the thread may still spend, as the server last reported it. */

export interface ThreadBudget {

  private readonly transcript: WireMessage[] = [];

  private remaining: ThreadBudget;

  private tools: ReadonlyArray<CoderTool> = [];

  /** Set for the one round that must answer rather than call another tool. */

  private mustAnswer = false;

  constructor(private readonly state: SourceState) {

    this.threadId = state.threadId;

  }

  async *reply(prompt: string, signal: AbortSignal): AsyncIterable<ReplyChunk> {

    // Per turn, not per session: a turn that had to answer without tools must

    // not leave the next one without them.

    this.mustAnswer = false;

    this.transcript.push({ role: "user", content: prompt });

    try {

        if (signal.aborted || calls.length === 0) return;

        if (step >= MAX_TOOL_STEPS) {

          yield {

            type: "text",

            value: `\n\n[stopped after ${String(MAX_TOOL_STEPS)} tool steps in one turn]`,

          };

          return;

          // Take the tools away for one more round rather than stopping on a

          // tool result. The work already done is the reason the turn is long,

          // and ending on "stopped" throws all of it away.

          this.mustAnswer = true;

          this.transcript.push({

            role: "user",

            content:

              "You have reached this turn's limit on tool calls. Do not call another tool. " +

              "Answer now with what you have found, and say plainly what is still unfinished.",

          });

          continue;

        }

        for (const call of calls) {

        model: this.state.model,

        stream: true,

        messages: this.transcript,

        ...(this.tools.length === 0

        ...(this.tools.length === 0 || this.mustAnswer

          ? {}

          : {

              tools: this.tools.map((tool) => ({

    });

  });

  it("stops after the tool-call ceiling rather than looping forever", async () => {

    const rounds = Array.from({ length: 8 }, () => CALLING);

  it("answers on the last round instead of stopping mid-work", async () => {

    // Always asking for a tool, so the ceiling is what ends the turn. The

    // ceiling is a backstop against looping forever, not a budget: reaching it

    // used to end with "Stopped after 6 rounds" and throw away every read.

    const rounds = Array.from({ length: 200 }, () => CALLING);

    const { source, stub } = sourceWith(rounds);

    source.useTools([delegate([])]);

    const chunks = await collect(source, "keep going");

    await collect(source, "keep going");

    // Six rounds, then a sentence saying why it stopped.

    expect(stub.chat).toHaveBeenCalledTimes(6);

    const spoken = chunks.filter((piece) => piece.type !== "usage");

    expect(spoken.at(-1)).toMatchObject({ type: "text" });

    expect((spoken.at(-1) as { value: string }).value).toContain("Stopped after 6 rounds");

    expect(stub.chat).toHaveBeenCalledTimes(100);

    // The last round is asked without tools, so the model has one thing left it

    // can do: report what it found.

    const last = stub.requests.at(-1);

    expect(last).not.toHaveProperty("tools");

    const messages = last?.["messages"] as ReadonlyArray<Record<string, unknown>>;

    expect(messages.at(-1)).toMatchObject({

      role: "user",

      content: expect.stringContaining("Do not call another tool"),

    });

  });

});

import { join } from "node:path";

import { describe, expect, it } from "vitest";

import { discoverSkills, loadSkillSelection } from "../src/coder-skills.js";

import { discoverSkills, loadSkillSelection, standingContext } from "../src/coder-skills.js";

import { skillTool } from "../src/coder-tools.js";

/** A repository with the given skills under `.agents/skills`. */

    expect(cli?.body).toContain("auth login --headless");

  });

});

describe("what a session is told without asking", () => {

  const AUTO = "---\nname: method\ndescription: How to work.\nauto: true\n---\n\nWork this way.";

  const NORMAL = "---\nname: other\ndescription: Something else.\n---\n\nRead me on request.";

  it("marks a skill that loads itself", () => {

    const found = discoverSkills(workspace({ method: AUTO, other: NORMAL }), EMPTY_HOME, NO_BUILT_INS);

    expect(found.find((skill) => skill.name === "method")?.auto).toBe(true);

    expect(found.find((skill) => skill.name === "other")?.auto).toBe(false);

  });

  it("carries an auto-loaded body and leaves the rest in the catalog", () => {

    const found = discoverSkills(workspace({ method: AUTO, other: NORMAL }), EMPTY_HOME, NO_BUILT_INS);

    const standing = standingContext(found, "/somewhere/else") ?? "";

    expect(standing).toContain("Work this way.");

    // The whole point of the catalog is that a body is read when it is wanted.

    expect(standing).not.toContain("Read me on request.");

  });

  it("says nothing when nothing loads itself", () => {

    const found = discoverSkills(workspace({ other: NORMAL }), EMPTY_HOME, NO_BUILT_INS);

    expect(standingContext(found, "/somewhere/else")).toBeUndefined();

  });

  it("tells a session inside OpenAgents which repository is which", () => {

    // Both were worked out from scratch, repeatedly, by sessions that had no

    // way to know: one is Phoenix, the other holds the CLI.

    const standing = standingContext([], "/Users/x/work/openagents.com") ?? "";

    expect(standing).toContain("Phoenix");

    expect(standing).toContain("packages/openagents-cli");

  });

  it("says nothing about repositories anywhere else", () => {

    expect(standingContext([], "/Users/x/work/something")).toBeUndefined();

  });

});