[FEATURE] Session metrics and lifecycle hooks for plugin analytics

[jerrythomas]

Summary

External tools and plugins building session analytics need token usage data and session lifecycle signals. Currently there is no way to know how many tokens a session consumed, what it cost, or when tasks within a session start and end.

What's needed

1. Token counts per session — tokens_in, tokens_out exposed via hooks, events, or API
2. Session/task lifecycle events — signals when a session starts/ends and when logical tasks within a session begin/complete
3. Tool call observability — post-tool-execution event should include truncated response content, not just tool name and exit code
4. Usage introspection — API or CLI to query remaining usage limits

Use case

Building a session observatory that shows developers:

• Cost per session and per task
• Session drill-down with tool call inputs AND outputs
• Quality metrics (first-try-right rate, rework rate) correlated with cost
• Which approaches are efficient vs expensive

Proposed events

// Session end
{"event": "session.end", "tokens_in": 24000, "tokens_out": 8000, "turns": 8}

// Task boundaries
{"event": "task.start", "prompt_preview": "Fix the parser bug"}
{"event": "task.end", "outcome": "completed", "turns": 8, "duration_s": 180}

// Post-tool enrichment
{"event": "tool.post", "tool": "search", "response_preview": "Found 3 results..."}

Why opencode

opencode's open architecture and plugin system are ideal for this — richer lifecycle data than proprietary alternatives would be a strong differentiator.

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• The Feature Request template requires a verification checkbox confirming the feature hasn't been suggested before. This is missing from the issue.

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Add expanded hook events to the plugin system to enable more powerful plugin capabilities. #21075: Requests expanded hook events for the plugin system including session.start/session.end, preToolUse/postToolUse — directly overlapping with the lifecycle hooks requested here
• [FEATURE]: Native OpenTelemetry (OTLP) export for OpenCode sessions/tools/events #14697: Requests native OpenTelemetry export covering session lifecycle events, token/cost tracking, and tool observability — substantially overlapping with this request
• [FEATURE]: Expose prompt/output message bodies to plugin chat.message hook #22831: Requests that plugin chat.message hook expose message bodies for telemetry/observability use cases — overlapping with the tool call observability goal here

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

This issue has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new issue that follows our issue templates.