Switch a task to another harness

Every agent task Kraft ships runs on Claude Code. This guide moves tasks to another agent CLI, which Kraft calls a harness. The examples use Codex. The steps are the same for the other shipped harnesses.

The harness is a property of the task in your templates. There is no per-item harness switch: kraft item set-overrides changes the model and effort only. To run one item on another harness, give it a chain that sets the harness, as in step 2.

Before you start

• The CLI is installed, on the PATH of the shell that starts Kraft, and logged in. A worker has nobody to answer a login prompt. For Amp and Cursor, see Set up Amp or Cursor credentials.
• Read the harness's row in the harness table. It lists what that CLI cannot do.

1. Check the harness profile

A task names a profile from $KRAFT_HOME/templates/harnesses.yaml, not a CLI. The shipped file has two profiles, claude and codex:

harnesses:
  codex:
    provider: codex
    enabled: true
    executable: codex
    defaults:
      effort: medium

For another shipped harness, add a profile the same way, with provider set to its id (cursor, opencode, gemini or amp). See Harnesses file.

A task with profile: strong gets its model from the profiles: section of the same file, keyed by provider. The shipped strong and deep tiers name a Codex model. fast does not, so a fast task on Codex cannot start: the item stops with profile 'fast' has no model for provider 'codex'. kraft admin templates lint does not catch this. Add the provider to a tier before you move a task that uses it. Amp takes no model, so a task on Amp sets effort: itself instead of a profile.

2. Pick which tasks move

List the tasks each profile runs:

kraft admin harnesses
kraft admin harnesses claude

Then choose how far the change reaches.

Every chain. Change harness: claude to harness: codex on the tasks you want to move in library.yaml. Every chain that extends them follows.

One chain. Leave the library alone and override the task in the chain file. A key set next to extends wins over the library's:

# chains/codex-impl.yaml
id: codex-impl
nodes:
  - id: implementation
    kind: exec
    tasks:
      - id: implement
        extends: implementer
        harness: codex

One item. File it on a chain like that one, with kraft item create "title" --chain codex-impl, or switch an item that has not started with kraft item set-chain ID --template codex-impl.

Kraft's own kraft: skills, such as kraft:code-review, are sent to the agent in its instructions, so they work on any harness. A skill from another plugin (plugin:skill) needs that plugin installed for the new CLI. If it cannot load, the task stops and asks for it.

3. Allow the profile

Skip this step if nothing in your policy sets allowed_harnesses.

allowed_harnesses can appear in policy.yaml under defaults: or maxima:, in a repo's policy: in repos.yaml, or in a chain, node or task policy:. When it is set, it must include the new profile. Otherwise Kraft refuses the item when you file it:

kraft 422: policy.allowed_harnesses: implementation.main.implement: harness 'codex' is not in its allowed_harnesses ['claude']

4. Check tool lists

An allowed_tools list in the task's policy can stop the new harness from launching:

• gemini has no way to restrict tools, so it refuses to launch under any allowed_tools list.
• codex enforces the list through Kraft's permission hook, which never sees its web search. It refuses a list that leaves out WebSearch.
• cursor refuses a list that leaves out WebFetch and WebSearch, for the same reason.

The refusal happens at launch. The item stops for you, and the stop reason names the harness and the missing tools. Add the tools to the list, or keep that task on Claude. See Policy fields and the Permission gate.

5. Decide where escalation runs

An escalation turn runs on claude unless policy says otherwise. To move it too, set escalation_harness in policy.yaml:

defaults:
  escalation_harness: codex   # or `item`: the harness the item's last agent task ran on

See Fallback and escalation.

6. Load it

kraft admin templates lint
kraft admin reload

Cost reporting changes

Codex, Cursor and Amp report tokens but no cost. Kraft estimates it from prices.json when it can price the model: Codex on the model it launched with, Amp on the model its log names. Cursor, a Codex task that passes no model, and any model the table lacks can't be priced. For those:

• budget.work_item_usd, budget.daily_usd and kraft item create --budget count their sessions as $0 and warn once on the item's timeline.
• A per-scope budget_usd treats their spend as unknown and stops the next launch in that scope for you. No higher cap passes that stop; see Raising a cap for budget_usd=none, the way past it.
• The board shows their tokens, with no dollar figure.

kraft admin doctor warns about each such harness. Use token_budget to bound them. See Harnesses that report no cost.

Verify

kraft admin harnesses
kraft admin templates show codex-impl --resolved
kraft admin doctor

• kraft admin harnesses lists the moved library tasks under the new profile. It lists library tasks only, so a chain-level override does not appear there.
• show --resolved prints harness: codex on each task you moved.
• kraft admin doctor has an agent: codex row once a chain selects the profile. It fails when the executable is not on PATH.

File a small item on the chain. kraft view show ID shows its token count and no dollar figure once a Codex session has run.