voyage/docs/deep-research-engine-research.md

---
type: trekresearch-brief
created: 2026-06-30
question: "Can a Claude Code plugin command programmatically trigger the built-in /deep-research workflow and capture its report, or must it instruct Claude to run it?"
confidence: 0.85
dimensions: 4
mcp_servers_used: []
local_agents_used: [claude-code-guide]
external_agents_used: []
slug: deep-research-engine
feeds_brief: docs/deep-research-engine-brief.md
research_topic: 1
---

# Research — Programmatic trigging of `/deep-research` from a plugin command

> Targeted single-topic research for the `deep-research-engine` brief (Topic 1 of
> the brief's Research Plan). Topics 2 & 3 are local Voyage-code questions folded
> into `/trekplan` exploration; only Topic 1 was a genuine external unknown.
> Method: `claude-code-guide` agent (Anthropic docs + CHANGELOG, cited) +
> direct inspection of this machine (CC 2.1.196 binary, a real local `/deep-research`
> run). Not run through the `/trekresearch` swarm — see brief reconcile note.

## Research Question

Can a Claude Code **plugin slash-command** (markdown under `commands/`)
**programmatically** start the built-in `/deep-research` workflow and **capture its
report artifact** for adaptation into the research-brief schema — or must the command
instead **instruct** Claude (in prose) to run `/deep-research` and then transform the
in-context result?

## Executive Summary

Programmatic trigger + file-based capture is **not feasible**: `/deep-research` is a
built-in **dynamic workflow** (not a skill), deliberately outside the Skill-tool
allowlist, and it returns its report **inline into conversation context with no
documented on-disk report artifact**. The **only reliable path is instruction-based
delegation** — the command's prose tells Claude to run `/deep-research <q>`, then
transforms the in-context report in the same turn. Confidence **high** (Anthropic docs +
CHANGELOG + local run), with one residual gap: there is no positive "is it enabled?"
probe, so feature-detection must lean on the documented *disable* switches + version
floor + a `swarm` default.

## Dimensions

### 1. Origin + gating -- Confidence: high

**External findings:**
- `/deep-research` is a **built-in dynamic workflow**, not a command and not a bundled
  skill. `commands.md` marks the `/deep-research <question>` row as **[Workflow]**;
  `workflows.md`: "Claude Code includes `/deep-research` as a built-in workflow."
  [VERIFIED — code.claude.com/docs/en/commands.md, code.claude.com/docs/en/workflows.md]
- Gating: available on **all paid plans** (pro/max/team/enterprise) + API/Bedrock/Vertex/
  Foundry. **On Pro it must be turned on** in the *Dynamic workflows* row of `/config`.
  Also requires the **WebSearch tool** to be available.
  [VERIFIED — workflows.md, commands.md bundled-workflows row]
- Version floor: dynamic workflows were **introduced in CC 2.1.154**; "Dynamic workflows
  require Claude Code v2.1.154 or later." The brief's `v2.1.154+` + `(Pro: via /config)`
  constraints are **both correct**. The exact version that first shipped the *named*
  `/deep-research` workflow is **[NOT DOCUMENTED]** (only a 2.1.196 bugfix mentions it by
  name) — treat 2.1.154 as the substrate floor, not a proven introduction point.
  [VERIFIED — workflows.md + CHANGELOG 2.1.154]

**Local findings:**
- This machine runs **CC 2.1.196** (`claude --version`) — substrate floor satisfied.
- The exact skill-description string lives **compiled into the binary**
  (`/Users/ktg/.local/share/claude/versions/2.1.196`, Mach-O 235 MB); there is **no
  `SKILL.md`** for it anywhere under `~/.claude` (system-wide `find`/`grep` — only hits
  are this brief + unrelated harness notes). Confirms "Anthropic-bundled, not user skill."

### 2. Invocation mechanism (programmatic vs instruction) -- Confidence: high

**External findings:**
- **Not** via the `Skill` tool. The Skill-tool built-in allowlist is closed: only
  `/init`, `/review`, `/security-review` are reachable; "Other built-in commands such as
  `/compact` are not." `/deep-research` is a Workflow and is not on that list.
  [VERIFIED — code.claude.com/docs/en/skills.md]
- **Instruction-based delegation is the documented mechanism.** Workflows launch when the
  user types the command, or **when Claude is asked in natural language** ("use a
  workflow" / "run a workflow") or via the `ultracode` keyword. A plugin command whose
  markdown instructs Claude to run `/deep-research <q>` is therefore the supported path.
  [VERIFIED — workflows.md "Have Claude write a workflow"]
- **Approval gate caveat:** launching a workflow triggers a per-run approval prompt —
  *every run* in default/acceptEdits; *first launch only* in auto; **never in `claude -p`
  / Agent SDK / bypass-permissions** ("the run starts immediately"). Voyage's headless
  surface (`claude -p`) thus delegates without an interactive gate; interactive sessions
  hit a prompt. [VERIFIED — workflows.md "Behavior and limits"]
- No documented blanket "commands/skills cannot nest" prohibition beyond the Skill-tool
  allowlist + workflow runtime limits (no mid-run user input; 16 concurrent agents;
  1000 agents/run). [VERIFIED — workflows.md; NOT DOCUMENTED for a general nesting ban]

### 3. Output capture -- Confidence: high

**External findings:**
- "When the run finishes, **the report lands in your session**"; "Claude's context holds
  only the final answer." The report is **in-context**, not a file.
  [VERIFIED — workflows.md]
- What *is* written to disk is the orchestration **script**, not the report: "Every run
  writes its script to a file under your session's directory in `~/.claude/projects/`."
  [VERIFIED — workflows.md "How a workflow runs"]

**Local findings:**
- A real `/deep-research` run on this machine left exactly one file —
  `~/.claude/projects/<session>/workflows/scripts/deep-research-wf_<id>.js` — and **no
  `.md` report** beside it. [VERIFIED — local filesystem inspection by claude-code-guide]
- **Consequence:** a calling command cannot `grep` a results file off disk (none is
  documented to exist). It can only consume the report **as it sits in conversation
  context in the same turn** — Claude reads its own prior output and transforms it into
  research-brief schema. [INFERENCE — file-based capture not feasible; in-context
  transform is the only avenue]

### 4. Feature detection + fallback -- Confidence: medium

**External findings:**
- **No positive enumeration / "is-enabled" API or flag is documented.** `claude --help`
  exposes `--disable-slash-commands` but no "list skills/workflows" or "is-feature-on"
  flag. [VERIFIED — local `claude --help`; NOT DOCUMENTED for any positive probe]
- The documented signals are the **off-switches**, read defensively: `/config` Dynamic-
  workflows off; `disableWorkflows: true` / `disableBundledSkills: true` in settings.json;
  `CLAUDE_CODE_DISABLE_WORKFLOWS=1` / `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1`.
  [VERIFIED — workflows.md "Turn workflows off"; CHANGELOG 2.1.x]
- **The gap:** the Pro `/config` *on*-state is the very thing you most need to detect, and
  only the *disable* keys are documented; the persisted key/value for the Pro enable-state
  is **[NOT DOCUMENTED]**, so it cannot be reliably grepped. A failed/disabled
  `/deep-research` is also **not documented** to raise a signal a sibling command can
  catch. [VERIFIED gap]

**Local findings:**
- On this machine both disable keys are unset/absent — workflows are not disabled.

## External Knowledge

### Best Practice
The "Have Claude write a workflow" + "Behavior and limits" sections of `workflows.md`
establish that workflows are operator/Claude-launched, run isolated, and return one
in-context report. The Skill-tool allowlist (`skills.md`) is the authoritative statement
that only three built-ins are tool-invocable.

### Known Issues
Per-run approval prompts outside `-p`/SDK/bypass mean an interactive `/trekresearch
--engine deep-research` will pause for operator approval on each launch — acceptable, but
worth documenting in the command UX. The absence of a positive availability probe is the
single biggest design constraint (see Dimension 4).

## Synthesis

Three cross-cutting insights that only emerge from combining the docs with Voyage's brief:

1. **The brief's SC3 is correct as written — an earlier review note was wrong.** Because
   `/deep-research` *is itself* a dynamic workflow, "med dynamic workflows avskrudd faller
   `--engine deep-research` tilbake til swarm" is the right feature-detection axis. A
   prior brief-review remark that SC3 "conflated `/deep-research` (skill) with dynamic
   workflows" was based on a wrong premise (that `/deep-research` was a skill) and is
   retracted. **No SC3 brief edit is needed.**

2. **The engine must be instruction-based + in-context, never file-based.** Topic 1's
   open question ("instruction (safe) vs. programmatic API (faster) — topic 1 decides")
   resolves decisively to **instruction-based**: there is no programmatic API and no
   on-disk report. The `deep-research` engine path in `commands/trekresearch.md` must
   (a) instruct Claude to run `/deep-research <q>`, then (b) transform the in-context
   report into the `research/NN-*.md` schema in the same turn. This is surface-only
   (`commands/` prose), matching the brief's "ingen nye `lib/`-avhengigheter."

3. **SC3's "ingen exception" cannot rest on runtime detection — pin it to a default.**
   Since no positive availability probe exists, robust fallback = version-floor check
   (≥ 2.1.154) + disable-key heuristic (`disableWorkflows` / env) + **`--engine` default
   of `swarm`** (explicit opt-in). The fallback is "graceful degradation by design,"
   not "catch an exception at runtime." This refines, but does not contradict, SC3.

## Open Questions

- **Adapter fidelity (brief Topic 2, partly answered locally):** `research-validator.mjs`
  requires `type: trekresearch-brief` + `created` + `question`; validates `confidence ∈
  [0,1]` and `dimensions ≥ 1` if present; body must carry `## Executive Summary` +
  `## Dimensions`. So the `/deep-research` report **can** be reduced to ≥ 1 dimension with
  per-claim citations and a confidence number — the brief's assumption holds. The
  remaining open part (how cleanly the in-context report maps to per-dimension
  local/external splits) is a `/trekplan` exploration concern, not an external unknown.
- **Exact intro version of the *named* `/deep-research` workflow** — not documented; the
  2.1.154 dynamic-workflows floor is the safe pin.

## Recommendation

Build the `deep-research` engine as **instruction-based delegation with in-context
adaptation**, not a programmatic trigger:
1. `--engine deep-research` makes `commands/trekresearch.md`'s external phase instruct
   Claude to run `/deep-research <q>` and transform the returned in-context report into
   `research/NN-*.md` (validator-conformant: `## Executive Summary` + `## Dimensions`,
   `confidence`, `dimensions ≥ 1`).
2. Feature-detect by **graceful degradation**: version floor + disable-key heuristic +
   `--engine` default `swarm`. Do not depend on a positive availability probe (none
   exists). Log the chosen engine. This satisfies SC3 without a runtime exception.
3. Keep `swarm` the default (brief's Non-Goal: "ikke default-bytte"). Document the
   per-run approval prompt for interactive (non-`-p`) sessions.

Confidence in the recommendation: **high** for the mechanism (instruction-based +
in-context), **medium** for the exact fallback-detection ergonomics (the one documented
gap). This is sufficient to green-light `/trekplan` with Topic 1 resolved.

## Sources

| # | Source | Type | Quality | Used in |
|---|--------|------|---------|---------|
| 1 | code.claude.com/docs/en/workflows.md | official | high | Dim 1,2,3,4 + Synthesis |
| 2 | code.claude.com/docs/en/commands.md | official | high | Dim 1 (Workflow classification, WebSearch req) |
| 3 | code.claude.com/docs/en/skills.md | official | high | Dim 2 (Skill-tool allowlist) |
| 4 | github.com/anthropics/claude-code CHANGELOG (2.1.154, 2.1.x, 2.1.196) | official | high | Dim 1,4 (version floor, disable keys) |
| 5 | Local: CC 2.1.196 binary inspection (`find`/`grep`, `claude --version`) | codebase | high | Dim 1 (bundled, no SKILL.md) |
| 6 | Local: real `/deep-research` run — only `.js` script written, no `.md` report | codebase | high | Dim 3 (no on-disk artifact) |
| 7 | Local: `lib/validators/research-validator.mjs` schema | codebase | high | Open Questions (adapter feasibility / Topic 2) |