Subagent

What the source does

• FilesystemDeclared5 observations
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

import { executeSubagentAbort } from "../../../../tools/subagent/abort.js";

} from "../../../../tools/types.js";

import { executeSubagentMessage } from "../../../../tools/subagent/message.js";

} from "../../../../tools/types.js";

import { executeSubagentRead } from "../../../../tools/subagent/read.js";

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/assistant/src/config/bundled-skills/subagentThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Spawn and manage autonomous background agents for parallel work

---
name: subagent
description: Spawn and manage autonomous background agents for parallel work
compatibility: "Designed for Vellum personal assistants"
metadata:
  emoji: "🤖"
  vellum:
    display-name: "Subagent"
    category: "system"
    activation-hints:
      - "Spawn a background worker that runs in parallel with the main turn"
      - "Delegate a self-contained research or implementation task off the main thread"
      - "Multiple agents at once, or a context-inheriting fork"
    avoid-when:
      - "Task is small enough to do inline (a handful of tool calls, quick lookups or reads)"
      - "User wants Claude Code or Codex — use the acp skill instead"
---

Subagent orchestration -- spawn background agents to work on tasks in parallel.

## Lifecycle

Subagents follow this status flow: `pending` -> `running` -> `completed` / `failed` / `aborted`

- **Spawn**: Use `subagent_spawn` with a label, objective, and type. The subagent runs autonomously.
- **Mid-run communication**: Subagents can send notifications to the parent via `notify_parent` while still running -- useful for sharing interim findings or signaling that they are blocked.
- **Auto-notification**: The parent conversation is automatically notified when a subagent reaches a terminal status (completed/failed/aborted). Do NOT poll `subagent_status`.
- **Read output**: Use `subagent_read` after the subagent reaches a terminal status to retrieve its full output.

## Types

There are three subagent types. Every one of them runs in the background: the spawn call returns straight away with an id, and the result reaches you as a notification. Pick one with two questions: **does it need to change anything**, and **what do you want back**?

`recall` is local information search across memory, the personal knowledge base, past conversations, and workspace files. Use it when a subagent needs prior context that is not already in the prompt.

| Type | Changes things? | Gives you back | Tools | When to use |
|---|---|---|---|---|
| `researcher` | No | Findings | `web_search`, `web_fetch`, `file_read`, `file_list`, `code_search`, `recall`, `skill_execute`, `notify_parent` | Web research, codebase exploration, reading documentation, root-cause investigation, reviewing an approach against the code |
| `builder` | Yes | Work done | Your whole tool surface, unrestricted: shell, file writes and edits, and every connector, MCP, and browser tool you can reach | Code changes, file output, build/test runs, anything that must run a command or act on an outside system |
| `advisor` | No | Guidance | Read-only fact checking in the workspace: `file_read`, `file_list`, `code_search` | Read-only senior-advisor consult. Reads the brief you write in `objective` and answers on a stronger model |

`researcher` and `builder` can call `notify_parent` for mid-run communication with the parent.

A `researcher` is scoped to the fixed read-only list above: it cannot write or edit files, run commands, reach a connector, or otherwise persist output. If the task must **produce a file, save results, run a command, or act on an outside system**, spawn a `builder`: a researcher finishes without producing anything, and the delegated write silently no-ops.

**Model tier is a separate knob.** Use `inference_profile` to run any type on a stronger or cheaper model. **A persona is not a type**: see the fallback below.

### Legacy names and unknown roles

The older role names still work: `planner` and `investigator` run as a `researcher`, `coder` and `general` run as a `builder`. The spawn result names the type that actually ran.

Any other `role` text is treated as a persona, not a type. The subagent runs as a **`researcher`** (read-only) with that text framing how it approaches the task, and the spawn result says so. That is deliberate least privilege: an invented or misspelled role must never silently hand out write access. If the task genuinely needed to write, the subagent reports that it cannot, and you re-spawn it with `role: "builder"`.

Omitting `role` entirely runs a `builder`, so a spawn that names no type keeps your full tool surface.

### Verification

Checking that something is actually done is not a fourth type. It is a `researcher` with `output_contract: "verdict"`.

A verdict subagent returns, for each criterion in the objective, `PASS` or `FAIL` plus the exact evidence (file path, line, value, or quote), `CANNOT VERIFY` where the evidence is missing, and nothing else. Give it the criteria explicitly in the objective; a vague "check the work" gets you a vague list.

It runs on a cheaper model by default, because checking a claim against evidence that already exists is mechanical work, not investigation. An explicit `inference_profile` still wins if a check genuinely needs a stronger model, and so does a profile pinned on the `subagentSpawn` call site in config (see Inference Profile below).

The other contracts: `output_contract: "artifact"` tells a `builder` that the deliverable is the thing produced and to end by listing the exact files it created or modified. `"report"` is the default and asks for nothing extra. A contract that does not match the type is rejected rather than quietly changed, and the `advisor` takes no contract (it has its own framing).

## Consulting the Advisor

The `advisor` is the one type you may spawn on your own judgment, unprompted: you do not wait for the user to ask for a subagent. The background types (`researcher`, `builder`) stay delegation-driven: reach for them to offload work, typically when the user's request calls for it.

A consult is expensive (a stronger model reviews your brief and answers), so reserve it for moments where a second perspective can genuinely change the outcome. Most tasks need no consult at all: a routine task with an obvious approach does not require sign-off, before you start or after you finish. Orient yourself first (read the relevant files, understand the task), then consult the advisor:

- **Before

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 19bc86343b63

Questions about Subagent

• github.com/vellum-ai/vellum-assistant/tree/main/assistant/src/co — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology