loki-mode 11.15.0 → 11.17.5

package/autonomy/lib/chat.sh

@@ -3,7 +3,7 @@
 # Sourced by autonomy/loki; defines cmd_chat. Free text goes to the provider
 # in the current mode; slash commands delegate to existing loki commands.
 
-_LOKI_CHAT_SYSTEM_PROMPT="You are running inside Loki Mode chat. Be concise. Prefer small, verifiable changes. Loki commands available to the user: loki start (also --workspace and --deploy), loki quick, loki verify, loki receipt, loki undo."
+_LOKI_CHAT_SYSTEM_PROMPT="You are running inside Loki Mode chat. Be concise. Prefer small, verifiable changes. Loki commands available to the user: loki start (also --workspace and --deploy), loki quick, loki verify, loki receipt, loki undo. During a run, /steer sends a mid-run directive via loki steer (applied at the next plan or implement stage); /pause and /resume control the run, and /answer replies to a blocked run."
 
 _chat_loki_bin() {
     local d="${_LOKI_SCRIPT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
@@ -41,7 +41,14 @@ _chat_help() {
 Loki chat commands:
   /plan              read-only mode (no edits)
   /build             edit mode
-  /run <prd|brief>   loki start with this session's model and provider (same run as the shell)
+  /run <prd|brief>   loki start with this session's model and provider, in the background (alias /start)
+  /start <prd|brief> alias of /run
+  /status            loki status
+  /steer <msg>       send a mid-run directive via loki steer (shows the "Steer rev N received" ack)
+  /stop              loki stop
+  /pause             loki pause (the run halts at the next iteration boundary)
+  /resume            loki resume
+  /answer <text>     loki answer --text: answer a BLOCKED run with a follow-up run
   /workspace <name> <brief>  loki start --workspace (multi-repo run, composite receipt)
   /deploy [--health-url U] [--auto-rollback]  loki deploy --execute after you confirm (gated on a VERIFIED receipt)
   /attach            attach to the current or most recent loki start run in this repo
@@ -64,6 +71,103 @@ HLP
 }
 
 
+# /steer: record source=chat and the chat user as actor (D02). Echo loki steer's own
+# "Steer rev N received" ack; never claim receipt it did not print.
+_chat_steer() {
+    local loki="$1" msg="$2" out rc=0 first
+    case "$msg" in
+        ""|help|h) echo "usage: /steer <message> (not help)"; return 0 ;;
+    esac
+    out="$(LOKI_STEER_SOURCE=chat LOKI_STEER_ACTOR="${LOKI_STEER_ACTOR:-${USER:-chat}}" "$loki" steer -- "$msg" 2>&1)" || rc=$?
+    [ -z "$out" ] || printf '%s\n' "$out"
+    if [ "$rc" -ne 0 ]; then echo "(exit $rc)"
+    elif ! printf '%s\n' "$out" | grep -q 'Steer rev [0-9][0-9]* received'; then
+        first="$(printf '%s\n' "$out" | tr -d '\000-\010\013-\037\177' | sed -n '/[^[:space:]]/{p;q;}' | cut -c1-120)"
+        echo "Steer not confirmed: ${first:-no confirmation from loki steer}"
+    fi
+    return 0
+}
+
+# Monotonic milliseconds and a ms sleep; both are functions so tests can inject a fake clock.
+# The clock source is chosen once per launch (_CHAT_CLOCK) so every read shares one base:
+# perl clock_gettime, else whole seconds from $SECONDS.
+_chat_clock_pick() {
+    if perl -MTime::HiRes=clock_gettime,CLOCK_MONOTONIC -e 'exit 0' >/dev/null 2>&1; then _CHAT_CLOCK=perl; else _CHAT_CLOCK=seconds; fi
+}
+_chat_now_ms() {
+    [ -n "${_CHAT_CLOCK:-}" ] || _chat_clock_pick
+    if [ "$_CHAT_CLOCK" = perl ]; then
+        perl -MTime::HiRes=clock_gettime,CLOCK_MONOTONIC -e 'printf "%d\n", clock_gettime(CLOCK_MONOTONIC) * 1000'
+    else
+        echo $(( SECONDS * 1000 ))
+    fi
+}
+_chat_sleep_ms() {
+    local ms="$1"
+    [ "$ms" -gt 0 ] 2>/dev/null || return 0
+    sleep "$(( ms / 1000 )).$(printf '%03d' $(( ms % 1000 )))"
+}
+
+# /run launch: background `loki start`, then print "Run started" only after the same
+# signals `loki status` reads show a live new run (a new engine10 run dir or a live pid file
+# that was not live before). A start that exits first reports its real error and the log path.
+# Returns non-zero when the start is not proven.
+_chat_run_launch() {
+    local loki="$1" input="$2" root="${LOKI_DIR:-.loki}" log pid rc=0 start_ms deadline_ms now_ms rem_ms iter=0 clock_failed=0 max_iter before_dir before_state
+    log="$root/chat-run.log"
+    mkdir -p "$root"
+    _chat_clock_pick
+    start_ms="$(_chat_now_ms)" || start_ms=""
+    case "$start_ms" in
+        ''|*[!0-9]*)
+            echo "Run not started (clock read failed before launch). Retry /run." >&2
+            return 1
+            ;;
+    esac
+    before_dir="$(_chat_run_dir)"; before_state="$(_chat_run_state "$before_dir")"
+    _chat_run_start "$loki" "$input" < /dev/null > "$log" 2>&1 &
+    pid=$!
+    local wait_s="${LOKI_CHAT_START_WAIT:-15}"
+    case "$wait_s" in ''|*[!0-9]*) wait_s=15 ;; esac
+    [ "$wait_s" -ge 1 ] || wait_s=1
+    deadline_ms=$(( start_ms + wait_s * 1000 ))
+    # Whole-second clock floors, so allow 1s of slack rather than give up early.
+    [ "$_CHAT_CLOCK" = perl ] || deadline_ms=$(( deadline_ms + 1000 ))
+    max_iter=$(( wait_s * 5 + 10 ))
+    while :; do
+        iter=$(( iter + 1 ))
+        local nd ns
+        nd="$(_chat_run_dir)"; ns="$(_chat_run_state "$nd")"
+        if [ "$ns" = "running" ] && { { [ "$nd" != "$before_dir" ] && _chat_pidfile_live "$nd/run.pid"; } || { [ "$nd" = "$before_dir" ] && [ "$before_state" != "running" ]; }; }; then
+            echo "Run started in the background (pid $pid). Output: $log"
+            return 0
+        fi
+        if ! kill -0 "$pid" 2>/dev/null; then
+            wait "$pid" 2>/dev/null || true
+            rc="$(sed -n 's/.*(run finished, exit \([0-9][0-9]*\).*/\1/p' "$log" 2>/dev/null | tail -n1)"
+            case "$rc" in ''|0) rc=1 ;; esac
+            echo "Run did not start (loki start exited $rc before a live run appeared). Log: $log" >&2
+            tail -n 5 "$log" 2>/dev/null | cut -c1-200 >&2
+            return "$rc"
+        fi
+        # A failed or non-numeric clock read (perl fork EAGAIN) counts as the deadline: never mix clock bases.
+        # No $SECONDS fallback here: switching sources mid-launch would mix bases with start_ms.
+        now_ms="$(_chat_now_ms)" || { clock_failed=1; break; }
+        case "$now_ms" in ''|*[!0-9]*) clock_failed=1; break ;; esac
+        rem_ms=$(( deadline_ms - now_ms ))
+        [ "$rem_ms" -gt 0 ] || break
+        [ "$iter" -lt "$max_iter" ] || break
+        [ "$rem_ms" -le 200 ] || rem_ms=200
+        _chat_sleep_ms "$rem_ms"
+    done
+    if [ "$clock_failed" = 1 ]; then
+        echo "Run start unproven (clock read failed while waiting; launcher pid $pid still running). Log: $log" >&2
+        return 1
+    fi
+    echo "Run start not confirmed after ${wait_s}s (no live run state; launcher pid $pid still running). Log: $log" >&2
+    return 1
+}
+
 # Run a delegate without letting a non-zero exit end the session (autonomy/loki runs under set -e).
 _chat_do() { local _rc=0; "$@" || _rc=$?; [ "$_rc" -eq 0 ] || echo "(exit $_rc)"; return 0; }
 
