Grok agent presence badges never appear on a fresh install

[ehthayer]

What happened?

Enabling Grok agent integration installs hooks, and Settings shows agent presence badges on, but Grok never gets a presence badge (no session_start / busy / idle) on a new install—or after a reinstall that leaves only the current composite hook shape.

Expected: sidebar / tab Grok badge tracks the session (session_start → busy → idle), same as other agents.

Verified cause (local, tip build): Grok loads the installed hooks, then refuses to run them with:

hook not executed: required env var(s) not set: ${PPID}

Installed composite commands embed $PPID in the command string (AgentPresenceOSC.ttyResolveSnippet / emitShell). Grok preflights $VAR / ${VAR} as required env before spawn; PPID is a shell special, not env, so every managed Grok presence hook no-ops. OSC 3008 never fires.

env passthrough for SUPACODE_* is already present on main; this failure is independent of that and hits new installs that only get the composite shape (no legacy helper script on the command line).

Steps to reproduce

1. Clean or new machine path: ensure no dual-map legacy helper entries (or use a user who has never had Grok hooks, then enable Grok integration in Supacode Settings so it writes ~/.grok/hooks/supacode.json).
2. Confirm Agent presence badges are enabled.
3. In a Supacode terminal surface, run grok (e.g. 0.2.106 stable) and send a prompt that uses tools.
4. Observe: no Grok presence badge on the worktree/tab.
5. Inspect session hook runs (e.g. session updates.jsonl hook_execution for global/supacode:*): every run fails with hook not executed: required env var(s) not set: ${PPID}.
6. Optional contrast: a command that only invokes a helper script path (no $PPID on the command line) succeeds; inline composite with $PPID fails.

Supacode version and build

0.10.6 (1784188664)

(tip channel; same composite $PPID shape is on origin/main.)

macOS version

macOS 26.5.2 (25F84)

System locale

en_US

Mac hardware

MacBook Pro (Mac15,6), Apple M3 Pro

Relevant logs or screenshots

From a live Grok session updates.jsonl (hook_execution):

global/supacode:session_start[0].hooks[0]
  failed: hook not executed: required env var(s) not set: ${PPID}

global/supacode:user_prompt_submit[0].hooks[0]
  failed: same

global/supacode:pre_tool_use[0].hooks[0]
  failed: same

Installed command fingerprint (managed hook body includes):

ps -o tty= -p "$PPID"
...
__sp=";pid=$PPID"

Anchors for triage: AgentPresenceOSC.ttyResolveSnippet, AgentPresenceOSC.emitShell, GrokHookSettings / GrokSettingsInstaller, ~/.grok/hooks/supacode.json, Grok error string above. Agent under test: Grok Build 0.2.106 (stable).

Are you planning to fix this yourself?

• I intend to open a pull request once this is confirmed and marked ready.

Before submitting

• I searched existing issues and this is not a duplicate.
• I am on the latest available version of Supacode.
• I understand pull requests are closed until the issue is marked ready.
• I agree to follow this project's Code of Conduct.

[github-actions]

Thank you for filing this. A maintainer will review it and follow up here.

Please do not start any work or open a pull request until this issue is labeled ready. That label is a maintainer's go-ahead: a pull request opened against an issue that is not yet ready is labeled invalid until then. You will get a comment here the moment it is marked ready.

See CONTRIBUTING.md for the full flow.

[github-actions]

Thanks for your patience. This is approved and marked ready, so it is now open for a pull request. If you'd like to work on it, open a pull request and link it with Closes #704 in the description. If the issue is assigned to someone, it is reserved for them; otherwise anyone is welcome to pick it up.

See CONTRIBUTING.md for the full flow.