loki-mode 11.3.9 → 11.4.2

package/autonomy/lib/help-core.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# Core help screen and help topics for `loki help`. Source this file; it
+# defines functions only. The full command table stays in show_help_all
+# (autonomy/loki) and is reached with `loki help all`.
+
+# Topics reachable as `loki help <topic>`. Keep in sync with help_topic_text.
+LOKI_HELP_TOPICS="providers exit-codes"
+
+help_core_screen() {
+    local version="$1"
+    echo "Loki Mode v${version}"
+    echo ""
+    echo "Usage: loki <command> [options]"
+    echo ""
+    echo "Start:"
+    echo "  start [SPEC]     PRIMARY: build from a PRD file, brief, or issue (owner/repo#N, PROJ-1) (alias: run)"
+    echo "  chat [--attach]  Interactive alternative; --attach joins the current 'loki start' run"
+    echo "  edit \"<change>\"  Make one targeted change to the current repo"
+    echo "  quick \"<task>\"   One small task, no PR"
+    echo ""
+    echo "Check:"
+    echo "  status [--json]  What is running and where it stands"
+    echo "  verify [--json]  Deterministic verification (CI-gate exit codes)"
+    echo "  receipt          Inspect the proof-of-run receipt (alias of: proof)"
+    echo "  diff / undo      See what a run changed; undo <run> to plan or apply a rollback"
+    echo ""
+    echo "Configure:"
+    echo "  setup            First-run setup (provider, keys, defaults)"
+    echo "  config           Show or change settings (config list --json)"
+    echo "  models           Model tiers and routes (models --local for local models)"
+    echo "  agents           Agent roles and routing (route shows where a task would go)"
+    echo "  doctor [--json]  Check your setup is ready"
+    echo ""
+    echo "Options for 'start': --provider NAME, --model ID, --budget USD, --isolation LVL (isolation dial: none | worktree | docker)"
+    echo "Also: cost / estimate (spend before you build), resume (continue a paused or interrupted run)"
+    echo "Exit codes: docs/exit-codes.md"
+    echo ""
+    echo "Examples:"
+    echo "  loki start ./prd.md                 Build from a spec file"
+    echo "  loki start owner/repo#123           Build from a GitHub issue"
+    echo "  loki start ./prd.md --budget 20     Cap spend at 20 USD"
+    echo "  loki plan ./prd.md                  Dry run: complexity, cost, plan"
+    echo "  loki verify --json                  Machine-readable verification for CI"
+    echo "  loki resume                         Continue a paused or interrupted run"
+    echo "  loki status --json                  What is running, as JSON"
+    echo "  loki cost ./prd.md                  Estimate spend before you build"
+    echo "  loki doctor --fix                   Check setup and repair what it can"
+    echo ""
+    echo "More:"
+    echo "  loki help all            Every command"
+    echo "  loki help <topic>        Topics: ${LOKI_HELP_TOPICS// /, }"
+    echo "  loki <command> --help    Help for one command"
+    echo ""
+    echo "New here? Run: loki doctor, then loki quickstart"
+}
+
+help_topic_text() {
+    case "$1" in
+        start)
+            cat <<'T'
+Starting work
+
+  loki start ./prd.md          Build from a spec file
+  loki start owner/repo#123    Build from a GitHub issue
+  loki "<task>"                Same as quick
+  loki quick "add dark mode"   One small task, no PR
+  loki edit "rename foo to bar" One targeted change
+  loki chat                    Interactive alternative to start (/run inside chat runs loki start)
+  loki chat --attach           Chat about the current or latest start run (/status /steer /diff /stop)
+  loki plan ./prd.md           Dry run: complexity, cost, plan
+
+Common flags: --provider NAME, --model ID (tier or route, e.g. ollama/qwen3-coder), --budget USD, --simple, --complex,
+--no-dashboard, --spec FILE, --config PATH. Full list: loki help all.
+T
+            ;;
+        models)
+            cat <<'T'
+Models
+
+Loki routes work by tier: planning (opus), development (sonnet), fast (haiku).
+  loki models                  Show the model for each tier
+  loki models --local          Show local models (Ollama, LM Studio, llama.cpp)
+  loki config set maxTier sonnet   Cap model cost
+  loki config set model.development <id>   Override one tier
+  LOKI_MODEL_OVERRIDE=<id>     Force one model id (Anthropic-protocol gateways)
+T
+            ;;
+        providers)
+            cat <<'T'
+Providers
+
+Claude Code is the default and the only Tier 1 provider.
+  loki provider list           Providers and install status
+  loki provider set codex      Switch provider (claude, codex, cline, aider, opencode)
+  loki start ./prd.md --provider cline
+
+Tier 2: cline. Tier 3 (sequential, degraded): codex, aider. opencode is model-agnostic.
+T
+            ;;
+        agents)
+            cat <<'T'
+Agents
+
+  loki agents list|new|show    Your own agents (.loki/agents/<name>.md); council reviewers use them
+  loki route "<task>"          Show which engine, provider and model a task would use
+  loki agent --help            Lower-level agent commands
+
+Roles use Opus for planning, Sonnet for development, Haiku for fast work.
+T
+            ;;
+        verify)
+            cat <<'T'
+Verification
+
+  loki verify                  Deterministic PR verification
+  loki verify --fast           Exogenous checks only, milliseconds, no model call
+  loki verify --json           One JSON object: command, exit_code, ok, output
+  loki verify --pubkey FILE    Check a receipt against a public key
+  loki receipt                 Inspect the proof-of-run receipt
+  loki undo <run> [--plan]     Plan or apply an undo of a run
+
+Exit codes: see loki help exit-codes.
+T
+            ;;
+        exit-codes)
+            cat <<'T'
+Exit codes
+
+  0   success
+  1   failure
+  2   usage error (unknown command, bad flag)
+  3   missing component
+
+Severity rises with the code: a bigger number is never better news.
+Per-command contracts (verify, proof, start under LOKI_DURABLE_STATE=1):
+docs/exit-codes.md
+T
+            ;;
+        config)
+            cat <<'T'
+Configuration
+
+  loki config                  Show current configuration
+  loki config list --json      Machine-readable configuration
+  loki config set KEY VALUE    Set a value (maxTier, model.planning, ...)
+  loki config get KEY          Read a value
+  loki config validate [FILE]  Validate loki.yaml
+  loki setup                   First-run setup
+  loki start --config FILE     Load settings from a file
+
+Precedence: CLI flag > env var > --config file > defaults.
+Environment variables: docs/environment-variables.md
+T
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+# Print the topic, or return 1 when $1 is not a topic.
+help_topic() {
+    help_topic_text "$1"
+}