@@ -318,7 +422,7 @@ Question: $line" || true
                 /status) _chat_do "$loki" status; continue ;;
                 /steer)
                     [ -n "$rest" ] || { echo "usage: /steer <message>"; continue; }
-                    _chat_do "$loki" steer "$rest"; continue ;;
+                    _chat_steer "$loki" "$rest"; continue ;;
                 /stop) _chat_do "$loki" stop; continue ;;
                 /detach) attached=0; echo "Detached."; continue ;;
             esac
@@ -328,10 +432,10 @@ Question: $line" || true
             /help) _chat_help ;;
             /plan) mode="plan"; echo "Plan mode: read-only." ;;
             /build) mode="build"; echo "Build mode: edits allowed." ;;
-            /run)
+            /run|/start)
                 [ -n "$rest" ] || { echo "usage: /run <prd|brief>"; continue; }
-                _chat_run_start "$loki" "$rest"
-                _chat_attach_banner || true ;;
+                local _lrc=0; _chat_run_launch "$loki" "$rest" || _lrc=$?
+                if [ "$_lrc" -eq 0 ]; then _chat_attach_banner || true; else echo "(exit $_lrc)"; fi ;;
             /workspace)
                 local _ws_name="${rest%% *}" _ws_brief=""
                 [ "$_ws_name" != "$rest" ] && _ws_brief="${rest#* }"
