Goals

/goal <objective> (or chanto goal "<objective>") works toward an objective over as many turns as it takes, not just one:

1. Criteria: the same first steps as outcome mode. The agent explores read-only and writes executable acceptance criteria, they run once as a baseline, and you approve them. From then on they're locked: Chanto runs the copy recorded when you approved them, and if the agent edits the criteria files, Chanto puts them back and tells it so. That iteration doesn't count as progress.
   • How criteria run. Every criterion runs the same way: in the baseline, after every iteration, and in the instructions the agent gets. Its check is a shell command run from the project root (a background goal's worktree). CHANTO_GOAL_DIR (the goal directory) and CHANTO_PROJECT_ROOT are set, and the project root is on PYTHONPATH, so check scripts are written as python3 "$CHANTO_GOAL_DIR/checks/test_x.py" and can import project modules. The agent is shown the exact line to reproduce a run (cd <root> && CHANTO_GOAL_DIR=… <check>).
   • Checks that can't run. The baseline tells "fails because the behavior is missing" apart from "fails because the check can't run". The second covers: a checks/... path that names the goal directory relative to the project, a command that isn't installed, an import of a project module that fails, a syntax error in a check script, and a timeout. Those criteria are flagged ⚠ can't run at approval, and you can let the agent fix them before anything is locked. Unattended, the agent gets two fix rounds, and if the criteria still can't run the goal stops and says why.
2. Iterations: each iteration is one agent turn. The agent plans the next step for the failing criteria, does it and runs the checks. Then Chanto runs every criterion itself and appends the result and the agent's summary to the goal's progress log. The next iteration starts from that log and the latest failure output. Existing tests are protected as in verified mode: weakening one doesn't count either.
3. Done when every criterion passes and no project check (verified mode's checks, or the detected ones) that passed when the work began fails now. A check that already failed then, or can't run in this project, doesn't hold the goal back.

It stops early, with a report saying why, when:

• it hits the iteration limit;
• it hits no progress: several iterations in a row without a new criterion passing (the report lists what still fails);
• it hits the budget or time limit;
• you pause or stop it;
• it's blocked: the agent ends a turn with BLOCKED: <what it needs> (a credential, a decision, access). Interactively, Chanto asks you, and your answer goes into the next iteration. Unattended, the goal stops as blocked.
• a criteria problem comes up: after an iteration a locked criterion fails because it can't run, or the agent ends with CRITERIA PROBLEM: <id and why>. Then the project may already be right and only the criteria are wrong, so Chanto doesn't keep iterating. Interactively it offers to unlock the criteria: the agent fixes them, you approve them again, and they're locked again. You can also keep going or stop. Unattended, the goal stops as blocked, and /goal resume starts with that fix-and-approve step.

The status line shows ◎ goal 2/5 · iteration 3 (criteria passing / total). /goal status shows the objective and each criterion. /goal pause stops after the current iteration, and /goal stop stops at once (both work while it runs). /goal resume [id] continues the newest unfinished goal, or the one you name. /goal list lists this project's goals. From another terminal, run chanto goal pause|stop [id]. Esc interrupts and pauses the goal. Limits count from the start or from the last resume.

Where its state lives. ~/.chanto/goals/<id>/ holds goal.json (state, the locked criteria, counters), criteria.json and its check scripts, progress.md and report.md. They live outside the project, unlike outcome mode's .chanto/outcome/. That keeps the bookkeeping out of git status and out of a background run's commits, it survives git clean and worktree removal, and the agent can't edit its own criteria without a permission prompt. When the conversation is compacted, the objective, the criteria and the tail of the progress log are put back into the conversation. After a restart, /goal resume reloads everything from that directory.

In the background. chanto goal --bg "<objective>" (or /goal --bg <objective>) runs it as a background run with the run id as the goal id. Approving the criteria is a needs-input question, answered with chanto attach or /runs attach. The run's own budget and wall-clock limit apply too. chanto runs resume <id> continues an interrupted goal run from its goal directory. A scheduled job with kind = "goal" starts goal runs the same way.

[goal]
max_iterations = 20          # work iterations (also `chanto goal --max-iterations N`)
max_stale_iterations = 3     # in a row without a new passing criterion
# max_cost_usd = 5.0         # default: no goal budget (the session budget still applies)
max_minutes = 120