Expand description
Worktree-aware path resolution for edit tools.
SymForge indexes one repo path and stores absolute file paths in its
index. When an agent runs from inside a parallel git worktree that
shares the same .git objects, an edit that resolves against the
indexed absolute path silently writes to the indexed repo copy
instead of the agent’s own working tree. The resolver below implements
explicit call-time routing through the working_directory edit parameter.
The edit handlers call resolve_target_path before writing. When
working_directory is None, behavior is byte-identical to pre-routing
releases (write to the indexed absolute path). When Some, the path
is re-rooted against the working directory and validated against a
cached git worktree list, refreshed on cache miss.
Structs§
- Resolved
Target - Outcome of
resolve_target_path: where the edit should land, plus where the index believes the file lives, plus a flag flipping true iff the two differ. - Worktree
Aware Edit Hook EditHookimplementation that reroutes edits into a siblinggit worktreewhen the caller suppliesworking_directory. Holds one sharedWorktreeCacheso repeated calls in the same session avoid re-shelling out togit worktree list.- Worktree
Cache - Cache of known worktrees for one indexed root. Populated on demand
by
refresh();lookup()refreshes once on cache miss before concluding the directory is unknown. - Worktree
Entry - A worktree known to be associated with the indexed root.
- Worktree
Misuse Counter - Counts edit-tool calls that omitted
working_directorywhile the transitional worktree observability knob is on. Exposed through thehealthtool as a rolling “last hour” signal so regressions stay visible after the feature ships.
Enums§
- Worktree
Error - Errors produced by worktree-aware resolution.
Constants§
Functions§
- canonicalize
- Canonicalize a path, returning a clean form without the
\\?\UNC prefix on Windows. Delegates todunce::canonicalizewhich falls back tostd::fs::canonicalizeon non-Windows. - register_
if_ feature_ enabled - Install
WorktreeAwareEditHookon the process-wide edit-hook registry, exactly once. Routing policy is resolved inside the hook so callers can request worktree routing at call time withworking_directory. - resolve_
target_ path - Re-root an indexed absolute path against an optional working directory, applying the spec §2.2 resolution algorithm.
- routing_
policy_ from_ env - Interpret the transitional worktree-routing env var as policy. Unset means explicit call-time routing is allowed; false/off/disabled values block requested routing before any write.