@@ -344,8 +448,13 @@ Question: $line" || true
             /status) _chat_do "$loki" status ;;
             /steer)
                 [ -n "$rest" ] || { echo "usage: /steer <message>"; continue; }
-                _chat_do "$loki" steer "$rest" ;;
+                _chat_steer "$loki" "$rest" ;;
             /stop) _chat_do "$loki" stop ;;
+            /pause) _chat_do "$loki" pause ;;
+            /resume) _chat_do "$loki" resume ;;
+            /answer)
+                [ -n "$rest" ] || { echo "usage: /answer <text>"; continue; }
+                _chat_do "$loki" answer --text "$rest" ;;
             /detach) echo "Not attached." ;;
             /quick)
                 [ -n "$rest" ] || { echo "usage: /quick <task>"; continue; }

package/autonomy/lib/claude-flags.sh

@@ -212,6 +212,93 @@ _loki_apikey_helper_configured() {
     return 1
 }
 
+# ---------- S2: lean child-session flags + cost ledger ----------
+# loki_lean_child_flags <role> prints the lean flag set for a NON-MAIN child
+# `claude -p` session, ONE ARGUMENT PER LINE (never an empty line).
+# Callers read it with a line loop.
+#   - API-key/apiKeyHelper host: "--bare" (gated by loki_subcall_bare_enabled,
+#     which keeps OAuth-only hosts off --bare; it would fail auth there).
+#   - Otherwise: --setting-sources project, --strict-mcp-config, an empty
+#     --mcp-config, --disable-slash-commands.
+#   - Text-only roles additionally get the single argument "--tools=" (no tools). --tools is
+#     variadic: "--tools" plus an empty argument swallows a trailing prompt.
+# Every flag is probed with loki_claude_flag_supported; an unsupported flag and
+# its value are dropped. LOKI_LEAN_CHILDREN=0 prints nothing. Main-session
+# flags are not touched by this helper.
+loki_lean_child_flags() {
+    local role="${1:-}"
+    [ "${LOKI_LEAN_CHILDREN:-1}" = "0" ] && return 0
+    if loki_subcall_bare_enabled; then
+        printf '%s\n' "--bare"
+    else
+        if loki_claude_flag_supported "--setting-sources"; then
+            printf '%s\n' "--setting-sources" "project"
+        fi
+        if loki_claude_flag_supported "--strict-mcp-config"; then
+            printf '%s\n' "--strict-mcp-config"
+        fi
+        if loki_claude_flag_supported "--mcp-config"; then
+            printf '%s\n' "--mcp-config" '{"mcpServers":{}}'
+        fi
+        if loki_claude_flag_supported "--disable-slash-commands"; then
+            printf '%s\n' "--disable-slash-commands"
+        fi
+    fi
+    case "$role" in
+        grill|council|vote|review|reviewer|enrich|wiki|docs|docgen|summary)
+            if loki_claude_flag_supported "--tools"; then
+                printf '%s\n' "--tools="
+            fi
+            ;;
+    esac
+    return 0
+}
+
+# loki_child_ledger_append <phase> <claude --output-format json> appends one
+# line to .loki/metrics/child-sessions.jsonl in the format read by
+# autonomy/lib/efficiency_cost.py read_child_ledger: phase, model,
+# input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, usd,
+# source. A missing usd is omitted, never written as 0. Returns 1 (writes
+# nothing) when the json is not a parseable result object.
+loki_child_ledger_append() {
+    local phase="${1:-}" payload="${2:-}"
+    [ -n "$phase" ] && [ -n "$payload" ] || return 1
+    local dir="${LOKI_DIR:-.loki}/metrics" line
+    line=$(printf '%s' "$payload" | python3 -I -c '
+import json, sys
+phase = sys.argv[1]
+try:
+    d = json.loads(sys.stdin.read())
+except Exception:
+    sys.exit(1)
+if isinstance(d, list):
+    d = next((x for x in reversed(d) if isinstance(x, dict) and x.get("type") == "result"), None)
+if not isinstance(d, dict):
+    sys.exit(1)
+u = d.get("usage") if isinstance(d.get("usage"), dict) else {}
+def n(v):
+    return v if isinstance(v, int) and not isinstance(v, bool) else 0
+mu = d.get("modelUsage")
+model = next(iter(mu), "") if isinstance(mu, dict) and mu else (d.get("model") or "")
+rec = {
+    "phase": phase,
+    "model": model if isinstance(model, str) else "",
+    "input_tokens": n(u.get("input_tokens")),
+    "output_tokens": n(u.get("output_tokens")),
+    "cache_creation_tokens": n(u.get("cache_creation_input_tokens")),
+    "cache_read_tokens": n(u.get("cache_read_input_tokens")),
+}
+usd = d.get("total_cost_usd", d.get("cost_usd"))
+if isinstance(usd, (int, float)) and not isinstance(usd, bool):
+    rec["usd"] = usd
+rec["source"] = "claude-json"
+print(json.dumps(rec, separators=(",", ":")))
+' "$phase" 2>/dev/null) || return 1
+    [ -n "$line" ] || return 1
+    mkdir -p "$dir" 2>/dev/null || return 1
+    printf '%s\n' "$line" >> "$dir/child-sessions.jsonl" || return 1
+}
+
 # EMBED 3 -- --disallowedTools (reviewer / adversarial subcalls). Motivation: a
 # parallel agent once ran `git reset --hard` and wiped uncommitted work, so a
 # reviewer/voter subcall should not casually mutate the tree. Per `claude --help`
@@ -972,3 +1059,73 @@ loki_export_subagent_capacity() {
 # subprocess tree inherits it, so every subcall site gets the same capacity
 # without each one having to remember to call this.
 loki_export_subagent_capacity
+
+# P12-26 / C-C2: the compiled permission policy swaps --dangerously-skip-permissions for
+# --permission-mode / --allowedTools / --disallowedTools compiled from the task policy by
+# src/policies/claude_permissions.js (shared with the TS permissionArgv). Resolution:
+#   LOKI_PERMISSION_POLICY=legacy    -> legacy (old flag, byte-identical)
+#   LOKI_PERMISSION_POLICY=compiled  -> compiled (fail-closed acceptEdits with no policy)
+#   unset                            -> compiled only when an operator claude_permissions
+#                                       policy exists, else legacy (headless acceptEdits
+#                                       with no allowedTools denies npm test / git commit)
+#   any other value                  -> compiled, with a one-time warning per process
+# Result lands in _LOKI_PERM_ARGV. A compile failure fails closed to plan.
+_LOKI_PERM_UNKNOWN_WARNED=0
+_loki_permission_policy_mode() {
+    case "${LOKI_PERMISSION_POLICY:-}" in
+        legacy) echo legacy ;;
+        compiled) echo compiled ;;
+        "")
+            local _helper
+            _helper="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/src/policies/claude_permissions.js"
+            if command -v node >/dev/null 2>&1 && [ -f "$_helper" ] \
+                && [ "$(node "$_helper" --has-operator-policy 2>/dev/null)" = "1" ]; then
+                echo compiled
+            else
+                echo legacy
+            fi
+            ;;
+        *) echo compiled ;;
+    esac
+}
+
+# Unknown-value warning, once per process. Runs in the caller shell (never inside $(...)),
+# so the guard variable persists.
+_loki_permission_warn_unknown_once() {
+    case "${LOKI_PERMISSION_POLICY:-}" in
+        ""|legacy|compiled) return 0 ;;
+    esac
+    [ "${_LOKI_PERM_UNKNOWN_WARNED:-0}" = "1" ] && return 0
+    _LOKI_PERM_UNKNOWN_WARNED=1
+    echo "[loki] WARNING: LOKI_PERMISSION_POLICY=${LOKI_PERMISSION_POLICY}: unknown value; using compiled" >&2
+}
+
+# The one start-banner line naming the active mode.
+loki_permission_policy_banner() {
+    if [ "$(_loki_permission_policy_mode 2>/dev/null)" = "legacy" ]; then
+        if [ -z "${LOKI_PERMISSION_POLICY:-}" ]; then
+            echo "Permission policy: legacy (no operator policy found; add one to use compiled)"
+        else
+            echo "Permission policy: legacy (unset LOKI_PERMISSION_POLICY to use compiled)"
+        fi
+    else
+        echo "Permission policy: compiled (set LOKI_PERMISSION_POLICY=legacy to revert)"
+    fi
+}
+
+_loki_claude_permission_argv() {
+    _LOKI_PERM_ARGV=(--dangerously-skip-permissions)
+    _loki_permission_warn_unknown_once
+    [ "$(_loki_permission_policy_mode)" = "legacy" ] && return 0
+    local _helper _out _a
+    _helper="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/src/policies/claude_permissions.js"
+    _LOKI_PERM_ARGV=(--permission-mode plan)
+    if ! command -v node >/dev/null 2>&1 || [ ! -f "$_helper" ]; then
+        echo "[loki] WARNING: compiled permission policy: compiler unavailable; using most restrictive mode (plan)" >&2
+        return 0
+    fi
+    _out="$(node "$_helper" "${LOKI_PROJECT_DIR:-$PWD}")" || return 0
+    [ -n "$_out" ] || return 0
+    _LOKI_PERM_ARGV=()
+    while IFS= read -r _a; do _LOKI_PERM_ARGV+=("$_a"); done <<< "$_out"
+}

