hitl-mcp-cli: Skill for Claude Code

hitl-mcp-usage skill

Tool selection guide

Handling return values

Every blocking tool can return one of these sentinels — always check before using the value:

result = await hitl_collect(message="Which branch?")

if isinstance(result, dict):
    match result.get("status") or result.get("action"):
        case "timeout":
            # Re-block: hitl_poll(question_id=result["question_id"])
            pass
        case "elaborate":
            # User wants more context — call hitl_request_elaboration
            pass
        case "cancel" | "rejected_question":
            # Abort or reformulate
            pass
        case "deferred":
            # Non-blocking question deferred to morning-batch JSONL
            pass
else:
    # result is the user's answer string
    use(result)

Elaboration flow

result = await hitl_collect(message="Which deployment target?", agent_name="deploy-agent")

if isinstance(result, dict) and result.get("action") == "elaborate":
    result = await hitl_request_elaboration(
        original_message="Which deployment target?",
        elaboration="Available targets: staging (us-east-1), prod (us-east-1, eu-west-1). "
                    "Staging is safe; prod requires approval from two reviewers.",
        question_id=result.get("question_id"),
        agent_name="deploy-agent",
    )

Timeout + poll flow

result = await hitl_confirm(
    message="Deploy to production?",
    severity="high",
    max_wait_minutes=5,
)

if isinstance(result, dict) and result.get("status") == "timeout":
    # Re-block for another 5 minutes
    result = await hitl_poll(
        question_id=result["question_id"],
        wait_minutes=5,
    )