---

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.

## The Devin CLI, for a whole task

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>" --permission-mode dangerous

```

Three things about that command are worth knowing before you run it.

**`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 in `-p` mode a prompt nobody can answer is a task that does

nothing. Read `devin --help` if unsure; the values it lists are the values it

takes.

**It refuses a workspace it does not trust.** In an untrusted directory it

exits at once with `Refusing to run in an untrusted workspace`. Trust is

granted by starting `devin` interactively there once, which is something only

the person at the keyboard can do. If you hit that, say so and name the

directory rather than retrying.

**`dangerous` auto-approves every tool it has, including writes and shell.**

That is the point of using it unattended, and it is also 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.

`openagents` CLI. The `openagents` tool runs the rest of it. The same binary

answers, so what you see is this machine's build, not a remembered one.

## Find out what a command does by asking it

## Finding a command, and reading its answer

Every command documents itself. `openagents --help` lists the subcommands;

`openagents <command> --help` gives one command's flags and arguments;

`openagents <command> <subcommand> --help` goes a level deeper.

The `openagents` tool's own description lists every command and subcommand,

read from this binary. You do not need to go looking for them, and you do not

need `--help` to find out that a command exists.

Ask before you guess. This file deliberately does not list flags: a written

copy of them goes stale the first time one changes, and the help output cannot.

Use `<command> --help` for a flag you do not know. This file lists no flags on

purpose: a written copy goes stale the first time one changes, and the help

output cannot.

Add `--json` to any command to get the response as JSON rather than as prose.

Prefer it when you are going to read a field out of the answer.

**Read the plain output.** It is what a person reads and it is small. A list of

three issues is 442 bytes plain and 20,000 as JSON, because the JSON carries

every issue's whole body — and a session that reads twenty thousand bytes to

answer one question pays for them on every turn after it, too.

Add `--json` only when you need one field out of one record. Prefer a narrower

command over a wider one you then read past: `--label`, `--state`, `--limit`

and a search term cost nothing and cut the answer to what was asked.

## What works with no credential

 * reads, and a function that runs on this machine.

 */

import { spawnSync } from "node:child_process";

import { existsSync } from "node:fs";

import { fileURLToPath } from "node:url";

  return undefined;

};

/**

 * The command tree, read out of the CLI's own completion script.

 *

 * A session that did not know `issue list` existed spent two turns finding out:

 * `issue --help`, then `issue list --help`, then the command it wanted. Two

 * round-trips of a model's time to learn two words.

 *

 * So the tree goes in the tool description. It is not written down here -- it

 * is asked for once, from the binary that is running, through the completion

 * script that already enumerates every command and subcommand. One process at

 * session start, and it cannot describe a CLI other than this one.

 *

 * Flags are still left to `--help`. There are hundreds and they change; the

 * command names are few and are what the round-trips were being spent on.

 */

