docs(agents): teach XML and multi-agent wait

docs/agent-profile-schema.md

@@ -145,16 +145,40 @@ Recommended body content:
 
 ## Model-facing workflow
 
-The Subagent skill teaches only:
+The Subagent skill uses the default compact XML fragments:
 
 ```bash
-devspace agents ls --json
-devspace agents targets --json
-devspace agents run <profile-or-provider> "<prompt>" --json
-devspace agents continue <id> "<prompt>" --json
-devspace agents show <id> --json
+devspace agents targets
+devspace agents ls
+devspace agents run <profile-or-provider> "<prompt>"
+devspace agents continue <id> "<prompt>"
+devspace agents show <id>
+devspace agents wait <id>...
 ```
 
+The commands do not add a document-level wrapper. `targets`, `ls`, and `wait`
+print one fragment per item and print nothing for an empty list. This keeps the
+model-facing result small:
+
+```xml
+<provider name="codex" model="gpt-5.4" effort="high"/>
+<profile name="reviewer" provider="codex">Read-only code review.</profile>
+<agent id="agt_123" status="running"/>
+<agent id="agt_123" status="completed">Review complete.</agent>
+<agent id="agt_456" status="failed" code="PROVIDER_EXECUTION_ERROR" retryable="true">Provider disconnected.</agent>
+<error code="AGENT_NOT_FOUND" retryable="false" agent-id="agt_missing">Subagent not found.</error>
+```
+
+`show` returns an immediate snapshot. `wait` accepts one or more agent IDs and
+waits for all of their current work. It does not stream fragments as individual
+agents finish. With `--timeout <seconds>`, it returns each unique agent in
+first-seen order and marks unfinished work with `status="running"
+wait="timeout"`.
+
+`--json` remains available for scripts that need it, but the bundled skill does
+not request it. Internal turn records, prompts, provider session IDs, workspace
+paths, and timestamps are absent from both output formats.
+
 `open_workspace` exposes compact profile metadata:
 
 ```json

docs/chatgpt-coding-workflow.md

@@ -144,7 +144,8 @@ Set `skills.enabled` to `false` to hide skills from workspace output. Enable
 Subagents and choose providers through `devspace init` or the persisted provider
 configuration. The bundled `subagents` skill teaches the minimal
 `devspace agents targets`, `devspace agents ls`, `devspace agents run`,
-`devspace agents continue`, and `devspace agents show` workflow. The catalog
+`devspace agents continue`, `devspace agents show`, and `devspace agents wait`
+workflow. The catalog
 comes from `open_workspace`; `devspace agents ls` lists existing subagent
 sessions for that workspace.
 

docs/configuration.md

@@ -115,6 +115,11 @@ Subagent providers are explicit. Omitted providers are disabled:
         "enabled": true,
         "model": "gpt-5.4",
         "effort": "high",
+        "command": "/opt/devspace/bin/codex-wrapper",
+        "env": {
+          "CODEX_HOME": "/home/alice/.codex-work",
+          "OPENAI_BASE_URL": "https://api.example.com/v1",
+        },
       },
       {
         "id": "claude",
@@ -130,10 +135,26 @@ Profiles are loaded from `~/.devspace/agents/*.md` and project
 `.devspace/agents/*.md`. `devspace agents targets` prints the configured targets
 available in the current workspace.
 
-Provider executable discovery remains process-scoped. The supported overrides
-are `CODEX_COMMAND`, `CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`,
-`COPILOT_COMMAND`, `GROK_COMMAND`, and `GROK_AGENT_PROFILE`. DevSpace does not
-persist provider credentials.
+`command` names one executable. DevSpace does not split shell arguments, so use
+a wrapper executable when startup needs fixed arguments. `env` maps environment
+variable names to literal string values and preserves empty strings. DevSpace
+does not expand `$NAME` references in these values.
+
+Codex, Claude, Cursor, Copilot, and Grok accept `command` and `env`. OpenCode and
+Pi are embedded, so their provider entries reject both fields. The daemon
+inherits its startup environment, then overlays the provider's `env`. An
+explicit `command` wins over both the inherited command override and a command
+override placed in `env`.
+
+Existing process-level overrides remain supported: `CODEX_COMMAND`,
+`CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`, `COPILOT_COMMAND`,
+`GROK_COMMAND`, and `GROK_AGENT_PROFILE`. Provider configuration takes
+precedence where the same value is set in both places.
+
+DevSpace writes `config.jsonc` with mode `0600`, but provider environment values
+are still plain text on disk. Keep the file out of version control. Leave
+credentials in the process environment if you do not want DevSpace to persist
+them.
 
 ## Native artifact download
 

docs/gotchas.md

@@ -218,7 +218,7 @@ When Subagents are enabled, DevSpace loads agent profiles from
 compact profile catalog through `open_workspace`. The bundled
 `subagents` skill keeps the model-facing workflow to
 `devspace agents targets`, `devspace agents ls`, `devspace agents run`,
-`devspace agents continue`, and `devspace agents show`.
+`devspace agents continue`, `devspace agents show`, and `devspace agents wait`.
 Those commands automatically manage the internal local agent daemon; `devspace
 serve` is not a prerequisite.
 `devspace agents ls` lists existing subagent sessions, not profile

docs/local-agent-daemon.md

@@ -5,7 +5,7 @@ by the MCP server and not by an individual CLI invocation. The daemon is an
 internal implementation detail: the normal workflow remains:
 
 ```text
-devspace agents run/continue/show/ls
+devspace agents targets/run/continue/show/wait/ls
           │
           ▼
     devspace-agentd
@@ -58,15 +58,24 @@ devspace agents daemon stop
 devspace agents daemon logs
 ```
 
-Agent commands accept `--json` when a machine-readable response is needed.
-They emit one compact JSON value. `run` and `continue` return only the logical
-agent ID and status, `ls` returns session summaries, and `show` returns the
-response or structured failure for one agent. Internal workspace paths,
-provider session IDs, timestamps, and prior responses are not included in list
-or receipt output. Immediate failures are emitted as
-`{ error: { code, message, retryable, ... } }` with a non-zero exit code.
-Successful `daemon status` and `daemon stop` output the daemon status object,
-and successful `daemon logs` output is `{ "logs": "<text>" }`.
+The client and daemon compare an internal revision of the provider
+configuration. A client replaces an idle daemon when that configuration has
+changed. It never stops a daemon with active work; the client returns the
+retryable `DAEMON_CONFIG_CHANGED` error until that work finishes. The revision
+is not included in status, logs, or agent command output.
+
+Model-facing agent commands emit compact XML fragments by default. Lists use
+one fragment per item without a root wrapper, and empty lists print nothing.
+`run` and `continue` return only the logical agent ID and status. `show` returns
+an immediate snapshot. `wait` blocks for one or more agents and can return a
+complete ordered snapshot at a caller-supplied timeout. It does not stream
+individual completions.
+
+Internal turns, prompts, workspace paths, provider session IDs, timestamps, and
+prior responses are not included. Immediate failures use an `<error>` fragment
+and a non-zero exit code. `--json` remains available for compatibility and
+scripts. Daemon diagnostic commands keep their existing text and JSON output;
+they do not use the model-facing XML format.
 
 Agent identity is explicit at the client boundary. `agents run` starts a new
 logical agent from a profile or provider; `agents continue <id>` continues an

docs/setup.md

@@ -65,7 +65,7 @@ npx skills add Waishnav/devspace --skill subagents --global
 ```
 
 The Skills CLI asks which installed Coding Agents should receive the skill.
-The skill uses `devspace agents targets`, `run`, `continue`, `show`, and `ls`.
+The skill uses `devspace agents targets`, `run`, `continue`, `show`, `wait`, and `ls`.
 These commands do not require `devspace serve`.
 
 ### Connect ChatGPT

skills/subagents/SKILL.md

@@ -5,49 +5,58 @@ description: Delegate focused coding, research, review, or verification work to
 
 # DevSpace subagents
 
-Use the DevSpace CLI through the shell or process tool. Run commands from the project the subagent should work on.
+Run the DevSpace CLI through the shell or process tool from the project the subagent should use. Agent commands print compact XML fragments by default. Read that output directly. Do not add `--json`.
 
 ## Choose a target
 
 Discover usable targets instead of guessing names:
 
 ```bash
-devspace agents targets --json
+devspace agents targets
 ```
 
-Configured profiles include a description and may define provider, model, effort, and task instructions. Choose a matching profile when one fits. Use a provider target when no profile fits or a specific provider is needed.
-
-Usually rely on the target's configured model and effort. Pass `--model` or `--effort` only with a value supported by that provider. DevSpace passes these values through without translating them between providers.
+Each line is a `<provider name="..."/>` or `<profile name="..." provider="...">description</profile>` fragment. Pass the profile or provider `name` as `<profile-or-provider>`. Prefer a matching profile. Use a provider target when no profile fits or the task needs a specific provider. Keep the configured model and effort unless the task requires a supported override.
 
 ## Start work
 
-Give the subagent a self-contained brief. Include the objective, relevant paths, constraints, decisions it needs from the current conversation, and the expected result. The subagent receives the brief and its profile instructions, not the parent conversation.
+Give the subagent a self-contained brief with the objective, relevant paths, constraints, context it cannot infer, and the expected result. The subagent receives this brief and its profile instructions, not the parent conversation.
 
 ```bash
-devspace agents run <profile-or-provider> "<brief>" --json
-devspace agents run <profile-or-provider> --model <model> --effort <effort> "<brief>" --json
+devspace agents run <profile-or-provider> "<brief>"
+devspace agents run <profile-or-provider> --model <model> --effort <effort> "<brief>"
 ```
 
-The result contains a DevSpace agent `id` and its current status. Execution continues independently, so retain the ID for later inspection or follow-up.
+The command returns an `<agent id="agt_..." status="running"/>` receipt. Keep the DevSpace agent ID for inspection, waiting, or follow-up.
+
+## Wait or inspect
 
-## Inspect and continue
+Use `wait` when work must finish before you proceed. One call can wait for several agents:
 
 ```bash
-devspace agents show <id> --json
-devspace agents continue <id> "<follow-up brief>" --json
-devspace agents ls --json
+devspace agents wait <id>
+devspace agents wait <id> <id> <id>
+devspace agents wait <id> <id> --timeout 60
 ```
 
-- `show` waits briefly for active work, then returns the current status and any
-  available response or error.
-- `continue` gives the same subagent another turn with its existing provider
-  session and context.
-- `ls` returns sessions belonging to the current project.
+Without `--timeout`, the command waits until every named agent's current work finishes. A timeout returns one fragment per unique agent in first-seen order; unfinished work has `status="running" wait="timeout"`. Completed output is the element text. Failures include `code` and `retryable` attributes. The command does not stream partial results.
+
+Use `show` for an immediate snapshot. Do not poll it when `wait` can express the dependency.
+
+```bash
+devspace agents show <id>
+devspace agents ls
+```
 
-Run `devspace agents show <id> --json` again later while the status is `running`.
-`completed` includes the response. `failed` includes a structured error, and
-`stopped` is terminal without a successful response. Continue an agent when its
-existing context is useful; start another agent for unrelated work.
+`ls` lists agents for the current project. Empty `targets` and `ls` results print nothing.
+
+## Continue related work
+
+Continue an agent when its existing provider context helps. Start another agent for unrelated work.
+
+```bash
+devspace agents continue <id> "<follow-up brief>"
+devspace agents wait <id>
+```
 
 ## Good uses
 

src/cli.ts

@@ -414,10 +414,12 @@ function printHelp(): void {
       "  devspace config get      Print persisted config",
       "  devspace config set publicBaseUrl <url|null>",
       "  devspace show-changes <review-ref> [--json]",
+      "  devspace agents targets [--json]  List usable subagent providers and profiles",
       "  devspace agents ls       List subagent sessions",
       "  devspace agents run <profile-or-provider> [--model <model>] [--effort <level>] <prompt>",
       "  devspace agents continue <id> [--model <model>] [--effort <level>] <prompt>",
-      "  devspace agents show <id>",
+      "  devspace agents show <id> [--json]",
+      "  devspace agents wait <id>... [--timeout <seconds>] [--json]",
       "  devspace agents daemon <status|stop|logs>",
       "  devspace -v, --version   Print the installed version",
       "",