pub struct Frontmatter {Show 52 fields
pub session: Option<String>,
pub resume: Option<String>,
pub agent: Option<String>,
pub model: Option<String>,
pub claude_model: Option<String>,
pub codex_model: Option<String>,
pub opencode_model: Option<String>,
pub branch: Option<String>,
pub tmux_session: Option<String>,
pub mode: Option<String>,
pub format: Option<AgentDocFormat>,
pub write_mode: Option<AgentDocWrite>,
pub stream_config: Option<StreamConfig>,
pub agent_args: Option<String>,
pub claude_args: Option<String>,
pub codex_args: Option<String>,
pub opencode_args: Option<String>,
pub codex_network_access: Option<CodexNetworkAccess>,
pub required_ssh_targets: Vec<String>,
pub required_ssh_profile: Option<String>,
pub managed_proof_max_attempts: Option<u32>,
pub managed_proof_retry_backoff_secs: Option<u64>,
pub managed_proof_probe_timeout_secs: Option<u64>,
pub no_mcp: Option<bool>,
pub enable_tool_search: Option<bool>,
pub debounce_ms: Option<u64>,
pub links: Vec<String>,
pub auto_compact: Option<usize>,
pub queue_context_reset: Option<bool>,
pub gate_autoverify: Option<bool>,
pub clear_threshold: Option<u8>,
pub supervisor_auto_recycle: Option<bool>,
pub agent_change_restart: Option<bool>,
pub supervisor_auto_install: Option<bool>,
pub model_tier: Option<Tier>,
pub pending_capture_guard: Option<PendingCaptureGuardMode>,
pub pending_done_guard: Option<PendingCaptureGuardMode>,
pub review_done_guard: Option<PendingCaptureGuardMode>,
pub auto_done: Option<bool>,
pub agent_doc_lint_dialect: Option<LintDialectMode>,
pub hooks: HashMap<String, Vec<String>>,
pub env: IndexMap<String, Option<String>>,
pub prompt_presets: IndexMap<String, String>,
pub dispatch: Option<String>,
pub agent_doc_env_inherit: Option<bool>,
pub cwd: Option<String>,
pub queue: Option<String>,
pub queue_active: Option<bool>,
pub queue_prompt_echo_max_chars: Option<usize>,
pub collaboration: Option<CollaborationMode>,
pub security_review: Option<String>,
pub pipeline: AgentDocPipeline,
}Fields§
§session: Option<String>Document/routing UUID — permanent identifier for tmux pane routing.
Serialized as agent_doc_session in YAML; reads legacy session via alias.
resume: Option<String>Agent conversation ID — used for --resume with agent backends.
Separate from session so the routing key never changes.
agent: Option<String>§model: Option<String>§claude_model: Option<String>Per-harness model override for Claude Code sessions.
When running under Claude Code, this takes precedence over model.
codex_model: Option<String>Per-harness model override for Codex sessions.
When running under Codex, this takes precedence over model.
opencode_model: Option<String>Per-harness model override for OpenCode sessions.
When running under OpenCode, this takes precedence over model.
branch: Option<String>§tmux_session: Option<String>Deprecated. Tmux session name for pane affinity (e.g., “claude”).
Session is now determined at runtime by --window argument (sync) or
current_tmux_session() (route/start). Still read for backward compatibility
and auto-repaired by sync when it differs from the context session.
Will be removed in a future version.
mode: Option<String>Deprecated. Use agent_doc_format + agent_doc_write instead.
Kept for backward compatibility. Values: “append”, “template”, “stream”.
Serialized as agent_doc_mode in YAML; reads legacy response_mode and shorthand mode via aliases.
format: Option<AgentDocFormat>Document format: controls document structure (append | template).
write_mode: Option<AgentDocWrite>Write strategy: controls merge behavior (merge | crdt).
stream_config: Option<StreamConfig>Stream mode configuration (used when write strategy is CRDT).
agent_args: Option<String>Additional CLI arguments to pass to the agent process (harness-neutral). Takes precedence over harness-specific aliases. Space-separated string.
claude_args: Option<String>Additional CLI arguments to pass to the claude process.
Backward-compatible alias for agent_args. agent_args takes precedence when both are set.
codex_args: Option<String>Additional CLI arguments to pass to the codex process.
Codex-only alias for agent_args. agent_args takes precedence when both are set.
opencode_args: Option<String>Additional CLI arguments to pass to the opencode process.
OpenCode-only alias for agent_args. agent_args takes precedence when both are set.
codex_network_access: Option<CodexNetworkAccess>Explicit Codex network policy. inherit keeps the launcher’s ambient
CODEX_SANDBOX_NETWORK_DISABLED setting, enabled removes it, and
disabled forces it on for the child session.
required_ssh_targets: Vec<String>Required SSH targets that must be reachable for Codex-backed work to proceed. When present, agent-doc probes these targets before trusting a resumed Codex session and fails closed when the capability cannot be proven.
required_ssh_profile: Option<String>Optional profile name resolved via project-local .agent-doc/config.toml
SSH mappings when the document omits direct required_ssh_targets.
managed_proof_max_attempts: Option<u32>Maximum number of managed-capability-proof attempts before the dispatch
gate is set to Failed. A transient network blip is retried (with
backoff) up to this many times so it no longer permanently wedges the
session. 1 disables retry (legacy behavior). Default 3.
managed_proof_retry_backoff_secs: Option<u64>Base back-off (seconds) between managed-capability-proof retries. The
delay grows exponentially from this value, capped internally. Default 2.
managed_proof_probe_timeout_secs: Option<u64>Override for the managed-capability child network/writable-root probe
timeout (seconds). Slow-network environments can raise it above the
default 45.
no_mcp: Option<bool>When true, passes --no-mcp to the claude process.
enable_tool_search: Option<bool>When true, passes --enable-tool-search to the claude process.
debounce_ms: Option<u64>Debounce duration in milliseconds for preflight mtime settling. Default: 2000ms. Set to 0 to disable debounce (run immediately).
links: Vec<String>Linked resources: local file paths or URLs (relative to this document’s directory). Changes in linked docs are surfaced during preflight.
auto_compact: Option<usize>Explicit opt-in for automatic compaction/reload policies. Session-accretion heuristics never compact by themselves; omit to disable.
queue_context_reset: Option<bool>Explicit opt-in for the supervisor idle-queue watch to pre-emptively
interleave a context-clear (/clear) before an active queue head when
session accretion is unhealthy (#nm1x-no-preempt-clear). Off by default.
gate_autoverify: Option<bool>Explicit opt-in for opportunistic gated-review auto-verification
(#optverify). When true, preflight may flip a gated [/] review item
carrying a verify predicate to [x] once its proof marker is provable
from ops.log (and no disproof marker fired). Off by default — without
the opt-in, preflight only surfaces the provable/failed status and
never silently flips a human gate.
clear_threshold: Option<u8>Context-usage percentage (0–100) at or above which an opted-in editor
(JB Run Agent Doc) pre-emptively runs /clear before the next dispatch
(#clear-opt-in-threshold). Resolution: this frontmatter value, then the
project config .agent-doc/config.toml, then the built-in default of 50.
The threshold value is owned by the binary so all editors share it; the
context-percentage comparison and the actual pre-emptive clear are the
editor’s responsibility.
supervisor_auto_recycle: Option<bool>Explicit per-document opt-in/opt-out for supervisor auto-recycle
(#ctlrecycle R3 / #suprecyclequeue). When the route-owned supervisor
detects it is running a stale binary at an idle / inter-queue-item
boundary, true lets it execve hot-reload onto the freshly-installed
build (preserving the live agent child + pane); false force-disables
that swap so a stale supervisor only logs supervisor_binary_stale_detected.
Resolution: env AGENT_DOC_SUPERVISOR_AUTO_RECYCLE, then this frontmatter
value, then the project config agent_doc_supervisor_auto_recycle, then
the built-in default of ON.
agent_change_restart: Option<bool>Explicit per-document opt-in/opt-out for restart-agent on a harness change
(#agentreloadrestart). When the resolved harness from current frontmatter
(agent:) differs from the one the running supervisor launched with,
true lets the supervisor auto-restart the agent at the next idle/turn
boundary so changing agent (e.g. claude→opencode) takes effect without a
manual restart; false disables that auto-restart (the change then applies
only on the next manual restart). Resolution: env
AGENT_DOC_AGENT_CHANGE_RESTART, then this frontmatter value, then the
project config agent_doc_agent_change_restart, then the built-in default
of ON.
supervisor_auto_install: Option<bool>Explicit per-document opt-in/opt-out for supervisor auto-install
(#supautoinstall). When a DOGFOODING supervisor (an agent-doc session
editing agent-doc’s own source) finds the source newer than the installed
binary at an idle boundary, true lets it cargo build --release +
cargo install + agent-doc lib-install so the #ctlrecycle recycle then
hot-reloads onto it; false force-disables that build so it only logs
supervisor_source_newer_detected. Resolution: env
AGENT_DOC_SUPERVISOR_AUTO_INSTALL, then this frontmatter value, then the
project config agent_doc_supervisor_auto_install, then the built-in
default of ON. Never fires for a non-agent-doc dogfood session document,
even when this field is true.
model_tier: Option<Tier>Required model tier for this document. When set, preflight emits this as
required_tier, which the skill uses as a hard gate: if the running model’s
tier is below this value, the skill writes a switch prompt and stops.
Values: auto | low | med | high. Default: absent (no gate).
pending_capture_guard: Option<PendingCaptureGuardMode>Pending-capture guard mode for session-check.
Values: warn (default when absent), strict, off.
pending_done_guard: Option<PendingCaptureGuardMode>Pending-done guard mode for session-check.
Values: warn (default when absent), strict, off.
review_done_guard: Option<PendingCaptureGuardMode>Review-done guard mode for --done.
Values: off (default when absent), warn, strict/error.
auto_done: Option<bool>When true, closeout may auto-apply --done for clear completion signals.
Default is absent/false; explicit --done and explicit #id done
directives still work without this opt-in.
agent_doc_lint_dialect: Option<LintDialectMode>Lint dialect mode for the agent-doc finalize lint gate. Values:
warn (default), strict, off. See lint_gate module for the
full precedence chain.
hooks: HashMap<String, Vec<String>>Document-level lifecycle hooks: shell commands executed at key events.
Supported events: session_start, post_write, post_commit.
Each event maps to a list of shell commands (run via sh -c).
Template variables substituted before execution:
{{session_id}}— document session UUID{{file}}— document file path{{agent}}— agent name (or empty string){{model}}— model name (or empty string)
Execution is best-effort: failures log to stderr and never block the session.
Example:
hooks:
session_start:
- "curl -s -X POST https://api.example.com/sessions -d '{\"session_id\": \"{{session_id}}\"}'"
post_write:
- "notify-send 'agent-doc' 'Response written to {{file}}'"env: IndexMap<String, Option<String>>Environment variables to inject into the Claude session.
Keys are env var names, values are strings supporting shell expansion
($(command), $VAR, ${VAR}). Order is preserved: later values can
reference earlier keys. A null value (YAML KEY: null) means “unset
this key in the child env” — supported by every consumer (start.rs,
run.rs, stream.rs, parallel.rs, supervisor/env.rs).
prompt_presets: IndexMap<String, String>Reusable prompt snippets that can be expanded into orchestrated task prompts.
Example:
prompt_presets:
"#1": |
Today is 2026-04-25.
Keep the work tree clean.dispatch: Option<String>Lower-agent dispatch policy for planning/job-packet generation.
Values are currently interpreted by plan as manual/auto/off text;
unknown values round-trip so newer policy names do not break older binaries.
agent_doc_env_inherit: Option<bool>Whether the supervisor starts from the parent process env before
applying the env: overlay. Default true — the supervised claude
child inherits PATH/HOME/TERM/TMUX/… from the shell that launched
agent-doc, then frontmatter env: overrides/unsets specific keys.
Set false for a sealed env (only the explicit env: keys, nothing
from the parent). Consumed by supervisor/env.rs::EnvSpec.
cwd: Option<String>Explicit working directory for the supervised claude child process.
Resolved relative to the document’s parent directory if a relative path
is given. When absent, the supervisor falls back to project-root detection
(.agent-doc/ walk) or the document’s parent directory.
See src/agent-doc/specs/supervisor.md § Core Invariants / CWD determinism.
queue: Option<String>Canonical queue activation control (#queue-state-unify).
start (alias go) activates the queue; stop deactivates it. This is
the preferred surface and subsumes the deprecated queue_active: boolean
and the auto marker attribute. normalize_queue_control folds an
explicit value onto queue_active at parse time so every existing reader
honors it; the canonical key wins over a stale queue_active:.
queue_active: Option<bool>Deprecated in favor of the canonical queue: control. Whether the
queue is currently active (consuming prompts). Set to true when the
queue is activated via queue: start/go, auto, a start fence, or
do queue/run queue. Cleared when the queue drains to empty. Still read
and written for backward compatibility.
queue_prompt_echo_max_chars: Option<usize>Opt-in length threshold for the #queue-prompt-echo-in-response echo.
When Some(n) and a consumed queue prompt is longer than n characters,
the echo records a bounded summary (first line + truncation note + a
pointer to the full agent:queue text) instead of copying the whole
prompt verbatim. None (default) preserves the verbatim copy
(#queue-prompt-echo-summary; the user deferred summarization with “for
now, let’s try copying the entire prompt”, so it stays opt-in).
collaboration: Option<CollaborationMode>Collaboration scope for the document.
shared opts the document into stricter cross-document security checks.
security_review: Option<String>Audit note / approval token for cross-document reads or transfers in shared mode.
pipeline: AgentDocPipelineLive finalize-pipeline state tracker (#fm-run-id-step). Ephemeral runtime
state written at each cycle phase transition and cleared at a terminal phase;
surfaces run_id / step / turn_id / queue_task_id for crash re-entrancy
and observability without a dedicated git commit. See AgentDocPipeline.
Implementations§
Source§impl Frontmatter
impl Frontmatter
Sourcepub fn has_agent_doc_marker(&self) -> bool
pub fn has_agent_doc_marker(&self) -> bool
Does this frontmatter carry any agent-doc-managed field?
Used by the opt-in document gate
(crate::project_config::is_agent_doc_document) to recognize a .md
that the user clearly authored as an agent-doc session. Plain
notes/README frontmatter (title/date/tags) carries none of these, so it
is not auto-converted. This is the single source of truth — keep it in
sync when adding new session-defining frontmatter fields.
Sourcepub fn resolve_mode(&self) -> ResolvedMode
pub fn resolve_mode(&self) -> ResolvedMode
Resolve the canonical (format, write) pair from all three fields.
Priority:
- Explicit
agent_doc_format/agent_doc_writefields (highest) - Deprecated
agent_doc_modefield (auto-migrated) - Defaults: format=template, write=crdt
Sourcepub fn resolve_harness_model(&self, harness: &str) -> Option<&str>
pub fn resolve_harness_model(&self, harness: &str) -> Option<&str>
Resolve the effective model for attribution, given the active harness.
Priority: harness-specific field (claude_model / codex_model / opencode_model)
over generic model.
Harness mapping: "claude-code" uses claude_model, "codex" uses codex_model,
and "opencode" uses opencode_model.