feat(workflow): tail-only loop break, final-step outcome report, artifact handoff

[Cidan]

Restores three workflow behaviors that the graph migration (#136) dropped or weakened, each done the ADK-native way.

1. Only the tail step of a loop can break out

exit_loop was attached to every inner step, so any step could end the loop. Now it's attached to the last inner step only.

// pkg/workflow/compile.go
if role.InLoop && role.IsTail {
    tools, err = withExitLoopTool(tools)
}

exit_loop sets Actions.Escalate — the only way an ask tool ends a loopagent — and no other tool touches Actions. So withholding the tool makes an early break structurally impossible for the non-tail steps. This is your old end_turn decision guard, except the old one detected the violation after the fact and re-prompted; this one makes it unrepresentable. The non-tail loop instruction is reworded to say the step cannot end the loop.

2. finish_workflow is attached again (regression fix)

The tool and the Progress capture both survived #136, but nothing attached the tool to a step once the graph became one session (the old IsWorkflowFinalStep flag was per-session). So runs reported no artifacts to the user. It's now attached to the final step, which is how the user learns what a run produced — PR links, tickets. Not optional.

3. Artifacts pass structured data between steps

Every step gets save_artifact and load_artifacts. This works now where it didn't before #136: the whole graph runs as one runner invocation, so the runner's ArtifactService (from RunnerBuilder) spans every step — a save in step 1 is visible to a load in step 3.

ADK ships load_artifacts but no save tool, so SaveArtifactTool is the missing half:

resp, err := ctx.Artifacts().Save(ctx, name, genai.NewPartFromText(p.Content))

This is the ADK-native replacement for the old ask/plans/ notes directories.

Mechanics

CompileWorkflow hands each step a StepRole{InLoop, IsTail, IsFinal} through its ToolsBuilder. IsTail gates exit_loop, IsFinal gates finish_workflow. The TUI builder (cmd/ask/workflow_graph.go) appends tools.WorkflowStepTools directly; the headless builder passes WorkflowStep/WorkflowFinalStep flags to the tool factory, which appends them in BuildCoreTools (pkg/engine can't import pkg/tools, hence the flag indirection).

Tests

• StepRole is computed correctly for linear / loop / final-loop shapes (the tail of a final loop is both IsTail and IsFinal)
• WorkflowStepTools attaches save+load always, finish only on the final step
• save_artifact writes name+content through ctx.Artifacts().Save (verified with a fake store), and returns a real Go error — so retryandreflect sees it — when there's no service or no name
• the loop instruction tells only the tail step how to break, and only the final step to call finish_workflow

make test green across all 9 packages.

Note

I did not touch docs/ — it was intentionally removed in 3683f9d. All doc updates are in CLAUDE.md.

🤖 Generated with Claude Code

[Cidan]

Added the real end-to-end test: TestWorkflowArtifactHandoff in pkg/engine/workflow_artifact_integration_test.go.

A two-step workflow runs on the actual ADK graph — step 1 calls save_artifact, step 2 calls load_artifacts — and the test asserts the saved content reaches step 2's model. It's in the external engine_test package so it can import pkg/tools (registering the real tool factory) without the tools -> engine cycle.

It's airtight against a false pass: the secret must be absent from the reader's step handoff (proving IncludeContentsNone keeps the saver's tool calls out) and present only after load_artifacts resolves. Verified with a negative control — a mismatched artifact name fails as expected.