claude-code - 💡(How to fix) Fix [DOCS] `/goal` docs do not explain evaluator waits for background shells or delegated subagents

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/goal

Section/Topic

How evaluation works and the turn-completion semantics for /goal

Current Documentation

The docs currently say:

The /goal command sets a completion condition and Claude keeps working toward it without you prompting each step. After each turn, a small fast model checks whether the condition holds. If not, Claude starts another turn instead of returning control to you. The goal clears automatically once the condition is met.

And later:

/goal is a wrapper around a session-scoped prompt-based Stop hook. Each time Claude finishes a turn, the condition and the conversation so far are sent to your configured small fast model, which defaults to Haiku.

Related docs also say:

Background subagents run concurrently while you continue working.

What's Wrong or Missing?

The /goal page explains that evaluation happens after each turn, but it does not define whether a turn is considered finished while Claude still has in-flight background shell commands or delegated subagents.

That missing detail matters because changelog v2.1.143 says:

Fixed /goal evaluator firing while background shells or delegated subagents are still running

So the actual behavior is more specific than the current docs imply: /goal should wait for outstanding delegated/background work to finish before the evaluator checks whether the condition is met.

Without that clarification, users cannot tell whether /goal may evaluate success too early, whether background shells and delegated subagents count as part of the active turn, or whether they need to avoid those workflows when using /goal.

Suggested Improvement

Add a short note under How evaluation works that makes the turn boundary explicit. For example:

/goal evaluates only after the turn is actually complete. If Claude still has a background shell command or delegated subagent running, the evaluator waits for that work to finish before checking the goal condition.

Also consider adding one sentence near the command overview clarifying that long-running delegated/background work can delay goal evaluation until it completes or is stopped.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: Changelog v2.1.143 says: Fixed /goal evaluator firing while background shells or delegated subagents are still running