package/autonomy/lib/json-output.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Shared --json helpers. Source this file; it defines functions only.
+#
+#   loki_json_requested ARGS...    exit 0 when --json is among ARGS
+#   loki_json_strip ARGS...        print ARGS (one per line) without --json
+#   loki_json_wrap NAME CMD ARGS.. run CMD, print one JSON object:
+#                                  {"command":NAME,"exit_code":N,"ok":bool,"output":"..."}
+#                                  and return CMD's exit code. Use ONLY for
+#                                  commands with no native --json output.
+
+loki_json_requested() {
+    local a
+    for a in "$@"; do
+        [ "$a" = "--json" ] && return 0
+    done
+    return 1
+}
+
+loki_json_strip() {
+    local a
+    for a in "$@"; do
+        [ "$a" = "--json" ] || printf '%s\n' "$a"
+    done
+}
+
+loki_json_wrap() {
+    local name="$1" out rc
+    shift
+    out="$("$@" 2>&1)"
+    rc=$?
+    LOKI_JW_NAME="$name" LOKI_JW_RC="$rc" LOKI_JW_OUT="$out" python3 -c '
+import json, os, re
+rc = int(os.environ["LOKI_JW_RC"])
+out = re.sub(r"\x1b\[[0-9;]*m", "", os.environ["LOKI_JW_OUT"])
+print(json.dumps({"command": os.environ["LOKI_JW_NAME"], "exit_code": rc, "ok": rc == 0, "output": out}))
+'
+    return "$rc"
+}

