@passioncode-ai/passioncode 0.2.15 → 0.2.17

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_service.py

@@ -1356,7 +1356,7 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
 #: Each contract protocol's published revisions, oldest first (the contract's `PROTOCOL_REVISIONS`, DEC-0067); a test
 #: holds it equal to the contract's register at the pin.
 PROTOCOL_REVISIONS: Dict[str, Tuple[str, ...]] = {
-    "access-log": ("1",), "approval": ("1",), "activity-summary": ("1",), "enroll-token": ("1",), "entitlement": ("1",),
+    "access-log": ("1",), "approval": ("1",), "activity-summary": ("1",), "coding-agents": ("1",), "enroll-token": ("1",), "entitlement": ("1",),
     "entitlement-key-set": ("1",), "estate-record": ("1",), "execution-packet": ("1",),
     "fabric-activity": ("0.1",), "fabric-dashboard": ("0.1",), "fabric-delegation": ("0.1",), "fabric-device": ("0.1",),
     "fabric-interop": ("0.1", "0.2"), "fabric-local-channel": ("0.1",), "fabric-local-runner": ("0.1",),
@@ -1364,7 +1364,7 @@ PROTOCOL_REVISIONS: Dict[str, Tuple[str, ...]] = {
     "fabric-provider": ("0.1",), "fabric-relay": ("0.1",), "fabric-secret-envelope": ("1",), "fabric-service": ("0.1",),
     "fabric-settings-backup": ("1",), "heartbeat": ("1",), "learning-note": ("1",), "memory": ("0.1",), "pairing-message": ("1",), "pipeline": ("0.1",),
     "revocation-delta": ("1",), "session-handoff": ("1",), "share-registration": ("1",),
-    "share-registration-receipt": ("1",), "window-lease": ("1",),
+    "share-registration-receipt": ("1",), "support-quality-daily": ("1",), "window-lease": ("1",),
 }
 MAX_PROTOCOLS = 64
 _REVISION = re.compile(r"([a-z][a-z0-9.-]{0,63})/([0-9]{1,4}(?:\.[0-9]{1,4}){0,2})", re.ASCII)
@@ -1622,9 +1622,13 @@ def make_usage_receipt(provider: str, model: str, *, input_tokens: int, output_t
                        cache_read_tokens: int = 0, cache_write_tokens: int = 0,
                        cost_usd: Optional[float] = None, cost_basis: Optional[str] = None,
                        at: Optional[str] = None, route: Optional[str] = None,
-                       project_id: Optional[str] = None, task_run_id: Optional[str] = None) -> Dict[str, Any]:
+                       project_id: Optional[str] = None, task_run_id: Optional[str] = None,
+                       tokens_measured: bool = True) -> Dict[str, Any]:
     """One model call, from the provider's own usage numbers. No prompt, output or caller.
 
+    `tokens_measured=False` marks a call whose token counts are a lower bound or unknown (the provider returned none,
+    the stream was cut): the report counts it in `unmeasuredCalls` and its token totals are a lower bound (DEC-0091).
+
     `project_id` (a URI, kept in its normal form, DEC-0076) and `task_run_id` (the service's own run id) attribute the
     call to the project the service ran it for (DEC-0065); they never name a caller, session or person.
 
@@ -1650,6 +1654,10 @@ def make_usage_receipt(provider: str, model: str, *, input_tokens: int, output_t
         raise ServiceError("route is subscription, key or platform-metered (DEC-0046, DEC-0061).")
     receipt = {"at": at or now_iso(), "provider": provider, "model": model, **counts,
                "costUsd": None if cost_usd is None else float(cost_usd), "costBasis": basis}
+    if tokens_measured is not True:
+        if tokens_measured is not False:
+            raise ServiceError("tokens_measured is True or False.")
+        receipt["tokensMeasured"] = False
     if route is not None:
         receipt["route"] = route  # the operator's own login in its vendor's runner, an issued key, or the platform's metered models
     if task_run_id is not None and project_id is None:
@@ -1703,6 +1711,8 @@ def _by_project(receipts: List[Dict[str, Any]], first: str, last: str) -> List[D
 
 def _add_totals(row: Dict[str, Any], receipt: Dict[str, Any]) -> None:
     row["calls"] += 1
+    if receipt.get("tokensMeasured") is False:
+        row["unmeasuredCalls"] = row.get("unmeasuredCalls", 0) + 1  # written only when above 0: absent is 0 (DEC-0091)
     for name in ("inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"):
         row[name] += int(receipt.get(name) or 0)
     if receipt.get("costUsd") is None:
@@ -1760,6 +1770,8 @@ def _priced_row(row: Dict[str, Any], at: str) -> List[Dict[str, str]]:
     flag = lambda path, message: [{"code": "FAC-SEM-025", "instancePath": path, "message": message}]  # noqa: E731
     if unpriced > calls:
         return flag(at + "/unpricedCalls", "more unpriced calls than calls")
+    if _usage_count(row.get("unmeasuredCalls")) > calls:  # DEC-0091: unknown token counts are some of the calls
+        return flag(at + "/unmeasuredCalls", "more calls with unknown tokens than calls")
     if calls > 0 and unpriced == calls and row.get("costUsd", _MISSING_COST) is not None:
         return flag(at + "/costUsd", "every call is unpriced, so the cost is unknown (null), not a number")
     if unpriced < calls and row.get("costUsd", _MISSING_COST) is None:
@@ -1800,7 +1812,7 @@ def usage_findings(report: Any) -> List[Dict[str, str]]:
             if spent:
                 flag(at + "/byModel", "a day with calls, tokens or cost names the models they belong to")
             continue
-        for field in ("calls", "unpricedCalls", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"):
+        for field in ("calls", "unpricedCalls", "unmeasuredCalls", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"):
             total = sum(m.get(field) or 0 for m in models if isinstance(m.get(field) or 0, (int, float)))
             if (day.get(field) or 0) != total:
                 flag("%s/%s" % (at, field), "the day's %s is not the sum of its models (%s ≠ %s)" % (field, day.get(field) or 0, total))
@@ -2001,6 +2013,8 @@ def usage_report(receipts: Iterable[Dict[str, Any]], *, service_id: str, instanc
         for m in models:
             for name in ("calls", "unpricedCalls", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"):
                 day[name] += m[name]
+            if m.get("unmeasuredCalls"):
+                day["unmeasuredCalls"] = day.get("unmeasuredCalls", 0) + m["unmeasuredCalls"]
             day["_cost"] += m["costUsd"] or 0.0
         day = _close_totals(day)
         day["byModel"] = models

package/payload/plugins/fabric-agent-adapter/skills/creating-fabric-agents/SKILL.md

@@ -5,9 +5,9 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.38.0"
+  version: "0.39.0"
   contract-version: "0.1.0"
-  contract-commit: "07042181bfae2a481aa0da1a5651f24c76669c48"
+  contract-commit: "c55f2d5a11c9a0197e958e87212fca7ae1154769"
 ---
 
 # Creating Fabric-compatible agents
@@ -141,7 +141,7 @@ python3 <plugin-dir>/skills/adapting-projects-to-fabric/scripts/adapt_project.py
 The effect class is declared, never defaulted: ask the author what the agent does outside itself when the request
 does not say. Cost presets are only for a run whose cost varies; their amounts come from the author or measured runs.
 
-Pin exactly contract `0.1.0` at commit `07042181bfae2a481aa0da1a5651f24c76669c48` and
+Pin exactly contract `0.1.0` at commit `c55f2d5a11c9a0197e958e87212fca7ae1154769` and
 read the pinned guide before implementing protocol details. If this skill is installed
 without its sibling, the scaffolder is absent: create the bundle by hand from the pinned
 contract's `docs/guides/connecting-compatible-agents.md` and mark the structural check

package/payload/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/where-agents-run.md

@@ -30,7 +30,8 @@ The normative rules are the Fabric Agent Contract's, at the commit this plugin p
 
 Every step up is paid as cloud only: the person or the organization pays for the cloud its agents run in, and the
 order says which hosting it holds (`personal-cloud`, `org-cloud`, `enterprise-cloud` in `entitlement/1`). An agent never
-checks a price; it may read whether its context's entitlement is current and degrade honestly when it is not.
+checks a price; it may read whether its context's entitlement is current and degrade honestly when it is not. An agent placed
+into a customer's cloud is part of that customer's tier, not a product of its own.
 
 ## Contexts: one agent, the person and each organization
 

package/payload/plugins/fabric-agent-adapter/skills/working-with-fabric/SKILL.md

@@ -19,7 +19,7 @@ compatibility: >-
   this plugin; Codex/Kimi use command hooks; Hermes/OpenCode/OpenClaw/Pi use native context plugins after opt-in.
 metadata:
   author: PassionCode.ai
-  version: "0.38.0"
+  version: "0.39.0"
 ---
 
 # Working with Fabric

package/payload/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session.py

@@ -65,7 +65,7 @@ WATCH_MIN_INTERVAL_S = 10
 WATCH_MAX_BACKOFF_S = 900
 SESSION_ID = re.compile(r"[A-Za-z0-9._:-]{1,128}")
 LOOPBACK_ORIGIN = re.compile(r"http://127\.0\.0\.1:(\d{1,5})")
-VERSION = "0.38.0"
+VERSION = "0.39.0"
 HOSTS = {"claude": "Claude Code", "codex": "Codex", "kimi": "Kimi Code",
          "hermes": "Hermes", "opencode": "OpenCode", "openclaw": "OpenClaw", "pi": "Pi"}
 NATIVE_PLUGIN_HOSTS = frozenset(("hermes", "opencode", "openclaw", "pi"))

package/payload/plugins/observatory-log/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "observatory-log",
   "displayName": "Observatory Log",
   "description": "Records what changed in a watched project at the end of every turn, and asks for the one thing a diff cannot contain: why.",
-  "version": "0.18.0",
+  "version": "0.26.0",
   "license": "AGPL-3.0-only OR LicenseRef-PassionCode-Commercial",
   "author": {
     "name": "PassionCode.ai",

package/payload/plugins/observatory-log/hooks/ask-why.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Turn a record_turn.py result into the Stop hook's structured output.
+"""Turn a record_turn.py result into the request for a `why`, delivered with the next prompt.
 
 Standard library only, and silent on anything unexpected: a hook that reports
 its own confusion as a failure teaches the operator to disable hooks.
