Chain file keys

read_only

How read_only makes Kraft verify that a step, node or recovery plan leaves the checkout as it found it, and what happens when it doesn't.

read_only goes on a step, an exec node or an on_failure plan, never on a task. A task that sets it is refused at load. On a plan, it makes every step of the plan read_only, the one a tasks plan becomes included.

  • What is checked. Before a read_only step's first task launches, Kraft records each repository of the checkout (the root and every workspace member): HEAD, git status --porcelain=v1 -z (ignored files stay out), and a hash of git diff HEAD. It reads them again after the last task exits. A read_only node does the same around all of its steps.
  • What counts as a change. Any difference, including an untracked file or a commit.
  • What happens. The item stops and waits for you, with a read_only_violated event and a stop reason naming the changed files. It isn't a task failure, so no recovery, fix loop or attempt is spent on it.
  • Exclusions. A read_only step's check doesn't cover a recovery or a fix loop. It runs again when a recovery retries the step's tasks. An on_failure plan, or a step in it, may be read_only, and is then checked around its own tasks. A fix_loop, an on_conflict and an on_merge_rejected repair write by design, and refuse read_only.
  • What the agent is told. An agent task in a read_only step, or in one of a read_only node's own steps, gets the read-only contract (change, write and commit nothing, run no tests) instead of the one that says to run tests and commit. A task in a handler of a read_only node doesn't, as the node's check doesn't cover it.
  • Sandboxed items. In a sandboxed item, if the worktree gains a repository Kraft didn't create, Kraft runs no host git there and reports that repository as the change.
  • Default. Off. The shipped chains set it on verification.review and review_feedback. Setting it on both a node and its steps is allowed and redundant.
Copyright © 2026