unique-sdk 2026.30.0.dev6__tar.gz → 2026.30.0.dev7__tar.gz

{unique_sdk-2026.30.0.dev6 → unique_sdk-2026.30.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.30.0.dev6
+Version: 2026.30.0.dev7
 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.30.0.dev6 → unique_sdk-2026.30.0.dev7}/pyproject.toml

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

{unique_sdk-2026.30.0.dev6 → unique_sdk-2026.30.0.dev7}/unique_sdk/cli/cli.py

@@ -84,11 +84,38 @@ from unique_sdk.cli.commands.web_search import (
 )
 from unique_sdk.cli.commands.web_search_config import ENV_CONFIG_PATH
 from unique_sdk.cli.config import load_config
+from unique_sdk.cli.identity import TurnIdentityError, resolve_message_id
 from unique_sdk.cli.shell import UniqueShell
 from unique_sdk.cli.state import ShellState
 
 _DYNAMIC_FRONTEND_ERROR_PREFIX = "dynamic-frontend "
 
+
+def _resolve_cli_message_id(
+    ctx: click.Context,
+    explicit: str | None,
+    *,
+    required: bool = False,
+) -> str | None:
+    """Resolve message id for Click commands; exit on turn-identity errors.
+
+    When *required* is True and no source yields a value, exits with code 2.
+    """
+    try:
+        resolved = resolve_message_id(explicit)
+    except TurnIdentityError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        ctx.exit(2)
+    if required and not resolved:
+        click.echo(
+            "Error: message id is required. Pass --message-id, or set "
+            "UNIQUE_TURN_IDENTITY_FILE / UNIQUE_MESSAGE_ID.",
+            err=True,
+        )
+        ctx.exit(2)
+    return resolved
+
+
 MAIN_HELP = """\
 Unique CLI -- Linux-like file explorer for the Unique AI Platform.
 
@@ -802,8 +829,12 @@ def uploaded_search(
 @click.option(
     "--message-id",
     "-m",
-    required=True,
-    help="Message ID for the MCP tool call context.",
+    default=None,
+    help=(
+        "Message ID for the MCP tool call context. Defaults to the "
+        "current turn identity file ($UNIQUE_TURN_IDENTITY_FILE), then "
+        "$UNIQUE_MESSAGE_ID."
+    ),
 )
 @click.option(
     "--file",
@@ -824,7 +855,7 @@ def mcp(
     ctx: click.Context,
     payload: str | None,
     chat_id: str,
-    message_id: str,
+    message_id: str | None,
     file_path: str | None,
     use_stdin: bool,
 ) -> None:
@@ -837,7 +868,8 @@ def mcp(
     \b
     The JSON is forwarded 1:1 to the MCP call-tool API. Chat ID and
     message ID are provided as separate flags to identify the
-    conversation context.
+    conversation context. When --message-id is omitted, the CLI resolves
+    it from $UNIQUE_TURN_IDENTITY_FILE (preferred) or $UNIQUE_MESSAGE_ID.
 
     \b
     Input sources (exactly one required):
@@ -854,11 +886,12 @@ def mcp(
 
       cat payload.json | unique-cli mcp -c chat_123 -m msg_456 --stdin
     """
