Feature Request: Formalize events.jsonl as an official hook/integration API

[RockNoggin]

Summary

Copilot CLI already writes a rich, machine-readable event stream to ~/.copilot/session-state/{id}/events.jsonl for every session. This file contains 20+ event types covering the full session lifecycle (task completion, user prompts, tool invocations, sub-agent activity, context compaction, model changes, etc.).

This is effectively a zero-configuration hook system — external tools can watch this file and react to events without any plugin API, registration, or modification to Copilot CLI itself.

Proposal

Formalize events.jsonl as a supported, documented external integration surface with:

1. Official documentation of the event schema (types, data fields, guarantees)
2. Stability contract — which event types/fields are stable vs. internal/experimental
3. Versioning — a schema version field so consumers can handle format changes gracefully
4. Best practices guide for external consumers (file sharing mode, incremental reading, offset tracking)

Why This Matters

Several community tools already consume this file for:

• Toast notifications when a task completes (the session.task_complete event even includes a natural-language summary)
• Real-time activity indicators (Working/Idle/NeedsInput/Problem states)
• Session dashboards and monitoring UIs
• Webhook integration (forward completion events to Slack, etc.)
• Cost tracking via session.compaction_complete token counts

Without documentation or stability guarantees, these integrations are fragile — any internal change to event formats could silently break them.

Current Event Types (observed in v1.0.54)

Event Type	Description
session.start	Session began (includes version, cwd, model)
session.task_complete	Agent finished work (includes summary text)
session.shutdown	Session ended permanently
session.model_change	Model switched
session.mode_changed	Mode changed (autopilot, etc.)
session.plan_changed	Implementation plan updated
session.compaction_start/complete	Context compaction (token counts)
assistant.turn_start/end	Agent reasoning turns
assistant.message	Agent output
user.message	User submitted prompt
tool.execution_start/complete	Tool invocations (includes tool name, args, success)
subagent.started/completed	Fleet agents
skill.invoked	Skill triggered
hook.start/end	Internal hooks
abort	User cancelled

Comparison to Claude Code Hooks

Claude Code requires explicit hook registration in ~/.claude/settings.json and only fires 2 events (Stop, UserPromptSubmit). Copilot CLI's events.jsonl is richer (20+ events), requires zero setup, and includes contextual data like task summaries and token counts. The only tradeoff is ~1-2s detection latency vs. instant script invocation.

Reference Implementation

I've documented the full pattern with code examples (PowerShell, C#, Node.js) and 10 use-case ideas:
https://gist.github.com/RockNoggin/8cc87f640ce5e3d284298a6db21f7523

Ask

• Document the event schema officially
• Declare which events/fields are stable for external consumption
• Add a schema version to the JSON line format
• Consider adding a simple session.idle event (agent finished turn, no pending tool calls) to make done detection even easier for simple consumers