From 6f229a86e3b21427969edf5b1d3af9d4271c89b4 Mon Sep 17 00:00:00 2001
From: YeonGyu-Kim <code.yeon.gyu@gmail.com>
Date: Sat, 13 Dec 2025 01:18:19 +0900
Subject: [PATCH] fix(background-task): change default block to false and
 clarify system notification
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Change background_output default from block=true to block=false
- Add documentation about system auto-notification on task completion
- Clarify that block=false returns full status info, not empty

🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)
---
 src/tools/background-task/constants.ts | 11 +++++++----
 src/tools/background-task/tools.ts     | 11 ++++++-----
 src/tools/call-omo-agent/constants.ts  |  3 ++-
 3 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/src/tools/background-task/constants.ts b/src/tools/background-task/constants.ts
index 019775b..361bf20 100644
--- a/src/tools/background-task/constants.ts
+++ b/src/tools/background-task/constants.ts
@@ -18,16 +18,19 @@ export const BACKGROUND_OUTPUT_DESCRIPTION = `Get output from a background task.
 
 Arguments:
 - task_id: Required task ID to get output from
-- block: If true (default), wait for task completion. If false, return current status immediately.
+- block: If true, wait for task completion. If false (default), return current status immediately.
 - timeout: Max wait time in ms when blocking (default: 60000, max: 600000)
 
 Returns:
+- When not blocking: Returns current status with task ID, description, agent, status, duration, and progress info
 - When blocking: Waits for completion, then returns full result
-- When not blocking: Returns current status and progress
+
+IMPORTANT: The system automatically notifies the main session when background tasks complete.
+You typically don't need block=true - just use block=false to check status, and the system will notify you when done.
 
 Use this to:
-- Check task progress (block=false)
-- Wait for and retrieve task result (block=true)
+- Check task progress (block=false) - returns full status info, NOT empty
+- Wait for and retrieve task result (block=true) - only when you explicitly need to wait
 - Set custom timeout for long tasks`
 
 export const BACKGROUND_CANCEL_DESCRIPTION = `Cancel a running background task.
diff --git a/src/tools/background-task/tools.ts b/src/tools/background-task/tools.ts
index 4769dea..d580551 100644
--- a/src/tools/background-task/tools.ts
+++ b/src/tools/background-task/tools.ts
@@ -46,9 +46,10 @@ Description: ${task.description}
 Agent: ${task.agent}
 Status: ${task.status}
 
-Use \`background_output\` tool with task_id="${task.id}" to check progress or retrieve results.
-- block=false: Check status without waiting
-- block=true (default): Wait for completion and get result`
+The system will notify you when the task completes.
+Use \`background_output\` tool with task_id="${task.id}" to check progress:
+- block=false (default): Check status immediately - returns full status info
+- block=true: Wait for completion (rarely needed since system notifies)`
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error)
         return `❌ Failed to launch background task: ${message}`
@@ -152,7 +153,7 @@ export function createBackgroundOutput(manager: BackgroundManager, client: Openc
     description: BACKGROUND_OUTPUT_DESCRIPTION,
     args: {
       task_id: tool.schema.string().describe("Task ID to get output from"),
-      block: tool.schema.boolean().optional().describe("Wait for completion (default: true)"),
+      block: tool.schema.boolean().optional().describe("Wait for completion (default: false). System notifies when done, so blocking is rarely needed."),
       timeout: tool.schema.number().optional().describe("Max wait time in ms (default: 60000, max: 600000)"),
     },
     async execute(args: BackgroundOutputArgs) {
@@ -162,7 +163,7 @@ export function createBackgroundOutput(manager: BackgroundManager, client: Openc
           return `Task not found: ${args.task_id}`
         }
 
-        const shouldBlock = args.block !== false
+        const shouldBlock = args.block === true
         const timeoutMs = Math.min(args.timeout ?? 60000, 600000)
 
         // Non-blocking: return status immediately
diff --git a/src/tools/call-omo-agent/constants.ts b/src/tools/call-omo-agent/constants.ts
index 0765dcf..1825585 100644
--- a/src/tools/call-omo-agent/constants.ts
+++ b/src/tools/call-omo-agent/constants.ts
@@ -11,7 +11,8 @@ When using this tool, you must specify a subagent_type parameter to select which
 
 **IMPORTANT: run_in_background parameter is REQUIRED**
 - \`run_in_background=true\`: Task runs asynchronously in background. Returns immediately with task_id.
-  Use \`background_output\` tool with the returned task_id to check progress or retrieve results.
+  The system will notify you when the task completes.
+  Use \`background_output\` tool with task_id to check progress (block=false returns full status info).
 - \`run_in_background=false\`: Task runs synchronously. Waits for completion and returns full result.
 
 Usage notes: