Struct Frontmatter 

pub struct Frontmatter {

    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 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 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_active: Option<bool>,
    pub collaboration: Option<CollaborationMode>,
    pub security_review: Option<String>,
}

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.

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.

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_active: Option<bool>

Whether the queue is currently active (consuming prompts). Set to true when the queue is activated via auto, start fence, or do queue/run queue. Cleared when the queue drains to empty.

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.

Implementations

impl Frontmatter

pub fn resolve_mode(&self) -> ResolvedMode

Resolve the canonical (format, write) pair from all three fields.

Priority:

1. Explicit agent_doc_format / agent_doc_write fields (highest)
2. Deprecated agent_doc_mode field (auto-migrated)
3. Defaults: format=template, write=crdt

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.

pub fn collaboration_mode(&self) -> CollaborationMode

pub fn has_security_review(&self) -> bool

Trait Implementations

impl Clone for Frontmatter

fn clone(&self) -> Frontmatter

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Frontmatter

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

Formats the value using the given formatter.

impl Default for Frontmatter

fn default() -> Frontmatter

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Frontmatter

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Frontmatter

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

where __S: Serializer,

Serialize this value into the given Serde serializer.