Begin learning a topic, or rejoin one already in progress.

Call this first, whenever the user wants to learn or study something. Returns the instruction for the current step and nothing about later ones.

Re-calling this for a topic already underway resumes it rather than starting over — mastery is tracked per element, so a second pass would split the record rather than double it.

Args: topic: What to learn, e.g. "kafka consumer groups" or "options pricing".

Hand in the current step's work and receive the next instruction.

This is the only way to advance. The artifact is checked for shape before the phase moves, so a thin or malformed submission comes back with a reason and the phase is unchanged — fix it and submit again rather than continuing.

Args: session_id: From start_topic. artifact: Whatever the current instruction asked you to produce — the research markdown as a string, or the decomposition as a list of {name, explanation, prereqs} objects.

Get the next element to drill and the kind of question to ask about it.

The choice accounts for prerequisites, review schedule and relative weakness, so take what you're given rather than picking a topic yourself. Returns the element's own explanation for grading against — do not show that to the user unless they get the question wrong.

Args: session_id: From start_topic.

Put your drill question to the user and return their answer.

Prefer this over asking in chat. The answer comes back to you as a tool result, which means it is genuinely the user's, and the question is recorded verbatim next to whatever verdict you give it.

If this tool errors because the client can't prompt the user, ask your question in the chat instead and pass both question and answer to grade_drill.

Args: session_id: From start_topic. element_id: From next_drill. question: The question, worded exactly as the user should see it.

Record how the user did, and schedule when the element comes back.

A question has to exist before a verdict can attach to it: either you asked through ask_user, or you asked in chat and pass question and answer here. Grading an element you never actually asked about is rejected.

Args: session_id: From start_topic. element_id: The element that was drilled. verdict: "correct", "partial", or "incorrect". See the standing rules on strictness — when genuinely torn, "partial" is the honest answer. answer: What the user said, in their words. question: Only when you asked in chat instead of through ask_user. notes: What they missed, in a phrase. Worth filling in — it's the only record of how they were wrong.

Where this topic stands: phase, mastery counts, and what's still locked.

Useful for orienting mid-session or after a break. Report it to the user as progress, not as a schedule — don't read out due dates.

Args: session_id: From start_topic.

List topics with elements due for review right now.

Call this when the user opens a session without naming a topic, or asks what they should study. Reviewing something about to decay beats starting something new, so offer these before suggesting a fresh topic.