Update background jobs

Author: alvinunreal

.slim/cartography.json

@@ -118,4 +118,4 @@
     "src/agents": "4f804a51b82dda11e1578d37b223459d",
     "src/tools": "566ef2faddc0903ac9a7162cc6c34da5"
   }
-}
+}

src/agents/index.ts

@@ -1,4 +1,5 @@
 import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk';
+import { getSkillPermissionsForAgent } from '../cli/skills';
 import {
   type AgentOverrideConfig,
   DEFAULT_MODELS,
@@ -8,7 +9,6 @@ import {
   SUBAGENT_NAMES,
 } from '../config';
 import { getAgentMcpList } from '../config/agent-mcps';
-import { getSkillPermissionsForAgent } from '../cli/skills';
 
 import { createDesignerAgent } from './designer';
 import { createExplorerAgent } from './explorer';

src/background/background-manager.test.ts

@@ -59,7 +59,6 @@ describe('BackgroundTaskManager', () => {
       const ctx = createMockContext();
       const manager = new BackgroundTaskManager(ctx, undefined, {
         background: {
-          notifyOnComplete: true,
           maxConcurrentStarts: 5,
         },
       });
@@ -577,7 +576,7 @@ describe('BackgroundTaskManager', () => {
       expect(task2.status).toBe('cancelled');
     });
 
-    test('notifyOnComplete sends notification to parent session', async () => {
+    test('always sends notification to parent session on completion', async () => {
       const ctx = createMockContext({
         sessionMessagesResult: {
           data: [
@@ -589,7 +588,7 @@ describe('BackgroundTaskManager', () => {
         },
       });
       const manager = new BackgroundTaskManager(ctx, undefined, {
-        background: { notifyOnComplete: true, maxConcurrentStarts: 10 },
+        background: { maxConcurrentStarts: 10 },
       });
 
       const task = manager.launch({

src/background/background-manager.ts

@@ -65,7 +65,6 @@ export interface LaunchOptions {
   prompt: string; // Initial prompt to send to the agent
   description: string; // Human-readable task description
   parentSessionId: string; // Parent session ID for task hierarchy
-  notifyOnComplete?: boolean; // Whether to notify parent session on completion
 }
 
 function generateTaskId(): string {
@@ -102,7 +101,6 @@ export class BackgroundTaskManager {
     this.tmuxEnabled = tmuxConfig?.enabled ?? false;
     this.config = config;
     this.backgroundConfig = config?.background ?? {
-      notifyOnComplete: false,
       maxConcurrentStarts: 10,
     };
     this.maxConcurrentStarts = this.backgroundConfig.maxConcurrentStarts;
@@ -126,8 +124,6 @@ export class BackgroundTaskManager {
       status: 'pending',
       startedAt: new Date(),
       config: {
-        notifyOnComplete:
-          opts.notifyOnComplete ?? this.backgroundConfig.notifyOnComplete,
         maxConcurrentStarts: this.maxConcurrentStarts,
       },
       parentSessionId: opts.parentSessionId,
@@ -333,8 +329,8 @@ export class BackgroundTaskManager {
       this.tasksBySessionId.delete(task.sessionId);
     }
 
-    // Send notification if configured
-    if (task.config.notifyOnComplete && task.parentSessionId) {
+    // Send notification to parent session
+    if (task.parentSessionId) {
       this.sendCompletionNotification(task).catch((err) => {
         log(`[background-manager] notification failed: ${err}`);
       });

src/config/schema.ts

@@ -41,7 +41,6 @@ export type McpName = z.infer<typeof McpNameSchema>;
 
 // Background task configuration
 export const BackgroundTaskConfigSchema = z.object({
-  notifyOnComplete: z.boolean().default(false),
   maxConcurrentStarts: z.number().min(1).max(50).default(10),
 });
 

src/tools/background.ts

@@ -7,54 +7,41 @@ import type { BackgroundTaskManager } from '../background';
 import type { PluginConfig } from '../config';
 import { SUBAGENT_NAMES } from '../config';
 import type { TmuxConfig } from '../config/schema';
-import { applyAgentVariant, resolveAgentVariant } from '../utils';
-import { log } from '../utils/logger';
 
 const z = tool.schema;
 
-interface SessionMessage {
-  info?: { role: string };
-  parts?: Array<{ type: string; text?: string }>;
-}
-
 /**
  * Creates background task management tools for the plugin.
- * @param ctx - Plugin input context
+ * @param _ctx - Plugin input context
  * @param manager - Background task manager for launching and tracking tasks
- * @param tmuxConfig - Optional tmux configuration for session management
- * @param pluginConfig - Optional plugin configuration for agent variants
+ * @param _tmuxConfig - Optional tmux configuration for session management
+ * @param _pluginConfig - Optional plugin configuration for agent variants
  * @returns Object containing background_task, background_output, and background_cancel tools
  */
 export function createBackgroundTools(
-  ctx: PluginInput,
+  _ctx: PluginInput,
   manager: BackgroundTaskManager,
-  tmuxConfig?: TmuxConfig,
-  pluginConfig?: PluginConfig,
+  _tmuxConfig?: TmuxConfig,
+  _pluginConfig?: PluginConfig,
 ): Record<string, ToolDefinition> {
   const agentNames = SUBAGENT_NAMES.join(', ');
 
   // Tool for launching agent tasks (fire-and-forget)
   const background_task = tool({
-    description: `Run agent task in background. Returns task_id immediately - use \`background_output\` to get results.
+    description: `Launch background agent task. Returns task_id immediately.
 
 Agents: ${agentNames}.
 
-Key behaviors:
-- Fire-and-forget: Returns task_id in ~1ms without waiting for session creation
-- Multiple tasks launch in parallel (up to 10 concurrent)
-- Completion detection via session.status events (no polling)
-- Optional: Set notifyOnComplete=true to get notification when task completes`,
+To get results: call \`background_output\` with timeout (e.g., timeout=30000). Without timeout, only returns current status.
+
+Use for: long-running tasks, parallel work, non-blocking operations.`,
 
     args: {
       description: z
         .string()
         .describe('Short description of the task (5-10 words)'),
       prompt: z.string().describe('The task prompt for the agent'),
       agent: z.string().describe(`Agent to use: ${agentNames}`),
-      notifyOnComplete: z
-        .boolean()
-        .optional()
-        .describe('Notify parent session when task completes (default: false)'),
     },
     async execute(args, toolContext) {
       if (
@@ -68,15 +55,13 @@ Key behaviors:
       const agent = String(args.agent);
       const prompt = String(args.prompt);
       const description = String(args.description);
-      const notifyOnComplete = args.notifyOnComplete === true;
 
       // Fire-and-forget launch
       const task = manager.launch({
         agent,
         prompt,
         description,
         parentSessionId: (toolContext as { sessionID: string }).sessionID,
-        notifyOnComplete,
       });
 
       return `Background task launched.
@@ -91,8 +76,16 @@ Use \`background_output\` with task_id="${task.id}" to get results.`;
 
   // Tool for retrieving output from background tasks
   const background_output = tool({
-    description:
-      'Get output from background task. Returns current state immediately (no blocking).',
+    description: `Get background task results.
+
+timeout=0: returns current status immediately (no wait)
+timeout=30000: waits up to 30s for completion
+
+Recommended: use timeout when you need results. Common: 30000 (30s), 60000 (60s).
+
+Returns: results if completed, error if failed, status if running.
+
+IMPORTANT: Call once with timeout. Do NOT poll repeatedly.`,
     args: {
       task_id: z.string().describe('Task ID from background_task'),
       timeout: z
@@ -153,8 +146,12 @@ Use \`background_output\` with task_id="${task.id}" to get results.`;
 
   // Tool for canceling running background tasks
   const background_cancel = tool({
-    description:
-      'Cancel running background task(s). Use all=true to cancel all.',
+    description: `Cancel background task(s).
+
+task_id: cancel specific task
+all=true: cancel all running tasks
+
+Only cancels pending/starting/running tasks.`,
     args: {
       task_id: z.string().optional().describe('Specific task to cancel'),
       all: z.boolean().optional().describe('Cancel all running tasks'),

src/tools/grep/cli.ts

@@ -8,8 +8,8 @@ import {
   DEFAULT_TIMEOUT_MS,
   GREP_SAFETY_FLAGS,
   type GrepBackend,
-  resolveGrepCli,
   RG_SAFETY_FLAGS,
+  resolveGrepCli,
 } from './constants';
 import type { CountResult, GrepMatch, GrepOptions, GrepResult } from './types';