request-human-input

request-human-input

Pause the loop, ask one clear thing, resume on reply. Hard rules: ../_shared/RULES.md.

Two modes

Compose mode (default — no --reply)

Decide if the situation needs human input. If yes, produce a mobile-first prompt + ≤ 3 options + a timeout default. Always writes requests/<id>.json so the the optional JobClaw agent's HITL MCP can pick it up.

Parse mode (--reply "<text>")

Match the reply to an option (case-insensitive prefix + fuzzy). Return a structured decision; mark the request file resolved.

Inputs (compose)

• situation — 1–3 sentences. The blocker.
• policy — freeform string. Escalation rules (e.g., "Escalate any irreversible action; auto-proceed on captcha if MFA backup is configured").
• context_attachments[] (optional) — file paths (screenshot, log) the human can review.
• request_id (optional) — caller-provided; else generate a 12-char hex slug.

Inputs (parse)

• --request_id — which request the reply is for.
• --reply — the user's verbatim reply string.

Method (compose)

1. Decide if a human is needed. Apply the policy text to situation. Output {needs_human: bool, reason}. If false, exit cleanly — no question, no file.

2. If needed, compose the prompt (mobile-first):

   • Stem — ≤ 1 sentence, ≤ 120 chars. The question itself.
   • Options — 1–3 quick-reply labels, each ≤ 24 chars. Verb-led.
   • Default on timeout — what JobClaw does if the human doesn't reply: skip | queue | retry | abort. Default abort for irreversible actions.
   • Context snippet — 1 line (e.g. "Captcha at Workday submit for Mercury, screenshot attached"). No more.

3. Persist. Always write requests/<request_id>.json:

   {
     "request_id": "...",
     "created_at": "ISO-8601",
     "situation":  "...",
     "policy":     "...",
     "prompt":     "string ≤ 120 chars",
     "options":    [{ "label": "string ≤ 24 chars", "value": "string" }],
     "timeout_default": { "after_minutes": 30, "action": "skip|queue|retry|abort" },
     "context_refs":    ["path/or/url"],
     "status":     "open"
   }