[Feature] Per-agent and per-phase goal in the Workflow tool (scope the /goal self-verification loop below the session level)

[Feature] Per-agent and per-phase goal in the Workflow tool (scope the /goal self-verification loop below the session level)

Summary

Allow a goal (a verifiable completion condition, like /goal) to be attached to an individual agent() and to a phase() inside a Workflow script — not just to the whole interactive session.

Today a goal is session-scoped only. Inside a Workflow, an agent is fire-and-forget: it runs its prompt once and returns. There is no declarative "keep working until condition X holds" at the agent or phase granularity. Bringing the existing /goal self-verification machinery down to the agent/phase level would make workflows meaningfully more autonomous (each unit drives itself to a defined end state) and more controllable (the end state is explicit and checked, not implied by the prompt).

Current behavior (verified)

• /goal exists but is session-level only — one goal per interactive session, evaluated turn-by-turn by a fast model until the condition holds. Docs: code.claude.com/docs/en/goal.md.
• agent(prompt, opts) in the Workflow tool accepts label, phase, schema, model, effort, isolation, agentType. There is no goal / objective option. The agent runs its prompt once and returns.
• phase(title) only groups agents in the progress view. It has no completion condition.
• Workarounds today require hand-rolling the loop in the script:

``js
// manual goal loop — works, but every author re-implements eval + retry + stop-conditions
let done = false, tries = 0;
while (!done && tries++ < 5) {
const r = await agent(prompt, { schema: RESULT });
const verdict = await agent(Does this satisfy: "${goal}"? ${JSON.stringify(r)}, { schema: VERDICT });
done = verdict.satisfied;
}
`
This is exactly the loop /goal` already automates at session level — it just isn't reusable per agent/phase.

Proposed behavior

Add an optional goal to agent() options and to phase(), reusing the existing /goal evaluator loop:

// Per-agent goal: the agent self-iterates (re-turns), a fast model checks the
// condition after each turn, and agent() resolves only once it holds (or a
// maxTurns budget is exhausted).
const fix = await agent('Fix the failing auth tests', {
  goal: 'all tests in services/gateway/tests/auth pass',
  maxTurns: 6,           // safety bound; reuse existing budget/turn semantics
  schema: RESULT,
});

// Per-phase goal: the phase is not considered complete until the condition
// holds; the runtime may re-run / spawn agents in the phase to converge.
phase('Harden', { goal: 'no HIGH findings remain in the security report' });

Semantics to define (open for discussion):

• Evaluator: same fast-model check as /goal (configurable model, defaulting to the session's fast/Haiku evaluator).
• Bound: a required or default maxTurns / token budget so a goal can't loop forever; on exhaustion resolve with a clear "goal-not-met" result the script can branch on (never hang).
• Return shape: agent() with a goal should surface whether the goal was met (e.g. { metGoal: boolean, ... }) so the script can react.
• Phase goal: define whether it re-runs the phase's existing agents, spawns new ones, or just gates completion + reports.
• Composition: goals compose with schema, parallel(), pipeline() as usual.

Why this matters

• Autonomy: each agent/phase drives itself to a defined, verifiable end state instead of "run once and hope the prompt was enough."
• Control: the success condition is explicit and machine-checked, so a long autonomous workflow is auditable ("phase X converged on goal Y") rather than opaque.
• DRY: the self-verification loop already exists for /goal; this just scopes it below the session so authors stop re-implementing eval+retry loops by hand.

Out of scope / already covered

• Asynchronous waiting for agent responses is already supported — workflows run in the background, parallel()/pipeline() fan out concurrently, and progress is observable via /workflows. No change requested there; noting it so it isn't conflated with this request.

Environment

• Claude Code Workflow tool (agent() / parallel() / pipeline() / phase() orchestration).