Proposal: official Grok Build integration (hooks + session restore

[esko]

I'd like to contribute an official integration for Grok Build, installed with herdr integration install grok.

This overlaps with #991 from @carlesso (#1173, which was marked as a duplicate). I've looked through @carlesso's branch as well. Their implementation follows the Claude/Codex model: it restores sessions, while the screen remains the source of truth for state. My branch takes that a bit further by adding lifecycle hooks, Windows support, and hybrid state arbitration. I see it as one possible way to resolve both issues, and I'm happy to coordinate with @carlesso or combine the work into one PR.

A couple of notes from comparing the branches:

The detection-manifest change in #991 targets an older manifest. Master now has 2026.07.16.2, which already covers current Grok releases. The branch also adds a pane label for background activity. I like the idea, but it feels like a separate UI decision that may be worth discussing independently.

Rationale:

I use Grok Build with Herdr daily. The existing screen-manifest detection already recognises it, but there is currently no session restore or hook-based state reporting That means Grok panes loose their session after a Herdr server restart, and their displayed state can lag behind what Grok is actually doing.

Proposed behaviour:

A SessionStart hook reports the Grok session ID.
Session restore runs grok --resume .
Lifecycle hooks report working, idle, blocked, and attention states.
Grok Notification events are used for permission prompts and ask-user questions.

I would keep Grok as a hybrid intergration rather than making its hooks the full lifecycle authority. Grok's hooks only describe the foreground turn, so the existing screen/OSC manifest would still correct the state when background work is happening.

This would only affect Grok. It would not change arbitration for any other agent.

Integration details:

Grok reads every json file in ~/.grok/hooks/ as global hook configuration and uses a Claude-compatible schema.

The implementation therefore follows the same general pattern as the existing hook integrations, especially mastracode's. The differnece is that Herdr would write and manage its own hooks file rather than modifying Grok's main configuration.

Documentation would only be added to the docs/next mirror.

I already have a working branch with tests, and just ci passes. I'm happy to adapt it based on the preferred direction.

If this sounds like the right approach, could you create an issue and approve the PR path?