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

type	created	question	confidence	dimensions	mcp_servers_used	local_agents_used	external_agents_used	slug	feeds_brief	research_topic
trekresearch-brief	2026-06-30	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?	0.85	4		claude-code-guide		deep-research-engine	docs/deep-research-engine-brief.md	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)