Capture the active instruction surface for each snapshot

[caioribeiroclw-pixel]

I found Ponytrail from the HN launch. The local snapshot tree is already useful for "what changed / why / how to revert". One audit gap I would consider: the snapshot currently explains the action, but not the instruction surface that made the action likely.

For AI-agent edits, that can matter as much as the diff. A future history --details entry could optionally include a compact instruction_context / decision_context block, for example:

{
  "agent": "claude|codex|copilot|unknown",
  "skill": { "name": "pony-trail", "version": "..." },
  "context_files": [
    { "path": "AGENTS.md", "sha256": "..." },
    { "path": ".cursor/rules/codegraph.mdc", "sha256": "..." },
    { "path": "CLAUDE.md", "sha256": "..." }
  ],
  "env": {
    "session_id": "...",
    "git_branch": "...",
    "git_commit": "..."
  }
}

The important bit is not storing prompts or private transcript text. It is recording the small set of local instruction/context files and skill metadata that were active when the agent decided to mutate files.

Why this helps:

• When a revert happens days later, the user can distinguish "bad edit" from "bad rule/skill/context caused the edit".
• If an agent rule changed between the pre and post snapshot, the history can show that the rollback should inspect the rule too, not only the target file.
• It makes Ponytrail more useful across Claude/Codex/Copilot because the causal context behind the same file diff may be different per agent.

A minimal v1 could be opt-in and local-only: hash known root instruction files (AGENTS.md, CLAUDE.md, .cursor/rules/*, .github/copilot-instructions.md, installed skill path) into the snapshot entry. No raw prompt capture required.

[0xroylee]

Thanks for opening this. I agree with the shape of this, especially the privacy boundary: Ponytrail should not capture raw prompts or transcript text, but it should be able to explain which local instruction surface was active when a snapshot was created.

A good v1 would be opt-in, local-only, and compact:

• add optional instruction_context metadata to snapshot entries
• hash known instruction files like AGENTS.md, CLAUDE.md, .cursor/rules/*, .github/copilot-instructions.md, and installed skill metadata
• include only allowlisted environment context such as session id, branch, and commit
• render it in history --mode details / JSON, while keeping the default history view small
• treat unreadable/missing context files as warnings rather than snapshot failures

The main design constraint is making this useful for causality without turning Ponytrail into a prompt recorder. I like the framing here: when a revert happens, users should be able to tell whether the diff was bad or whether the active rule/skill/context nudged the agent into the bad edit.

I’ll keep this open as a feature candidate. The first implementation probably belongs beside the existing snapshot metadata rather than as a separate audit system.

[caioribeiroclw-pixel]

That v1 shape sounds right to me.

If helpful, I’d keep the schema boring and snapshot-local, something like:

"instruction_context": {
  "mode": "opt_in",
  "captured_at": "2026-06-22T17:04:23Z",
  "session_id_hash": "sha256:...",
  "git": { "branch": "main", "commit": "abc123", "dirty": true },
  "files": [
    { "path": "AGENTS.md", "sha256": "...", "bytes": 8421, "status": "captured" },
    { "path": ".cursor/rules/security.mdc", "sha256": "...", "bytes": 1933, "status": "captured" },
    { "path": "CLAUDE.md", "status": "missing" }
  ],
  "skills": [
    { "name": "untrusted-tool-output", "version_or_sha256": "...", "status": "captured" }
  ],
  "warnings": [".github/copilot-instructions.md unreadable"]
}

The important bit is making the hash list stable enough to compare two snapshots:

• same diff + different instruction hashes => likely rule/context regression
• different diff + same instruction hashes => likely task/model/tool behavior
• unreadable/missing files => visible warning, not a failed snapshot

I agree it belongs beside existing snapshot metadata. Keeping it out of the default compact view but present in JSON/details avoids making Ponytrail feel like a prompt recorder.