github / github/copilot-cli

Feature request: emit periodic heartbeat hook events during agent processing

Ouverte
#2,701 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
area:plugins
Langage dominant
Shell
Étoiles
11.2k
Forks
1.9k
Merge moyen
14 h 16 min
PR mergées (30 j)
6

Description

## Problem

Tools that integrate with Copilot CLI via the hook system (e.g. [agent-deck](https://github.com/asheshgoplani/agent-deck)) rely on lifecycle events like `UserPromptSubmit` and `Stop` to track whether the agent is actively working. However, there are **no events emitted while the agent is processing** — only a start event and an end event.

For long-running operations (multi-minute responses, complex code generation, large refactors), external tools have no signal that the agent is still alive. They must either:
- Trust the last event indefinitely (risks showing "running" for crashed sessions)
- Use a freshness window and fall back to heuristics (loses accurate status after timeout)

Neither option is great. Agent-deck currently uses a 10-minute freshness window with tmux activity heuristics as a fallback, but this is fragile.

## Proposed Solution

Emit a periodic `Heartbeat` (or `Processing`) hook event every 15-30 seconds while the agent is actively working (between `UserPromptSubmit`/`BeforeAgent` and `Stop`/`AfterAgent`).

The payload would be identical to existing hook events:

```json
{
"hook_event_name": "Heartbeat",
"session_id": "session-uuid-here"
}
```

### Why this works well

- **Zero protocol changes** — same JSON format, same stdin delivery, same hook handler invocation
- **Minimal implementation** — a timer that fires during processing and calls the existing hook dispatch
- **Graceful degradation** — tools that dont recognize `Heartbeat` ignore it (unknown events already map to no-op)
- **Solves the freshness problem** — external tools reset their freshness timer on each heartbeat, keeping accurate status for arbitrarily long operations

### What tools get from this

- Accurate "running" vs "idle" status for long operations
- Reliable detection of crashed/hung sessions (heartbeats stop = session is dead)
- No need for fragile heuristics (tmux pane activity polling, process tree inspection)

## Alternatives Considered

- **Tool-use events** — emitting a hook on each tool invocation (file edit, bash, grep) would also reset freshness, but is more invasive and couples the hook protocol to internal tool execution
- **Longer freshness windows** — what we do today; works but loses accuracy for sessions that genuinely crash during a long operation

## Context

This came up while investigating status tracking gaps in agent-deck, where Copilot sessions would show as "idle" in the TUI even though they were actively processing. The root cause is the silence between start/end events during long operations.

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Start by locating the existing hook-event dispatch and the agent-processing lifecycle around UserPromptSubmit/BeforeAgent and Stop/AfterAgent. Trace how hook payloads are delivered, then add periodic Heartbeat coverage while processing and tests that verify emission during work and cessation after completion.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
shell
Domaine
cli
Type d'issue
Fonctionnalité
Difficulté
4/5
Temps estimé
3-5 jours
Activité
Calme
Clarté
Plutôt claire
Accessibilité débutants
48/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.