Pre-flight knowledge context: capturing the agent's knowledge state in Checkpoints

[totto]

Problem

Checkpoints does an excellent job recording what the agent thought and decided — prompts, transcripts, tool calls, reasoning. But it currently doesn't capture what the agent knew before execution: the structured knowledge context that was available at the time.

For audit and compliance purposes, the complete record should answer three questions:

1. What knowledge was the agent operating from? (knowledge available)
2. What did it decide and do? (reasoning applied — this is what Checkpoints records today)
3. What code did it produce? (git diff)

Question 1 is currently missing.

The missing layer: pre-flight knowledge context

When agents run with structured knowledge systems — like KCP (Knowledge Context Protocol) — the agent loads a scoped set of knowledge manifests before execution: architecture decisions, coding standards, governance rules, suppression constraints, role-specific context. This is the structured briefing the agent operates from.

If a compliance auditor asks "did this agent have access to the correct governance rules when it wrote this code?", the answer lives in the knowledge manifest state, not in the reasoning trace. These are different layers.

Proposed addition

Add an optional metadata field to checkpoint records for knowledge context — whatever structured context was loaded before the session started. At minimum, this could be:

• A snapshot of loaded manifest IDs + versions (e.g., a KCP kcp_knowledge_map.yaml state at session start)
• A content hash of the knowledge context
• Or simply: a knowledge_context_file config option that Entire reads and appends to checkpoint metadata

For KCP specifically, the manifest is compact — a version, a load_strategy, and references to in-scope knowledge units. It fits naturally alongside prompt/transcript metadata.

Why this matters

A checkpoint that includes knowledge state becomes a complete audit record:

• Was the agent operating with the right context? (governance, access, version)
• Did applicable constraints apply? (scope rules, suppression, load strategy)
• Root cause separation: If the generated code is wrong, is it because the agent reasoned incorrectly (visible in transcript) or because it lacked the right knowledge (visible in manifest state)? These are different failure modes with different remediation paths.

Claude Code is already a supported integration. KCP manifests are how many Claude Code-based workflows structure agent context. Capturing that state at checkpoint time closes the loop between "what the agent was given" and "what the agent produced."

Happy to elaborate on the manifest format or sketch an integration approach.