goal_tools

Lifecycle status of a TUI-owned goal.

active and blocked are unfinished working states, paused preserves the goal without driving work, and complete is terminal. A blocked goal is still considered actionable (active=True) by get_goal, whereas a paused goal is unfinished but reports active=False.

Tool names used by behavioral absence gates and middleware contract tests.

Build one canonical append-only goal/rubric state notice.

Return a stable digest for authoritative goal/rubric state.

Return whether state contains a goal or an active rubric.

Return the newest goal-state source index, including invalid messages.

Return the newest valid notice and its raw-history index.

Return whether the latest human turn carries an unsaved goal fallback.

Narrow a persisted goal-status value to a known GoalStatus.

A corrupt or forward-version checkpoint can carry an unexpected status string (or a non-string). Coercing to None rather than passing the raw value through keeps the GoalStatus Literal load-bearing on the read path, so an unknown status is treated as "no goal status" instead of a silently active goal. Resume/restore callers should log the discard separately so it is surfaced rather than dropped; the model-read path (_goal_snapshot) intentionally treats an unknown status as active without logging.

Goal/rubric state channels shared by every schema that touches them.

Declared once here so each schema that carries these channels — ResumeState and goal_tools.GoalToolState — inherits the same PrivateStateAttr-marked annotations. Middleware state schemas merge with later entries winning, so an independent re-declaration that dropped the PrivateStateAttr marker would override these and leak the field into the public graph input/output schema. Inheriting from a single base makes that drift unrepresentable.

Read-only rubric view returned by the get_rubric tool to the model.

active is always criteria is not None; the two never disagree.

Read-only goal view returned by the get_goal tool to the model.

A fixed-shape projection of goal state. Both construction branches in _goal_snapshot must populate every key, so the type checker catches a drift between them.

State fields used by goal tools.

Inherits the shared _goal_*/_sticky_rubric channels (with their PrivateStateAttr markers) from GoalRubricChannels, so the goal tools and ResumeState cannot drift apart. Adds only the public rubric graph input, which is intentionally non-private — it is the RubricMiddleware input.

Expose constrained goal tools and maintain the goal-state notice.

Besides registering get_goal/get_rubric/update_goal, this middleware keeps the model oriented at each model boundary: before_model persists a fresh goal-state notice into checkpointed history when the latest one no longer matches authoritative state, and wrap_model_call re-pins the notice into the (post-summarization) request when the persisted one is out of view. Tool usage guidance lives in the tool docstrings and notices.