"""Control tools (L13): handled in the harness, acting only on the agent's
own state, conversation and records. A *waiting* tool ends the driver's run:
the item then waits on the operator."""

from typing import Any


def _tool(tool: str, description: str, /, **params: str) -> dict[str, Any]:
    return {
        "type": "function",
        "function": {
            "name": tool,
            "description": description,
            "parameters": {
                "type": "object",
                "properties": {
                    p: {"type": "string", "description": d} for p, d in params.items()
                },
                "required": list(params),
            },
        },
    }


RESTATE = _tool(
    "restate",
    "Put your understanding of the request to the operator, in their item's "
    "thread: what you take it to mean, how it fits the project, and your "
    "first step. Ends your turn; work starts when they agree.",
    text="Your restatement, in plain language.",
)
ASK_HUMAN = _tool(
    "ask_human",
    "Ask the operator a question in the item's thread. Ends your turn; you "
    "continue when they answer.",
    question="The question.",
)
CLOSE_ITEM = _tool(
    "close_item",
    "The work is done: close the work item with a summary of what was done, "
    "what was verified, and what is left open.",
    summary="What was done, verified, and left open.",
)

START_MILESTONE = _tool(
    "start_milestone",
    "Start a milestone before changing code: the harness cuts its branch. "
    "Never create or switch branches yourself.",
    name="A short name for the milestone.",
)
FINISH_MILESTONE = _tool(
    "finish_milestone",
    "The milestone's work is done and its tests pass: the harness commits "
    "the work, pushes it and opens a PR, or, after review comments, pushes "
    "your fix to the PR. Ends your turn; you continue when the PR is "
    "reviewed or merged.",
    summary="What the milestone did and how it was verified, for the PR.",
)

WAITING = frozenset({"restate", "ask_human", "close_item", "finish_milestone"})


def names(tools: list[dict[str, Any]]) -> set[str]:
    return {tool["function"]["name"] for tool in tools}