Merge pull request #2374 from deepseek-harness/codex/product-subagent-one-shot-background

feat(agent-presets): enable background Codex and Claude Code subagent tasks

examples/acp-agent/cordis.yml

@@ -123,7 +123,8 @@
 
 # Fork stays one-shot because a continuable child's `report` tool and prompt
 # section precede the inherited history a fork reuses; `run_in_background` is off
-# because this example mounts no task service. See .agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md.
+# as an explicit foreground-only choice even though agent-spine-demo mounts the
+# generic Job runtime. See .agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md.
 - id: tool-subagent-fork
   name: '@deepseek-ai/dsh-tool-subagent'
   config:

examples/acp-agent/product-subagent-both.cordis.snapshot.yml

@@ -27,12 +27,12 @@
             config:
               provider: codex
               toolName: subagent_codex
-              enableRunInBackground: false
+              backgroundMode: one-shot
               maxDepth: provider-managed
           - id: tool-subagent-claude-code
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
               provider: claude-code
               toolName: subagent_claude_code
-              enableRunInBackground: false
+              backgroundMode: one-shot
               maxDepth: provider-managed

examples/acp-agent/product-subagent-both.cordis.yml

@@ -1,5 +1,5 @@
-# Add both native product providers and the same independent foreground tool
-# rows an Agent Preset may contribute. Loading the composition starts neither
+# Add both native product providers and the same independent one-shot tool rows
+# an Agent Preset may contribute. Loading the composition starts neither
 # product; the scenario pins both model-visible schemas.
 - id: base
   name: '@deepseek-ai/cordis-plugin-include'
@@ -16,12 +16,12 @@
             config:
               provider: codex
               toolName: subagent_codex
-              enableRunInBackground: false
+              backgroundMode: one-shot
               maxDepth: provider-managed
           - id: tool-subagent-claude-code
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
               provider: claude-code
               toolName: subagent_claude_code
-              enableRunInBackground: false
+              backgroundMode: one-shot
               maxDepth: provider-managed

examples/acp-agent/product-subagent-codex.cordis.snapshot.yml

@@ -25,5 +25,5 @@
             config:
               provider: codex
               toolName: subagent_codex
-              enableRunInBackground: false
+              backgroundMode: one-shot
               maxDepth: provider-managed

examples/acp-agent/product-subagent-codex.cordis.yml

@@ -1,4 +1,4 @@
-# Add the native Codex product provider and its preset-shaped foreground tool to
+# Add the native Codex product provider and its preset-shaped one-shot tool to
 # the real ACP composition. The model is told not to call it; the scenario pins
 # the assembled request schema without starting Codex.
 - id: base
@@ -14,5 +14,5 @@
             config:
               provider: codex
               toolName: subagent_codex
-              enableRunInBackground: false
+              backgroundMode: one-shot
               maxDepth: provider-managed

examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml

@@ -1,4 +1,4 @@
-# Test-only composition of both public opt-in providers and foreground tools.
+# Test-only composition of both public opt-in providers and one-shot task tools.
 # The owning e2e boots this tree but never invokes a model or product process.
 - id: fixture
   name: './fixture.ts'
@@ -20,7 +20,7 @@
   config:
     provider: codex
     toolName: subagent_codex
-    enableRunInBackground: false
+    backgroundMode: one-shot
     maxDepth: 'provider-managed'
 
 - id: tool-subagent-claude-code
@@ -28,7 +28,7 @@
   config:
     provider: claude-code
     toolName: subagent_claude_code
-    enableRunInBackground: false
+    backgroundMode: one-shot
     maxDepth: 'provider-managed'
 
 - id: agent-spine

examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/driver.ts

@@ -53,11 +53,16 @@ try {
       required: tool.parameters.required,
     }
   })
+  const jobTools = ctx.tools.schemas()
+    .map(schema => schema.name)
+    .filter(name => name === 'job_kill' || name === 'job_list' || name === 'job_output')
+    .sort()
 
   process.stdout.write(`${JSON.stringify({
     registeredProviders: ctx.subagents.list(),
     providers,
     tools,
+    jobTools,
     starts,
   })}\n`)
 } finally {

examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml

@@ -1,4 +1,4 @@
-# Test-only composition of the public opt-in provider and foreground tool.
+# Test-only composition of the public opt-in provider and one-shot task tool.
 # The owning e2e boots this tree but never invokes the model or Codex.
 - id: fixture
   name: './fixture.ts'
@@ -17,7 +17,7 @@
   config:
     provider: codex
     toolName: subagent_codex
-    enableRunInBackground: false
+    backgroundMode: one-shot
     maxDepth: 'provider-managed'
 
 - id: agent-spine

examples/acp-agent/tests/fixtures/subagent/subagent-codex/driver.ts

@@ -31,6 +31,10 @@ try {
   if (typeof properties !== 'object' || properties === null || Array.isArray(properties)) {
     throw new Error('subagent_codex tool has invalid parameter properties')
   }
+  const jobTools = ctx.tools.schemas()
+    .map(schema => schema.name)
+    .filter(name => name === 'job_kill' || name === 'job_list' || name === 'job_output')
+    .sort()
 
   process.stdout.write(`${JSON.stringify({
     providers: ctx.subagents.list(),
@@ -44,6 +48,7 @@ try {
       parameterNames: Object.keys(properties).sort(),
       required: tool.parameters.required,
     },
+    jobTools,
     starts,
   })}\n`)
 } finally {

examples/acp-agent/tests/snapshots/product-subagent-both/tool-schemas.expected.json

@@ -308,7 +308,7 @@
     },
     {
       "name": "subagent_claude_code",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the subagent and returns its result.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -319,6 +319,10 @@
           "prompt": {
             "type": "string",
             "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
           }
         },
         "required": [
@@ -329,7 +333,7 @@
     },
     {
       "name": "subagent_codex",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the subagent and returns its result.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -340,6 +344,10 @@
           "prompt": {
             "type": "string",
             "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
           }
         },
         "required": [

examples/acp-agent/tests/snapshots/product-subagent-codex/tool-schemas.expected.json

@@ -308,7 +308,7 @@
     },
     {
       "name": "subagent_codex",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the subagent and returns its result.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -319,6 +319,10 @@
           "prompt": {
             "type": "string",
             "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
           }
         },
         "required": [

examples/headless-agent/cordis.yml

@@ -120,7 +120,8 @@
 
 # Fork stays one-shot because a continuable child's `report` tool and prompt
 # section precede the inherited history a fork reuses; `run_in_background` is off
-# because this example mounts no task service. See .agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md.
+# as an explicit foreground-only choice even though agent-spine-demo mounts the
+# generic Job runtime. See .agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md.
 - id: tool-subagent-fork
   name: '@deepseek-ai/dsh-tool-subagent'
   config: