Add skill event metadata for Claude and Pi

[dipree]

https://entire.io/gh/entireio/cli/trails/449

Summary

• add normalized skill_events metadata persisted in session checkpoint metadata
• detect Claude Code Skill tool calls from transcripts
• capture Pi /skill:name commands via the Pi input extension before expansion
• carry skill events through session state, condensation, and turn finalization

Skill metadata format

Skill events are sidecar annotations in the session-level checkpoint metadata.json (<checkpoint>/<session-index>/metadata.json). The raw transcript is not rewritten.

When present:

{
  "skill_events_version": 1,
  "skill_events": [
    {
      "id": "claude-skill-toolu_123",
      "event_type": "tool_invocation",
      "skill": {
        "name": "trigger-analysis"
      },
      "source": {
        "agent": "claude-code",
        "signal": "skill_tool_use",
        "confidence": "explicit"
      },
      "turn_id": "turn_abc123",
      "timestamp": "2026-05-25T12:34:56Z",
      "transcript_anchor": {
        "unit": "line",
        "start": 132,
        "end": 133,
        "entry_ids": ["assistant-msg-uuid"],
        "tool_use_id": "toolu_123"
      },
      "native": {
        "tool_name": "Skill",
        "tool_use_id": "toolu_123"
      },
      "collapse": {
        "target": "tool_pair",
        "label": "Skill: trigger-analysis",
        "default_collapsed": true
      }
    }
  ]
}

Fields:

• id: best-effort stable event ID used for de-duplication when present
• event_type: currently tool_invocation or prompt_invocation
• skill.name: normalized skill name from the native agent signal
• source.agent: agent registry name, e.g. claude-code, pi
• source.signal: native signal used, currently skill_tool_use or input_slash_command
• source.confidence: currently only explicit
• turn_id: Entire turn ID when known
• timestamp: runtime timestamp when available
• transcript_anchor: best-effort location of the raw transcript event
• native: agent-specific fields preserved for debugging/future consumers
• collapse: UI hint for what can be collapsed by default

Claude Code example

Claude Code emits a tool_invocation event from assistant tool_use blocks where name == "Skill" and input.skill is set:

{
  "id": "claude-skill-toolu_123",
  "event_type": "tool_invocation",
  "skill": { "name": "trigger-analysis" },
  "source": {
    "agent": "claude-code",
    "signal": "skill_tool_use",
    "confidence": "explicit"
  },
  "transcript_anchor": {
    "unit": "line",
    "start": 132,
    "end": 133,
    "entry_ids": ["a1"],
    "tool_use_id": "toolu_123"
  },
  "native": {
    "tool_name": "Skill",
    "tool_use_id": "toolu_123"
  },
  "collapse": {
    "target": "tool_pair",
    "label": "Skill: trigger-analysis",
    "default_collapsed": true
  }
}

Consumer expectation: collapse the Skill tool call/result pair, not the original user prompt.

Pi example

Pi emits a prompt_invocation event when the extension observes raw input beginning with /skill:name before Pi expands the prompt:

{
  "id": "pi-skill-trigger-analysis-2026-05-25T12:34:56Z-0",
  "event_type": "prompt_invocation",
  "skill": { "name": "trigger-analysis" },
  "source": {
    "agent": "pi",
    "signal": "input_slash_command",
    "confidence": "explicit"
  },
  "timestamp": "2026-05-25T12:34:56Z",
  "native": {
    "command": "/skill:trigger-analysis"
  },
  "collapse": {
    "target": "user_message",
    "label": "/skill:trigger-analysis",
    "default_collapsed": true
  }
}

Consumer expectation: collapse the resulting skill-expanded user message/prompt.

Non-goal for this PoC: default-collapsible events from weak transcript heuristics like reading SKILL.md, paths containing /skills/, expanded skill text, or system prompt skill listings.

Testing

• mise exec -- go test ./cmd/entire/cli/agent/claudecode ./cmd/entire/cli/agent/pi ./cmd/entire/cli/agent ./cmd/entire/cli/checkpoint ./cmd/entire/cli/strategy ./cmd/entire/cli
• env -u GIT_TERMINAL_PROMPT -u PI_CODING_AGENT mise exec -- go test ./...
• Manual E2E: enabled Entire in a temp repo, simulated Claude Code user-prompt-submit + commit with trailer, verified skill_events in entire/checkpoints/v1:<checkpoint>/0/metadata.json.
• Manual E2E: enabled Entire in a temp repo, simulated Pi before_agent_start with /skill:name metadata + commit with trailer, verified skill_events in checkpoint metadata.
• Manual E2E: simulated Claude mid-turn commit, appended another Skill tool call, ran claude-code stop, verified finalize updated the existing checkpoint metadata with both skill events.

[Copilot]

Pull request overview

Adds normalized skill_events sidecar metadata that captures when AI agents invoke native skills, without rewriting raw transcripts. Claude Code derives events from Skill tool-use blocks in its transcript; Pi captures /skill:name slash commands in the TypeScript extension and forwards them through hooks. Events flow through session state (with dedup), are merged with transcript-extracted events during condensation/finalization, and persisted to per-session checkpoint metadata.json with a skill_events_version.

Changes:

• New agent.SkillEvent data model, SkillEventExtractor capability/interface, and generic ExtractSkillEvents helper.
• Claude transcript extraction of Skill tool calls (using new ContentBlock.ID); Pi hook payload + TS extension capture of /skill:name before prompt expansion.
• Lifecycle/state plumbing: Event.SkillEvents, session-state append+dedup, condensation/finalization merging and write into WriteCommittedOptions/UpdateCommittedOptions plus CommittedMetadata.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
cmd/entire/cli/agent/skill_events.go	Defines SkillEvent types, constants, and SkillEventExtractor interface.
cmd/entire/cli/agent/skill_events_extract.go	Generic extractor wrapper that no-ops/logs on unsupported agents or errors.
cmd/entire/cli/agent/capabilities.go	Adds SkillEventExtractor declared capability and AsSkillEventExtractor helper.
cmd/entire/cli/agent/event.go	Adds SkillEvents field to lifecycle Event.
cmd/entire/cli/agent/claudecode/lifecycle.go	Declares SkillEventExtractor interface assertion for Claude.
cmd/entire/cli/agent/claudecode/transcript.go	Implements ExtractSkillEvents parsing assistant Skill tool_use blocks.
cmd/entire/cli/agent/claudecode/transcript_test.go	Test for extraction of one Skill tool use.
cmd/entire/cli/agent/pi/lifecycle.go	Adds skill_events to hook payload and maps to SkillEvent on before_agent_start.
cmd/entire/cli/agent/pi/lifecycle_test.go	Test for Pi skill event hook parsing.
cmd/entire/cli/agent/pi/entire_extension.ts	Captures /skill:name on input, batches and forwards on before_agent_start.
cmd/entire/cli/transcript/types.go	Adds ID to ContentBlock for tool_use anchoring.
cmd/entire/cli/session/state.go	Persists SkillEvents in session state JSON.
cmd/entire/cli/lifecycle.go	Appends event skill events into state with dedup; participates in mutation-skip check.
cmd/entire/cli/strategy/manual_commit_types.go	Adds SkillEvents to ExtractedSessionData.
cmd/entire/cli/strategy/manual_commit_condensation.go	Extracts skill events from transcript and merges into write options.
cmd/entire/cli/strategy/manual_commit_hooks.go	Finalize-all path extracts and merges skill events for committed updates.
cmd/entire/cli/strategy/skill_events.go	Merge + turn-id helpers with composite-key dedup.
cmd/entire/cli/checkpoint/checkpoint.go	Adds SkillEvents/SkillEventsVersion to write/update options and metadata.
cmd/entire/cli/checkpoint/committed.go	Writes skill events into metadata and adds replaceSkillEvents for UpdateCommitted.