package/autonomy/lib/run-summary.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# OC-OUTPUT: unified end-of-run summary for the legacy engine. Same format as
+# loki-ts/src/util/run_summary.ts (Result, Files, Cost, Elapsed, Receipt, next).
+# Sourced by autonomy/run.sh; defines functions only.
+#
+#   loki_run_summary RESULT_CODE [START_SHA]
+# Honors NO_COLOR and LOKI_SUMMARY_JSON=1 (machine summary). LOKI_QUIET=1 is applied by the
+# caller's log threshold (banner noise off); the summary itself always prints.
+
+loki_run_summary() {
+    # Print once per process even if two exit paths both call it.
+    [ "${_LOKI_SUMMARY_PRINTED:-0}" = "1" ] && return 0
+    _LOKI_SUMMARY_PRINTED=1
+    local code="${1:-0}" start_sha="${2:-${_LOKI_RUN_START_SHA:-}}"
+    local loki_dir="${LOKI_DIR:-${TARGET_DIR:-.}/.loki}"
+    local result="done-unverified" files="" ins="" del="" shortstat="" cost="" receipt="" next=""
+    local elapsed=$(( $(date +%s) - ${SESSION_START_EPOCH:-$(date +%s)} ))
+
+    # Result: verified only when a proof exists and the run exited 0.
+    local rid="" proof=""
+    if [ -s "$loki_dir/state/last-proof-id.txt" ]; then rid="$(head -n1 "$loki_dir/state/last-proof-id.txt" 2>/dev/null | tr -d '[:space:]')"; fi
+    case "$rid" in *[!A-Za-z0-9._-]*) rid="" ;; esac
+    [ -n "$rid" ] && [ -f "$loki_dir/proofs/$rid/proof.json" ] && proof="$loki_dir/proofs/$rid/proof.json"
+    case "$code" in
+        0) if [ -n "$proof" ]; then result="verified"; else result="done-unverified"; fi ;;
+        130|143) result="stopped" ;;
+        *) result="failed" ;;
+    esac
+    [ -f "$loki_dir/STOPPED" ] && result="stopped"
+    [ -n "$proof" ] && receipt="$proof"
+
+    # Files changed vs run-start SHA (excluding .loki and .git).
+    if [ -n "$start_sha" ]; then
+        local range="${start_sha}..HEAD"
+        # LOKI_SUMMARY_WORKTREE=1 (loki edit): compare against the working tree, edits are uncommitted.
+        [ "${LOKI_SUMMARY_WORKTREE:-0}" = "1" ] && range="${start_sha}"
+        shortstat="$( (cd "${TARGET_DIR:-.}" && git diff --shortstat "$range" -- . ':(exclude).loki/' ':(exclude).git/') 2>/dev/null || true )"
+        files="$(printf '%s\n' "$shortstat" | grep -oE '[0-9]+ file' | grep -oE '[0-9]+' | head -1)"
+        ins="$(printf '%s\n' "$shortstat" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' | head -1)"
+        del="$(printf '%s\n' "$shortstat" | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' | head -1)"
+        [ -z "$files" ] && files=0
+        [ -z "$ins" ] && ins=0
+        [ -z "$del" ] && del=0
+    fi
+
+    # Cost: legacy cost comes from the context tracker (token estimate), so it is always marked estimated.
+    if [ -f "$loki_dir/context/tracking.json" ]; then
+        cost="$(LOKI_TRK="$loki_dir/context/tracking.json" python3 -E -c "
+import json, os
+try:
+    c = json.load(open(os.environ['LOKI_TRK'])).get('totals', {}).get('total_cost_usd')
+    print('' if c is None else '%.2f' % float(c))
+except Exception:
+    print('')
+" 2>/dev/null || true)"
+    fi
+
+    # LOKI_SUMMARY_COST: exact cost from the caller (loki edit reads it from the provider).
+    local cost_exact=false
+    if [ -n "${LOKI_SUMMARY_COST:-}" ]; then cost="$LOKI_SUMMARY_COST"; cost_exact=true; fi
+
+    case "$result" in
+        verified) if [ "${files:-0}" != "0" ] && [ -n "$files" ]; then next="loki diff"; else next="loki status"; fi ;;
+        done-unverified) next="loki verify" ;;
+        stopped) next="loki status" ;;
+        *) if [ -n "$files" ] && [ "$files" != "0" ]; then next="loki undo"; else next="loki doctor"; fi ;;
+    esac
+
+    local mm=$((elapsed / 60)) ss=$((elapsed % 60)) elapsed_h
+    if [ "$elapsed" -lt 60 ]; then elapsed_h="${elapsed}s"; else elapsed_h="${mm}m$(printf '%02d' "$ss")s"; fi
+
+    if [ "${LOKI_SUMMARY_JSON:-0}" = "1" ]; then
+        printf '{"result":"%s","files_changed":%s,"insertions":%s,"deletions":%s,"cost_usd":%s,"cost_estimated":%s,"elapsed_s":%s,"receipt":%s,"next":"%s"}\n' \
+            "$result" "${files:-null}" "${ins:-null}" "${del:-null}" "${cost:-null}" "$([ "$cost_exact" = true ] && echo false || echo true)" "$elapsed" \
+            "$([ -n "$receipt" ] && printf '"%s"' "$receipt" || printf 'null')" "$next"
+        return 0
+    fi
+
+    local c0="" c1=""
+    if [ -t 1 ] && [ -z "${NO_COLOR+x}" ]; then
+        c1=$'\033[0m'
+        case "$result" in verified) c0=$'\033[32m' ;; done-unverified) c0=$'\033[33m' ;; *) c0=$'\033[31m' ;; esac
+    fi
+    local files_h="unknown" cost_h="not measured"
+    [ -n "$files" ] && files_h="${files} changed (+${ins} -${del})"
+    if [ -n "$cost" ]; then
+        if [ "$cost_exact" = true ]; then cost_h="\$${cost}"; else cost_h="\$${cost} (estimated)"; fi
+    fi
+    printf '\n'
+    printf 'Result:   %s%s%s\n' "$c0" "$result" "$c1"
+    printf 'Files:    %s\n' "$files_h"
+    printf 'Cost:     %s\n' "$cost_h"
+    printf 'Elapsed:  %s\n' "$elapsed_h"
+    [ -n "$receipt" ] && printf 'Receipt:  %s\n' "$receipt"
+    printf 'next:     %s  (or: loki chat --attach)\n' "$next"
+}