@@ -9,43 +9,45 @@ cooperation, so the only thing left to ask for is the `why` — and asking is
 worth more than a veto that costs a turn. An absent `why` stays visible in the
 ledger as a proposed record with a null field, which is accountability without
 obstruction.
+
+**Once, where the model reads it.** This printed the ask as a Stop
+`systemMessage` after every changed turn: measured over fourteen days of one
+machine's transcripts, 3,593 asks for 34 answers. A Stop `systemMessage` is a
+notice for the person, never rendered into the model's input, and a session is
+ONE record revised per turn, so every ask after the first repeated the question.
+Now the recorder decides (`ask` is false once a record was asked about, and when
+the turn wrote its own rationale), and this hook leaves the ask in a private
+per-session file that `prompt-why.py` hands to the model as the next prompt's
+`additionalContext`, once. If that file cannot be written the ask falls back to
+the old Stop notice: an ask is never lost to a full disk.
 """
 from __future__ import annotations
 import json
+import os
+import re
 import sys
+import time
 
 OWNER = "agent:claude-code"
+#: A session id names a file, so it is held to a shape that cannot leave the directory.
+SESSION = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+#: An ask nobody collected — the session ended — is removed after this long.
+PRUNE_SECONDS = 7 * 86400
+#: A session's pending asks, newest kept: a record is asked about once, so more
+#: than a few undelivered ones means the session is gone, not busy.
+KEEP = 3
 
 
-def main() -> int:
-    try:
-        r = json.load(sys.stdin)
-    except Exception:
-        return 0
-    if not r.get("recorded"):
-        # A FAULT IS NOT A QUIET TURN. This returned 0 for every `recorded:
-        # false`, and the recorder's reasons are two different kinds: "nothing
-        # changed" is an answer about the work, while `IllegalTransition:
-        # observed -> proposed` is the recorder failing. Measured 2026-09-07:
-        # once `tools/corroborate.py` promoted a session's record, every later
-        # turn of that session raised that error and said nothing — roughly
-        # seventy-two turns in one session, and the only visible sign was a
-        # ledger row that had stopped moving.
-        #
-        # The recorder marks which kind it is; this only has to stop hiding it.
-        reason = r.get("reason") or ""
-        if not r.get("fault"):
-            return 0                   # nothing changed, not watched, or explained
-        print(json.dumps({"systemMessage":
-                          "Observatory could NOT record this turn: " + reason +
-                          "\n\nThe facts of this turn are not in the ledger. "
-                          "`store/raw/record-turn.json` holds the same reason, and "
-                          "`project-observatory full findings` raises it.",
-                          "suppressOutput": True}))
-        return 0
-    if r.get("hasWhy"):
-        return 0                                          # already explained
+def pending_dir() -> str:
+    """Where a session's undelivered ask waits; `prompt-why.py` computes the same."""
+    base = os.environ.get("XDG_STATE_HOME") or os.path.join(
+        os.path.expanduser("~"), ".local", "state")
+    return os.path.join(base, "project-observatory", "ask-why")
+
 
