spec: issue-3829 Record the human touch points of an AI coding session
Summary
This PR adds a design spec and its implementation plan for #3829.
The AI coding session evidence will record how often a person stepped in during the session. Each type of human touch point gets its own count: prompts, answered questions, permission approvals and rejections, plan approvals and rejections, and interrupts. The evidence will also record who started the session (session.started_by: a person, another agent, or an automated run), and the permission modes of the agent. The team needs this data to compare sessions and to improve autonomous agents. With it, a reader can tell apart:
-
sessions that another agent or an automated run started, with no human touch point,
-
sessions that a person started, with no human touch point after the first prompt,
-
sessions that a person started, with human touch points after the first prompt. A later autonomy score can use it, but this spec does not define that score.
-
Spec:
docs/specs/issue-3829-session-human-touch-points.md. All providers are in scope, with one milestone for each provider. -
Plan:
docs/plans/issue-3829-session-human-touch-points.md. It covers milestone 1 only: the evidence section and Claude Code.
Open questions for reviewers
- Spec: none.
- Plan: does the Claude Code permission request hook carry the tool call ID? Proposed: find out in step 03. Without an ID, match each request to the next result of the same tool.
We would like two reviewers to approve this spec before it merges.
AI assistance: Claude Code helped draft the spec and the plan.
Refs #3829