Struct WorktreeConfig 

pub struct WorktreeConfig {

    pub enabled: bool,
    pub base_ref: WorktreeBaseRef,
    pub default_branch: String,
    pub root: String,
    pub branch_prefix: String,
    pub prune_branch_on_remove: bool,
    pub cleanup_on_completion: bool,
    pub bg_isolation: BgIsolation,
    pub git_timeout_secs: u64,
    pub max_worktrees: Option<usize>,
    pub disk_quota_mb: Option<u64>,
    pub auto_reconcile_secs: u64,
    pub reconcile_on_startup: bool,
}

Configuration for the per-subagent git worktree isolation feature.

When enabled = true, each subagent that opts in via SubAgentPermissions::worktree receives a dedicated git worktree on a fresh branch, ensuring that file edits from concurrent agents do not interfere with each other or with the main working tree.

Examples

use zeph_config::WorktreeConfig;

let cfg = WorktreeConfig::default();
assert!(!cfg.enabled);
assert_eq!(cfg.root, ".claude/worktrees");
assert_eq!(cfg.branch_prefix, "agent/");
assert_eq!(cfg.git_timeout_secs, 30);

Fields

enabled: bool

Enable per-subagent git worktrees. When false, no worktrees are created regardless of other settings.

base_ref: WorktreeBaseRef

Base commit strategy for new worktree branches.

default_branch: String

Default remote branch used when base_ref = "fresh".

Empty string triggers auto-detection of origin/HEAD.

root: String

Root directory for worktrees, relative to the repository root.

Each worktree is placed in a subdirectory named after the subagent ID.

branch_prefix: String

Branch name prefix. The full branch name is "{prefix}{subagent_id}".

prune_branch_on_remove: bool

Delete the worktree branch after the worktree is removed.

When false (default), the branch persists so the agent’s work can be reviewed, merged, or discarded manually.

cleanup_on_completion: bool

Remove the worktree when the agent completes or is cancelled.

When false, worktrees persist until an explicit worktree clean command.

bg_isolation: BgIsolation

Background subagent isolation mode.

Controls whether background subagents receive a dedicated worktree or edit the working copy directly.

git_timeout_secs: u64

Per-command timeout for git invocations, in seconds.

Applied to every git call issued by the worktree subsystem (e.g. git worktree add, git fetch, git rev-parse). Increase this value on repositories that are slow to clone or when running over high-latency network links. A value of 0 is clamped to 1 second by DefaultGitRunner, not by any call site.

max_worktrees: Option<usize>

Maximum number of concurrent worktrees under root. None (default) means unlimited.

Enforced as a creation-time admission cap: a create() call that would push the count of git-registered secondary worktrees to max_worktrees or beyond fails with WorktreeError::QuotaExceeded instead of silently growing disk usage. The count includes worktrees created by other, concurrently running zeph sessions over the same root — max_worktrees bounds total disk-safe usage under the repository, not just this session’s own worktrees. The check is a best-effort soft cap: it is not atomic across processes, so two concurrent create() calls can both pass and briefly exceed the configured maximum by a small margin. Lowering this value below the current worktree count does not evict existing worktrees; it only blocks new admissions until an operator runs zeph worktree clean or raises the limit. A value of Some(0) is rejected at config-validation time (it would block all worktree creation).

disk_quota_mb: Option<u64>

Soft total-disk-usage threshold, in megabytes, across all worktrees under root. None (default) disables disk accounting.

When exceeded, the reconcile sweep (startup and/or periodic, see auto_reconcile_secs / reconcile_on_startup) emits a warning status indicator and auto-reclaims only git-prunable entries — an intact worktree is never force-removed to satisfy this threshold. The reported total is a sum of logical file sizes (metadata().len()), not on-disk block usage; content shared via hardlinks across worktrees (e.g. zeph-session blobs) can be double-counted, so treat the total as an approximation, not exact du output. A value of Some(0) is rejected at config-validation time (it would leave every non-empty worktree permanently over quota).

auto_reconcile_secs: u64

Interval, in seconds, for the supervised background reconcile-and-quota sweep. 0 (default) disables the periodic sweep.

When greater than zero, one task is registered with the session TaskSupervisor that, on this cadence, reconciles the git worktree registry, auto-reclaims prunable entries via the same path as zeph worktree clean (non-force), and evaluates max_worktrees / disk_quota_mb. Each tick may perform a filesystem walk of every worktree (potentially multi-gigabyte target/ directories), so a short interval is wasteful; an hourly cadence (3600) is a reasonable default when enabling this. Config::validate rejects any value in 1..60 — a sub-minute interval would run a full filesystem walk in a tight loop.

reconcile_on_startup: bool

Run one reconcile-and-quota sweep at bootstrap, immediately after the worktree manager is constructed. Default true.

Recovers from a crash that left prunable worktrees behind without waiting for the first periodic tick, and evaluates disk_quota_mb / max_worktrees once per launch even when auto_reconcile_secs = 0 — without this, a disk_quota_mb set by itself would never be evaluated at all. Config::validate rejects disk_quota_mb.is_some() combined with both this field false and auto_reconcile_secs == 0, so that exact inert combination cannot reach a running session. Safe by construction: the startup sweep only ever removes entries git itself reports as prunable (directory or gitdir-link already gone), identical to zeph worktree clean without --force.

Trait Implementations

impl Clone for WorktreeConfig

fn clone(&self) -> WorktreeConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WorktreeConfig

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

Formats the value using the given formatter.

impl Default for WorktreeConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for WorktreeConfig

where WorktreeConfig: Default,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for WorktreeConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.