package/autonomy/loki

@@ -123,6 +123,12 @@ _loki_caveman_narration_level() {
     fi
 }
 
+# loki edit: one-pass small change fast path (functions-only, self-guarded).
+if [ -f "$_LOKI_SCRIPT_DIR/edit.sh" ]; then
+    # shellcheck source=edit.sh
+    source "$_LOKI_SCRIPT_DIR/edit.sh"
+fi
+
 # Quickstart guided interview (v7.29.0): provides cmd_quickstart and its
 # deterministic offline template matcher. Functions-only file (no top-level
 # command), sourced here so the dispatch case can call cmd_quickstart. Composes
@@ -1722,7 +1728,14 @@ _help_verify_dsse() {
     echo "          66  no signing key, or no runs"
 }
 
+# Default help screen: core verbs only. `loki help all` prints show_help_all.
 show_help() {
+    # shellcheck source=/dev/null
+    source "$_LOKI_SCRIPT_DIR/lib/help-core.sh"
+    help_core_screen "$(get_version)"
+}
+
+show_help_all() {
     local version=$(get_version)
     # Strip color when stdout is not a TTY (piped/redirected) so captured help
     # output is clean, matching the bare-loki welcome path. Local overrides only.
@@ -1735,6 +1748,7 @@ show_help() {
     echo "Usage: loki <command> [options]"
     echo ""
     echo "New here? Try these in order:"
+    echo "  loki setup                One-step wizard: tools, provider login, model route, spend cap (--yes for defaults)"
     echo "  loki welcome              Friendly first-run opener (what Loki is, next steps)"
     echo "  loki doctor               Check your setup is ready (a few seconds)"
     echo "  loki quickstart           Guided first build from your idea (no PRD needed)"
@@ -1815,6 +1829,7 @@ show_help() {
     echo ""
     echo "Options for 'start':"
     echo "  --provider NAME  AI provider: claude (default), codex, cline, aider, opencode"
+    echo "  --model ID       Model tier or route (e.g. ollama/qwen3-coder)"
     echo "  --simple         Force simple complexity tier (3 phases)"
     echo "  --complex        Force complex complexity tier (8 phases)"
     echo "  --no-dashboard   Disable web dashboard"
@@ -1899,6 +1914,7 @@ show_help() {
     # missing from this list, so a new command cannot ship invisible.
     echo ""
     echo "All commands:"
+    echo "  agents chat diff edit models route"
     echo "  acp agent analyze api assets audit backlog bench checkpoint (cp) ci cleanup"
     echo "  cluster cockpit code compliance completions compound config context (ctx)"
     echo "  cost council crash dashboard demo deploy docker docs doctor dogfood"
@@ -1908,7 +1924,7 @@ show_help() {
     echo "  next notify onboard open optimize otel outcomes own (handoff) pause plan preview"
     echo "  projects proof (receipt) provider quick quickstart rc remote report reset"
     echo "  merge resume review rollback run sandbox secrets secure self-update sentrux"
-    echo "  serve setup-skill share ship spec start state stats status steer stop"
+    echo "  serve setup setup-skill share ship spec start state stats status steer stop"
     echo "  syslog telemetry template test tour trigger trust trust-metrics"
     echo "  ultracode undo update verify version voice watch watchdog web welcome why"
     echo "  wiki workspace worktree (wt)"
@@ -2575,7 +2591,8 @@ cmd_start() {
                 echo "                        Token from LOKI_REMOTE_TOKEN / LOKI_REMOTE_TOKEN_FILE"
                 echo "                        (never an argument). Env: LOKI_REMOTE_URL."
                 echo "  --provider NAME       AI provider: claude (default), codex, cline, aider, opencode"
-                echo "  --allow-haiku         Enable Haiku model for the fast tier (default: disabled)"
+                echo "  --model NAME          Model or route override (for example ollama/qwen3-coder)"
+                echo "  --allow-haiku        Enable Haiku model for the fast tier (default: disabled)"
                 echo "  --simple              Force simple complexity tier (3 phases)"
                 echo "  --complex             Force complex complexity tier (8 phases)"
                 echo "  --no-dashboard        Disable web dashboard"
@@ -3184,7 +3201,7 @@ cmd_start() {
                 ;;
             -*)
                 echo -e "${RED}Unknown option: $1${NC}"
-                exit 1
+                exit 64
                 ;;
             *)
                 # Capture first positional arg for unified mode detection.
@@ -12931,6 +12948,16 @@ cmd_config() {
         show)
             cmd_config_show
             ;;
+        list)
+            # HELP slice: `config list [--json]` is `config show` (json: wrapped).
+            # shellcheck source=/dev/null
+            source "$_LOKI_SCRIPT_DIR/lib/json-output.sh"
+            if loki_json_requested "$@"; then
+                loki_json_wrap config-list cmd_config_show
+            else
+                cmd_config_show
+            fi
+            ;;
         init)
             cmd_config_init
             ;;
@@ -12956,9 +12983,10 @@ cmd_config() {
             cmd_config_validate "$@"
             ;;
         *)
-            echo -e "${YELLOW}Usage: loki config [show|init|edit|path|set|get|example|schema|validate]${NC}"
+            echo -e "${YELLOW}Usage: loki config [show|list|init|edit|path|set|get|example|schema|validate]${NC}"
             echo ""
             echo "  show            Show current configuration (default)"
+            echo "  list [--json]   Same as show; --json emits one JSON object"
             echo "  init            Create a config file from template"
             echo "  edit            Open config file in editor"
             echo "  path            Show config file paths"
@@ -15625,6 +15653,7 @@ cmd_quick() {
             echo ""
             echo "Runs the Loki 10 engine on one small task (no PR is opened). Best for"
             echo "tiny tasks."
+            echo "quick = small task with the verify loop. For a single pass with no loop, use loki edit."
             echo ""
             echo "Examples:"
             echo "  loki quick \"add dark mode to this React app\""
@@ -15654,7 +15683,7 @@ cmd_quick() {
         echo "  loki quick \"fix the login bug in auth.js\""
         echo "  loki quick \"add input validation to the signup form\""
         echo "  loki quick \"write unit tests for the API endpoints\""
-        exit 2
+        exit 64
     fi
 
     # v7.29.0: provider pre-flight gate. Offer install on a TTY; print honest
@@ -15690,7 +15719,7 @@ cmd_quick() {
     if [ $# -eq 0 ]; then
         echo -e "${RED}Error: No task description provided${NC}"
         echo "Usage: loki quick [--verbose] \"description of what to do\""
-        exit 2
+        exit 64
     fi
 
     local task_desc="$*"
@@ -17902,6 +17931,8 @@ cmd_verify() {
     fi
     # shellcheck source=/dev/null
     source "$verify_mod"
+    # verify_main handles --json natively (evidence document on stdout, banner
+    # on stderr); the generic json-output.sh wrapper must not intercept it.
     verify_main "$@"
     return $?
 }
@@ -20794,13 +20825,14 @@ _suggest_command() {
 ultracode council demo dogfood heal modernize import issue github init template \
 status stop pause resume monitor watch watchdog dashboard web open preview share \
 memory context ctx checkpoint state report kpis cost metrics stats logs otel \
-syslog telemetry crash config provider doctor setup-skill onboard quickstart \
+syslog telemetry crash config provider doctor setup setup-skill onboard quickstart \
 welcome update self-update rollback merge failover cluster enterprise remote deploy docker \
 sandbox api mcp magic compound assets export wiki control docs explain why audit compliance \
 welcome update self-update rollback failover cluster enterprise remote deploy docker \
 sandbox api mcp acp magic compound assets export wiki control docs explain why audit compliance \
 secrets analyze optimize bench ci reset cleanup notify trigger voice sentrux \
-worktree wt projects cp rc trust-metrics serve agent code self_update test help version"
+worktree wt projects cp rc trust-metrics serve agent code self_update test help version \
+chat route agents models edit receipt setup diff undo"
     local best
     best=$(printf '%s\n' $known | awk -v t="$typo" '
         function min3(a, b, c) { if (a < b) { if (a < c) return a; return c } if (b < c) return b; return c }
@@ -20968,6 +21000,32 @@ main() {
         quick)
             cmd_quick "$@"
             ;;
+        chat)
+            # shellcheck disable=SC1091
+            source "$_LOKI_SCRIPT_DIR/lib/chat.sh"
+            cmd_chat "$@"
+            ;;
+        edit)
+            cmd_edit "$@"
+            ;;
+        diff)
+            # Show what the last run changed: uncommitted changes, else the HEAD commit.
+            # Extra args pass through to git (for example --stat or a path).
+            if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+                echo "Usage: loki diff [git diff args]"
+                echo "Show uncommitted changes; if there are none, show the latest commit."
+                exit 0
+            fi
+            if ! git rev-parse --git-dir >/dev/null 2>&1; then
+                echo "loki diff: not inside a git repository" >&2
+                exit 1
+            fi
+            if git diff --quiet HEAD -- 2>/dev/null; then
+                git show --format='%h %s' "$@" HEAD
+            else
+                git diff "$@" HEAD
+            fi
+            ;;
         monitor)
             cmd_monitor "$@"
             ;;
@@ -20991,6 +21049,11 @@ main() {
         welcome)
             cmd_welcome "$@"
             ;;
+        setup)
+            # shellcheck disable=SC1091
+            . "${SKILL_DIR}/autonomy/setup-wizard.sh"
+            cmd_setup "$@"
+            ;;
         init)
             cmd_init "$@"
             ;;
@@ -21174,6 +21237,9 @@ main() {
         doctor)
             cmd_doctor "$@"
             ;;
+        models)
+            bash "$SKILL_DIR/providers/model_routes.sh" "$@"
+            ;;
         sentrux)
             cmd_sentrux "$@"
             ;;
@@ -21255,6 +21321,9 @@ main() {
         agent)
             cmd_agent "$@"
             ;;
+        agents)
+            cmd_agents "$@"
+            ;;
         template)
             cmd_template "$@"
             ;;
