Struct CheckpointObserver 

pub struct CheckpointObserver { /* private fields */ }

WriteObserver implementation backing [capabilities.checkpoint]. One instance per crate::Agent (installed on its crate::tools::ToolContext AND held directly so crate::Agent::run_loop can call Self::begin_turn once per user turn — see that method’s call site’s doc comment).

Implementations

impl CheckpointObserver

pub fn new( store: CheckpointStore, project_root: PathBuf, retain: usize, protected: Vec<String>, ) -> Self

protected layers extra glob patterns (typically Config::permissions_protected_paths, when module 13 is active) on top of the unconditional .git/** floor — consulted by Self::restore.

pub fn store(&self) -> &CheckpointStore

Read-only access to the underlying store (e.g. so a caller can list/turn_diff/restore without re-deriving the root path).

pub fn list(&self) -> Result<Vec<CheckpointMeta>>

List every checkpoint, newest first — see CheckpointStore::list.

pub fn turn_diff(&self, id: &str) -> Result<Vec<String>>

D3 turn-diff for one checkpoint — see CheckpointStore::turn_diff.

pub fn restore(&self, id: &str) -> Result<RestoreReport>

D4-adjacent revert: restore this project’s working files to checkpoint id, honoring THIS observer’s own project_root and protected globs (the fields set at construction) — see CheckpointStore::restore for the full security contract.

pub fn is_disabled(&self) -> bool

Whether this observer has disabled itself after an I/O failure.

pub fn begin_turn(&self, label: &str) -> Option<CheckpointId>

Open a fresh checkpoint for a new turn — called once at the top of crate::Agent::run_loop (i.e. once per Agent::send/ send_with_files/send_with_images call, cc’s “per-prompt file-history-snapshot”). label is a short excerpt of the turn’s prompt, display-only. Also prunes past the retention bound here (once per turn, not once per write) — see CheckpointStore::prune. Returns None when disabled (config-off is never routed here at all — see observer_for_config — so None here specifically means an I/O failure already tripped the breaker).

pub fn current(&self) -> Option<CheckpointId>

The checkpoint currently open for the in-flight turn, if any.

Trait Implementations

impl Debug for CheckpointObserver

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl WriteObserver for CheckpointObserver

fn before_write<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

path (already resolved + sandbox-checked) is about to be created/overwritten/deleted. Implementations must be fast and must never propagate a failure as a tool error — a capture failure should degrade the OBSERVER (e.g. disable itself with a one-time warning), never block or fail the user’s actual edit.

fn after_write<'life0, 'life1, 'async_trait>( &'life0 self, _path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = Option<String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

path was just written/deleted successfully. Not called when the tool call itself failed (e.g. the write errored before completing). Returns an optional annotation for the calling tool’s result text — see the trait doc comment above.