fix(sisyphus-task): complete overhaul of background agent model handling and sync mode

[Gladdonilli]

Summary

Complete overhaul of the background agent and sisyphus_task systems, building upon PRs #592, #610, #628, #638, #648, #649, #652, and #653.

Key Architectural Change: Push-Based Notification (Not Polling)

Background agents now use a push-based notification system instead of polling:

┌─────────────────────────────────────────────────────────────┐
│                    NOTIFICATION FLOW                        │
├─────────────────────────────────────────────────────────────┤
│  1. DETECTION: session.idle event fires                     │
│  2. GUARD: Wait MIN_IDLE_TIME_MS (5s) elapsed               │
│  3. COMPLETE: task.status = "completed"                     │
│  4. TRACK: pendingByParent.delete(task.id)                  │
│  5. CHECK: allComplete = pendingSet.size === 0              │
│  6. NOTIFY: session.prompt() to parent with noReply flag    │
└─────────────────────────────────────────────────────────────┘

The noReply Batching Pattern

await this.client.session.prompt({
  path: { id: task.parentSessionID },
  body: {
    noReply: !allComplete,  // Silent unless ALL complete
    agent: task.parentAgent,
    parts: [{ type: "text", text: notification }],
  },
})

Scenario	noReply	Effect
1 of 3 tasks done	true	Message injected silently, agent continues
2 of 3 tasks done	true	Message injected silently, agent continues
3 of 3 tasks done	false	Triggers agent response with summary

This prevents the main agent from being interrupted for each individual completion - it only "wakes up" when ALL background tasks are done.

Changes

Background Agent Completion Detection (PR #638)

• Simplified completion detection logic that was causing stuck tasks
• Tasks now complete after MIN_IDLE_TIME_MS (5s) on session.idle event
• Added 15-minute global timeout (MAX_RUN_TIME_MS) to prevent runaway tasks

Sync Mode Category Model Fix (NEW)

• Fixed bug where sync mode was NOT passing categoryModel to session.prompt()
• Category model overrides now work consistently in both sync and async modes

Model Override Architecture

Path	Model Source
category=X	Explicit from category config (passed)
subagent_type=X	Agent's configured model (at creation)
resume	Agent's configured model (not passed)

JSONC Config File Support

• Extended config detection to support both .json and .jsonc extensions
• Enables comments in config files

Test Improvements

• Increased sync resume test timeout from 5s to 10s (was flaky)

Verified Test Results (8/8 pass)

Test	Type	Mode	Result
quick	category	async	✅
ultrabrain	category	async	✅
most-capable	category	async	✅
quick	category	sync	✅
librarian	subagent	async	✅
Metis	subagent	async	✅
oracle	subagent	sync	✅
quick + git-master	category	async	✅

Known Issues (Not Regressions)

Explore Agent Hangs on Non-Exploration Tasks

Explore is a specialized codebase search agent, not general Q&A. When given non-exploration tasks, it hangs. Recommendation: Add max_steps limit in future PR.

Clickable Child Sessions Not Working

Sessions pass parentID correctly but don't appear clickable in OpenCode sidebar. kdcokenny/opencode-background-agents uses identical approach. Recommendation: May need OpenCode core change.

Files Changed

• src/features/background-agent/manager.ts
• src/tools/sisyphus-task/tools.ts
• src/tools/sisyphus-task/tools.test.ts
• src/shared/config-path.ts
• src/plugin-config.ts
• src/plugin-handlers/config-handler.ts

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa4a87d86a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep output/todo checks before completing on idle

This path now marks a task completed solely on session.idle after 5s, even though the file already notes that idle can be emitted before the agent fully starts. If a model/tool takes longer than 5s to produce its first assistant/tool output or leaves incomplete todos, this will prematurely complete the task and notify the parent with no real result (e.g., background_output returns empty). The polling path still guards with validateSessionHasOutput/checkSessionTodos, so skipping those here creates a regression for slow-start sessions; consider re‑using those guards before completing on idle.

Useful? React with 👍 / 👎.

[ShivamB25]

claude fix it for me, make no mistake

[jkoelker]

LGTM. I have been running with this patch and the series in the description all morning. I have seen no ill effects, and it subjectively feels like background agents complete more often (previous every now and then i'd get one that would "spin" and just chew tokens as the launcher checked on it).

[Gladdonilli]

more major refactor in new pr, this is now outdated