@event4u/agent-config 1.18.0 → 1.20.0

package/scripts/update_prices.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Refresh `.agent-prices.md` from the LiteLLM model-prices feed.
+"""Refresh `agents/.agent-prices.md` from the LiteLLM model-prices feed.
 
 Source: https://raw.githubusercontent.com/BerriAI/litellm/main/
         model_prices_and_context_window.json
@@ -9,7 +9,7 @@ Network failure or invalid response → fall back to
 always written. Stdlib only; no extra dependency.
 
 Usage:
-    python3 scripts/update_prices.py            # writes .agent-prices.md
+    python3 scripts/update_prices.py            # writes agents/.agent-prices.md
     python3 scripts/update_prices.py --check    # exit 1 if file is stale
 """
 
@@ -81,7 +81,7 @@ def _to_rows_from_litellm(payload: dict[str, dict[str, object]]) -> list[tuple[s
 
 
 def refresh(path: Path = PRICES_FILE) -> str:
-    """Write a fresh `.agent-prices.md`. Returns the source label used."""
+    """Write a fresh `agents/.agent-prices.md`. Returns the source label used."""
     payload = _fetch_litellm()
     if payload is not None:
         rows = _to_rows_from_litellm(payload)

package/scripts/verify_before_complete_hook.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Platform-agnostic hook for the `verify-before-complete` rule.
+
+Records observable evidence that a verification command (tests, quality
+tools, build) ran. The rule body cites the resulting state file as the
+source of truth for the "have I verified this turn?" question. The hook
+itself never blocks — it is observability infra, not control flow.
+
+Wired to multiple events via the manifest:
+  - session_start / user_prompt_submit → reset turn-scoped counters
+  - post_tool_use → inspect tool + command, record verifications
+  - stop                                → record stop fired (claim-done window)
+
+Output: `agents/state/verify-before-complete.json`
+  {
+    "schema_version": 1,
+    "session_id": "<str>",
+    "turn_started_at": "<iso8601|null>",
+    "last_verification": {"command": ..., "tool": ..., "at": ...} | null,
+    "verifications_this_turn": <int>,
+    "verifications_this_session": <int>,
+    "last_stop_at": "<iso8601|null>",
+    "verified_this_turn": <bool>,
+    "checked_at": "<iso8601>"
+  }
+
+Exit code is always 0.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from hooks.state_io import atomic_write_json  # noqa: E402
+
+STATE_FILE = Path("agents") / "state" / "verify-before-complete.json"
+
+# Tool names across platforms whose `command` / `tool_input.command` field
+# carries a shell command we can inspect. Edit tools are deliberately
+# excluded — they cannot run verification.
+COMMAND_TOOLS = frozenset({
+    "launch-process", "launch_process",     # Augment
+    "Bash", "BashTool",                     # Claude Code
+    "run-process", "runProcess",            # variants
+    "shell", "execute_shell",               # generic / Cline
+    "RunShellCommand",                      # Cursor
+})
+
+# Permissive verification-command pattern. Observability — false positives
+# are cheaper than false negatives. Word-boundary anchored on common
+# shell separators so chained commands (`task sync && task ci`) match.
+_VERIFICATION_RE = re.compile(
+    r'(?:^|[\s;&|`(])('
+    r'task\s+(?:ci|test|tests|lint|check|qa|phpstan|rector|ecs|pest|pytest)'
+    r'|(?:\./|\.venv/bin/|vendor/bin/)?(?:pest|phpunit|phpstan|psalm|rector|ecs)\b'
+    r'|(?:python3?|\.venv/bin/python3?)\s+-m\s+pytest'
+    r'|pytest\b'
+    r'|(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|check|lint|typecheck|tsc)'
+    r'|cargo\s+(?:test|check|clippy)'
+    r'|go\s+test'
+    r'|make\s+(?:test|check|lint)'
+    r'|composer\s+(?:test|check|lint|phpstan)'
+    r'|(?:php\s+)?artisan\s+test'
+    r')',
+    re.IGNORECASE,
+)
+
+
+def _now() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds")
+
+
+def _empty_state() -> dict:
+    return {
+        "schema_version": 1,
+        "session_id": "",
+        "turn_started_at": None,
+        "last_verification": None,
+        "verifications_this_turn": 0,
+        "verifications_this_session": 0,
+        "last_stop_at": None,
+        "verified_this_turn": False,
+        "checked_at": _now(),
+    }
+
+
+def _load_state(target: Path) -> dict:
+    if not target.is_file():
+        return _empty_state()
+    try:
+        decoded = json.loads(target.read_text(encoding="utf-8"))
+        if isinstance(decoded, dict):
+            return {**_empty_state(), **decoded}
+    except (OSError, json.JSONDecodeError):
+        pass
+    return _empty_state()
+
+
+def _extract_command(payload: dict) -> tuple[str | None, str | None]:
+    """Return (tool_name, command_text) from a tool-event payload."""
+    tool = (payload.get("tool_name") or payload.get("toolName")
+            or payload.get("tool"))
+    if not isinstance(tool, str) or tool not in COMMAND_TOOLS:
+        return (tool if isinstance(tool, str) else None, None)
+    ti = payload.get("tool_input")
+    if isinstance(ti, dict):
+        for key in ("command", "cmd", "shell_command"):
+            v = ti.get(key)
+            if isinstance(v, str) and v:
+                return (tool, v)
+    # Some platforms surface the command at the top level.
+    for key in ("command", "cmd"):
+        v = payload.get(key)
+        if isinstance(v, str) and v:
+            return (tool, v)
+    return (tool, None)
+
+
+def _is_verification(command: str) -> bool:
+    return bool(_VERIFICATION_RE.search(command))
+
+
+def _reset_turn(state: dict, session_id: str) -> dict:
+    state["session_id"] = session_id or state.get("session_id") or ""
+    state["turn_started_at"] = _now()
+    state["verifications_this_turn"] = 0
+    state["verified_this_turn"] = False
+    return state
+
+
+def _update(state: dict, event: str, envelope: dict) -> dict:
+    session_id = envelope.get("session_id") or state.get("session_id") or ""
+    if session_id and session_id != state.get("session_id"):
+        # Session boundary — reset session-scoped counters.
+        state["session_id"] = session_id
+        state["verifications_this_session"] = 0
+        state = _reset_turn(state, session_id)
+
+    payload = envelope.get("payload") or {}
+    if not isinstance(payload, dict):
+        payload = {}
+
+    if event in ("session_start", "user_prompt_submit"):
+        state = _reset_turn(state, session_id)
+    elif event == "post_tool_use":
+        tool, cmd = _extract_command(payload)
+        if cmd and _is_verification(cmd):
+            state["last_verification"] = {
+                "command": cmd[:512],
+                "tool": tool,
+                "at": _now(),
+                "platform": envelope.get("platform") or "",
+            }
+            state["verifications_this_turn"] = int(
+                state.get("verifications_this_turn") or 0) + 1
+            state["verifications_this_session"] = int(
+                state.get("verifications_this_session") or 0) + 1
+            state["verified_this_turn"] = True
+    elif event == "stop":
+        state["last_stop_at"] = _now()
+
+    state["checked_at"] = _now()
+    return state
+
+
+def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
+    envelope: dict = {}
+    if stdin_text.strip():
+        try:
+            decoded = json.loads(stdin_text)
+            if isinstance(decoded, dict):
+                envelope = decoded
+        except json.JSONDecodeError:
+            envelope = {}
+
+    event = envelope.get("event") or ""
+    target = consumer_root / STATE_FILE
+    state = _load_state(target)
+    state = _update(state, event, envelope)
+
+    try:
+        atomic_write_json(target, state)
+    except OSError:
+        if verbose:
+            print("verify-before-complete-hook: state write failed",
+                  file=sys.stderr)
+        return 0
+
+    if verbose:
+        print(
+            f"verify-before-complete-hook: event={event} "
+            f"verified_this_turn={state.get('verified_this_turn')} "
+            f"verifications_this_turn={state.get('verifications_this_turn')}",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--platform", default="generic",
+                        help="informational platform tag")
+    parser.add_argument("--verbose", action="store_true",
+                        help="emit one stderr line per invocation")
+    args = parser.parse_args(argv)
+    return run(sys.stdin.read(), consumer_root=Path.cwd(),
+               verbose=args.verbose)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/.agent-src/commands/chat-history/checkpoint.md

@@ -1,126 +0,0 @@
----
-name: chat-history:checkpoint
-cluster: chat-history
-sub: checkpoint
-description: Append a phase-boundary entry to .agent-chat-history — CHECKPOINT fallback for platforms without a native hook (Augment IDE, Cursor pre-1.7, Cline non-Mac/Linux). ~1s.
-disable-model-invocation: true
-suggestion:
-  eligible: true
-  trigger_description: "User wants to flush a chat-history phase boundary on a CHECKPOINT-class platform (Augment IDE, Cursor < 1.7, Cline on Windows) — phrases like 'checkpoint chat history', 'log a phase boundary', 'manual chat-history append'."
-  trigger_context: "chat_history.path == checkpoint AND a phase-shaped boundary just completed (decision recorded, multi-tool sequence finished, task-list item closed)."
----
-<!-- cloud_safe: noop -->
-
-# /chat-history checkpoint
-Force-append a `phase`-typed entry to `.agent-chat-history`. CHECKPOINT
-fallback for platforms without native hooks — see
-[`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md)
-for the per-platform classification.
-
-Use this at decision points, end of phase, or after a meaningful tool
-sequence on a CHECKPOINT/MANUAL platform. On HOOK platforms (Claude
-Code, Augment CLI, Cursor 1.7+, Cline non-Windows, Windsurf, Gemini
-CLI), the platform fires hooks automatically — manual use is allowed
-but rarely needed.
-
-## When to use
-
-- IDE plugin without hooks (Augment Code IDE plugin as of 2026-04-30).
-- Long-running tool sequence on any platform that did not flush.
-- Explicit phase-boundary marker after a multi-tool refactor.
-- Crash-recovery rehearsal — verifies the append path works before a
-  real outage.
-
-## When NOT to use
-
-- HOOK platform mid-session — the platform already records turn-level
-  cadence; an extra checkpoint just adds noise.
-- After every line of agent output — that's `per_turn` cadence and is
-  configured in `.agent-settings.yml`, not via this command.
-- To inspect the log → [`/chat-history`](chat-history.md).
-- To wipe the log → [`/chat-history-clear`](chat-history-clear.md).
-- To reload the log into context → [`/chat-history-resume`](chat-history-resume.md).
-
-## Steps
-
-### 1. Check if enabled
-
-Read `chat_history.enabled` from `.agent-settings.yml`. If `false` or
-the section is missing, say so and stop:
-
-```
-> 📒 chat-history is disabled (chat_history.enabled = false).
-> Nothing to checkpoint. Enable in .agent-settings.yml first.
-```
-
-### 2. Determine the phase label
-
-Pick a short label (2–6 words) that names what just happened:
-
-- "phase-1-done", "refactor-extracted", "tests-green",
-  "review-comments-fixed", "merge-ready".
-
-If the user invoked the command without context, ask once with
-numbered options per [`user-interaction`](../rules/user-interaction.md):
-
-```
-> 1. Use a free-text label — type 2–6 words for the checkpoint
-> 2. Use a generic "manual-checkpoint" label
-> 3. Skip — close without writing
-```
-
-### 3. Append the checkpoint
-
-Invoke the master CLI:
-
-```
-./agent-config chat-history:checkpoint \
-  --first-user-msg "<the conversation's first user message>" \
-  --payload '{"phase": "<label>"}'
-```
-
-The wrapper delegates to `scripts/chat_history.py hook-append --event phase`,
-which performs cadence filtering and ownership checks. Cadence is read
-from `chat_history.frequency` in `.agent-settings.yml` — `per_turn` /
-`per_phase` / `per_tool`. `per_tool` cadence drops the `phase` event;
-say so explicitly if that is the active mode.
-
-### 4. Confirm
-
-Render a one-line confirmation, mirroring the user's language:
-
-```
-> 📒 Checkpoint logged: <label>  (entries: N → N+1)
-```
-
-If the helper returned `skipped_cadence`, surface it:
-
-```
-> 📒 Checkpoint skipped — current cadence is per_tool, phase events are dropped.
-> Switch chat_history.frequency to per_phase or per_turn to capture phase boundaries.
-```
-
-## Gotchas
-
-- The command writes through the same ownership-state machine as
-  hooks — a `foreign` log triggers the
-  [`chat-history`](../rules/chat-history-ownership.md) Foreign-Prompt before any
-  append. This is intentional; the checkpoint must not silently
-  hijack another session's log.
-- The `phase` payload key is required. Other keys are accepted but
-  ignored by the JSONL schema (forward-compat — they may be promoted
-  to first-class fields later).
-- On HOOK platforms, hook entries and checkpoint entries coexist
-  cleanly. The schema does not deduplicate; if you checkpoint
-  immediately after a hook fires, expect two adjacent entries with
-  different `source` values.
-
-## See also
-
-- [`chat-history`](../rules/chat-history-ownership.md) — the rule defining the
-  conditional Iron Law (HOOK platforms vs CHECKPOINT/MANUAL platforms)
-- [`/chat-history`](chat-history.md) — read-only status display
-- [`/chat-history-resume`](chat-history-resume.md) — adopt + load
-- [`/chat-history-clear`](chat-history-clear.md) — wipe
-- [`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md) — per-platform strategy table
-- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — `hook-append` API

package/.agent-src/commands/chat-history/clear.md

@@ -1,103 +0,0 @@
----
-name: chat-history:clear
-cluster: chat-history
-sub: clear
-description: Manually delete the persistent chat-history log — asks for confirmation, optionally archives to a timestamped backup before wiping
-disable-model-invocation: true
-suggestion:
-  eligible: false
-  rationale: "Destructive log wipe — must be deliberate."
----
-<!-- cloud_safe: noop -->
-
-# /chat-history clear
-Wipes `.agent-chat-history`. Use when the log is stale (wrong session),
-bloated beyond usefulness, or contains information you do not want
-persisted on disk.
-
-This command is **destructive** — always asks for confirmation before
-touching the file, unless the file does not exist in the first place.
-
-## When NOT to use
-
-- Inspect before deleting → [`/chat-history`](chat-history.md).
-- Keep the entries but re-point the header → [`/chat-history-resume`](chat-history-resume.md).
-- Disable logging entirely → set `chat_history.enabled: false` in
-  `.agent-settings.yml`; see
-  [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
-  Disabling does not delete the existing file; run this command
-  afterwards if you also want it gone.
-
-## Steps
-
-### 1. Check current state
-
-Run `scripts/chat_history.py status`. If `exists: false`, tell the user
-and stop:
-
-```
-> 📒 No .agent-chat-history to clear.
-```
-
-### 2. Show what is about to be deleted
-
-Render a short preview so the user sees what they are wiping:
-
-```
-> 📒 About to clear .agent-chat-history
->
-> Size:       {size_kb} KB
-> Entries:    {entries}
-> Session:    {short_fp}  (started {created_at_relative})
->
-> 1. Archive — rename to .agent-chat-history.{YYYYMMDD-HHMMSS}.bak, then start fresh
-> 2. Delete — permanent, no backup
-> 3. Cancel — keep the file as-is
-```
-
-### 3. Act on the choice
-
-- `1` (Archive) → `mv .agent-chat-history
-  .agent-chat-history.{timestamp}.bak`. The rule will create a fresh
-  file on the next append.
-- `2` (Delete) → run `scripts/chat_history.py clear`. Permanent.
-- `3` (Cancel) → stop. Make no changes.
-
-Free-text replies ("abbrechen", "keep it", "nevermind") count as `3`.
-An unrecognized reply also counts as `3` — never delete on ambiguous
-input.
-
-### 4. Confirm
-
-After a successful archive or delete, print a one-line confirmation:
-
-```
-> 📒 Archived to .agent-chat-history.{timestamp}.bak
-```
-
-or
-
-```
-> 📒 .agent-chat-history deleted.
-```
-
-Do **not** re-enable logging or change `.agent-settings.yml` as a side
-effect — this command is scoped to the file on disk only.
-
-## Gotchas
-
-- `.agent-chat-history.*.bak` files are also git-ignored by the
-  installer's `.gitignore` block. They accumulate if archived often —
-  users can delete them manually.
-- If `chat_history.enabled: false`, the file will **not** be recreated
-  after clearing. That is usually fine, but mention it so the user
-  knows the log is now silent.
-- Deletion cannot be undone. When in doubt, prefer option `1` (Archive).
-
-## See also
-
-- [`chat-history`](../rules/chat-history-ownership.md) — the rule that writes the file
-- [`/chat-history`](chat-history.md) — status inspection
-- [`/chat-history-resume`](chat-history-resume.md) — load + adopt instead of wipe
-- [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference
-- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — helper API

package/.agent-src/commands/chat-history/resume.md

@@ -1,183 +0,0 @@
----
-name: chat-history:resume
-cluster: chat-history
-sub: resume
-description: Load the persistent chat-history log into the current conversation — picks match/returning/foreign flow and supports resume, merge, replace, or continue
-disable-model-invocation: true
-suggestion:
-  eligible: false
-  rationale: "Explicit resume mechanic with foreign/returning state machine."
----
-<!-- cloud_safe: noop -->
-
-# /chat-history resume
-Reconnects the current conversation with an existing `.agent-chat-history`
-file. Depending on the 4-state ownership check, it routes to the right
-flow: silent summarize, adopt, merge, or replace.
-
-Use after a crashed chat, after switching tools (Augment → Claude Code),
-or when the agent showed the foreign- or returning-session prompt from
-the [`chat-history`](../rules/chat-history-ownership.md) rule and the user picked
-"resume".
-
-## When NOT to use
-
-- Just inspect metadata → [`/chat-history`](chat-history.md).
-- Start fresh instead of resuming → [`/chat-history-clear`](chat-history-clear.md)
-  or pick "New start" in the foreign prompt.
-- Logging is disabled (`chat_history.enabled: false`) → enable it in
-  `.agent-settings.yml` first; this command refuses to run otherwise.
-
-## Preconditions
-
-- `.agent-settings.yml` exists and `chat_history.enabled: true`.
-- `.agent-chat-history` exists at the project root.
-
-If either is missing, tell the user and stop — do not create files here.
-
-## Steps
-
-### 1. Load status
-
-Run `scripts/chat_history.py status`. If `exists: false` or
-`entries: 0`, tell the user there is nothing to resume and stop.
-
-### 2. Determine ownership state
-
-Run `scripts/chat_history.py state --first-user-msg "<current first user
-message>"`. Branch on the result:
-
-- `match` → step 3a (already owner)
-- `returning` → step 3b (pick Merge / Replace / Continue)
-- `foreign` → step 3c (pick Resume / New start / Ignore)
-- `missing` → header corrupt; tell the user and suggest
-  `/chat-history-clear` to start fresh. Stop.
-
-### 3a. `match` — already owner
-
-Nothing to adopt. Skip to step 4 (summarize) for the user's benefit.
-
-### 3b. `returning` — this chat once owned the file
-
-Another session took over. Present the Returning-Prompt from the rule
-and wait for a number:
-
-```
-> 📒 Welcome back. This chat once owned the history file; another
-> session has written to it since.
->
-> On-file entries: {N}   Size: {X} KB
->
-> 1. Merge — my in-memory history first, the foreign entries after
-> 2. Replace — wipe the foreign entries, keep only my history
-> 3. Continue — leave the file as-is; only new entries from now on
-```
-
-- **1 (Merge)** — build the in-memory entries list (see below), then:
-  ```bash
-  scripts/chat_history.py prepend --entries-json '<list>'
-  scripts/chat_history.py adopt --first-user-msg "<msg>"
-  ```
-- **2 (Replace)** — build the in-memory entries list, then:
-  ```bash
-  scripts/chat_history.py reset --first-user-msg "<msg>" \
-    --freq <frequency> --entries-json '<list>'
-  ```
-- **3 (Continue)** —
-  ```bash
-  scripts/chat_history.py adopt --first-user-msg "<msg>"
-  ```
-
-### 3c. `foreign` — new chat finds an unknown session's file
-
-Present the Foreign-Prompt from the rule and wait for a number:
-
-```
-> 📒 Found chat history from an unknown session.
->
-> Entries on file: {N}   Size: {X} KB
->
-> 1. Resume — adopt this file, load entries as context, keep appending
-> 2. New start — archive to .agent-chat-history.bak, init fresh
-> 3. Ignore — leave the file untouched, disable logging for this session
-```
-
-- **1 (Resume)** — `adopt --first-user-msg "<msg>"`.
-- **2 (New start)** — rename file to `.agent-chat-history.bak`, run
-  `init --first-user-msg "<msg>" --freq <frequency>`. Skip summary.
-- **3 (Ignore)** — do nothing. Report that logging is off for this
-  conversation. Stop.
-
-### 3d. Building the in-memory entries list (Merge / Replace)
-
-Reconstruct the agent's prior turns as a JSON array:
-
-- one `{"t":"user","text":"<preview>","ts":"<iso>"}` per user message
-- one `{"t":"agent","text":"<preview>","ts":"<iso>"}` per agent reply
-- `text` previews capped at ~200 chars (whitespace flattened)
-- timestamps in ISO-8601 UTC (current time is acceptable if exact times
-  are unknown; order is what matters)
-- no tool-call payloads, no file contents, no secrets
-
-If the list is large (>30 KB), stream it via stdin:
-`prepend --entries-stdin` or `reset --entries-stdin`.
-
-### 4. Overflow check
-
-After any Merge or Replace, run
-`scripts/chat_history.py rotate --max-kb <max_size_kb>
---mode <on_overflow>` so the combined body stays within the user's
-budget.
-
-### 5. Summarize into conversation context
-
-Read the entries via the helper (`read --all` or `read --last N` for
-bounded). Produce a short, structured summary — **not** a verbatim dump:
-
-```
-> 📒 Resumed chat-history ({entries} entries, {age})
->
-> ## What was done
-> - {1–3 bullets from agent/decision entries}
->
-> ## Open threads
-> - {1–3 bullets from the most recent entries and any pending questions}
->
-> ## Key decisions
-> - {decisions captured during the prior session}
->
-> Ready to continue. What would you like to do?
-```
-
-Keep the summary under ~25 lines. Rationale: this is input into the new
-turn, not a display artifact (see
-[`token-efficiency`](../rules/token-efficiency.md)).
-
-### 6. Hand control back to the user
-
-After presenting the summary, stop and wait. Do not auto-resume work —
-the user decides what to do next.
-
-## Gotchas
-
-- **Iron law — one question at a time.** Even if the log contains
-  several open threads, ask about one at a time after the summary
-  (see [`ask-when-uncertain`](../rules/ask-when-uncertain.md)).
-- `adopt` rewrites the header in place and pushes the previous fp into
-  `former_fps` (capped at 10). No backup is created — use
-  `/chat-history-clear` first if you want a clean slate.
-- `reset` discards whatever was on disk. Only use it when the user
-  explicitly picks "Replace".
-- The summary is derived from the agent's reading of the JSONL. Old
-  entries may be incomplete (especially under `per_turn` with
-  previews only). Flag gaps explicitly.
-
-## See also
-
-- [`chat-history`](../rules/chat-history-ownership.md) — the rule that triggers
-  this command via the foreign- and returning-session prompts
-- [`/chat-history`](chat-history.md) — status inspection without adopting
-- [`/chat-history-clear`](chat-history-clear.md) — wipe instead of adopt
-- [`/agent-handoff`](agent-handoff.md) — complementary: generates a
-  paste-into-new-chat prompt (no disk file)
-- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — helper API