Inject CSM_SESSION_ID into session environments (self-reported state now covered by OSC 7501, #190) #163

This was generated by AI during triage.

Summary

Let the program running in a session report its own agent state (working / idle / blocked), rather than CSM having to guess from the screen. Also inject per-session environment variables so a hook or script knows which session it belongs to.

Inspired by Herdr v0.9.2+ (Add Herdr support to your agent).

How Herdr does it

• Every pane gets HERDR_ENV=1, HERDR_PANE_ID, HERDR_BIN_PATH and HERDR_SOCKET_PATH.
• herdr pane report-agent <pane> --source <id> --agent <name> --state working|idle|blocked [--message …] [--seq N].
  • --seq must increase with every report (a timestamp works). Reports that aren't newer are dropped, so a slow hook can't overwrite a fresher state.
  • --source identifies the reporter. A user's custom reporter (custom:…) can't clobber a built-in integration.
• pane release-agent clears the state when the agent quits. As a safety net, Herdr also clears it once the pane is back at an idle shell prompt.
• Herdr separates done ("finished, not yet looked at") from idle ("finished and seen"). Seen-state is per viewer, and focusing the pane marks it seen.

Proposal for CSM

1. Environment. Start every session with CSM_ENV=1, CSM_SESSION_ID and TERM_PROGRAM=CodeShellManager (+ TERM_PROGRAM_VERSION). This depends on the environment-block work in the env-leak issue filed alongside this one.
2. Transport (v1). Extend OSC 9001 with state=working|idle|blocked, state-msg=… and seq=N. Validate it in ShellIntegrationPayload like every other field: a strict allowlist, with the message length-capped and stripped of control characters.
3. A Claude Code hook (optional install). Claude's UserPromptSubmit / Stop / Notification hooks print the OSC. This gives exact "working" and "done" state for Claude without screen-scraping.
4. Done vs idle. Add an unseen-completion state that clears when the session becomes ActiveSession.
5. Precedence. Reported state beats screen detection for as long as the reporter holds the session. Screen detection (AlertDetector) remains the fallback.

Trust note

OSC 9001 is untrusted: any cat of a file can emit it. A forged state= only affects display, which is acceptable. It must never drive an action such as auto-answering a prompt or resuming.

Feeds #154 (working indicator) and #161 (kanban). Related: #138 (Team Bus), #132.