@@ -21401,6 +21470,10 @@ main() {
             # deprecated-alias table; bare help prints the grouped front page.
             if [ "${1:-}" = "aliases" ]; then
                 show_help_aliases
+            elif [ "${1:-}" = "all" ]; then
+                show_help_all
+            elif [ -n "${1:-}" ] && case "${1:-}" in providers|exit-codes) true ;; *) false ;; esac && { source "$_LOKI_SCRIPT_DIR/lib/help-core.sh"; help_topic_text "$1"; }; then
+                :
             elif [ -n "${1:-}" ]; then
                 # `loki help <command>` reaches the command's own help. Before
                 # this, $1 was read only for the literal "aliases" and otherwise
@@ -21470,8 +21543,8 @@ main() {
                 echo "Did you mean 'loki ${_suggestion}'?" >&2
             fi
             # Always point to the full command list, even with no near-miss match.
-            echo "Run 'loki help' to see every command." >&2
-            exit 1
+            echo "Run 'loki help' for the core commands, 'loki help all' for every command." >&2
+            exit 2
             ;;
     esac
 }
@@ -29495,6 +29568,28 @@ PYEOF
     esac
 }
 
+# User-configurable child agents: .loki/agents/<name>.md, ~/.config/loki/agents/<name>.md
+cmd_agents() {
+    local sub="${1:-list}"
+    case "$sub" in
+        help|-h|--help)
+            echo "Usage: loki agents <list|new|show|export> [args]"
+            echo "  list                    List configured agents (project overrides user)"
+            echo "  new <name> [--user]     Scaffold .loki/agents/<name>.md (or ~/.config/loki/agents)"
+            echo "                          Names reviewer, planner, tester copy the shipped examples"
+            echo "  show <name>             Show one agent and its system prompt"
+            echo "  export --claude [--user] Write agents as Claude Code subagents (.claude/agents/)"
+            echo "Council reviewers use a configured agent named reviewer, tester or security."
+            return 0
+            ;;
+    esac
+    local script_dir helper
+    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    helper="${script_dir}/../agents/custom_agents.py"
+    [ -f "$helper" ] || { echo -e "${RED}Error: agents/custom_agents.py not found${NC}"; return 1; }
+    python3 -I "$helper" "$@"
+}
+
 # Agent type dispatch (v6.7.0)
 cmd_agent() {
     local subcommand="${1:-list}"