fix(delegate-task): default run_in_background and load_skills instead of throwing (fixes #4119)

Sisyphus and other delegators occasionally invoke the task() tool without
an explicit run_in_background or load_skills argument. The runtime
validators in tool-argument-preparation.ts threw a hard Error in that
case, which short-circuited tool.execute() entirely. Because OpenCode's
tool.execute.after hook only runs on returned results, the
delegate-task-retry hook never had a chance to attach corrective
guidance — so the model saw a raw failure and either burned several
retries or fell back to a synchronous Explore call, silently losing
parallel execution.

Behavior change:
- run_in_background omitted -> defaults to false (sync delegation), with
  a log entry for observability.
- load_skills omitted or null -> normalized to [] with a log entry on
  the explicit-null path.
- The Zod schema entries are now .optional() and their .describe()
  strings declare the defaults honestly; the markdown tool description
  was updated to match (no more 'REQUIRED' lie).

The orthogonal validation 'Must provide either category or
subagent_type.' is unchanged and still surfaces as a returned error.

Tests:
- The five throw-on-missing tests in tools.test.ts are rewritten to
  assert the new default-and-proceed contract.
- The 'no category, no subagent_type' test now asserts the
  missing-target error remains intact.

Refs the workaround the reporter validated in the original issue body;
matches the design from PR #2375 which was previously reverted by
566031f4.

src/tools/delegate-task/tool-argument-preparation.ts

@@ -29,9 +29,17 @@ export async function prepareDelegateTaskArgs(args: Record<string, unknown>, ctx
     title: description,
   })
 
-  const runInBackground = args.run_in_background
+  let runInBackground = args.run_in_background
   if (runInBackground === undefined) {
-    throw new Error("Invalid arguments: 'run_in_background' parameter is REQUIRED. Specify run_in_background=false for task delegation, or run_in_background=true for parallel exploration.")
+    // Default to sync delegation. Tool description still nudges the model to be
+    // explicit, but a missing flag should not fail an otherwise valid call —
+    // hard-failing here burns turns and silently downgrades parallel work to
+    // synchronous fallbacks. See issue #4119.
+    runInBackground = false
+    log("[task] run_in_background omitted; defaulting to false (sync delegation)", {
+      category: args.category,
+      subagent_type: originalSubagentType,
+    })
   }
 
   let loadSkills = args.load_skills
@@ -44,12 +52,16 @@ export async function prepareDelegateTaskArgs(args: Record<string, unknown>, ctx
     }
   }
 
