Canopy

Template Variables

Last updated 2026 · Sol 303 · 20:05 UTC

Agent node prompts support these placeholders:

Outputs are read from nodes, never from ensembles: {{output:<name>}} naming an ensemble is refused, and the message names the ensemble’s quorum node when one exists — that node is the source meant instead. Any other placeholder nothing can bind is refused when the template is written — graph_node add, graph_node update, graph_ensemble add and graph_ensemble update (the shared prompt and every member prompt_override), and graph_edit import (all-or-nothing) — naming the node or ensemble and the placeholder, plus the forms it accepts when the fix is a different marker, instead of failing member by member at run time. A marker meant as literal text stays accepted when escaped as \{{...}}. A prompt_preset is a file name, not text, so it keeps its spawn-time check. A router’s prompt_template binds only {{previous_feedback}}, {{previous_output}}, {{spec_content}} and {{spec_name}}: it reads no node output, so an {{output:…}} marker there is refused as well.

A template stored before this validation is reported by graph_control preflight in graph_warnings, one entry per offending placeholder naming the node or ensemble — advisory only, since the spawn-time refusal still applies. The exception is an unknown {{output:…}} target in a graph node’s prompt_template, which preflight has always refused as an error.

Check node commands

Check node command strings have their own marker vocabulary, separate from the agent-prompt table above — a check command cannot use {{spec_content}}, {{node_id}}, {{previous_feedback}} or {{output:…}}. Every marker a check command supports:

The shell-quoted markers expand to a single POSIX-quoted shell word, so a name containing spaces or quotes can never break or inject into the command. Write them bare ({{spec_name}}) or already single-quoted ('{{spec_name}}' — the engine strips that exact wrapper so the quoting is not doubled), never inside other quotes; a \{{marker}} escape stays literal text. The raw markers expand unquoted exactly as before.

Any other {{…}} marker fails the check node before the command runs: the run records unknown marker {{x}} in check command and nothing reaches the shell. graph_control preflight reports the same defect as an error before spending any probe quota.

Every check command also runs with these environment variables (there is no CANOPY_WORKDIR — the command’s working directory already is the workdir):

{{spec_start_head}} only proves some commit landed since the spec began; it’s satisfied just as well by a commit from outside this run sharing the same worktree (another agent, a human, a cherry-pick) as by this spec’s own work. A check node that exists to gate “did this spec’s work actually get committed” should use {{spec_committed_head}} instead:

{{spec_start_dirty}} is the number of non-ignored entries reported by git status --porcelain at the spec boundary. It is empty when the workdir is not a Git repository or when reading a legacy run, rather than being reported as clean.

spec_end_dirty/spec_end_dirty_paths (readable via graph get/ graph node_runs, not a template placeholder) record the same count and the first 20 paths at the moment the spec’s attempt actually ends — Completed, Failed, or Interrupted. A spec that ends Failed or Interrupted with a dirty tree folds a one-line note onto its own failure summary/blocker text and (for a plain Failed ending) onto the on_failed hook’s {{node}} value.

graph_control run and the autorun scheduler refuse to launch the next spec when the workdir is currently dirty and a different spec of the same graph — or a member of its active queue run — ended Failed or Interrupted with recorded dirty paths that overlap the ones dirty now. Records from other graphs, and from standalone backlog specs outside the active queue run, are ignored, so a stale row elsewhere on the workdir never blocks a spec resuming its own work. Completed specs never block, and neither do Skipped ones: a skipped spec never ran, so its stale record must not make a later spec’s own dirt look ambiguous. The comparison uses the (first 20) paths each spec recorded at its end, so a record naming files that are no longer dirty never blocks. A spec resuming interrupted work of its own proceeds when the dirty paths are exactly the ones its own latest run recorded. The warning names the spec whose last recorded run in this graph left the workdir dirty (graph_runs joined to spec_end_dirty > 0); when no run of this graph recorded dirt the warning says dirty before this graph ran and names no spec. A resuming spec is still refused while another spec of the same graph (or active queue run) left overlapping dirt on the workdir: the refusal names the blocking predecessor — its name (id when the name is empty), the graph it ran in, its end status and end time — and, when the next spec is resuming its own dirt, says so in the same line. Finish, reset or remove that blocking spec (or set allow_dirty_start) to proceed. When the launch proceeds, the warning says why — allow_dirty_start is set on the graph, or the next spec is resuming the dirty work it left itself — instead of telling you to set a flag. When it blocks, the message says not launched before the Set allow_dirty_start hint. Set allow_dirty_start: true via graph_edit update to downgrade a refusal to a warning. graph_control preflight separately reports a dirty workdir as a warning unconditionally, with no “previous spec” logic — call it before graph_control run to see this regardless of history. A queue run applies the same guard between its specs, not only at launch — see Spec queues.

test -z "$(git status --porcelain -- src/)" \
  && test -n "{{spec_committed_head}}" \
  && test "$(git rev-parse HEAD)" = "{{spec_committed_head}}"

This requires a node in the graph to declare commit_rights: true — without one, nothing ever populates {{spec_committed_head}} and the check above always fails. {{spec_start_head}} remains useful on its own for anything that only needs “did the tree change at all”, where a concurrent commit from outside this run isn’t a concern.