const commandTree = (entry: string): string | undefined => {

  const shown = spawnSync(process.execPath, [entry, "--completions", "zsh"], {

    encoding: "utf8",

    timeout: 10_000,

  });

  if (shown.status !== 0 || typeof shown.stdout !== "string") return undefined;

  const lines: string[] = [];

  // Each `commands=( … )` block belongs to the function it sits in, and that

  // function is named for the command whose subcommands it lists.

  for (const match of shown.stdout.matchAll(/_openagents(_[a-z_]*)?\(\)\s*\{([\s\S]*?)\n\}/g)) {

    const owner = (match[1] ?? "").replaceAll("_", " ").trim();

    const block = /commands=\(([\s\S]*?)\n\s*\)/.exec(match[2] ?? "");

    if (block === null) continue;

    const names = [...(block[1] ?? "").matchAll(/'([a-z][a-z0-9-]*):/g)].map((found) => found[1]);

    if (names.length === 0) continue;

    lines.push(owner.length === 0 ? `openagents ${names.join(" | ")}` : `  ${owner} ${names.join(" | ")}`);

  }

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

};

/**

 * The openagents tool: run the CLI this session is part of.

 *

 * can go stale.

 */

export function openagentsTool(): CoderTool {

  const entry = cliEntry();

  const tree = entry === undefined ? undefined : commandTree(entry);

  return {

    name: "openagents",

    description:

      "Run the OpenAgents CLI: issues, projects, repositories, the forum, authentication, and " +

      "any API route through `api`. Pass the arguments after `openagents` as a list, without " +

      "`openagents` itself. Discover what exists with `--help` on any command rather than " +

      "guessing at flags, and add `--json` when you are going to read a field out of the " +

      "answer. Reads are free; a write is visible to other people at once, so say what you are " +

      "about to write before the first one. Read the `openagents-cli` skill for the auth model " +

      "and what works with no credential.",

      "`openagents` itself.\n\n" +

      (tree === undefined ? "" : `Commands:\n${tree}\n\n`) +

      "Run `<command> --help` when you need a flag you do not know; the commands above are the " +

      "whole set, so you do not need to go looking for them.\n\n" +

      "Read the plain output. It is what a person reads and it is small: a list of three issues " +

      "is 442 bytes plain and 20,000 as JSON, because the JSON carries every issue's whole body. " +

      "Add `--json` only when you need one field out of one record, and prefer a narrower " +

      "command over a wider one you then have to read past.\n\n" +

      "Reads are free; a write is visible to other people at once, so say what you are about to " +

      "write before the first one. Read the `openagents-cli` skill for the auth model and what " +

      "works with no credential.",

    parameters: {

      type: "object",

      properties: {

      if (refusal !== undefined) return refusal;

      const { spawn } = await import("node:child_process");

      const entry = cliEntry();

      if (entry === undefined) return "This session cannot find the CLI it is running from.";

      return await new Promise<string>((resolve) => {

        });

        child.on("close", (code) => {

          // The advice has to fit what was run. This used to say "or use

          // --json" on every truncation, which for a list is the thing that

          // caused it: three issues are 442 bytes plain and 20,000 as JSON,

          // because the JSON carries every body.

          const advice = args.includes("--json")

            ? "drop --json and read the plain output, or ask for one record"

            : "narrow it with a flag such as --limit, --label, or --state";

          const bounded =

            output.length > CLI_OUTPUT_LIMIT

              ? `${output.slice(0, CLI_OUTPUT_LIMIT)}\n\n[truncated; narrow the command or use --json]`

              ? `${output.slice(0, CLI_OUTPUT_LIMIT)}\n\n[The output was cut off here. Run it again and ${advice}; what you have above is incomplete and must not be summarized as if it were the whole answer.]`

              : output;

          const body = bounded.trim();

          // The exit code is reported on failure because it is what the CLI

const STATUS_ROWS = 1;

const COMPOSER_ROWS = 3;

/**

 * One blank row between the transcript and the composer.

 *

 * The composer sat directly under the last line of the reply, so a rule was

 * doing all the work of saying where reading stops and typing starts. A line of

 * nothing does it better and costs one row.

 */

const SPACER_ROWS = 1;

/**

 * Rows the fleet block may take before it scrolls internally.

 *

        paint(rows, rows.length, 1);

        return;

      }

      const transcriptHeight = Math.max(1, height - STATUS_ROWS - COMPOSER_ROWS - 1);

      const transcriptHeight = Math.max(

        1,

        height - STATUS_ROWS - COMPOSER_ROWS - SPACER_ROWS - 1,

      );

      const fleet = fleetLines(snapshot, width);

      // The fleet takes its rows from the transcript, not from the chrome: the

      for (let row = 0; row < transcriptRows; row += 1) rows.push(lines[start + row] ?? "");

      rows.push(...fleet);

      // Bottom chrome, in the order a reader scans it: what the session is

      // doing now, then where the typing goes, then what the keys do. The

      // composer sits between two rules so it reads as its own region rather

      // Bottom chrome, in the order a reader scans it: where the typing goes,

      // what the session is doing, then what the keys do. The composer sits

      // between a blank row and a rule so it reads as its own region rather

      // than as the last line of the transcript.

      const rule = `${DIM}${"─".repeat(Math.max(0, width))}${RESET}`;

      const inner = Math.max(10, width - 4);

        where = candidate;

        break;

      }

      rows.push(`  ${justify(activity, where, inner)}`);

      // A blank row, then the composer, then what the session is doing. The

      // status line reads as a caption under the thing it describes: the reader

      // looks at where they type, and the state of the session is the next

      // thing down rather than something to scan back up for.

      rows.push("");

      rows.push(rule);

      // The composer shows its tail, never more characters than the row holds.

      // A row written past the last column makes the terminal wrap it, which

          ? `…${typed.slice(typed.length - composerRoom + 1).join("")}`

          : composer;

      rows.push(`  › ${visible}`);

      rows.push(`  ${justify(activity, where, inner)}`);

      rows.push(rule);

      // Every key named here does something in the state it is named in, and

    await expect(run(["--version"])).resolves.toContain("openagents v");

  });

  it("carries the command tree, so a session need not go looking for one", async () => {

    const { description } = openagentsTool();

    // Two round-trips of a model's time went on `issue --help` then

    // `issue list --help`, to learn two words. The tree is read from this

    // binary, so it cannot describe a CLI other than the one running.

    expect(description).toContain("Commands:");

    expect(description).toContain("issue list");

    expect(description).toContain("auth login");

  });

  it("says to read the plain output, not the JSON", async () => {

    const { description } = openagentsTool();

    expect(description).toContain("442 bytes plain and 20,000 as JSON");

  });

  it("tells a truncated --json call to drop --json, not to add it", async () => {

    // This once advised "use --json" on every truncation, which for a list is

    // the thing that caused it.

    const output = await run(["issue", "list", "-R", "OpenAgentsInc/openagents.com", "--json"]);

    if (output.includes("cut off here")) {

      expect(output).toContain("drop --json");

      expect(output).toContain("must not be summarized");

    }

  });

  it("asks for arguments rather than running something arbitrary", async () => {

    await expect(run([])).resolves.toContain("`args` is required");

  });