[AviPeltz]

Summary

• Agent lifecycle hooks (notify-hook, gemini-hook) were writing debug/diagnostic lines to stderr. Hooks run as children of TUI agents (OpenCode, Claude, Gemini) with stdio inherited from the PTY, so those lines printed at the cursor position and corrupted the TUI's diff-rendered screen — interleaved [notify-hook] lines and orphaned text fragments overlaying the UI.
• All diagnostics now go exclusively to the existing debug_log file channel (/tmp/superset-agent-hooks.log, overridable via SUPERSET_HOOK_DEBUG_LOG). No hook template writes to stdout/stderr anymore (gemini-hook still prints its protocol-required {} JSON to stdout).

Why / Context

notify-hook.template.sh auto-enables debug output when SUPERSET_ENV=development, and its stderr echoes were exact duplicates of the debug_log file writes next to them. In dev builds, every agent lifecycle event (Start/Stop/PermissionRequest) sprayed log lines into the agent's TUI. Diff-rendering TUIs never recover from foreign writes: they repaint only cells they believe changed, so hook text persists as garbage and bottom-row writes desync their screen model by one line. gemini-hook.template.sh additionally had an ungated stderr echo on its v2→v1 fallback path that fired even in production.

How It Works

• notify-hook.template.sh: dropped the three stderr echoes; the event-received debug_log line now carries the full field set the echo had (adds paneId, workspaceId). The v1 dispatch was duplicated into debug/non-debug branches solely so debug mode could echo the status code — collapsed to a single branch that always captures the status and debug_logs it.
• gemini-hook.template.sh: the fallback echo now appends to the same log file (unconditional, since it's a rare failure-path signal).
• New regression test asserts no hook template contains >&2.

Debugging workflow is unchanged in capability: tail -f /tmp/superset-agent-hooks.log instead of reading interleaved (and mangled) lines inside the TUI.

Manual QA

• Rendered the template ({{MARKER}}/{{DEFAULT_PORT}} substituted) and executed it with a fake Stop payload:
  • with SUPERSET_DEBUG_HOOKS=1: stdout+stderr empty, log file receives the event line (full field set) and dispatch status line
  • without debug: stdout+stderr empty
• bash -n on both modified templates.
• Rollout is automatic: createNotifyScript() rewrites the installed notify.sh on next app launch via content comparison (no marker bump needed — hook semantics unchanged, wire payloads identical).

Testing

• bun test src/main/lib/agent-setup (73 pass, includes new no-stderr regression test)
• bun run lint
• bun run typecheck (desktop)

Known Limitations

• OpenCode's payload fields (hookSessionId/resourceId) parse as empty in the notify hook — pre-existing and unrelated to the logging channel; the Stop event still dispatches. Worth a separate ticket.

---

---

Summary by cubic

Keep agent hook debug output off the PTY to stop corrupting diff-rendered TUIs. All diagnostics now go to the hook debug log file instead of stdout/stderr.

• Bug Fixes
  • Removed all stderr echoes from notify-hook.template.sh and gemini-hook.template.sh; diagnostics append to ${SUPERSET_HOOK_DEBUG_LOG:-/tmp/superset-agent-hooks.log}. Gemini still prints only the required JSON to stdout.
  • Simplified notify-hook v1 dispatch into a single path and logged status with more context fields (paneId, workspaceId, etc.).
  • Added a regression test to ensure no hook template writes to stderr (>&2) and updated expectations for the notify script content.

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

Summary by CodeRabbit

• Bug Fixes
  • Prevented agent hook diagnostics from appearing unexpectedly in terminal output or interfering with command-line protocols.
  • Improved logging for host-service dispatch failures, including response status details and event context.
  • Preserved fallback behavior when host-service delivery is unavailable, while recording failures in the debug log.

[ghost]

Ready to review this PR? Stage has broken it down into 3 individual chapters for you:

	Title
1	Redirect notify-hook diagnostics to debug log file
2	Fix gemini-hook fallback logging to avoid PTY corruption
3	Verify hook output constraints with regression tests

_{Chapters generated by Stage for commit 819d943 on Jul 12, 2026 5:15pm UTC.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 146c6964-84ac-4049-b36b-4a8e9a07feb1

📥 Commits

Reviewing files that changed from the base of the PR and between 20191d6 and 819d943.

📒 Files selected for processing (3)

• apps/desktop/src/main/lib/agent-setup/notify-hook.test.ts
• apps/desktop/src/main/lib/agent-setup/templates/gemini-hook.template.sh
• apps/desktop/src/main/lib/agent-setup/templates/notify-hook.template.sh

---

📝 Walkthrough

Walkthrough

Hook templates now route diagnostics to configurable log files instead of stdout or stderr, while retaining host-service and v1 fallback dispatches. Tests cover detailed debug payloads and prevent stderr redirection.

Changes

Hook diagnostic logging

Layer / File(s)	Summary
Template dispatch logging apps/desktop/src/main/lib/agent-setup/templates/*.template.sh	Notify and Gemini hooks record dispatch statuses and fallback notices in debug log files without emitting stderr output.
Logging behavior tests apps/desktop/src/main/lib/agent-setup/notify-hook.test.ts	Tests verify detailed event context in debug logs and reject stderr redirection in hook templates.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• superset-sh/superset#4703: Updates the same notify and Gemini hook templates and related logging assertions.
• superset-sh/superset#5552: Connects managed notify-hook execution to the updated v2 payload and logging path.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: keeping agent hook debug logs off the PTY to avoid TUI corruption.
Description check	✅ Passed	The description covers summary, context, implementation, manual QA, and testing; only optional template sections are omitted.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/notify-hook-stderr-tui

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR moves agent hook diagnostics out of the TUI PTY. The main changes are:

• Notify hook debug output now goes through the file-backed debug log.
• Notify hook v1 dispatch now uses one status-capturing curl path.
• Gemini fallback diagnostics now append to the debug log instead of stderr.
• A regression test checks hook templates for direct stderr writes.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
apps/desktop/src/main/lib/agent-setup/templates/notify-hook.template.sh	Moves notify-hook diagnostics to debug_log and keeps v1/v2 dispatch behavior intact.
apps/desktop/src/main/lib/agent-setup/templates/gemini-hook.template.sh	Moves Gemini fallback diagnostics from stderr to the debug log while preserving required stdout output.
apps/desktop/src/main/lib/agent-setup/notify-hook.test.ts	Updates debug-log expectations and adds coverage for direct stderr redirection in hook templates.

_{Reviews (1): Last reviewed commit: "fix(desktop): keep agent hook debug logs..." | Re-trigger Greptile}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}