-  if (loadSkills === undefined) {
+  if (loadSkills === undefined || loadSkills === null) {
-    throw new Error("Invalid arguments: 'load_skills' parameter is REQUIRED. Pass [] if no skills needed.")
+    // Default to no skills. Same rationale as run_in_background above: callers
-  }
+    // that omit the field already implicitly mean "no skill content needed".
-
+    if (loadSkills === null) {
-  if (loadSkills === null) {
+      log("[task] load_skills=null received; normalizing to []", {
-    throw new Error("Invalid arguments: load_skills=null is not allowed. Pass [] if no skills needed.")
+        category: args.category,
+        subagent_type: originalSubagentType,
+      })
+    }
+    loadSkills = []
   }
 
   const normalizedLoadSkills = Array.isArray(loadSkills)

src/tools/delegate-task/tool-description.ts

@@ -42,17 +42,17 @@ export function createDelegateTaskPresentation(options: DelegateTaskToolOptions)
 
   **COMMON MISTAKE (DO NOT DO THIS):**
   \`\`\`
-  task(description="...", prompt="...", run_in_background=false)  // ❌ FAILS - missing category AND subagent_type
+  task(description="...", prompt="...")  // ❌ FAILS - missing category AND subagent_type
   \`\`\`
 
   **CORRECT - Using category:**
   \`\`\`
-  task(category="quick", load_skills=[], description="Fix type error", prompt="...", run_in_background=false)
+  task(category="quick", description="Fix type error", prompt="...")
   \`\`\`
 
-  **CORRECT - Using subagent_type:**
+  **CORRECT - Using subagent_type with parallel exploration:**
   \`\`\`
-  task(subagent_type="explore", load_skills=[], description="Find patterns", prompt="...", run_in_background=true)
+  task(subagent_type="explore", description="Find patterns", prompt="...", run_in_background=true)
   \`\`\`
 
   REQUIRED: Provide ONE of:
@@ -61,12 +61,12 @@ export function createDelegateTaskPresentation(options: DelegateTaskToolOptions)
 
   **DO NOT provide both.** If category is provided, subagent_type is ignored.
 
-  - load_skills: ALWAYS REQUIRED. Pass [] if no skills needed, or ["skill-1", "skill-2"] for category tasks.
+  - load_skills: Optional. Defaults to [] when omitted. Pass ["skill-1", "skill-2"] for skill-specific tasks.
   - category: Use predefined category → Spawns Sisyphus-Junior with category config
     Available categories:
   ${categoryList}
   - subagent_type: Use specific agent directly (explore, librarian, oracle, metis, momus)
-  - run_in_background: REQUIRED. true=async (returns a background task ID like \`bg_...\` for \`background_output\`), false=sync (waits). Use background=true ONLY for parallel exploration with 5+ independent queries.
+  - run_in_background: Optional. Defaults to false (sync, waits). Set true=async (returns a background task ID like \`bg_...\` for \`background_output\`) ONLY for parallel exploration with 5+ independent queries.
     Sync waits use a 30-minute inactivity window: OpenCode busy/retry/running status resets the window, so this is not a total wall-clock limit.
   - task_id: Continuation session id (\`ses_...\`) from task metadata. Continues the same subagent session with FULL CONTEXT PRESERVED; not the background task id (\`bg_...\`).
   - command: The command that triggered this task (optional, for slash command tracking).

src/tools/delegate-task/tools.test.ts

@@ -1180,19 +1180,30 @@ describe("sisyphus-task", () => {
   })
 
   describe("skills parameter", () => {
-    test("skills parameter is required - throws error when not provided", async () => {
+    test("#given load_skills omitted #when executing #then defaults to [] and proceeds (fixes #4119)", async () => {
       // given
       const { createDelegateTask } = require("./tools")
+      let promptBody: any
 
       const mockManager = { launch: async () => ({}) }
+
+      const promptMock = async (input: any) => {
+        promptBody = input.body
+        return { data: {} }
+      }
+
       const mockClient = {
         app: { agents: async () => ({ data: [] }) },
         config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
         session: {
+          get: async () => ({ data: { directory: "/project" } }),
           create: async () => ({ data: { id: "test-session" } }),
-          prompt: async () => ({ data: {} }),
+          prompt: promptMock,
-          promptAsync: async () => ({ data: {} }),
+          promptAsync: promptMock,
-          messages: async () => ({ data: [] }),
+          messages: async () => ({
+            data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "Done" }] }]
+          }),
+          status: async () => ({ data: {} }),
         },
       }
 
@@ -1208,9 +1219,9 @@ describe("sisyphus-task", () => {
         abort: new AbortController().signal,
       }
 
-      // when - skills not provided (undefined)
+      // when - skills not provided (undefined); previously threw a hard error.
-      // then - should throw error about missing skills
+      // then - should default to [] and proceed normally.
-      await expect(tool.execute(
+      await tool.execute(
         {
           description: "Test task",
           prompt: "Do something",
@@ -1218,50 +1229,65 @@ describe("sisyphus-task", () => {
           run_in_background: false,
         },
         toolContext
-      )).rejects.toThrow("Invalid arguments: 'load_skills' parameter is REQUIRED")
+      )
-    })
 
-     test("null skills throws error", async () => {
+      expect(promptBody).toBeDefined()
-       // given
+    }, { timeout: 20000 })
-       const { createDelegateTask } = require("./tools")
 
-       const mockManager = { launch: async () => ({}) }
+    test("#given load_skills=null #when executing #then normalizes to [] and proceeds (fixes #4119)", async () => {
-       const mockClient = {
+      // given
-         app: { agents: async () => ({ data: [] }) },
+      const { createDelegateTask } = require("./tools")
-         config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
+      let promptBody: any
-         session: {
-           create: async () => ({ data: { id: "test-session" } }),
-           prompt: async () => ({ data: {} }),
-           promptAsync: async () => ({ data: {} }),
-           messages: async () => ({ data: [] }),
-         },
-       }
 
-       const tool = createDelegateTask({
+      const mockManager = { launch: async () => ({}) }
-         manager: mockManager,
-         client: mockClient,
-       })
 
-       const toolContext = {
+      const promptMock = async (input: any) => {
-         sessionID: "parent-session",
+        promptBody = input.body
-         messageID: "parent-message",
+        return { data: {} }
-         agent: "sisyphus",
+      }
-         abort: new AbortController().signal,
-       }
 
-       // when - null passed
+      const mockClient = {
-       // then - should throw error about null
+        app: { agents: async () => ({ data: [] }) },
-       await expect(tool.execute(
+        config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
-         {
+        session: {
-           description: "Test task",
+          get: async () => ({ data: { directory: "/project" } }),
-           prompt: "Do something",
+          create: async () => ({ data: { id: "test-session" } }),
-           category: "ultrabrain",
+          prompt: promptMock,
-           run_in_background: false,
+          promptAsync: promptMock,
-           load_skills: null,
+          messages: async () => ({
-         },
+            data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "Done" }] }]
-         toolContext
+          }),
-        )).rejects.toThrow("Invalid arguments: load_skills=null is not allowed")
+          status: async () => ({ data: {} }),
-    })
+        },
+      }
+
+      const tool = createDelegateTask({
+        manager: mockManager,
+        client: mockClient,
+      })
+
+      const toolContext = {
+        sessionID: "parent-session",
+        messageID: "parent-message",
+        agent: "sisyphus",
+        abort: new AbortController().signal,
+      }
+
+      // when - load_skills=null passed; previously threw "load_skills=null is not allowed".
+      // then - should normalize to [] and proceed.
+      await tool.execute(
+        {
+          description: "Test task",
+          prompt: "Do something",
+          category: "ultrabrain",
+          run_in_background: false,
+          load_skills: null,
+        },
+        toolContext
+      )
+
+      expect(promptBody).toBeDefined()
+    }, { timeout: 20000 })
 
      test("empty array [] is allowed and proceeds without skill content", async () => {
        // given
@@ -1320,25 +1346,33 @@ describe("sisyphus-task", () => {
   })
 
   describe("run_in_background parameter", () => {
-    test("#given category without run_in_background #when executing #then throws required parameter error", async () => {
+    test("#given category without run_in_background #when executing #then defaults to sync and proceeds (fixes #4119)", async () => {
       // given
       const { createDelegateTask } = require("./tools")
+      let promptBody: any
+      const promptMock = async (input: any) => {
+        promptBody = input.body
+        return { data: {} }
+      }
       const mockManager = { launch: async () => ({}) }
       const mockClient = {
         app: { agents: async () => ({ data: [] }) },
         config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
         session: {
+          get: async () => ({ data: { directory: "/project" } }),
           create: async () => ({ data: { id: "test-session" } }),
-          prompt: async () => ({ data: {} }),
+          prompt: promptMock,
-          promptAsync: async () => ({ data: {} }),
+          promptAsync: promptMock,
-          messages: async () => ({ data: [] }),
+          messages: async () => ({
+            data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "Done" }] }]
+          }),
+          status: async () => ({ data: {} }),
         },
       }
       const tool = createDelegateTask({ manager: mockManager, client: mockClient })
 
-      // when
+      // when - run_in_background omitted (previously a hard throw)
-      // then
+      await tool.execute(
-      await expect(tool.execute(
         {
           description: "Category without run flag",
           prompt: "Do something",
@@ -1346,28 +1380,39 @@ describe("sisyphus-task", () => {
           load_skills: [],
         },
         { sessionID: "parent-session", messageID: "parent-message", agent: "sisyphus", abort: new AbortController().signal }
-      )).rejects.toThrow("Invalid arguments: 'run_in_background' parameter is REQUIRED")
+      )
-    })
 
-    test("#given subagent_type without run_in_background #when executing #then throws required parameter error", async () => {
+      // then - sync path should run and the session prompt should be sent
+      expect(promptBody).toBeDefined()
+    }, { timeout: 20000 })
+
+    test("#given subagent_type without run_in_background #when executing #then defaults to sync and proceeds (fixes #4119)", async () => {
       // given
       const { createDelegateTask } = require("./tools")
+      let promptBody: any
+      const promptMock = async (input: any) => {
+        promptBody = input.body
+        return { data: {} }
+      }
       const mockManager = { launch: async () => ({}) }
       const mockClient = {
         app: { agents: async () => ({ data: [{ name: "explore", mode: "subagent" }] }) },
         config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
         session: {
+          get: async () => ({ data: { directory: "/project" } }),
           create: async () => ({ data: { id: "test-session" } }),
-          prompt: async () => ({ data: {} }),
+          prompt: promptMock,
-          promptAsync: async () => ({ data: {} }),
+          promptAsync: promptMock,
-          messages: async () => ({ data: [] }),
+          messages: async () => ({
+            data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "Done" }] }]
+          }),
+          status: async () => ({ data: {} }),
         },
       }
       const tool = createDelegateTask({ manager: mockManager, client: mockClient })
 
       // when
-      // then
+      await tool.execute(
-      await expect(tool.execute(
         {
           description: "Subagent without run flag",
           prompt: "Find patterns",
@@ -1375,39 +1420,13 @@ describe("sisyphus-task", () => {
           load_skills: [],
         },
         { sessionID: "parent-session", messageID: "parent-message", agent: "sisyphus", abort: new AbortController().signal }
-      )).rejects.toThrow("Invalid arguments: 'run_in_background' parameter is REQUIRED")
+      )
-    })
 
-    test("#given task_id without run_in_background #when executing #then throws required parameter error", async () => {
-      // given
-      const { createDelegateTask } = require("./tools")
-      const mockManager = { resume: async () => ({ id: "task-1", sessionId: "ses_1", status: "running" }) }
-      const mockClient = {
-        app: { agents: async () => ({ data: [] }) },
-        config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
-        session: {
-          create: async () => ({ data: { id: "test-session" } }),
-          prompt: async () => ({ data: {} }),
-          promptAsync: async () => ({ data: {} }),
-          messages: async () => ({ data: [] }),
-        },
-      }
-      const tool = createDelegateTask({ manager: mockManager, client: mockClient })
-
-      // when
       // then
-      await expect(tool.execute(
+      expect(promptBody).toBeDefined()
-        {
+    }, { timeout: 20000 })
-          description: "Continue without run flag",
-          prompt: "Continue",
-          task_id: "ses_existing",
-          load_skills: [],
-        },
-        { sessionID: "parent-session", messageID: "parent-message", agent: "sisyphus", abort: new AbortController().signal }
-      )).rejects.toThrow("Invalid arguments: 'run_in_background' parameter is REQUIRED")
-    })
 
-    test("#given no category no subagent_type no task_id and no run_in_background #when executing #then throws required parameter error", async () => {
+    test("#given no category no subagent_type and no run_in_background #when executing #then still returns the (different) missing-target error (fixes #4119)", async () => {
       // given
       const { createDelegateTask } = require("./tools")
       const mockManager = { launch: async () => ({}) }
@@ -1423,16 +1442,18 @@ describe("sisyphus-task", () => {
       }
       const tool = createDelegateTask({ manager: mockManager, client: mockClient })
 
-      // when
+      // when - omitting run_in_background no longer throws, but missing category+subagent_type still produces a (returned) error.
-      // then
+      const result = await tool.execute(
-      await expect(tool.execute(
         {
           description: "Missing required args",
           prompt: "Do something",
           load_skills: [],
         },
         { sessionID: "parent-session", messageID: "parent-message", agent: "sisyphus", abort: new AbortController().signal }
-      )).rejects.toThrow("Invalid arguments: 'run_in_background' parameter is REQUIRED")
+      )
+
+      // then - the missing-target error remains intact; only the run_in_background gate was removed.
+      expect(String(result)).toContain("Must provide either category or subagent_type")
     })
 
     test("#given category without description #when executing #then auto-generates description from prompt", async () => {

src/tools/delegate-task/tools.ts

@@ -21,12 +21,16 @@ export type { SyncSessionCreatedEvent, DelegateTaskToolOptions, BuildSystemConte
 export { buildSystemContent, buildTaskPrompt } from "./prompt-builder"
 
 const delegateTaskArgsSchema = {
-  load_skills: tool.schema.array(tool.schema.string()).describe("Skill names to inject. REQUIRED - pass [] if no skills needed."),
+  load_skills: tool.schema
+    .array(tool.schema.string())
+    .optional()
+    .describe("Skill names to inject. Optional; defaults to [] when omitted. Pass an explicit array (e.g. [\"git-master\"]) for skill-specific tasks."),
   description: tool.schema.string().optional().describe("Short task description (3-5 words). Auto-generated from prompt if omitted."),
   prompt: tool.schema.string().describe("Full detailed prompt for the agent"),
   run_in_background: tool.schema
     .boolean()
-    .describe("REQUIRED. true=async (returns background task ID `bg_...` for background_output), false=sync (waits). Use false for task delegation, true ONLY for parallel exploration."),
+    .optional()
+    .describe("Optional; defaults to false (sync). true=async (returns background task ID `bg_...` for background_output), false=sync (waits). Use true ONLY for parallel exploration; otherwise omit or pass false for task delegation."),
   category: tool.schema.string().optional().describe("REQUIRED if subagent_type not provided. Do NOT provide both category and subagent_type."),
   subagent_type: tool.schema.string().optional().describe("REQUIRED if category not provided. Do NOT provide both category and subagent_type."),
   task_id: tool.schema