+def message(r: dict, at_stop: bool = False) -> str:
+    """The ask. `at_stop` words it for a Stop notice, which follows the turn it is
+    about, rather than for the next prompt, which comes after it."""
     mid = r.get("memoryId")
     rev = r.get("revision")
     project = r.get("project", "this project")
@@ -53,11 +55,11 @@ def main() -> int:
     plural = "" if files == 1 else "s"
     unpushed = r.get("unpushed") or 0
     extra = f", {unpushed} unpushed commit(s)" if unpushed else ""
-
-    message = (
-        f"Observatory recorded the facts of this turn in {project}: "
+    text = (
+        f"Observatory recorded the facts of {'this' if at_stop else 'your previous'} turn in {project}: "
         f"{files} file{plural} changed, +{r.get('insertions', 0)}/-{r.get('deletions', 0)}"
-        f"{extra}. Stored as {mid}@{rev}, state proposed, with no `why`.\n\n"
+        f"{extra}. Stored as {mid}@{rev}, state proposed, with no `why`."
+        + (" This record is asked about once." if r.get("ask") is True else "") + "\n\n"
         "The diff already says WHAT changed. Add WHY — one or two sentences a "
         "reader in six months could not reconstruct from the diff: the constraint "
         "that forced the shape, the alternative rejected, the trap avoided.\n\n"
@@ -66,6 +68,7 @@ def main() -> int:
         "If the change genuinely needs no explanation — a typo, a rename — say so "
         "and skip it. An empty `why` on a trivial edit is honest; an invented one "
         "is worse than nothing, because it will be read as true."
+        + ("" if at_stop else " Then answer the user's new message.")
     )
     # THE NUDGE AT THE MOMENT OF WORK. The agent is already inside this project;
     # rebuilding its graph or touching its note costs least right now. Thresholds
@@ -82,9 +85,111 @@ def main() -> int:
                           f"work changed what the project IS (modules, scope, "
                           f"stack), update the overview note too")
     if stale_bits:
