feat(background): optional tool-output completion notifications for delegated tasks

[dankochetov]

Summary

• Add an experimental alternative to the background-notification prompt-injection path: experimental.background_notifications_via_tool_output.
• When enabled, background task completion updates are appended to the next regular tool.execute.after output in the same session, then cleared from queue.
• Disable parent session.prompt injection while this mode is active, preserving toast notifications.
• Add integration coverage for the tool.execute.after pipeline and stabilize background-update-check tests so full suite remains green.

Why

This provides a practical option for GitHub Copilot users on metered/premium plans: delegated-task status can be surfaced without synthetic reminder prompts that consume premium requests.

Trade-off

This mode can delay agent awareness of delegated-task completion until the next tool execution in the parent session. It saves premium requests at the cost of potentially delayed status visibility.

Config

Enable in oh-my-opencode.jsonc:

{
  "experimental": {
    "background_notifications_via_tool_output": true
  }
}

Validation

• bun test (full suite)
• bun run typecheck
• bun run build

---

Summary by cubic

Adds an experimental mode that appends background task updates to the next tool.execute.after output instead of injecting reminder prompts. Preserves updates under truncation via pipeline ordering while keeping toast notifications.

• New Features

  • Added experimental.background_notifications_via_tool_output to append queued updates to the next tool.execute.after output and then clear them; disables parent session prompt-injection notifications while enabled (toasts remain).
  • Introduced background-tool-output-notifier hook and wired it into the tool.execute.after pipeline; updated schema and docs.

• Bug Fixes

  • Reordered tool.execute.after so updates are appended before truncation/compaction/context monitoring; sanitizes multiline text, truncates long fields, and writes only the notification block when tool output is empty.
  • Auto-update checker: pinned versions and install failures now fall back to notification-only; improved dependency injection and stabilized tests with fresh module imports.
  • Comment-checker: returns early for non-apply_patch tools without a pending call to avoid unnecessary processing.

^{Written for commit de5c279. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 13 files

Confidence score: 3/5

• There is a concrete user-impact risk: appended background notifications can bypass output truncation and context window monitoring due to the execution order in src/plugin/tool-execute-after.ts.
• This is a moderate-severity (6/10) behavior change, so while likely fixable, it could affect output limits at runtime.
• Pay close attention to src/plugin/tool-execute-after.ts - pipeline order allows notifications to skip truncation/context checks.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/plugin/tool-execute-after.ts">

<violation number="1" location="src/plugin/tool-execute-after.ts:46">
P2: Appended background notifications bypass output truncation and context window monitoring due to pipeline execution order.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[Copilot]

Pull request overview

Adds an experimental alternative background-task completion notification path that appends queued completion summaries to the next tool.execute.after output (instead of injecting synthetic parent session.prompt turns), along with config/docs updates and test stabilization for the auto-update checker.

Changes:

• Add background_notifications_via_tool_output experimental flag and documentation/schema coverage.
• Introduce background-tool-output-notifier hook and wire it into the tool.execute.after pipeline.
• Refactor runBackgroundUpdateCheck to support dependency overrides and update tests to use the new injection style.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/plugin/tool-execute-after.ts	Adds the new notifier hook into the tool.execute.after hook pipeline.
src/plugin/tool-execute-after.test.ts	Adds integration coverage ensuring the notifier participates in the pipeline when present.
src/plugin/hooks/create-continuation-hooks.ts	Creates the notifier hook when the experimental flag is enabled and exposes it via created hooks.
src/hooks/index.ts	Re-exports the new hook factory from the hooks barrel.
src/hooks/background-tool-output-notifier/index.ts	Adds barrel export for the new hook module.
src/hooks/background-tool-output-notifier/index.test.ts	Adds unit tests for formatting/clearing behavior of the notifier hook.
src/hooks/background-tool-output-notifier/hook.ts	Implements the tool-output-based notification appending + queue clearing.
src/hooks/auto-update-checker/hook/background-update-check.ts	Refactors update check to accept dependency overrides and adjusts bun install invocation.
src/hooks/auto-update-checker/hook/background-update-check.test.ts	Updates tests to call runBackgroundUpdateCheck with injected dependencies.
src/create-managers.ts	Disables parent-session prompt injection when tool-output notifications mode is enabled (toasts remain).
src/config/schema/experimental.ts	Adds the new experimental config flag to the schema.
src/config/schema.test.ts	Adds schema test coverage for the new experimental flag.
docs/configurations.md	Documents the new experimental option and its behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dankochetov]

Addressed all review feedback.

• Reordered tool.execute.after so taskResumeInfo runs before background notifier append.
• Ensured truncation/compaction/context monitoring run after appending background updates.
• Wrapped backgroundToolOutputNotifier creation in safeHook and included hook name in HookNameSchema.
• Sanitized appended task description/error text and added coverage for multiline + long cases.
• Removed unreachable pinned-version revert branch in background auto-update failure path.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dankochetov]

Addressed the latest review items.

• Notification block is now prepended so it survives header-preserving truncation and won’t be dropped before queue clear.
• backgroundToolOutputNotifier now honors disabled_hooks via isHookEnabled("background-tool-output-notifier").
• commentChecker now returns early for non-apply_patch calls with no pending write/edit call before scanning tool output, avoiding unnecessary large-string scans.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dankochetov]

@cubic-dev-ai re-review

[cubic-dev-ai]

@cubic-dev-ai re-review

@dankochetov I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 17 files

Confidence score: 5/5

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

_{Requires human review: Large refactor with 757 lines changed may cause regressions; AI review found no issues but criteria require 100% sure no regressions.}