Call immediately whenever cast_omen returns doubles=True — this isn't
the player's to invoke, Claude always calls it. Plays the oldest
outstanding debt card if any are owed (owed debt always comes due
first), otherwise deals a fresh card from the Fortuneteller's Hand
deck. Either way the landing must intrude on the scene — it costs
something, and the original question the omen asked stays unanswered.
If the player wants to fight the landed fortune, that's when they call
defiance (see defy_roll).

Takes no parameters. Not idempotent: mutates the shared debt row
(pops the oldest card) or the shared Hand deck (deals a fresh card).
Returns a dict with source ("debt_row" or "fresh_deal"), card (the
landed card's rank/suit/phrase/etc.), and a fixed note reminding you
the landing must intrude and the question stays unanswered.

Call whenever a scene reaches something no one can know in advance —
other hearts, hidden things, or the turn of luck — or when a player
claims an uncertain, high-stakes action simply succeeded. At least one
omen must be asked before a scene can close. Not for material that just
needs new story content rather than a yes/no answer — use
draw_unclaimed_card for that instead.

hope: a plain sentence naming the real stakes being asked about — what
the asker hopes is true (e.g. "I hope the guard doesn't notice me").

Not idempotent: each call rolls fresh dice and increments an internal
counter that alternates who narrates the result. Doesn't mutate any
other game state. Returns a dict describing the roll: on doubles,
{hope, light, dark, doubles: True, reading} — no answer, the Hand is
called instead (see call_the_hand). Otherwise {hope, light, dark,
doubles: False, direction, gap, texture, complication_rank,
complication_meaning, grounds_by} — direction and gap give the answer's
shape, grounds_by says whether the player or Claude narrates the
complication.

Call at most once per Sitting, only after an Omen's grounding has landed
and, checked against the Goal's saved interpretation (get_sheet's 'goal'
field), genuinely resolves what the Goal meant — never call this
preemptively, ahead of the grounding that earns it. Distinct from
draw_goal_card, which deals the Goal at the start of the Sitting;
complete_goal only marks it finished later in play.

Takes no parameters. Idempotent in effect (repeated calls leave the flag
True) but should only be invoked the one time the resolution actually
happens. Sets and returns goal_completed as True.

Call once, after defy_roll has been called at least once and the
player is done rolling (whether by choice or because three rolls were
taken). Ends the current defiance ritual — a subsequent defy_roll call
starts a fresh one from scratch.

Takes no parameters. Raises ValueError if called before any defy_roll
in this ritual. Not idempotent: mutates the shared debt row, adding
one debt card per roll taken during the ritual (more rolls, more debt,
win or lose), and clears the ritual's dice/roll-count state. Returns a
dict with final_dice, rolls_taken, pattern and bend (None if no
scoring pattern was hit — otherwise three of a kind/"turn the blade",
small straight/"stay the hand", full house/"take the cup", or five of
a kind/"seize the pen"), and debt_dealt (the cards just added to the
debt row).

Call once to make the first roll (keep=None or []), then optionally
call again up to two more times to re-roll, keeping whichever dice the
player wants to hold between rolls. Up to three rolls total; call
defy_resolve once the player is satisfied with the dice (or after the
third roll) to lock in the result and deal debt.

keep: the die face values (1-6) to hold onto from the current dice
before rolling the rest fresh — e.g. keep=[6, 6] to hold two sixes.
Must be a subset of what's actually currently showing (raises
ValueError otherwise), and must be empty/None on the very first roll of
a ritual (there are no dice to keep yet).

Not idempotent: mutates shared dice/roll-count state across calls
within one defiance ritual; each extra roll taken also means more debt
dealt later at defy_resolve. Returns a dict with dice (sorted current
values), rolls_taken, rolls_remaining, and current_pattern/current_bend
if the dice already match a scoring pattern (three of a kind, small
straight, full house, or five of a kind — see defy_resolve).

Call once per drive during the Sitting, after the player has chosen a
suit for that drive: Motivation, then Seek, then Carry, then Ends, in
that order. Each of the four positions and each of the four suits can
only be used once each — calling this with a position or suit already
used raises ValueError. "Blind" means the card is drawn face-down from
the matching suit's own 13-card pile without looking; don't reveal its
phrase to the player until all four drives have a card.

suit: which of the four card suits (♥ Hearts, ♦ Diamonds, ♣ Clubs,
♠ Spades) the player chose for this drive — each suit represents a
different domain of meaning (love/loyalty, wealth/ambition,
labor/growth, death/conflict).
position: which of the four drives this card fills — Motivation, Seek,
Carry, or Ends.

Not idempotent: mutates the shared cross and removes a card from the
suit's pile. Returns the drawn card as a dict with rank, suit,
suit_name, domain, rank_meaning, and phrase.

Call once, during the Sitting, right after all four calls to
draw_cross_card are done (one per drive: Motivation, Seek, Carry, Ends)
and the player has described their character. Unlike draw_cross_card,
this draws from the combined remainder of all four suit piles at once,
not one specific suit — and it's revealed to the player immediately,
not held back. After dealing it and asking what it means, pass the
player's answer to record_goal_interpretation.

Takes no parameters. Raises ValueError if called before all four cross
positions are filled, or if a Goal has already been dealt this Sitting.
Not idempotent: mutates the shared Goal and the relevant suit pile.
Returns the drawn card as a dict with rank, suit, suit_name, domain,
rank_meaning, and phrase.

Call at the start of every new scene, and again mid-scene any time the
story genuinely needs new material rather than a yes/no answer — for a
yes/no question, use cast_omen instead. Read the returned phrase cold,
before narrating anything else; only afterward do you narrate the scene
forward and let its meaning land in the fiction.

Takes no parameters. Not idempotent: each call removes and returns a
different card from the shared, shuffled deck (auto-reshuffles when the
deck runs out). Returns a dict with rank, suit, suit_name, domain,
rank_meaning, and phrase.

Call any time you need to check saved state rather than re-deriving
it — for example, checking the Goal's saved interpretation before
calling complete_goal, or checking goal_completed before deciding
whether to close the campaign at a scene's end. Read-only: never
mutates game state.

player_name: must exactly match the name already set via
name_character for the character currently in play; raises ValueError
if no character has been named yet, or if the name doesn't match the
current character.

Returns a dict with cross (the four drive-to-card mapping), goal (the
dealt Goal card plus its recorded interpretation, or None if not yet
dealt), debt_row (list of outstanding debt cards), and goal_completed
(bool).

Already called automatically, once, when the start_game prompt runs —
you typically won't need to call this tool yourself. It exists as a
standalone tool mainly so get_sheet and other tools have a name to
validate against. Call it directly only if you need to (re)name a
character outside the normal start_game flow.

player_name: the player-chosen name for their character. No format
constraints.

Not idempotent: overwrites the shared character name each time it's
called, with no confirmation or uniqueness check. Returns
{"player_name": player_name}.

Call once, during the Sitting, right after the player has answered what
the Goal means and Claude has reflected that answer back in a sentence
or two — pass that reflected sentence in. This becomes the saved
reference that complete_goal later checks against (via get_sheet's
'goal' field) to judge whether a moment in play genuinely resolves the
Goal.

interpretation: a plain-language sentence or two capturing what the
Goal means for this character — Claude's own reflected summary, not a
verbatim quote of the player's answer.

Raises ValueError if called before draw_goal_card has dealt a Goal.
Not idempotent: overwrites any existing interpretation on the shared
Goal. Returns the full updated Goal card dict, including the new
'interpretation' field.