-        message += ("\n\nWhile you are here — this project's recorded knowledge "
-                    "is behind its code:\n  - " + "\n  - ".join(stale_bits))
-    print(json.dumps({"systemMessage": message, "suppressOutput": True},
+        text += ("\n\nWhile you are here — this project's recorded knowledge "
+                 "is behind its code:\n  - " + "\n  - ".join(stale_bits))
+    return text
+
+
+def leave_for_next_prompt(session: str, r: dict, text: str) -> bool:
+    """Write the ask where `prompt-why.py` finds it. False when it could not be kept."""
+    if not isinstance(session, str) or not SESSION.fullmatch(session):
+        return False
+    try:
+        d = pending_dir()
+        os.makedirs(d, mode=0o700, exist_ok=True)
+        os.chmod(d, 0o700)
+        now = time.time()
+        for name in os.listdir(d):                  # sessions that never prompted again
+            p = os.path.join(d, name)
+            try:
+                if now - os.stat(p).st_mtime > PRUNE_SECONDS:
+                    os.unlink(p)
+            except OSError:
+                pass
+        path = os.path.join(d, session + ".json")
+        asks = []
+        try:
+            with open(path, encoding="utf-8") as fh:
+                asks = [a for a in (json.load(fh).get("asks") or []) if isinstance(a, dict)]
+        except (OSError, ValueError, AttributeError):
+            asks = []
+        asks = [a for a in asks if a.get("memoryId") != r.get("memoryId")]
+        entry = {"at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now)),
+                 "memoryId": r.get("memoryId"), "revision": r.get("revision"),
+                 "context": text}
+        # Where `prompt-why.py` records the delivery: the engine's journal, named by
+        # the recorder. Only a file of that exact name is ever written there.
+        journal = r.get("journal")
+        if isinstance(journal, str) and os.path.basename(journal) == "why-asks.jsonl":
+            entry["journal"] = journal
+        asks.append(entry)
+        tmp = f"{path}.{os.getpid()}.tmp"
+        # Created owner-only by the umask, not by a raw `os.open`: this script runs
+        # from the plugin's own copy without the engine, so `osprivacy` (the one
+        # module allowed to pass open flags) is out of reach, and the hook is one
+        # single-threaded process, so the umask is its own.
+        mask = os.umask(0o077)
+        try:
+            with open(tmp, "w", encoding="utf-8") as fh:
+                json.dump({"asks": asks[-KEEP:]}, fh, ensure_ascii=False)
+        finally:
+            os.umask(mask)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+        return True
+    except Exception:                                                  # noqa: BLE001
+        return False
+
+
+def main() -> int:
+    try:
+        r = json.load(sys.stdin)
+    except Exception:
+        return 0
+    if not isinstance(r, dict):
+        return 0
+    if not r.get("recorded"):
+        # A FAULT IS NOT A QUIET TURN. This returned 0 for every `recorded:
+        # false`, and the recorder's reasons are two different kinds: "nothing
+        # changed" is an answer about the work, while `IllegalTransition:
+        # observed -> proposed` is the recorder failing. Measured 2026-09-07:
+        # once `tools/corroborate.py` promoted a session's record, every later
+        # turn of that session raised that error and said nothing — roughly
+        # seventy-two turns in one session, and the only visible sign was a
+        # ledger row that had stopped moving.
+        #
+        # The recorder marks which kind it is; this only has to stop hiding it.
+        # A fault stays a Stop notice: it is for the person, and it is urgent.
+        reason = r.get("reason") or ""
+        if not r.get("fault"):
+            return 0                   # nothing changed, not watched, or explained
+        print(json.dumps({"systemMessage":
+                          "Observatory could NOT record this turn: " + reason +
+                          "\n\nThe facts of this turn are not in the ledger. "
+                          "`store/raw/record-turn.json` holds the same reason, and "
+                          "`project-observatory full findings` raises it.",
+                          "suppressOutput": True}))
+        return 0
+    if r.get("hasWhy"):
+        return 0                                          # already explained
+    if r.get("rationale"):
+        return 0          # the turn wrote its rationale; the record links that file
+    if "ask" not in r:
+        # AN OLDER ENGINE, which decides nothing about asking: it would send this
+        # every changed turn, and an every-turn ask injected into the model's context
+        # is worse than the notice it replaces. So it gets the old Stop notice.
+        print(json.dumps({"systemMessage": message(r, at_stop=True), "suppressOutput": True},
+                         ensure_ascii=False))
+        return 0
+    if r.get("ask") is not True:
+        return 0          # this record was asked about already
+
+    text = message(r)
+    if leave_for_next_prompt(r.get("session"), r, text):
+        return 0
+    # THE OLD CHANNEL, as the fallback. A notice the model may not read is better
+    # than an ask that silently never happens.
+    print(json.dumps({"systemMessage": message(r, at_stop=True), "suppressOutput": True},
                      ensure_ascii=False))
     return 0
 

package/payload/plugins/observatory-log/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Optional Claude Code hooks: record changes in watched Git projects and request missing reasoning. SessionStart reports brief actionable context. Missing workspace, interpreter or watched project degrades quietly; hooks do not block a turn. Project names and paths stay in the private workspace.",
+  "description": "Optional Claude Code hooks: record changes in watched Git projects and request missing reasoning. SessionStart reports brief actionable context. Stop records the facts of a turn that changed something since the previous turn first, counting only what differs from the session's baseline (taken at SessionStart; files untracked before the session never count); then, within 2 seconds, it reads the last 4 MB of the session transcript once for this session's writing calls (Edit, Write, MultiEdit, NotebookEdit, and Bash writes through >, >>, tee or sed -i; failed calls, subagent calls and commands over 65,536 characters are skipped). It leaves a request for the why at most once per record, only when the turn changed tracked content, none while a revision's rationale link is still true (same repository, a regular file in the checkout with one hard link and no symbolic link, the exact heading line present once and the file unchanged or with only a new entry appended after it; any other edit asks again), and none when such a call targeted a decisions.md or an adr/ .md, .markdown or .txt file (outside vendored trees) with text carrying the entry's own heading (unique in the register) or, with no heading, most of its added lines, or wrote a decision: or stage: line into .task-pipeline/run.md. UserPromptSubmit hands that pending request to the model with the next prompt, once, within 4,000 characters, records the delivery, and prints nothing when none is pending. Missing workspace, interpreter or watched project degrades quietly; hooks do not block a turn or a prompt. Project names and paths stay in the private workspace.",
   "hooks": {
     "SessionStart": [
       {
@@ -26,6 +26,18 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "py=\"${OBSERVATORY_PYTHON:-}\"; [ -x \"$py\" ] || py=python3; \"$py\" \"${CLAUDE_PLUGIN_ROOT}/hooks/prompt-why.py\" 2>/dev/null; exit 0",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/payload/plugins/observatory-log/hooks/prompt-why.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Hand the model the request for a `why` that the Stop hook left for this session.
+
+A UserPromptSubmit hook, so it runs before EVERY prompt of every session, and the
+whole design is about that cost:
+
+- **Silent unless an ask is pending.** One `stat` of a per-session file and exit 0;
+  the file exists only after `ask-why.py` asked about a record, at most once per
+  record (`why_asks.py` in the engine).
+- **Once.** The file is taken by an atomic rename before it is read, so two prompts
+  cannot both deliver it, and it is deleted after.
+- **Never in the way of the prompt.** Every error — a payload that is not JSON, a
+  session id that is not a plain name, a torn file — is exit 0 with nothing on
+  stdout. It cannot block: it prints no `decision`, and it exits 0 on every path.
+- **Delivery is recorded.** For each ask handed over it appends
+  `{"event": "delivered"}` to the engine's journal (`store/raw/why-asks.jsonl`, the
+  path the recorder named), because the answer rate is measured on delivered asks: a
+  headless session that never sends a second prompt never receives its ask, and must
+  not count as having ignored it.
+- **Where the model reads it.** The ask goes out as
+  `hookSpecificOutput.additionalContext`, which Claude Code renders into the
+  model's input; the Stop `systemMessage` it replaces is a notice for the person
+  (`tests/test_ask_why_reach.py`).
+
+It holds no secret: the pending file carries the ask's text — a project id, a
+record id and a diff's size — and is written 0600 in a 0700 directory.
+Standard library only; it does not need the engine.
+"""
+from __future__ import annotations
+import calendar
+import json
+import os
+import re
+import sys
+import time
+
+SESSION = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+#: An ask older than this is about a turn too far back to explain well; it is dropped.
+STALE_SECONDS = 7 * 86400
+#: The context a prompt can be handed, at most. One ask is about a thousand characters.
+MAX_CHARS = 4000
+
+
+def pending_dir() -> str:
+    """The directory `ask-why.py` writes; the two must agree."""
+    base = os.environ.get("XDG_STATE_HOME") or os.path.join(
+        os.path.expanduser("~"), ".local", "state")
+    return os.path.join(base, "project-observatory", "ask-why")
+
+
+SEPARATOR = "\n\n---\n\n"
+
+
+def _put_back(path: str, asks: list) -> None:
+    """Return undelivered asks to the session's pending file, beside any the Stop hook
+    wrote meanwhile. Owner-only, like the file `ask-why.py` writes."""
+    try:
+        try:
+            with open(path, encoding="utf-8") as fh:
+                current = [a for a in (json.load(fh).get("asks") or []) if isinstance(a, dict)]
+        except (OSError, ValueError, AttributeError):
+            current = []
+        ids = {a.get("memoryId") for a in current}
+        merged = [a for a in asks if a.get("memoryId") not in ids] + current
+        tmp = f"{path}.{os.getpid()}.back"
+        mask = os.umask(0o077)
+        try:
+            with open(tmp, "w", encoding="utf-8") as fh:
+                json.dump({"asks": merged}, fh, ensure_ascii=False)
+        finally:
+            os.umask(mask)
+        os.replace(tmp, path)
+    except Exception:                                                  # noqa: BLE001
+        pass                          # an ask that is not put back stays pending, unasked
+
+
+def _record_delivery(ask: dict, session: str) -> None:
+    """Append a `delivered` row to the journal the recorder named. Never raises."""
+    journal = ask.get("journal")
+    if not isinstance(journal, str) or os.path.basename(journal) != "why-asks.jsonl" \
+            or os.path.islink(journal) or not os.path.isdir(os.path.dirname(journal) or "/nonexistent"):
+        return
+    row = {"at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+           "memoryId": ask.get("memoryId"), "event": "delivered", "session": session}
+    if not isinstance(row["memoryId"], str):
+        return
+    try:
+        with open(journal, "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+    except OSError:
+        pass                    # an undelivered count is a floor, not a failed prompt
+
+
+def _prune(directory: str) -> None:
+    """Remove pending asks older than STALE_SECONDS: sessions that ended without a
+    further prompt. Run only after a delivery, so a quiet prompt stays one `stat`."""
+    try:
+        now = time.time()
+        for name in os.listdir(directory):
+            path = os.path.join(directory, name)
+            try:
+                if now - os.stat(path).st_mtime > STALE_SECONDS:
+                    os.unlink(path)
+            except OSError:
+                pass
+    except OSError:
+        pass
+
+
+def _fresh(stamp) -> bool:
+    try:
+        when = calendar.timegm(time.strptime(str(stamp), "%Y-%m-%dT%H:%M:%SZ"))
+    except (ValueError, OverflowError):
+        return True                                  # an odd stamp still delivers
+    return time.time() - when <= STALE_SECONDS
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return 0
+    session = payload.get("session_id") if isinstance(payload, dict) else None
+    if not isinstance(session, str) or not SESSION.fullmatch(session):
+        return 0
+    path = os.path.join(pending_dir(), session + ".json")
+    if not os.path.isfile(path):
+        return 0                                     # the common case: nothing pending
+    taking = f"{path}.taking-{os.getpid()}"
+    try:
+        os.replace(path, taking)                     # one prompt takes it, not two
+    except OSError:
+        return 0
+    try:
+        with open(taking, encoding="utf-8") as fh:
+            doc = json.load(fh)
+    except Exception:
+        doc = {}
+    finally:
+        try:
+            os.unlink(taking)
+        except OSError:
+            pass
+    _prune(os.path.dirname(path))
+    asks = doc.get("asks") if isinstance(doc, dict) else None
+    chosen = [a for a in (asks or [])
+              if isinstance(a, dict) and isinstance(a.get("context"), str)
+              and a["context"].strip() and _fresh(a.get("at"))]
+    if not chosen:
+        return 0
+    # THE CAP, honestly counted. Only asks that fit inside MAX_CHARS whole are handed
+    # over and marked delivered; the rest go back for the next prompt. The first ask
+    # always goes (cut at the cap if it alone is longer: its record id and the call
+    # to make come first).
+    sent, rest, used = [], [], 0
+    for a in chosen:
+        cost = len(a["context"]) + (len(SEPARATOR) if sent else 0)
+        if sent and used + cost > MAX_CHARS:
+            rest.append(a)
+            continue
+        sent.append(a)
+        used += cost
+    if rest:
+        _put_back(path, rest)
+    context = SEPARATOR.join(a["context"] for a in sent)[:MAX_CHARS]
+    for a in sent:
+        _record_delivery(a, session)
+    print(json.dumps({"hookSpecificOutput": {"hookEventName": "UserPromptSubmit",
+                                             "additionalContext": context}},
+                     ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except SystemExit:
+        raise
+    except Exception:
+        raise SystemExit(0)

package/payload/plugins/observatory-log/hooks/record-turn.sh

@@ -52,29 +52,45 @@ py="${OBSERVATORY_PYTHON:-$root/.venv/bin/python}"   # set by `full agent instal
 [ -x "$py" ] || py="$(command -v python3 2>/dev/null)"
 [ -n "$py" ] || exit 0                         # no interpreter: silent
 
-read_field() {                     # read_field <key>
+# ONE PARSE of the payload, not one interpreter start per field: four starts cost
+# 0.1-0.4 s of every turn's Stop before the recorder ran. A value holding a line
+# break is dropped rather than split across the fields that follow it.
+read_fields() {                    # stop_hook_active, cwd, session_id, transcript_path
   [ -n "$payload" ] || return 0
   printf '%s' "$payload" | "$py" -c '
 import json, sys
 try:
     d = json.load(sys.stdin)
 except Exception:
-    sys.exit(0)
-print(d.get(sys.argv[1]) or "")
-' "$1" 2>/dev/null
+    d = {}
+if not isinstance(d, dict):
+    d = {}
+for k in ("stop_hook_active", "cwd", "session_id", "transcript_path"):
+    v = d.get(k)
+    v = "" if v is None or v is False else str(v)
+    print("" if ("\n" in v or "\r" in v) else v)
+' 2>/dev/null
 }
+fields="$(read_fields)"
+active=""; cwd=""; session=""; transcript=""
+{ IFS= read -r active; IFS= read -r cwd; IFS= read -r session; IFS= read -r transcript; } <<EOF_FIELDS || true
+$fields
+EOF_FIELDS
+
+[ "$active" = "True" ] && exit 0
+[ "$active" = "true" ] && exit 0
+
+[ -n "$cwd" ] || cwd="${CLAUDE_PROJECT_DIR:-$PWD}"
+# `transcript` is the session's own transcript, so a register another session is
+# editing in the same checkout does not silence this session's ask. Passed only to a
+# recorder that reads it: an older engine's argument parser would refuse the flag
+# and record nothing.
+extra=()
+if [ -n "$transcript" ] && [ -f "$transcript" ] && grep -q -- '--transcript' "$root/tools/record_turn.py" 2>/dev/null; then
+  extra=(--transcript "$transcript")
+fi
 
-
-
-
-[ "$(read_field stop_hook_active)" = "True" ] && exit 0
-[ "$(read_field stop_hook_active)" = "true" ] && exit 0
-
-cwd="$(read_field cwd)"; [ -n "$cwd" ] || cwd="${CLAUDE_PROJECT_DIR:-$PWD}"
-session="$(read_field session_id)"
-
-
-result="$("$py" "$root/tools/record_turn.py" --cwd "$cwd" --session-id "$session" 2>/dev/null)"
+result="$("$py" "$root/tools/record_turn.py" --cwd "$cwd" --session-id "$session" ${extra[@]+"${extra[@]}"} 2>/dev/null)"
 [ -n "$result" ] || exit 0
 
 printf '%s' "$result" | "$py" "${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/hooks/ask-why.py" 2>/dev/null