package/autonomy/lib/claude_permissions.py

@@ -0,0 +1,60 @@
+"""P12-26b: Python entry to the shared Claude permission policy.
+
+New file: the python launch sites (dashboard, magic) need the same argv as the
+bash and TS routes; this is a thin caller of src/policies/claude_permissions.js
+(the single compiler), not a second implementation. LOKI_PERMISSION_POLICY=legacy returns
+the legacy flag byte-identically; unset resolves to compiled only when an operator
+claude_permissions policy exists (asked of the same js helper), else legacy (C-C2).
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+_LEGACY = ["--dangerously-skip-permissions"]
+_FAIL_CLOSED = ["--permission-mode", "plan"]
+_unknown_warned = False
+
+
+def _has_operator_policy(node: str | None, helper: Path, env: dict) -> bool:
+    if node is None or not helper.is_file():
+        return False
+    try:
+        done = subprocess.run([node, str(helper), "--has-operator-policy"], capture_output=True,
+                              text=True, timeout=30, env=dict(env), check=False)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return done.stdout.strip() == "1"
+
+
+def claude_permission_argv(project_dir: str | None = None, env: dict | None = None) -> list:
+    env = os.environ if env is None else env
+    mode = env.get("LOKI_PERMISSION_POLICY", "")
+    if mode == "legacy":
+        return list(_LEGACY)
+    global _unknown_warned
+    helper = Path(__file__).resolve().parents[2] / "src" / "policies" / "claude_permissions.js"
+    node = shutil.which("node")
+    if mode == "" and not _has_operator_policy(node, helper, env):
+        return list(_LEGACY)
+    if mode not in ("", "compiled") and not _unknown_warned:
+        _unknown_warned = True
+        print(f"[loki] WARNING: LOKI_PERMISSION_POLICY={mode}: unknown value; using compiled", file=sys.stderr)
+    if node is None or not helper.is_file():
+        print("[loki] WARNING: compiled permission policy: compiler unavailable; using most restrictive mode (plan)", file=sys.stderr)
+        return list(_FAIL_CLOSED)
+    target = project_dir or env.get("LOKI_PROJECT_DIR") or os.getcwd()
+    try:
+        done = subprocess.run([node, str(helper), str(target)], capture_output=True, text=True,
+                              timeout=30, env=dict(env), check=False)
+    except (OSError, subprocess.SubprocessError):
+        return list(_FAIL_CLOSED)
+    if done.stderr:
+        sys.stderr.write(done.stderr)
+    args = [a for a in done.stdout.split("\n") if a]
+    if done.returncode != 0 or not args:
+        return list(_FAIL_CLOSED)
+    return args

package/autonomy/lib/decision_record.py

@@ -168,22 +168,111 @@ def summarize(loki_dir):
     }
 
 
+# DESIGN RECORDS. A second record type next to the dispatch record: why a design
+# approach was chosen, not which model ran. Kept in its own file so
+# summarize() and verdict.py, which read decisions.jsonl as dispatch records,
+# never see a record without model_id. Same rules: fixed allowlist, append-only.
+DESIGN_FIELDS = (
+    "schema_version",
+    "recorded_at",
+    "rationale",      # required: why this approach
+    "alternatives",   # list of approaches considered and not chosen
+    "source",         # what made the call, e.g. plan
+    "scope",          # what the decision covers
+    "decided_at",
+)
+
+
+def _design_path(loki_dir):
+    return os.path.join(loki_dir, "decisions", "design.jsonl")
+
+
+def record_design(loki_dir, fields):
+    """Append one design decision record, or return a named refusal."""
+    clean = {}
+    dropped = []
+    for k, v in (fields or {}).items():
+        if k in DESIGN_FIELDS:
+            clean[k] = v
+        else:
+            dropped.append(k)
+
+    rationale = clean.get("rationale")
+    if not isinstance(rationale, str) or not rationale.strip():
+        return {"status": "UNKNOWN", "reason": "no_rationale",
+                "detail": "a design record without a rationale records nothing about why"}
+    alts = clean.get("alternatives", [])
+    if isinstance(alts, str):
+        alts = [a.strip() for a in alts.split("|") if a.strip()]
+    if not isinstance(alts, list) or not all(isinstance(a, str) for a in alts):
+        return {"status": "UNKNOWN", "reason": "bad_alternatives",
+                "detail": "alternatives must be a list of strings"}
+    for k in ("source", "scope", "decided_at"):
+        if k in clean and not isinstance(clean[k], str):
+            return {"status": "UNKNOWN", "reason": "bad_" + k,
+                    "detail": k + " must be a string"}
+
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    clean["rationale"] = rationale.strip()
+    clean["alternatives"] = alts
+    clean.setdefault("decided_at", now)
+    clean["schema_version"] = SCHEMA_VERSION
+    clean["recorded_at"] = now
+
+    path = _design_path(loki_dir)
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(clean, sort_keys=True) + "\n")
+    except OSError as exc:
+        return {"status": "UNKNOWN", "reason": "unwritable", "detail": str(exc)}
+
+    out = {"status": "recorded", "path": path, "record": clean}
+    if dropped:
+        out["dropped_fields"] = sorted(dropped)
+    return out
+
+
+def read_design(loki_dir):
+    """Return the parseable design records, oldest first."""
+    path = _design_path(loki_dir)
+    recs = []
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            for line in fh:
+                try:
+                    recs.append(json.loads(line))
+                except ValueError:
+                    continue
+    except OSError:
+        pass
+    return recs
+
+
 def main(argv):
     if not argv:
-        print("usage: decision_record.py record|summary [--field=value ...]",
+        print("usage: decision_record.py record|design|design-file|summary [--field=value ...]",
               file=sys.stderr)
         return 2
     action = argv[0]
     cwd = os.environ.get("LOKI_DECISION_CWD") or os.getcwd()
     loki_dir = os.environ.get("LOKI_DIR") or os.path.join(cwd, ".loki")
 
-    if action == "record":
+    if action in ("record", "design"):
         fields = {}
         for arg in argv[1:]:
             if arg.startswith("--") and "=" in arg:
                 k, v = arg[2:].split("=", 1)
                 fields[k] = v
-        res = record(loki_dir, fields)
+        res = (record_design if action == "design" else record)(loki_dir, fields)
+    elif action == "design-file" and len(argv) == 2:
+        try:
+            with open(argv[1], "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+        except (OSError, ValueError):
+            data = None
+        res = record_design(loki_dir, data) if isinstance(data, dict) else {
+            "status": "UNKNOWN", "reason": "unreadable_file"}
     elif action == "summary":
         res = summarize(loki_dir)
     else:

package/autonomy/lib/done-recognition.sh

@@ -157,13 +157,15 @@ _loki_done_recog_invoke() {
         local _dr_schema_content _dr_json _dr_obj
         _dr_schema_content="$(cat "$_dr_schema" 2>/dev/null)" || _dr_schema_content=""
         if [ -n "$_dr_schema_content" ]; then
+            _LOKI_PERM_ARGV=(--dangerously-skip-permissions)
+            ! type _loki_claude_permission_argv >/dev/null 2>&1 || _loki_claude_permission_argv
             if command -v timeout >/dev/null 2>&1; then
                 _dr_json=$(CAVEMAN_DEFAULT_MODE=off timeout "${LOKI_DONE_RECOG_TIMEOUT}" \
-                    claude --dangerously-skip-permissions -p "$prompt" \
+                    claude "${_LOKI_PERM_ARGV[@]}" -p "$prompt" \
                     --json-schema "$_dr_schema_content" --output-format json 2>/dev/null) || _dr_json=""
             else
                 _dr_json=$(CAVEMAN_DEFAULT_MODE=off \
-                    claude --dangerously-skip-permissions -p "$prompt" \
+                    claude "${_LOKI_PERM_ARGV[@]}" -p "$prompt" \
                     --json-schema "$_dr_schema_content" --output-format json 2>/dev/null) || _dr_json=""
             fi
             local _dr_py
@@ -192,12 +194,14 @@ except Exception:
 
     local rc=0
     local out=""
+    _LOKI_PERM_ARGV=(--dangerously-skip-permissions)
+    ! type _loki_claude_permission_argv >/dev/null 2>&1 || _loki_claude_permission_argv
     if command -v timeout >/dev/null 2>&1; then
         out=$(CAVEMAN_DEFAULT_MODE=off timeout "${LOKI_DONE_RECOG_TIMEOUT}" \
-                  claude --dangerously-skip-permissions -p "$prompt" 2>/dev/null) || rc=$?
+                  claude "${_LOKI_PERM_ARGV[@]}" -p "$prompt" 2>/dev/null) || rc=$?
     else
         out=$(CAVEMAN_DEFAULT_MODE=off \
-                  claude --dangerously-skip-permissions -p "$prompt" 2>/dev/null) || rc=$?
+                  claude "${_LOKI_PERM_ARGV[@]}" -p "$prompt" 2>/dev/null) || rc=$?
     fi
     [ "$rc" -ne 0 ] && return 1
     [ -z "$out" ] && return 1

package/autonomy/lib/efficiency_cost.py

@@ -29,6 +29,7 @@ import os
 __all__ = [
     "collect_efficiency",
     "record_is_measured",
+    "read_child_ledger",
     "load_prices",
     "price_from_tokens",
     "DEFAULT_PRICES_PATH",
@@ -223,9 +224,110 @@ def collect_efficiency(loki_dir):
             "cache_read_tokens", "cache_creation_tokens",
         ):
             cost[key] = None
+    _merge_child_ledger(loki_dir, cost)
     return cost, model
 
 
+# ---------------------------------------------------------------------------
+# child-session ledger (S1 of the cost program)
+# ---------------------------------------------------------------------------
+
+LEDGER_RELPATH = os.path.join("metrics", "child-sessions.jsonl")
+_LEDGER_TOKEN_KEYS = (
+    "input_tokens", "output_tokens", "cache_read_tokens", "cache_creation_tokens",
+)
+
+
+def read_child_ledger(loki_dir):
+    """Read .loki/metrics/child-sessions.jsonl, one JSON object per child session.
+
+    Record format: phase, model, input_tokens, output_tokens,
+    cache_creation_tokens, cache_read_tokens, usd, source.
+
+    Returns (records, invalid_lines) or (None, 0) when the file is absent or
+    unreadable. None is the honest "no ledger" signal: callers must not treat
+    it as zero child spend. Blank lines are ignored; non-JSON lines and
+    non-object lines are skipped and counted.
+    """
+    path = os.path.join(loki_dir, LEDGER_RELPATH)
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except Exception:
+        return None, 0
+    records, invalid = [], 0
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except Exception:
+            invalid += 1
+            continue
+        if isinstance(rec, dict):
+            records.append(rec)
+        else:
+            invalid += 1
+    return records, invalid
+
+
+def _merge_child_ledger(loki_dir, cost):
+    """Fold the child-session ledger into the cost dict, in place.
+
+    The main RARV session's efficiency record is only one of 11-20 child
+    `claude -p` sessions per run (grill, reviewers, council, docgen); summing
+    it alone undercounts true spend. Always sets cost["ledger"] to "present" or
+    "absent" so a missing ledger is visible, never a silent zero. A ledger line
+    without a usd value is unpriced (counted, never treated as 0.0), and the
+    total then becomes a lower bound via cost_partial.
+    """
+    records, invalid = read_child_ledger(loki_dir)
+    main_usd = cost.get("usd")
+    by_phase = {}
+    if main_usd is not None:
+        by_phase["implement"] = main_usd
+    if records is None:
+        cost["ledger"] = "absent"
+        if by_phase:
+            cost["cost_by_phase"] = by_phase
+        return
+    cost["ledger"] = "present"
+    cost["ledger_records"] = len(records)
+    cost["ledger_invalid_lines"] = invalid
+    if not records:
+        if by_phase:
+            cost["cost_by_phase"] = by_phase
+        return
+    ledger_usd, priced, unpriced = 0.0, 0, 0
+    main_known = bool(cost.get("available"))
+    tokens = {k: cost.get(k) for k in _LEDGER_TOKEN_KEYS}
+    if not main_known:
+        tokens = {k: 0 for k in _LEDGER_TOKEN_KEYS}
+    for rec in records:
+        usd = rec.get("usd")
+        if isinstance(usd, (int, float)) and not isinstance(usd, bool):
+            ledger_usd += float(usd)
+            priced += 1
+            phase = str(rec.get("phase") or "unknown")
+            by_phase[phase] = by_phase.get(phase, 0.0) + float(usd)
+        else:
+            unpriced += 1
+        for k in _LEDGER_TOKEN_KEYS:
+            if tokens[k] is not None:
+                tokens[k] += _to_int(rec.get(k))
+    cost.update(tokens)
+    cost["available"] = True
+    if priced:
+        cost["usd"] = round((main_usd or 0.0) + ledger_usd, 4)
+        cost["cost_available"] = True
+    partial = bool(cost.get("cost_partial")) or unpriced > 0 or not main_known
+    cost["cost_partial"] = partial
+    cost["cost_unpriced_records"] = int(cost.get("cost_unpriced_records") or 0) + unpriced
+    if by_phase:
+        cost["cost_by_phase"] = {k: round(v, 4) for k, v in by_phase.items()}
+
+
 # ---------------------------------------------------------------------------
 # uniform token -> USD pricing (R2 benchmark; not used by the proof generator)
 # ---------------------------------------------------------------------------