Launch and observe native subagents

Advanced workflow · Profiles · Tokens

A bridge job owns one parent Claude Code process. When the selected profile includes Agent, that parent can delegate to named native Claude Code subagents. The parent receives their results; the bridge records reported task events and exposes them to the console and SSE clients.

PNG version

Configure once

Follow the profile setup in Advanced workflows. The included profile example defines:

• planner: inspect the project and propose a focused implementation plan.
• reviewer: inspect existing changes and report concrete defects.
• Agent in the parent's allowed tools, with a reported child-task cap of four per attempt.

Bridge profiles explicitly pass these definitions through Claude Code's native --agents mechanism. A worker does not automatically inherit a host's personal plugins, project agents, or skills. See Anthropic's subagent documentation for the underlying model.

Launch from Claude Desktop or Code

Ask the host:

Call bridge_submit with profile code-workflow and mode cli.
Prompt: Use Agent to delegate a read-only review of /absolute/path/to/project
to the reviewer subagent. Summarize its findings with file paths and evidence.
Return the job ID so I can follow it in the bridge console.

The host submits the request to a dedicated worker, which performs the review through its configured subagent.

Launch from the console

Choose New job → Execution profile: code-workflow → Configured local coding-agent worker. Enter the same prompt and queue it. Select the job and inspect Child tasks and the activity stream.

Launch from an application

curl --fail-with-body "$BRIDGE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"bridge/code-workflow","messages":[{"role":"user","content":"Use Agent to delegate a read-only review of /absolute/path/to/project to the reviewer subagent. Return findings with file paths and evidence."}],"bridge":{"execution":"agent","background":true}}'

Standard inference requests disable native Agent tools; use bridge.execution: "agent" for delegation. Client-side Pydantic AI functions are a separate execution mechanism explained in the SDK guide.

The client token must include read for inspection and submit for admission, and allow code-workflow. Grant control when it also needs execution controls.

Observe and control

job.subagent events contain the native task ID and reported status. The current job's subagents map is visible through bridge_job, the job API, and the console. Progress depends on the events emitted by the installed Claude Code version.

Pause or cancel the parent job to stop its owned process tree. Children do not have separate bridge job IDs or individual pause endpoints. The child cap applies to reported tasks in one attempt, not to a persistent shared pool of agents. Profiles prevent Agent in the configured child's own tool list.

If no child task appears, confirm the selected profile includes Agent and the named definition, inspect the job's error/result, and verify that Claude actually delegated. The bridge does not invent a completed child task merely because the prompt requested one.

Open the parent job's Activity tab to inspect the Agent invocation and emitted child tool calls. Expand Advanced record to see the parent tool ID and session metadata. Files includes reported child file actions. See execution audit for full payloads and coverage.

Host skills

The Claude Code and Codex plugins include the bridge operation skill. It checks readiness before submission, uses the durable job and workflow tools, distinguishes resume from retry, and keeps tokens out of chat. The skill guides the host's tool sequence; it does not change the selected worker or grant native permissions.

Worker processes do not inherit arbitrary host plugins or personal skills. Put task-specific instructions in the prompt or saved workflow. Claude native specialists belong to the configured profile; Codex uses its own native thread behavior.