unique-sdk 2026.32.0.dev9__tar.gz → 2026.32.0.dev11__tar.gz

{unique_sdk-2026.32.0.dev9 → unique_sdk-2026.32.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.32.0.dev9
+Version: 2026.32.0.dev11
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.32.0.dev9 → unique_sdk-2026.32.0.dev11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.32.0.dev9"
+version = "2026.32.0.dev11"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.32.0.dev9 → unique_sdk-2026.32.0.dev11}/unique_sdk/cli/cli.py

@@ -1154,9 +1154,24 @@ def elicit() -> None:
     default=DEFAULT_WAIT_TIMEOUT_SECONDS,
     show_default=True,
     help=(
-        "Max seconds to block waiting for the user's response. This also "
-        "sets when the elicitation expires, so the request expires exactly "
-        "when we stop waiting and the chat UI can offer a way to continue."
+        "Max seconds to block waiting for the user's response. Without "
+        "--expires-in, this also sets when the elicitation expires, so the "
+        "request expires exactly when we stop waiting and the chat UI can "
+        "offer a way to continue."
+    ),
+)
+@click.option(
+    "--expires-in",
+    "expires_in_seconds",
+    type=int,
+    default=None,
+    help=(
+        "Seconds before the platform expires the request, decoupled from "
+        "--timeout (the local wait budget). Use this when this process's "
+        "wait budget is shorter than how long a human should realistically "
+        "get to answer (e.g. a harness with its own foreground timeout) -- "
+        "otherwise the request expires under the user before they can "
+        "answer. Defaults to --timeout, exactly matching prior behavior."
     ),
 )
 @click.option(
@@ -1217,6 +1232,7 @@ def elicit_ask(
     chat_id: str | None,
     message_id: str | None,
     timeout: int,
+    expires_in_seconds: int | None,
     poll_interval: float,
     metadata: tuple[str, ...],
     visible: bool = True,
@@ -1229,7 +1245,9 @@ def elicit_ask(
     \b
     Creates a FORM elicitation in the Unique UI with the given MESSAGE
     and blocks until the user responds, the elicitation is declined /
-    cancelled / expired, or --timeout is reached.
+    cancelled / expired, or --timeout is reached. Immediately after
+    creation, before polling starts, a single line is written to stderr:
+    "UNIQUE_ELICITATION_CREATED id=<id> expires_at=<iso8601>".
 
     \b
     Examples:
@@ -1237,6 +1255,8 @@ def elicit_ask(
       unique-cli elicit ask "Confirm deletion of /Archive" --timeout 60
       unique-cli elicit ask "Pick a region" \\
         --schema '{"type":"object","properties":{"region":{"type":"string","enum":["EU","US","APAC"]}},"required":["region"]}'
+      unique-cli elicit ask "Long-running approval" \\
+        --expires-in 7200 --timeout 300
     """
     parsed_metadata: list[tuple[str, str]] = []
     for kv in metadata:
@@ -1253,6 +1273,7 @@ def elicit_ask(
         "chat_id": chat_id,
         "message_id": _resolve_cli_message_id(ctx, message_id),
         "timeout": timeout,
+        "expires_in_seconds": expires_in_seconds,
         "poll_interval": poll_interval,
         "metadata": parsed_metadata or None,
         "visible": visible,

{unique_sdk-2026.32.0.dev9 → unique_sdk-2026.32.0.dev11}/unique_sdk/cli/commands/elicitation.py

@@ -13,8 +13,9 @@ from __future__ import annotations
 
 import json
 import os
+import sys
 import time
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from typing import Any, Literal, cast
 
 import unique_sdk
@@ -37,6 +38,23 @@ TERMINAL_STATUSES = {
     "COMPLETED",
 }
 
+# --- Transient-failure retry (UN-23310) ---------------------------------
+#
+# ``cmd_elicit_wait`` used to return on the very first ``APIError`` /
+# ``APIConnectionError`` raised mid-poll, treating a transient 502 the same
+# as a genuine terminal condition. Now that a single ``elicit ask`` call is
+# expected to carry the whole wait unsupervised, that one dropped connection
+# would otherwise cost the entire turn. These constants bound the retry
+# loop's backoff; the overall ``--timeout`` remains the hard outer bound.
+TRANSIENT_RETRY_BASE_SECONDS = 1.0
+TRANSIENT_RETRY_MAX_BACKOFF_SECONDS = 30.0
+
+# Prefix for the machine-readable line ``cmd_elicit_ask`` writes to stderr
+# immediately after creating the elicitation, before it starts polling. Kept
+# as a module constant so producer (here) and any future consumer/tests stay
+# in lockstep on the exact contract string.
+ELICITATION_CREATED_STDERR_PREFIX = "UNIQUE_ELICITATION_CREATED"
+
 # --- Visibility workaround for UN-19815 ---------------------------------
 #
 # The chat UI (as of 2026-04-21) only renders an elicitation when the host
@@ -632,6 +650,74 @@ def cmd_elicit_respond(
         return f"elicit: {exc}"
 
 
+def _is_transient_api_failure(exc: BaseException) -> bool:
+    """Return ``True`` if *exc* is worth retrying.
+
+    Transient: connection-level failures (timeouts, resets --
+    ``APIConnectionError``) and ``APIError``s with no HTTP status or a 5xx
+    status. Not transient: 4xx client errors, which cannot succeed on
+    retry -- retrying those would just burn the wait budget on a request
+    that is doomed regardless.
+
+    Note ``InvalidRequestError`` / ``AuthenticationError`` / ``PermissionError``
+    are not ``APIError`` subclasses and are not matched here; they propagate
+    unchanged, exactly as they did before this retry logic existed.
+    """
+    if isinstance(exc, unique_sdk.APIConnectionError):
+        return True
+    if isinstance(exc, unique_sdk.APIError):
+        status = getattr(exc, "http_status", None)
+        return status is None or status >= 500
+    return False
+
+
+def _get_elicitation_with_retry(
+    state: ShellState,
+    elicitation_id: str,
+    *,
+    deadline: float,
+) -> dict[str, Any]:
+    """Fetch an elicitation, retrying transient failures with backoff.
+
+    Retries are bounded by *deadline* (a ``time.monotonic()`` timestamp) --
+    once it passes, the last exception is re-raised so the caller's overall
+    ``--timeout`` is always the hard outer bound, never exceeded by retries.
+    Non-transient failures (see :func:`_is_transient_api_failure`) are
+    re-raised immediately without retrying. Each retry is logged to stderr
+    with the attempt number and backoff so a string of dropped connections
+    is diagnosable instead of silently eating the wait budget.
+    """
+    backoff = TRANSIENT_RETRY_BASE_SECONDS
+    attempt = 0
+    while True:
+        try:
+            return dict(
+                unique_sdk.Elicitation.get_elicitation(
+                    user_id=state.config.user_id,
+                    company_id=state.config.company_id,
+                    elicitation_id=elicitation_id,
+                )
+            )
+        except (unique_sdk.APIError, unique_sdk.APIConnectionError) as exc:
+            if not _is_transient_api_failure(exc):
+                raise
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise
+            attempt += 1
+            sleep_for = max(
+                0.0, min(backoff, TRANSIENT_RETRY_MAX_BACKOFF_SECONDS, remaining)
+            )
+            print(
+                f"elicit: transient error on attempt {attempt} fetching "
+                f"{elicitation_id} ({exc}); retrying in {sleep_for:.1f}s",
+                file=sys.stderr,
+            )
+            if sleep_for > 0:
+                time.sleep(sleep_for)
+            backoff = min(backoff * 2, TRANSIENT_RETRY_MAX_BACKOFF_SECONDS)
+
+
 def cmd_elicit_wait(
     state: ShellState,
     elicitation_id: str,
@@ -658,12 +744,10 @@ def cmd_elicit_wait(
     try:
         deadline = time.monotonic() + max(1, timeout)
         while True:
-            elicitation = unique_sdk.Elicitation.get_elicitation(
-                user_id=state.config.user_id,
-                company_id=state.config.company_id,
-                elicitation_id=elicitation_id,
+            elicitation = _get_elicitation_with_retry(
+                state, elicitation_id, deadline=deadline
             )
-            last = dict(elicitation)
+            last = elicitation
             status = str(elicitation.get("status", "")).upper()
             if status in TERMINAL_STATUSES:
                 terminal_status = status
@@ -675,12 +759,8 @@ def cmd_elicit_wait(
                 # same instant; this fetch forces the backend's lazy expiry to
                 # run so we report a clean EXPIRED — and publish it to the chat
                 # subscription — instead of a stale PENDING.
-                final = dict(
-                    unique_sdk.Elicitation.get_elicitation(
-                        user_id=state.config.user_id,
-                        company_id=state.config.company_id,
-                        elicitation_id=elicitation_id,
-                    )
+                final = _get_elicitation_with_retry(
+                    state, elicitation_id, deadline=deadline
                 )
                 last = final
                 final_status = str(final.get("status", "")).upper()
@@ -703,7 +783,7 @@ def cmd_elicit_wait(
                     f"{format_elicitation(last)}"
                 )
             time.sleep(poll_interval)
-    except unique_sdk.APIError as exc:
+    except (unique_sdk.APIError, unique_sdk.APIConnectionError) as exc:
         return f"elicit: {exc}"
     finally:
         # If the poll loop exited before we ever received a response
@@ -720,7 +800,7 @@ def cmd_elicit_wait(
                         elicitation_id=elicitation_id,
                     )
                 )
-            except unique_sdk.APIError:
+            except (unique_sdk.APIError, unique_sdk.APIConnectionError):
                 last = None
         ctx = _extract_visibility_context(last)
         if ctx is not None:
@@ -735,6 +815,36 @@ def cmd_elicit_wait(
             )
 
 
+def _emit_elicitation_created_stderr_line(
+    elicitation_id: str,
+    expires_at: object,
+    expires_in_seconds: int,
+) -> None:
+    """Write the ``UNIQUE_ELICITATION_CREATED`` contract line to stderr.
+
+    Format (stable, greppable, one line, stderr only)::
+
+        UNIQUE_ELICITATION_CREATED id=<id> expires_at=<iso8601>
+
+    Prefers the platform-returned ``expiresAt`` (authoritative); falls back
+    to a locally computed timestamp if the platform omitted it, so the line
+    is always emitted with a usable value.
+    """
+    if isinstance(expires_at, str) and expires_at:
+        resolved_expires_at = expires_at
+    else:
+        resolved_expires_at = (
+            (datetime.now(tz=timezone.utc) + timedelta(seconds=expires_in_seconds))
+            .isoformat(timespec="milliseconds")
+            .replace("+00:00", "Z")
+        )
+    print(
+        f"{ELICITATION_CREATED_STDERR_PREFIX} id={elicitation_id} "
+        f"expires_at={resolved_expires_at}",
+        file=sys.stderr,
+    )
+
+
 def cmd_elicit_ask(
     state: ShellState,
     *,
@@ -745,6 +855,7 @@ def cmd_elicit_ask(
     message_id: str | None = None,
     timeout: int = DEFAULT_WAIT_TIMEOUT_SECONDS,
     poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
+    expires_in_seconds: int | None = None,
     metadata: list[tuple[str, str]] | None = None,
     visible: bool = True,
     assistant_id: str | None = None,
@@ -757,6 +868,23 @@ def cmd_elicit_ask(
     free-text ``answer`` is used. This is the preferred entry point when an
     agent needs to ask the user a clarifying question.
 
+    ``expires_in_seconds``, when given, decouples the server-side expiry
+    (``expiresInSeconds`` sent to the platform) from ``timeout`` (how long
+    *this process* blocks polling). When omitted (the default), behaviour is
+    unchanged from before this parameter existed: the elicitation expires
+    exactly when the local wait gives up, coupling the two. Pass this when
+    the caller's own wait budget (e.g. a harness's foreground timeout) is
+    shorter than how long a human should realistically have to answer --
+    otherwise the elicitation expires under the user before they see it.
+
+    Immediately after creation (before polling starts), a single line is
+    written to stderr for callers that want the elicitation id without
+    polling the pending list:
+
+        UNIQUE_ELICITATION_CREATED id=<id> expires_at=<iso8601>
+
+    This is stderr-only and does not change stdout's format.
+
     When ``chat_id`` is set and ``visible`` is ``True`` (the default), the
     elicitation is wrapped in a placeholder thinking timeline so the chat UI
     actually renders it — see the "Visibility workaround for UN-19815" note
@@ -778,16 +906,17 @@ def cmd_elicit_ask(
                 "required": ["answer"],
             }
 
-        # `ask` exposes a single knob: `--timeout` is both how long we wait and
-        # when the record expires. The two are always the same here, so the
-        # backend's default (5 minutes) never leaves the record PENDING after
-        # we have stopped waiting — which would otherwise prevent the chat UI
-        # from flipping the prompt to EXPIRED and offering the user a way to
-        # continue. The poll loop below reads the freshly EXPIRED record and the
-        # elicitation subscription delivers the terminal status to the chat.
-        # (Use `elicit create --expires-in` if you need expiry decoupled from a
-        # local wait.)
-        expires_in_seconds = timeout
+        # By default `ask` exposes a single knob: `--timeout` is both how long
+        # we wait and when the record expires. The two are the same unless the
+        # caller passes `--expires-in` explicitly, so the backend's default (5
+        # minutes) never leaves the record PENDING after we have stopped
+        # waiting — which would otherwise prevent the chat UI from flipping
+        # the prompt to EXPIRED and offering the user a way to continue. The
+        # poll loop below reads the freshly EXPIRED record and the elicitation
+        # subscription delivers the terminal status to the chat.
+        effective_expires_in_seconds = (
+            expires_in_seconds if expires_in_seconds is not None else timeout
+        )
 
         user_metadata = _parse_metadata_pairs(metadata)
         effective_message_id = message_id
@@ -836,7 +965,7 @@ def cmd_elicit_ask(
             url=None,
             chat_id=chat_id,
             message_id=effective_message_id,
-            expires_in_seconds=expires_in_seconds,
+            expires_in_seconds=effective_expires_in_seconds,
             external_elicitation_id=None,
             metadata=user_metadata,
         )
@@ -856,6 +985,12 @@ def cmd_elicit_ask(
             _cleanup_placeholder_if_needed()
             return "elicit: platform did not return an elicitation id"
 
+        _emit_elicitation_created_stderr_line(
+            elicitation_id,
+            elicitation.get("expiresAt"),
+            effective_expires_in_seconds,
+        )
+
         # ``cmd_elicit_wait`` handles its own placeholder teardown by
         # reading the markers back from the elicitation's metadata.
         return cmd_elicit_wait(

{unique_sdk-2026.32.0.dev9 → unique_sdk-2026.32.0.dev11}/unique_sdk/cli/shell.py

@@ -89,7 +89,10 @@ OVERVIEW_HELP = textwrap.dedent("""\
         --chat-id / -c <id>            Associated chat ID
         --message-id / -m <id>         Associated message ID
         --timeout <seconds>            Max wait time, also sets when the
-                                       request expires (default: 7200)
+                                       request expires unless --expires-in
+                                       is given (default: 7200)
+        --expires-in <seconds>         Decouple server-side expiry from
+                                       --timeout (defaults to --timeout)
         --poll-interval <seconds>      Poll frequency (default: 2.0)
         --metadata key=value           Metadata (repeatable)
         --no-visible                   Skip the UN-19815 visibility workaround
@@ -814,9 +817,12 @@ class UniqueShell(cmd.Cmd):
           --mode FORM|URL              Display mode (create only, default: FORM)
           --chat-id / -c <id>          Associated chat ID
           --message-id / -m <id>       Associated message ID
-          --expires-in <seconds>       Auto-expire the request (create only)
+          --expires-in <seconds>       Auto-expire the request. For ask, this
+                                       decouples expiry from --timeout
+                                       (defaults to --timeout when omitted)
           --timeout <seconds>          (ask / wait) max wait time, default 7200;
                                        for ask this also sets when it expires
+                                       unless --expires-in is given
           --poll-interval <seconds>    (ask / wait) poll frequency, default 2
           --external-id <id>           External identifier (create only)
           --metadata key=value         Metadata (repeatable)
@@ -999,13 +1005,6 @@ class UniqueShell(cmd.Cmd):
         if not message:
             self._print("Usage: elicit ask <message> [options]")
             return
-        if opts["expires_in_seconds"] is not None:
-            self._print(
-                "No such option: --expires-in for 'elicit ask'. Use --timeout "
-                "(it also sets when the request expires). For expiry decoupled "
-                "from a local wait, use 'elicit create --expires-in'."
-            )
-            return
 
         ask_kwargs: dict[str, Any] = {
             "message": message,
@@ -1014,6 +1013,7 @@ class UniqueShell(cmd.Cmd):
             "chat_id": opts["chat_id"],
             "message_id": opts["message_id"],
             "timeout": opts["timeout"],
+            "expires_in_seconds": opts["expires_in_seconds"],
             "poll_interval": opts["poll_interval"],
             "metadata": opts["metadata"] or None,
             "visible": opts["visible"],

{unique_sdk-2026.32.0.dev9 → unique_sdk-2026.32.0.dev11}/unique_sdk/cli/skills/unique-cli-elicitation/SKILL.md

@@ -6,8 +6,10 @@ description: >-
   (especially destructive actions), missing parameters, multiple-choice
   decisions, or structured form input. Elicitations are routed through
   the Unique AI Platform UI via `unique-cli elicit create` + `elicit wait`
-  (or `elicit ask` outside an agent harness) so the user gets a proper
-  structured prompt and you get a structured answer back.
+  (the default polling pattern) or a single supervised `unique-cli elicit
+  ask` call (only when your agent instructions say your environment
+  supervises the wait) so the user gets a proper structured prompt and
+  you get a structured answer back.
   Do NOT ask the user in plain chat when you can use this skill instead.
 ---
 
@@ -15,22 +17,55 @@ description: >-
 
 Use this skill **whenever you need input from the user** -- a clarifying question, a confirmation before a destructive action, a choice between options, or a structured form. Elicitations create a first-class UI prompt on the Unique AI Platform and return the answer as structured JSON.
 
-> **Rule of thumb:** if you catch yourself about to write "Could you clarify…?" or "Do you want me to…?" or "Which one should I pick?" in chat, stop and use `unique-cli elicit create` + `elicit wait` instead (see "The pattern" below).
+> **Rule of thumb:** if you catch yourself about to write "Could you clarify…?" or "Do you want me to…?" or "Which one should I pick?" in chat, stop and use an elicitation instead (see "Two patterns" below for which command sequence to use).
 
 !!! danger "`--visible` is currently MANDATORY"
     You **must always create elicitations with visibility on** (it is on by default for both `elicit create` and `elicit ask` — just don't pass `--no-visible`). Until the UN-19815 UI fix ships in your environment, an elicitation created without the visibility workaround is stored by the backend but **never rendered in the chat UI** — the user simply never sees the question and you will wait forever. There is no situation in which you should disable it today.
 
-## The pattern: `elicit create` + short polling loop with `elicit wait`
+!!! danger "A non-terminal status is not an answer"
+    This is the single rule that matters most, in **every** pattern below:
+    `PENDING` is not `DECLINED`, is not an answer, and is never a reason to
+    stop or proceed. Never treat a non-terminal status as a decline, never
+    proceed on an unanswered form, and never fabricate what you think the
+    user would say. If the last known status is `PENDING`, the only correct
+    next action is to keep waiting -- either loop `elicit wait` again
+    (Pattern A) or re-issue `elicit wait <id>` on the same elicitation
+    (Pattern B) -- until you observe one of the terminal statuses in
+    "Reading the response" below.
+
+## Two patterns -- your agent instructions decide which one to use
+
+There are two valid ways to wait for an elicitation's answer. **Which one you
+use is decided by your agent instructions (system prompt / `AGENTS.md`), not
+by this skill file guessing which harness you're running in:**
+
+- **Your instructions are silent, or say nothing about your environment
+  supervising long-running waits** -- use **Pattern A: `elicit create` +
+  short polling loop with `elicit wait`** below. This is the default and is
+  safe everywhere, including inside a harness whose Bash/shell tool has its
+  own foreground-wait timeout (Claude Code, Codex, ~2 minutes commonly).
+- **Your instructions explicitly say your environment supervises the wait**
+  for a single long-running tool call (it will not silently background or
+  kill the process before the human answers) -- use **Pattern B: a single
+  supervised `elicit ask` call** below instead.
+
+If in doubt, use Pattern A -- it is correct in every environment, whereas
+Pattern B is only correct in one that actually supervises the wait. Neither
+pattern is forbidden; pick the one your instructions call for.
+
+## Pattern A: `elicit create` + short polling loop with `elicit wait` (default)
 
 Do **not** call `elicit ask` from inside an agent harness (Claude Code, Codex,
 or any environment where your Bash/shell tool has its own foreground-wait
-timeout — commonly ~2 minutes). `elicit ask` blocks synchronously for up to
-`--timeout` seconds (default 2 hours) waiting for the human to answer, but a
-human reading and answering a prompt routinely takes longer than a typical
-Bash tool timeout. If that timeout fires first, your harness will silently
-detach the process to the background and hand you a "running in background"
-stub instead of the real answer — you will not see the user's response, and
-the chat may appear stuck to the user.
+timeout — commonly ~2 minutes) **unless your agent instructions explicitly
+say your environment supervises the wait (see Pattern B below)**. `elicit
+ask` blocks synchronously for up to `--timeout` seconds (default 2 hours)
+waiting for the human to answer, but a human reading and answering a prompt
+routinely takes longer than a typical Bash tool timeout. If that timeout
+fires first and your instructions did not say otherwise, your harness will
+silently detach the process to the background and hand you a "running in
+background" stub instead of the real answer — you will not see the user's
+response, and the chat may appear stuck to the user.
 
 Instead, use `elicit create` (returns immediately) followed by a short
 polling loop with `elicit wait`, where **every individual command finishes
@@ -86,7 +121,9 @@ default — comfortably under Claude Code's ~120s):
 `elicit ask` remains the right choice for **non-agent, scripted, or
 human-operated CLI usage** where a single blocking call is expected and
 there is no surrounding tool-timeout concern (tests, ops scripts, manual CLI
-use). Do not reach for it from inside an agent turn.
+use), and for **Pattern B below** when your instructions say your
+environment supervises the wait. Do not reach for it from inside an agent
+turn unless one of those two conditions applies.
 
 ```bash
 unique-cli elicit ask "<question>" [options]
@@ -99,6 +136,43 @@ unique-cli elicit ask "<question>" [options]
     (preferred) or `$UNIQUE_MESSAGE_ID`. Do **not** pass a stale
     `$UNIQUE_MESSAGE_ID` from a persistent process environment.
 
+## Pattern B: a single supervised `elicit ask` call
+
+Use this **only when your agent instructions explicitly say your
+environment supervises the wait** for a single long-running tool call --
+i.e. it will not silently background or kill the process before the human
+answers. Do not use Pattern B just because it is simpler; use it only
+because your instructions told you your environment can safely block for
+the full wait.
+
+```bash
+unique-cli elicit ask "<question>" \
+  --chat-id "$UNIQUE_CHAT_ID" \
+  --expires-in 7200 \
+  --timeout 1800
+```
+
+- **`--expires-in`** sets how long the request stays live on the platform
+  (a human-scale deadline, e.g. `7200` = 2 hours) independently of
+  **`--timeout`**, which is how long *this call* blocks. Set `--timeout` to
+  match your supervisor's own wait budget; omit `--expires-in` only if you
+  want it to default to `--timeout` (today's coupled behavior, unchanged).
+- Immediately after creating the elicitation -- before it starts waiting --
+  the CLI writes one line to **stderr** (never stdout):
+  `UNIQUE_ELICITATION_CREATED id=<id> expires_at=<iso8601>`. A supervisor
+  watching stderr can capture the elicitation id the instant it exists,
+  without waiting for `ask` to return.
+- While waiting, transient failures (connection errors, timeouts, 5xx) are
+  retried automatically with bounded exponential backoff and logged to
+  stderr -- you do not need your own retry loop around `ask` to survive a
+  single dropped connection. 4xx errors are not retried.
+- The result of the single call **is** the answer. Check `Status:` exactly
+  as described in "Reading the response" below, and the same rule applies
+  if `ask` still returns `PENDING` when `--timeout` elapses: that is **not**
+  a decline and not a reason to stop -- the elicitation is still live on
+  the platform (until `--expires-in`), so re-issue `elicit wait <id>` on the
+  same id to keep waiting for the real answer.
+
 ## When to use
 
 | Situation | Use elicitation? |
@@ -113,9 +187,11 @@ unique-cli elicit ask "<question>" [options]
 ## Examples
 
 > The examples below use `elicit ask` for brevity to show the schema shapes.
-> From an agent harness, use the same `--schema`/`--message`/`--tool-name`
-> arguments with `elicit create` instead, then poll with `elicit wait` as
-> shown in "The pattern" above.
+> From an agent harness whose instructions are silent on supervision, use the
+> same `--schema`/`--message`/`--tool-name` arguments with `elicit create`
+> instead, then poll with `elicit wait` as shown in "Pattern A" above (or use
+> `elicit ask` directly per "Pattern B" if your instructions say your
+> environment supervises the wait).
 
 ### Minimal — free-text answer
 
@@ -173,7 +249,7 @@ unique-cli elicit ask "Permanently delete /Archive/2024 and everything inside it
   --schema '{"type": "object", "properties": {}}'
 ```
 
-Proceed **only** if the `Status:` is `ACCEPTED`. Treat `DECLINED`, `CANCELLED`, or `EXPIRED` all as "do not proceed" -- tell the user you stopped and return control. Put everything the user needs to decide into the message text, since the form has no fields.
+Proceed **only** if the `Status:` is `ACCEPTED`. Treat `DECLINED`, `REJECTED`, `CANCELLED`, or `EXPIRED` all as "do not proceed" -- tell the user you stopped and return control. Put everything the user needs to decide into the message text, since the form has no fields.
 
 ### Structured form (multiple fields)
 
@@ -194,11 +270,12 @@ unique-cli elicit ask "Please provide report settings" \
 
 ## Options
 
-The table below documents `elicit ask`'s flags. `elicit create` takes the
-same `--chat-id`, `--message-id`, `--tool-name`, `--schema`, `--metadata`,
-and `--assistant-id` flags, but uses `--expires-in <seconds>` instead of
-`--timeout`/`--poll-interval` (those two apply only to `elicit wait`, which
-you call separately in the polling pattern). `elicit create` also takes
+The table below documents `elicit ask`'s flags (used in both Pattern A's
+"scripting" case and Pattern B). `elicit create` takes the same `--chat-id`,
+`--message-id`, `--tool-name`, `--schema`, `--metadata`, and `--assistant-id`
+flags, plus `--expires-in <seconds>` (`elicit create` has no `--timeout`/
+`--poll-interval` -- those two apply only to `elicit wait`, which you call
+separately in the Pattern A polling loop). `elicit create` also takes
 `--mode FORM|URL` (default: `FORM` — you only need to pass it for URL
 elicitations).
 
@@ -208,7 +285,8 @@ elicitations).
 | `--message-id` | `-m` | auto | Optional. Prefer omitting this flag — the CLI resolves the current turn's message ID from `$UNIQUE_TURN_IDENTITY_FILE` (preferred) or `$UNIQUE_MESSAGE_ID`. Do not pass a stale env value from a persistent process. |
 | `--tool-name` | `-t` | `agent_question` | Short snake_case label shown to the user (e.g. `clarify`, `confirm_delete`, `choose_report`). |
 | `--schema` | | single `answer` string | JSON Schema for the form body. |
-| `--timeout` | | `7200` | Max seconds to block locally before giving up. This is the single knob for `ask`: it also sets when the request expires on the platform, so the prompt expires exactly when you stop waiting and the chat UI can offer the user a way to continue. |
+| `--expires-in` | | `--timeout`'s value | Seconds before the platform auto-expires the request, decoupled from `--timeout`. This is the flag Pattern B uses to give the elicitation a human-scale deadline (e.g. `7200`) independent of the caller's own wait budget. Omit it to keep today's coupled behavior. |
+| `--timeout` | | `7200` | Max seconds to block locally before giving up. Unless you pass `--expires-in`, this is also when the request expires on the platform, so the prompt expires exactly when you stop waiting and the chat UI can offer the user a way to continue. |
 | `--poll-interval` | | `2.0` | Seconds between status polls. |
 | `--metadata` | | none | `key=value` metadata (repeatable). |
 | `--assistant-id` | | `$UNIQUE_ASSISTANT_ID`, else latest assistant in chat | Assistant id for the placeholder message created by the visibility workaround. Set this (or export `UNIQUE_ASSISTANT_ID`) only if the chat is brand-new with no prior assistant messages. |
@@ -230,12 +308,19 @@ Terminal statuses:
 
 | Status | Meaning | What to do |
 |--------|---------|------------|
-| `RESPONDED` / `COMPLETED` | User answered | Parse `Response:` JSON and proceed. |
-| `DECLINED` | User explicitly declined | Do not proceed. Acknowledge and stop. |
+| `RESPONDED` / `ACCEPTED` / `COMPLETED` | User answered, or confirmed (accepted) an empty-schema confirmation | Parse `Response:` JSON and proceed. |
+| `DECLINED` / `REJECTED` | User explicitly declined, or rejected (declined) an empty-schema confirmation | Do not proceed. Acknowledge and stop. |
 | `CANCELLED` | Cancelled (by user or system) | Do not proceed. |
-| `EXPIRED` | Timed out on the platform — the user did not answer within `--timeout` | Ask again only if the task still needs it; do not treat the expiry as approval. |
+| `EXPIRED` | Timed out on the platform — the user did not answer before the request's expiry (`--timeout`, or `--expires-in` if you passed it) | Ask again only if the task still needs it; do not treat the expiry as approval. |
+
+`ACCEPTED`/`REJECTED` and `RESPONDED`/`DECLINED` are functionally
+equivalent terminal outcomes -- `ACCEPTED`/`REJECTED` are the accept/decline
+synonyms produced by some response paths (e.g. the Codex approval-bridge
+integration), while `RESPONDED`/`DECLINED` are produced by others. Treat
+them the same way: `ACCEPTED` like `RESPONDED` (proceed), `REJECTED` like
+`DECLINED` (stop).
 
-Because `ask` derives the request's expiry from `--timeout`, when the user does not answer in time the platform expires the request and `elicit ask` returns a clean `EXPIRED` status (rather than a local-only timeout). If you instead see `elicit: timed out after Ns ...`, raise `--timeout` and try again. If this happens repeatedly, double-check that you passed `--chat-id` and did not pass `--no-visible` — an invisible elicitation is the most common cause of a local timeout.
+Because `ask` derives the request's expiry from `--timeout` (unless you pass `--expires-in`), when the user does not answer in time the platform expires the request and `elicit ask` returns a clean `EXPIRED` status (rather than a local-only timeout). If you instead see `elicit: timed out after Ns ...` (Pattern B) or `elicit: still PENDING after Ns ...` (Pattern A's `elicit wait`), that is **not** `EXPIRED` -- see the danger box at the top of this file: keep waiting, do not treat it as a stopping condition. If this happens repeatedly, double-check that you passed `--chat-id` and did not pass `--no-visible` — an invisible elicitation is the most common cause of a local timeout.
 
 ### Repeat the answer back in chat
 
@@ -266,10 +351,12 @@ Do not expose raw JSON by default when a natural-language confirmation would be
 
 This one-shot pattern is for **scripts, tests, or manual CLI use outside an
 agent harness** — i.e. contexts with no Bash-tool foreground timeout to worry
-about. From inside an agent harness, use the `elicit create` + `elicit wait`
-polling pattern from "The pattern" section above instead; the output parsing
-below (pulling `Response:` out of the text) is identical either way, only the
-command(s) producing that output differ.
+about. From inside an agent harness whose instructions are silent on
+supervision, use the `elicit create` + `elicit wait` polling pattern from
+"Pattern A" above instead (or "Pattern B" if your instructions say your
+environment supervises the wait); the output parsing below (pulling
+`Response:` out of the text) is identical either way, only the command(s)
+producing that output differ.
 
 In a shell script or agent tool wrapper, capture the output and pull out the `Response:` line:
 
@@ -301,7 +388,7 @@ esac
 
 ## Agent workflow rules
 
-1. **Default to `elicit create` + `elicit wait` polling.** If you need an answer from the user, use this pattern, not a chat message and not a single blocking `elicit ask` call. See "The pattern" above.
+1. **Default to `elicit create` + `elicit wait` polling (Pattern A).** If you need an answer from the user, use this pattern, not a chat message -- unless your agent instructions explicitly say your environment supervises the wait, in which case use a single `elicit ask` call (Pattern B). See "Two patterns" above.
 2. **Always pass `--chat-id "$UNIQUE_CHAT_ID"`.** Without it the elicitation is not attached to a chat and the user will not see it.
 3. **Omit `--message-id`.** The CLI resolves the current turn's assistant message ID from `$UNIQUE_TURN_IDENTITY_FILE` (preferred) or `$UNIQUE_MESSAGE_ID`. Do not pass a stale `$UNIQUE_MESSAGE_ID` from a persistent process environment.
 4. **Never pass `--no-visible`.** See the warning above. The visibility workaround is mandatory today.
@@ -309,10 +396,10 @@ esac
 6. **Pick a meaningful `--tool-name`.** `confirm_delete`, `choose_region`, `pick_report` -- short snake_case describing the intent.
 7. **Constrain answers with a schema** whenever the valid set is finite -- don't rely on parsing free text when `enum` is an option.
 8. **Repeat answered elicitations back in chat.** Summarize what the user chose in natural language before acting on it; hide raw JSON in a collapsible details block only when it adds value.
-9. **Handle non-`RESPONDED` outcomes explicitly.** If the status is `DECLINED` / `CANCELLED` / `EXPIRED`, tell the user you stopped and ask what they want to do next instead of silently proceeding.
+9. **Handle non-`RESPONDED`/`ACCEPTED` outcomes explicitly.** If the status is `DECLINED` / `REJECTED` / `CANCELLED` / `EXPIRED`, tell the user you stopped and ask what they want to do next instead of silently proceeding. A non-terminal (`PENDING`) status is never one of these outcomes -- see the danger box at the top of this file.
 10. **Don't spam elicitations.** One well-designed form with a few related fields is better than five sequential yes/no questions.
 11. **Cap each elicitation at 5 questions.** If you need more than 5 answers, split them into multiple focused elicitations so the user can respond confidently.
-12. **Never make a single blocking call longer than your harness's Bash foreground timeout.** Use `--expires-in` on `elicit create` to set the real, human-scale deadline (e.g. 7200s / 2 hours), but keep each individual `elicit wait --timeout N` call short (≈90s) and loop until a terminal status or the overall deadline is reached. Never call `elicit ask` with a multi-minute `--timeout` from an agent harness.
+12. **Never make a single blocking call longer than your harness's Bash foreground timeout, unless your instructions say your environment supervises the wait.** In Pattern A, use `--expires-in` on `elicit create` to set the real, human-scale deadline (e.g. 7200s / 2 hours), but keep each individual `elicit wait --timeout N` call short (≈90s) and loop until a terminal status or the overall deadline is reached. In Pattern B, `--expires-in` on `elicit ask` does the same job, decoupled from the (now safely long) `--timeout` your supervisor manages. Never call `elicit ask` with a multi-minute `--timeout` from an agent harness unless Pattern B applies.
 
 ## Prerequisites