+    resolved_message_id = _resolve_cli_message_id(ctx, message_id, required=True)
     click.echo(
         cmd_mcp(
             LazyState.get(ctx),
             chat_id=chat_id,
-            message_id=message_id,
+            message_id=resolved_message_id or "",
             payload=payload,
             file=file_path,
             stdin=use_stdin,
@@ -887,8 +920,11 @@ def mcp(
     "--message-id",
     "parent_message_id",
     default=None,
-    envvar="UNIQUE_MESSAGE_ID",
-    help="Parent message ID for message correlation.",
+    help=(
+        "Parent message ID for message correlation. Defaults to the "
+        "current turn identity file ($UNIQUE_TURN_IDENTITY_FILE), then "
+        "$UNIQUE_MESSAGE_ID."
+    ),
 )
 @click.option(
     "--assistant-id",
@@ -931,13 +967,14 @@ def subagent(
       unique-cli subagent LegalReview "Review this contract clause"
       unique-cli subagent Finance "Summarize Q4 revenue" --reset-chat
     """
+    resolved_message_id = _resolve_cli_message_id(ctx, parent_message_id)
     output = cmd_subagent(
         LazyState.get(ctx),
         tool_name=tool_name,
         message=message,
         config_path=config_path,
         parent_chat_id=parent_chat_id,
-        parent_message_id=parent_message_id,
+        parent_message_id=resolved_message_id,
         parent_assistant_id=parent_assistant_id,
         reset_chat=reset_chat,
         output_json=output_json,
@@ -1195,7 +1232,15 @@ def elicit() -> None:
     ),
 )
 @click.option("--chat-id", "-c", default=None, help="Associated chat ID.")
-@click.option("--message-id", "-m", default=None, help="Associated message ID.")
+@click.option(
+    "--message-id",
+    "-m",
+    default=None,
+    help=(
+        "Associated message ID. Defaults to the current turn identity "
+        "file ($UNIQUE_TURN_IDENTITY_FILE), then $UNIQUE_MESSAGE_ID."
+    ),
+)
 @click.option(
     "--timeout",
     type=int,
@@ -1299,7 +1344,7 @@ def elicit_ask(
         "tool_name": tool_name,
         "schema": schema,
         "chat_id": chat_id,
-        "message_id": message_id,
+        "message_id": _resolve_cli_message_id(ctx, message_id),
         "timeout": timeout,
         "poll_interval": poll_interval,
         "metadata": parsed_metadata or None,
@@ -1334,7 +1379,15 @@ def elicit_ask(
 )
 @click.option("--url", default=None, help="External URL (required for --mode URL).")
 @click.option("--chat-id", "-c", default=None, help="Associated chat ID.")
-@click.option("--message-id", "-m", default=None, help="Associated message ID.")
+@click.option(
+    "--message-id",
+    "-m",
+    default=None,
+    help=(
+        "Associated message ID. Defaults to the current turn identity "
+        "file ($UNIQUE_TURN_IDENTITY_FILE), then $UNIQUE_MESSAGE_ID."
+    ),
+)
 @click.option(
     "--expires-in",
     "expires_in_seconds",
@@ -1439,7 +1492,7 @@ def elicit_create(
         "schema": schema,
         "url": url,
         "chat_id": chat_id,
-        "message_id": message_id,
+        "message_id": _resolve_cli_message_id(ctx, message_id),
         "expires_in_seconds": expires_in_seconds,
         "external_elicitation_id": external_elicitation_id,
         "metadata": parsed_metadata or None,

unique_sdk-2026.30.0.dev7/unique_sdk/cli/identity.py

@@ -0,0 +1,150 @@
+"""Resolve the current turn's assistant message identity.
+
+Persistent agent subprocesses freeze their OS environment at spawn time, so
+``UNIQUE_MESSAGE_ID`` can be stale on later turns. The parent runner writes a
+per-turn identity file and exposes its path via ``UNIQUE_TURN_IDENTITY_FILE``
+(stable across turns). Fresh ``unique-cli`` invocations then read the current
+message ID from that file.
+
+Resolution precedence for message IDs:
+
+1. Explicit ``--message-id`` / ``-m`` flag value
+2. Turn-identity file pointed to by ``$UNIQUE_TURN_IDENTITY_FILE``
+3. ``$UNIQUE_MESSAGE_ID`` environment variable (one-shot / external callers)
+
+When ``UNIQUE_TURN_IDENTITY_FILE`` is set but the file is missing or malformed,
+resolution fails loudly — silent fallback to a stale env value is forbidden.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+TURN_IDENTITY_ENV_VAR = "UNIQUE_TURN_IDENTITY_FILE"
+MESSAGE_ID_ENV_VAR = "UNIQUE_MESSAGE_ID"
+CHAT_ID_ENV_VAR = "UNIQUE_CHAT_ID"
+
+
+class TurnIdentityError(ValueError):
+    """Raised when the turn-identity file is configured but unusable."""
+
+
+@dataclass(frozen=True)
+class TurnIdentity:
+    """Parsed contents of the per-turn identity file.
+
+    Mirrors the JSON contract written by the platform runner. Only
+    ``message_id`` is mandatory; the remaining fields are informational.
+    """
+
+    message_id: str
+    chat_id: str | None = None
+    user_id: str | None = None
+    company_id: str | None = None
+    assistant_id: str | None = None
+    turn: int | None = None
+
+
+def _optional_str(payload: dict[str, object], key: str) -> str | None:
+    value = payload.get(key)
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def read_turn_identity(
+    path: str | Path | None = None,
+) -> TurnIdentity | None:
+    """Load and validate the turn-identity JSON file.
+
+    When *path* is ``None``, reads ``$UNIQUE_TURN_IDENTITY_FILE``. Returns
+    ``None`` when neither is set. Raises ``TurnIdentityError`` if the env
+    var / path is set but the file cannot be read or does not contain a
+    non-empty ``message_id`` string.
+    """
+    raw_path = str(path) if path is not None else os.environ.get(TURN_IDENTITY_ENV_VAR)
+    if not raw_path:
+        return None
+
+    identity_path = Path(raw_path)
+    if not identity_path.is_file():
+        raise TurnIdentityError(
+            f"{TURN_IDENTITY_ENV_VAR} is set to {raw_path!r} but the file "
+            "is missing; refusing to fall back to a stale message id"
+        )
+    if identity_path.is_symlink():
+        raise TurnIdentityError(
+            f"refusing to read turn-identity file {raw_path!r}: path is a symlink"
+        )
+
+    try:
+        payload = json.loads(identity_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise TurnIdentityError(
+            f"failed to read turn-identity file {raw_path!r}: {exc}"
+        ) from exc
+
+    if not isinstance(payload, dict):
+        raise TurnIdentityError(
+            f"turn-identity file {raw_path!r} must contain a JSON object"
+        )
+
+    message_id = payload.get("message_id")
+    if not isinstance(message_id, str) or not message_id.strip():
+        raise TurnIdentityError(
+            f"turn-identity file {raw_path!r} is missing a non-empty "
+            "'message_id' string"
+        )
+
+    raw_turn = payload.get("turn")
+    return TurnIdentity(
+        message_id=message_id.strip(),
+        chat_id=_optional_str(payload, "chat_id"),
+        user_id=_optional_str(payload, "user_id"),
+        company_id=_optional_str(payload, "company_id"),
+        assistant_id=_optional_str(payload, "assistant_id"),
+        turn=raw_turn if isinstance(raw_turn, int) else None,
+    )
+
+
+def resolve_message_id(explicit: str | None = None) -> str | None:
+    """Resolve the assistant message ID for a message-bound CLI operation.
+
+    Returns ``None`` when no source yields a value (callers may then mint a
+    placeholder message, as elicit does for visible prompts without a chat
+    context). Raises ``TurnIdentityError`` when the turn-identity file is
+    configured but unusable.
+    """
+    if explicit is not None and str(explicit).strip():
+        return str(explicit).strip()
+
+    identity = read_turn_identity()
+    if identity is not None:
+        return identity.message_id
+
+    env_id = os.environ.get(MESSAGE_ID_ENV_VAR)
+    if env_id is not None and env_id.strip():
+        return env_id.strip()
+    return None
+
+
+def resolve_chat_id(explicit: str | None = None) -> str | None:
+    """Resolve chat ID with the same file-then-env precedence as message ID.
+
+    Explicit flag wins. The turn-identity file is consulted next (and fails
+    loudly when configured but unusable). Falls back to ``$UNIQUE_CHAT_ID``.
+    """
+    if explicit is not None and str(explicit).strip():
+        return str(explicit).strip()
+
+    identity = read_turn_identity()
+    if identity is not None and identity.chat_id is not None:
+        return identity.chat_id
+
+    env_id = os.environ.get(CHAT_ID_ENV_VAR)
+    if env_id is not None and env_id.strip():
+        return env_id.strip()
+    return None

{unique_sdk-2026.30.0.dev6 → unique_sdk-2026.30.0.dev7}/unique_sdk/cli/skills/unique-cli-elicitation/SKILL.md

@@ -5,8 +5,9 @@ description: >-
   question in free-form chat -- for clarifications, confirmations
   (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 ask` so the user gets
-  a proper structured prompt and you get a structured answer back.
+  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.
   Do NOT ask the user in plain chat when you can use this skill instead.
 ---
 
@@ -14,21 +15,82 @@ 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 call `unique-cli elicit ask` instead.
+> **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).
 
 !!! danger "`--visible` is currently MANDATORY"
-    You **must always run `elicit ask` with visibility on** (it is on by default — 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 only command you need: `elicit ask`
-
-`elicit ask` is a **single call that creates the elicitation, shows it to the user, and blocks until the user answers** (or declines / cancels / expires). This is the command you reach for every time. You do not need to learn `elicit create`, `elicit wait`, `elicit pending`, `elicit get`, or `elicit respond` — they exist for scripting and tests, not for agent workflows.
+    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`
+
+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.
+
+Instead, use `elicit create` (returns immediately) followed by a short
+polling loop with `elicit wait`, where **every individual command finishes
+comfortably under your harness's Bash foreground timeout** (90s is a safe
+default — comfortably under Claude Code's ~120s):
+
+1. **Create** the elicitation:
+
+   ```bash
+   create_output=$(unique-cli elicit create "<question>" \
+     --mode FORM \
+     --tool-name "<tool_name>" \
+     --chat-id "$UNIQUE_CHAT_ID" \
+     --expires-in 7200 \
+     --schema '<json schema>')
+   elicitation_id=$(echo "$create_output" | awk '/^Created elicitation/{print $3}')
+   ```
+
+2. **Poll in short bursts**, each well under your harness's Bash foreground
+   timeout:
+
+   ```bash
+   status="PENDING"
+   elapsed=0
+   total_timeout=7200   # match --expires-in above
+   chunk=90
+   while [ "$elapsed" -lt "$total_timeout" ]; do
+     result=$(unique-cli elicit wait "$elicitation_id" --timeout "$chunk" --poll-interval 3)
+     status=$(echo "$result" | awk -F': *' '/^Status:/{print $2}')
+     case "$status" in
+       RESPONDED|ACCEPTED|DECLINED|CANCELLED|REJECTED|EXPIRED|COMPLETED) break ;;
+     esac
+     elapsed=$((elapsed + chunk))
+   done
+   ```
+
+   Each `elicit wait ... --timeout 90` call is a normal, short-lived Bash
+   invocation that always returns within ~90 seconds — either with a
+   terminal status (done) or the current non-terminal status (loop again).
+   Your harness never sees a single call run long enough to background it.
+
+3. Parse `Response:` from the final `$result` exactly as you would with
+   `elicit ask`'s output — the format is identical (see "Reading the
+   response" below).
+
+`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.
 
 ```bash
 unique-cli elicit ask "<question>" [options]
 ```
 
-!!! danger "`--chat-id` and `--message-id` are MANDATORY"
-    You **must always pass both** `--chat-id "$UNIQUE_CHAT_ID"` **and** `--message-id "$UNIQUE_MESSAGE_ID"` on every `elicit ask` call. These environment variables are always available in the agent environment. Without both flags the elicitation is not correctly anchored to the current conversation and the user will not see it.
+!!! danger "`--chat-id` is MANDATORY"
+    You **must always pass** `--chat-id "$UNIQUE_CHAT_ID"` on every
+    `elicit create`/`elicit ask` call. 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.
 
 ## When to use
 
@@ -43,12 +105,16 @@ 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.
+
 ### Minimal — free-text answer
 
 ```bash
 unique-cli elicit ask "Which quarter should I report on?" \
-  --chat-id "$UNIQUE_CHAT_ID" \
-  --message-id "$UNIQUE_MESSAGE_ID"
+  --chat-id "$UNIQUE_CHAT_ID"
 ```
 
 Under the hood this creates a form with a single required string field `answer`. The reply you receive will look like:
@@ -71,7 +137,6 @@ Provide an explicit JSON schema so the user sees proper UI controls instead of a
 ```bash
 unique-cli elicit ask "Which report format do you want?" \
   --chat-id "$UNIQUE_CHAT_ID" \
-  --message-id "$UNIQUE_MESSAGE_ID" \
   --schema '{
     "type": "object",
     "properties": {
@@ -92,7 +157,6 @@ Always use this before `rm`, `rmdir -r`, mass uploads, or anything irreversible.
 ```bash
 unique-cli elicit ask "Confirm deleting /Archive/2024 and everything inside it" \
   --chat-id "$UNIQUE_CHAT_ID" \
-  --message-id "$UNIQUE_MESSAGE_ID" \
   --schema '{
     "type": "object",
     "properties": {
@@ -112,7 +176,6 @@ Proceed **only** if the response contains `"confirm": true`. Treat `DECLINED`, `
 ```bash
 unique-cli elicit ask "Please provide report settings" \
   --chat-id "$UNIQUE_CHAT_ID" \
-  --message-id "$UNIQUE_MESSAGE_ID" \
   --schema '{
     "type": "object",
     "properties": {
@@ -127,10 +190,16 @@ 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).
+
 | Option | Short | Default | Description |
 |--------|-------|---------|-------------|
 | `--chat-id` | `-c` | none | **MANDATORY.** Chat to show the question in. Always pass `"$UNIQUE_CHAT_ID"`. Without it the visibility workaround cannot run and the user will not see the elicitation. |
-| `--message-id` | `-m` | none | **MANDATORY.** The current assistant message ID. Always pass `"$UNIQUE_MESSAGE_ID"`. Anchors the elicitation to the correct message in the conversation thread. |
+| `--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. |
@@ -187,14 +256,20 @@ If the exact structured response is useful for auditing or debugging, put it beh
 
 Do not expose raw JSON by default when a natural-language confirmation would be clearer.
 
-## Scripting pattern
+## Scripting pattern (non-agent-harness only)
+
+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.
 
 In a shell script or agent tool wrapper, capture the output and pull out the `Response:` line:
 
 ```bash
 result=$(unique-cli elicit ask "Which region?" \
   --chat-id "$UNIQUE_CHAT_ID" \
-  --message-id "$UNIQUE_MESSAGE_ID" \
   --schema '{
     "type":"object",
     "properties":{"region":{"type":"string","enum":["EU","US","APAC"]}},
@@ -220,9 +295,9 @@ esac
 
 ## Agent workflow rules
 
-1. **Default to `elicit ask`.** If you need an answer from the user, use this command, not a chat message. Do not use any of the other `elicit *` subcommands from an agent.
+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.
 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. **Always pass `--message-id "$UNIQUE_MESSAGE_ID"`.** This anchors the elicitation to the current message in the conversation. Both `$UNIQUE_CHAT_ID` and `$UNIQUE_MESSAGE_ID` are always available as environment variables — never omit either.
+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.
 5. **Never run destructive CLI commands without a confirmation elicitation.** This includes `rm`, `rmdir -r`, bulk renames, large uploads, schedule deletion, etc.
 6. **Pick a meaningful `--tool-name`.** `confirm_delete`, `choose_region`, `pick_report` -- short snake_case describing the intent.
@@ -231,7 +306,7 @@ esac
 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.
 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. **Respect timeouts.** The default `--timeout` is 2 hours -- override it only when the task needs a shorter or longer wait.
+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.
 
 ## Prerequisites
 
@@ -243,7 +318,8 @@ UNIQUE_COMPANY_ID # Company ID (required)
 UNIQUE_API_KEY    # API key -- optional on localhost / secured cluster
 UNIQUE_APP_ID     # App ID -- optional on localhost / secured cluster
 UNIQUE_CHAT_ID    # Current chat ID -- always pass as --chat-id (required)
-UNIQUE_MESSAGE_ID # Current message ID -- always pass as --message-id (required)
+UNIQUE_TURN_IDENTITY_FILE # Per-turn identity JSON — CLI resolves message ID from here
+UNIQUE_MESSAGE_ID # Fallback message ID when no turn-identity file is present
 ```
 
 Install: `pip install unique-sdk`

{unique_sdk-2026.30.0.dev6 → unique_sdk-2026.30.0.dev7}/unique_sdk/cli/skills/unique-cli-mcp/SKILL.md

@@ -77,7 +77,7 @@ unique-cli mcp [--chat-id <id>] [--message-id <id>] [PAYLOAD | --file <path> | -
 | Option | Short | Required | Description |
 |--------|-------|----------|-------------|
 | `--chat-id` | `-c` | Yes | Chat ID for the conversation context |
-| `--message-id` | `-m` | Yes | Message ID for the conversation context |
+| `--message-id` | `-m` | No | Message ID for the conversation context. Optional — resolved from `$UNIQUE_TURN_IDENTITY_FILE` (preferred) or `$UNIQUE_MESSAGE_ID` when omitted. |
 | `PAYLOAD` | | One of three | Inline JSON string |
 | `--file` | `-f` | One of three | Path to a JSON file |
 | `--stdin` | | One of three | Read JSON from stdin |

{unique_sdk-2026.30.0.dev6 → unique_sdk-2026.30.0.dev7}/unique_sdk/cli/skills/unique-cli-subagent/SKILL.md

@@ -17,10 +17,12 @@ the tool name shown in the generated connected-space skill.
 ```bash
 unique-cli subagent "<tool_name>" "<message>" \
   --chat-id "$UNIQUE_CHAT_ID" \
-  --message-id "$UNIQUE_MESSAGE_ID" \
   --assistant-id "$UNIQUE_ASSISTANT_ID"
 ```
 
+Omit `--message-id`: the CLI resolves the current turn's assistant message ID
+from `$UNIQUE_TURN_IDENTITY_FILE` automatically.
+
 ## Rules
 
 1. Use the exact tool name from the connected-space skill or from
@@ -49,7 +51,7 @@ The platform sets these environment variables automatically:
 UNIQUE_USER_ID
 UNIQUE_COMPANY_ID
 UNIQUE_CHAT_ID
-UNIQUE_MESSAGE_ID
+UNIQUE_TURN_IDENTITY_FILE
 UNIQUE_ASSISTANT_ID
 UNIQUE_API_KEY
 UNIQUE_APP_ID