policy.yaml

policy.yaml sets caps, budget, concurrency, archiving, and defaults for every work item. It lives at $KRAFT_HOME/config/policy.yaml.

kraft admin reload rereads this file with the same validation as startup. If the file does not validate, Kraft keeps the running policy and reload exits 1 naming why. New loop caps apply to loops that start after the reload.

For how caps, maxima and layers combine, see Caps and budgets.

loops: {}
default: { attempts: 3, wall_clock_s: 3600 }

findings:
  loop_severities: [critical, important]

max_concurrent: 3

budget:
  work_item_usd: 10
  daily_usd: 50

rate_limit_retries: 5
forge_cli_timeout_s: 120

archive:
  after_days: 30

The shipped file also holds defaults: and maxima: as comments; see defaults and maxima.

Top-level keys

A budget cap refuses to start the next agent task and cannot interrupt one that is running. See Caps and budgets.

Storage keys

storage.worktrees bounds the disk the worktrees use:

storage:
  worktrees:
    limit: 10G
    quota: 8G
    auto_cleanup:     # optional; the block being there turns it on
      min_age: 24h

• A size is a whole number and a unit, K, M, G or T, in either case, and binary: 1G is 1024³ bytes. A bare number such as 10 is refused, because it would be a 10-byte limit.
• Without limit nothing is measured, warned about or held. quota without a limit, or at or above it, is invalid.
• Kraft counts worktrees/, sandbox-git/ and sandbox-home/ under run/: what archiving an item removes. Logs, databases, attachments and Docker's images and volumes are not counted.
• The figure is measured at startup and every 10 minutes, and matches du. An archive or abandon takes that item's size off it at once.
• At or under quota, nothing happens. Over quota, /api/health and kraft admin doctor warn.
• Over limit, a start that would create a new worktree is queued until usage is back under the limit, and its item gets a work_item_storage_held event. A resume or retry of an item that already has a worktree is not held.
• Unless auto_cleanup is set, Kraft never archives or deletes anything for the limit. archive.after_days works as before. See Limit the disk worktrees use.
• auto_cleanup turns on automatic clean-up. auto_cleanup: {} is min_age: 24h, and auto_cleanup: with nothing after it is off. It needs a limit.
• min_age is a whole number and h or d, in either case: 12h, 24h, 2d. Days are the largest unit, so 1w is refused, and so is a bare 24. 0h means no floor.
• Over limit, Kraft archives completed and abandoned items that have a worktree and ended at least min_age ago, oldest first, until usage is at or under quota. One archive runs at a time, and one item's failure is logged and skipped.
• Archiving removes the worktree and any uncommitted changes in it. A branch with unpushed commits is kept, and the item stays restorable under Archived. Its work_item_archived event carries by: auto and reason: storage.
• When that cannot free enough, because every finished item is newer than min_age or the rest is live work, starts stay held and kraft admin doctor says how many finished items were too recent.
• A running item can pass the limit between two measurements. The limit stops the next start, not work in flight.

kraft admin reload applies a change.

Loop keys

loops maps a loop key to its own attempts and wall_clock_s. A key that names no live loop is silently unused, so spell it exactly:

loops:
  verification.fix_loop: { attempts: 5, wall_clock_s: 7200 }

Retired and moved keys

defaults and maxima

Kraft ships these commented out, because an uncommented value is a real ceiling. This example is illustrative. Uncomment and edit it to use it:

# defaults:
#   timeout_minutes: 60
#   max_attempts: 3
#   allowed_harnesses: [codex, claude]
#   escalation_harness: claude
#   work_item: { time_cap_minutes: 480, total_time_cap_minutes: 2880, budget_usd: 20 }
#   nodes:     { time_cap_minutes: 180 }
#   steps:     { time_cap_minutes: 120 }
#   tasks:     { time_cap_minutes: 90 }
# maxima:
#   timeout_minutes: 180
#   allowed_harnesses: [codex, claude]
#   work_item: { time_cap_minutes: 1440, token_budget: 2000000, budget_usd: 25 }
#   tasks:     { time_cap_minutes: 240, total_time_cap_minutes: 10080 }

defaults takes timeout_minutes, max_attempts, allowed_harnesses, escalation_harness, escalation_grants and the per-level caps. maxima takes allowed_tools, allowed_harnesses, timeout_minutes, max_attempts and the per-level caps.

Two rules hold for both sections:

• A narrower level's cap may not exceed a broader one's (tasks <= steps <= nodes <= work_item), and a defaults entry may not exceed its level's maximum. Kraft refuses either when it reads the file, naming both.
• A cap written flat (defaults: time_cap_minutes: 30) is refused, with a message naming the level form to use.

Policy fields

These keys go in a policy: block on a repo (repos.yaml), a chain, a node, a step, a task, or a work item's override. Kraft applies the layers from the broadest to the narrowest. The "Rule down the layers" column says how a layer may change what it inherits: the safety fields only narrow, and the operational ones move either way within maxima. Kraft refuses a layer that breaks its row's rule, and names the scope.

A launch into a sandbox with neither network: nor unrestricted_network: true is refused. Which tool policies a sandbox refuses depends on its network:; see Tool policy.

Tool lists

allowed_tools and deny_tools hold tool names, never permission rules. Use a bare tool (Bash, Read) or one exact MCP tool (mcp__kraft__report_progress). Kraft refuses a scoped rule (Bash(git *)), a glob (mcp__github__*) or a whole server (mcp__github) wherever the list is read, and the message names the field and the name to write instead.

What a harness does under an allowed_tools list:

Allowing Bash allows its read-only use without a gate ask. Claude runs a read-only shell command (cat, ls, git status) itself, so it can read any file the worktree holds, gitignored ones included.

Related

• Caps and budgets: how caps, maxima and layers combine.
• Permission gate: how tool lists and grants are enforced.
• Chain file keys: where a chain, node, step or task sets its own policy:.