Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
58.6 KB
Raw Blame
# ai-memory hook helper — find marker file + parse minimal TOML.
# Sourced by per-agent lifecycle hook scripts. POSIX shell only —
# no bash-isms, no non-standard deps (no jq, no toml crate). Keep changes
# byte-trivial because every supported agent (claude-code, codex,
# cursor, gemini-cli, kimi-code, kiro-cli, antigravity-cli, opencode,
# omp, pool) sources this same file.

# Set `_amhome` to $HOME without trailing slashes ("/" stays "/"), so the
# string patterns below treat `HOME=/home/u/` as the native walk does.
ai_memory_home() {
    _amhome="${HOME:-}"
    while [ "${_amhome%/}" != "$_amhome" ] && [ -n "${_amhome%/}" ]; do
        _amhome="${_amhome%/}"
    done
}

# Walk up from "$1" toward $HOME (or /) looking for `.ai-memory.toml`.
# Prints the absolute path of the first marker found, or nothing.
# Stops at $HOME to avoid leaking declarations from a shared system
# user's home into another user's session on multi-user boxes. When cwd is
# outside HOME, stop at the nearest checkout root (`.git` file/dir); a plain
# non-git directory checks only cwd. This keeps unrelated parent markers out.
ai_memory_find_marker() {
    dir="$1"
    [ -z "$dir" ] && return 0
    boundary=""
    ai_memory_home
    if [ -n "$_amhome" ]; then
        case "$dir" in
            "$_amhome"|"${_amhome%/}"/*) boundary="$_amhome" ;;
            *)
                probe="$dir"
                while [ -n "$probe" ] && [ "$probe" != "/" ]; do
                    if [ -e "$probe/.git" ]; then
                        boundary="$probe"
                        break
                    fi
                    parent=$(dirname "$probe")
                    [ "$parent" = "$probe" ] && break
                    probe="$parent"
                done
                [ -n "$boundary" ] || boundary="$dir"
                ;;
        esac
    fi
    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
        if [ -f "$dir/.ai-memory.toml" ]; then
            printf '%s\n' "$dir/.ai-memory.toml"
            return 0
        fi
        if [ -n "$boundary" ] && [ "$dir" = "$boundary" ]; then
            return 0
        fi
        parent=$(dirname "$dir")
        [ "$parent" = "$dir" ] && return 0
        dir="$parent"
    done
}

# Parse `key = "value"` at the TOML root (no nesting, no arrays, no
# tables). Returns the first match or nothing. Ignores comments and
# blank lines by construction (the regex only matches the `key = "..."`
# shape).
ai_memory_strip_utf8_bom() {
    # Byte spelling keeps this portable across GNU/BSD sed and the awk images
    # used in CI; LC_ALL=C makes the three bytes ordinary pattern characters.
    LC_ALL=C sed "1s/^$(printf '\357\273\277')//"
}

ai_memory_parse_toml_key() {
    file="$1"; key="$2"
    [ -f "$file" ] || return 0
    ai_memory_strip_utf8_bom <"$file" \
        | sed -n -E "s/^[[:space:]]*${key}[[:space:]]*=[[:space:]]*\"([^\"]*)\".*/\1/p" \
        | head -n 1
}

# Like ai_memory_parse_toml_key but also accepts a BARE value
# (`key = true` / `key = 6000`), so section-style flags such as
# `[briefing] inject_on_session_start = true` work quoted or not.
# Parity with `parse_toml_flag` in hook_capture.rs: line-based (section
# headers are ignored), first match wins, trailing `# comment` stripped.
ai_memory_parse_toml_flag() {
    file="$1"; key="$2"
    [ -f "$file" ] || return 0
    ai_memory_strip_utf8_bom <"$file" \
        | sed -n -E "s/^[[:space:]]*${key}[[:space:]]*=[[:space:]]*\"?([^\"#]*)\"?.*/\1/p" \
        | head -n 1 | sed 's/[[:space:]]*$//'
}

# A resolved marker's `[profile]` flag as the explicit value the hook sends:
# 0 for a falsy value (0/false/no/off, any case), 1 for anything else, an
# absent key included. Parity with `profile_flag_value` in hook_capture.rs.
ai_memory_profile_flag() {
    case "$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')" in
        0 | false | no | off) printf '0' ;;
        *) printf '1' ;;
    esac
}

# Whether "$1" (a marker file) declares anything beyond a `[capture]`
# section: any root-level scope key (workspace/project/project_strategy), or
# any of the other settings ai_memory_marker_qs / ai_memory_briefing_qs
# forward (drop_subagent_captures, default_global, [briefing], [profile] and
# [handoff] keys). Mirrors
# `declares_more_than_capture` in marker.rs. A marker with any of these is a
# resolution boundary; only a marker whose only content is `[capture]` (e.g.
# ignore_paths) is scope/settings-transparent (#668).
ai_memory_marker_declares_settings() {
    file="$1"
    [ -f "$file" ] || return 1
    for key in workspace project project_strategy drop_subagent_captures identity identity_style; do
        [ -n "$(ai_memory_parse_toml_key "$file" "$key")" ] && return 0
    done
    ai_memory_strip_utf8_bom <"$file" \
        | LC_ALL=C grep -Eq '^[[:space:]]*aliases[[:space:]]*=' && return 0
    ai_memory_marker_declares_server "$file" && return 0
    for key in default_global inject_on_session_start inject_on_subagent_start max_chars contribute consume deliver_on_session_start; do
        [ -n "$(ai_memory_parse_toml_flag "$file" "$key")" ] && return 0
    done
    return 1
}

# Whether marker "$1" declares a `server = ...` profile selection (#992), in
# any value shape. Line-based and section-blind like marker.rs
# `server_selection_in`; the leading class also skips a UTF-8 BOM, which is
# not whitespace to grep. An unreadable marker counts as declaring one.
ai_memory_marker_declares_server() {
    [ -r "$1" ] || return 0
    LC_ALL=C grep -Eq '^[^A-Za-z0-9_#"]*server[[:space:]]*=' "$1"
}

# Whether any marker on the walk from "$1" (default: the process cwd)
# selects a server profile (#992). These script hooks cannot route profiles
# — only native `ai-memory hook` commands can — so a routed repository must
# emit nothing rather than reach the install-default server. Mirrors the
# native walk: inside $HOME it stops at $HOME; outside it continues past the
# checkout root, so an organisation-level marker above a repository counts.
ai_memory_server_routed() {
    _amsr_dir="${1:-${PWD:-}}"
    [ -z "$_amsr_dir" ] && return 1
    _amsr_boundary=""
    ai_memory_home
    if [ -n "$_amhome" ]; then
        case "$_amsr_dir" in
            "$_amhome"|"${_amhome%/}"/*) _amsr_boundary="$_amhome" ;;
        esac
    fi
    while [ -n "$_amsr_dir" ]; do
        if [ -f "$_amsr_dir/.ai-memory.toml" ] \
            && ai_memory_marker_declares_server "$_amsr_dir/.ai-memory.toml"; then
            return 0
        fi
        [ "$_amsr_dir" = "$_amsr_boundary" ] && return 1
        [ "$_amsr_dir" = "/" ] && return 1
        # Parameter expansion, not `dirname`: this walk runs on every hook
        # event, and a fork per directory level adds up.
        _amsr_parent="${_amsr_dir%/*}"
        [ "$_amsr_parent" = "$_amsr_dir" ] && return 1
        _amsr_dir="${_amsr_parent:-/}"
    done
    return 1
}

# Query-string flag `ai_memory_marker_qs` appends for a profile-routed
# repository. `ai_memory_post_hook` and `ai_memory_get_handoff` refuse any URL
# carrying it, so every script that builds its URL from the marker query —
# all of them — fails closed without a per-script check.
AI_MEMORY_SERVER_ROUTED_QS="&server_routed=1"

# Like ai_memory_find_marker, but skips a marker that declares nothing beyond
# `[capture]` (see ai_memory_marker_declares_settings) and continues the walk
# to the next ancestor. Resolves workspace/project/project_strategy and the
# other root-level settings ai_memory_marker_qs / ai_memory_briefing_qs
# forward, so a nested capture-only marker no longer resets them to their
# fallback (#668). [capture]/ignore_paths itself keeps using
# ai_memory_find_marker (the nearest marker, unchanged). Boundary logic is
# duplicated rather than shared with ai_memory_find_marker on purpose: this
# file is sourced by every supported agent's hook scripts, so the existing,
# well-exercised walk stays untouched.
ai_memory_find_settings_marker() {
    dir="$1"
    [ -z "$dir" ] && return 0
    boundary=""
    ai_memory_home
    if [ -n "$_amhome" ]; then
        case "$dir" in
            "$_amhome"|"${_amhome%/}"/*) boundary="$_amhome" ;;
            *)
                probe="$dir"
                while [ -n "$probe" ] && [ "$probe" != "/" ]; do
                    if [ -e "$probe/.git" ]; then
                        boundary="$probe"
                        break
                    fi
                    parent=$(dirname "$probe")
                    [ "$parent" = "$probe" ] && break
                    probe="$parent"
                done
                [ -n "$boundary" ] || boundary="$dir"
                ;;
        esac
    fi
    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
        if [ -f "$dir/.ai-memory.toml" ]; then
            if [ -n "$_amhome" ] && [ "$dir" = "$_amhome" ]; then
                printf '%s\n' "$dir/.ai-memory.toml"
                return 0
            fi
            if ai_memory_marker_declares_settings "$dir/.ai-memory.toml"; then
                printf '%s\n' "$dir/.ai-memory.toml"
                return 0
            fi
        fi
        if [ -n "$boundary" ] && [ "$dir" = "$boundary" ]; then
            return 0
        fi
        parent=$(dirname "$dir")
        [ "$parent" = "$dir" ] && return 0
        dir="$parent"
    done
}

# Extract the first cwd-like path from a JSON payload on stdin or in $1.
# Returns the value or nothing. This is intentionally a tiny shell fallback,
# not a JSON parser; taking the first match preserves the top-level cwd when
# tool payloads contain nested `cwd` fields later in the object. Antigravity
# CLI sends `workspacePaths: ["/repo", ...]` instead of `cwd`; Cursor sends
# `workspace_roots: ["/repo", ...]`.
# Undo the JSON string escapes that can appear in a path value: \\ -> \
# and \/ -> /. Windows payloads carry cwd as "C:\\dev\\proj"; without this
# the doubled backslashes leak into the query string (#188).
ai_memory_json_unescape_path() {
    printf '%s' "$1" | sed 's/\\\\/\\/g; s/\\\//\//g'
}

# Print the payload text after the first `"$1"` (a JSON key, quotes added
# here) and succeed, or fail when the key is absent. Same result as
# `${payload#*"key"}`, which is quadratic in the payload size under dash and
# bash and pinned a CPU for minutes on a large tool result (#870).
ai_memory_after_key() {
    LC_ALL=C awk -v k="\"$1\"" '
        found { print; next }
        { i = index($0, k); if (i) { found = 1; print substr($0, i + length(k)) } }
        END { exit !found }'
}

ai_memory_extract_cwd() {
    payload="${1:-$(cat)}"
    if rest=$(printf '%s' "$payload" | ai_memory_after_key cwd); then
        raw=$(printf '%s' "$rest" \
            | sed -n -E 's/^[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p' \
            | head -n 1)
        if [ -n "$raw" ]; then
            ai_memory_json_unescape_path "$raw"
            return 0
        fi
    fi
    # Antigravity CLI sends `workspacePaths`, Cursor `workspace_roots`.
    # Cursor never sends a usable `cwd`: `sessionStart` / `sessionEnd` omit it
    # and its tool events send `cwd: ""`, so an empty match above must fall
    # through to here rather than returning the empty string.
    for key in workspacePaths workspace_roots; do
        rest=$(printf '%s' "$payload" | ai_memory_after_key "$key") || continue
        raw=$(printf '%s' "$rest" \
            | sed -n -E 's/^[[:space:]]*:[[:space:]]*\[[[:space:]]*"([^"]*)".*/\1/p' \
            | head -n 1)
        if [ -n "$raw" ]; then
            ai_memory_json_unescape_path "$raw"
            return 0
        fi
    done
}

# Extract a harness-native session id from the common hook payload spellings.
# Like the cwd fallback above this intentionally handles top-level JSON strings
# only; native `ai-memory hook` uses a real JSON parser.
ai_memory_extract_session_id() {
    payload="${1:-$(cat)}"
    for key in session_id sessionId sessionID session conversationId; do
        if rest=$(printf '%s' "$payload" | ai_memory_after_key "$key"); then
            printf '%s' "$rest" \
                | sed -n -E 's/^[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p' \
                | head -n 1
            return 0
        fi
    done
}

# True when the payload claims to be a subagent/child session: a known marker
# key at the TOP LEVEL holding a non-empty string. Parity with the native
# router (`commands/hook.rs::payload_is_subagent`) and the PowerShell
# `Test-AiMemorySubagentPayload`, both of which read keyed values. The depth
# walk is what makes it a payload check rather than a text search: tool input
# and tool output routinely quote these key names (reading a source file that
# names them is enough), and a session must not lose its handoff over that.
ai_memory_payload_is_subagent() {
    printf '%s' "${1:-$(cat)}" | LC_ALL=C awk '
        { buf = buf $0 "\n" }
        END {
            split("subagentType subagent_type agent_type agent_id parentSessionId", names, " ")
            for (n in names) marker[names[n]] = 1
            len = length(buf)
            depth = 0
            want = "key"
            for (i = 1; i <= len; i++) {
                c = substr(buf, i, 1)
                if (c == "{" || c == "[") { depth++; if (depth == 1) want = "key"; continue }
                if (c == "}" || c == "]") { depth--; continue }
                if (c == ",") { if (depth == 1) want = "key"; continue }
                if (c != "\"") continue
                tok = ""
                for (i++; i <= len; i++) {
                    c = substr(buf, i, 1)
                    if (c == "\\") { tok = tok substr(buf, i, 2); i++; continue }
                    if (c == "\"") break
                    tok = tok c
                }
                if (depth != 1) continue
                if (want == "key") { key = tok; want = "value"; continue }
                gsub(/^[ \t\r\n]+|[ \t\r\n]+$/, "", tok)
                if (marker[key] && tok != "") exit 0
                want = "key"
            }
            exit 1
        }'
}

# Antigravity's PreInvocation hook fires before every model call. Only the
# documented invocationNum=0 boundary represents the startup event that
# ai-memory maps to SessionStart. Missing or malformed counters fail closed so
# a repeated invocation cannot consume a next-session handoff.
ai_memory_antigravity_is_initial_invocation() {
    payload="${1:-$(cat)}"
    rest=$(printf '%s' "$payload" | ai_memory_after_key invocationNum) || return 1
    value=$(printf '%s' "$rest" \
        | sed -n -E 's/^[[:space:]]*:[[:space:]]*([0-9]+)[[:space:]]*([,}]).*/\1/p' \
        | head -n 1)
    [ "$value" = "0" ]
}

ai_memory_managed_qs() {
    [ -n "${AI_MEMORY_RUN_ID:-}" ] || return 0
    printf '&managed_run=%s' "$(ai_memory_url_encode "$AI_MEMORY_RUN_ID")"
}

# Resolve cwd for agents whose native hook payload omits it. Payload wins,
# then Devin's project env var, then the hook process cwd.
ai_memory_resolve_cwd() {
    payload="${1:-$(cat)}"
    cwd=$(ai_memory_extract_cwd "$payload")
    if [ -n "$cwd" ]; then
        printf '%s' "$cwd"
        return 0
    fi
    if [ -n "${DEVIN_PROJECT_DIR:-}" ]; then
        printf '%s' "$DEVIN_PROJECT_DIR"
        return 0
    fi
    pwd 2>/dev/null || true
}

# URL-encode the minimal set of characters that have meaning in a query
# string. Sufficient for the schema's value regex (`^[a-z0-9][a-z0-9._-]*$`)
# plus a defensive pass for anything a hand-edited marker might contain.
# Percent-encode everything outside the RFC 3986 unreserved set
# (A-Z a-z 0-9 - _ . ~), byte-wise under LC_ALL=C so multibyte UTF-8 is
# encoded per byte. Allow-list on purpose: the old deny-list missed
# backslash, so a Windows cwd went into the query string raw and the
# request never reached the server (#188). Parity with the native
# helper's url_encode in hook_capture.rs.
ai_memory_url_encode() {
    LC_ALL=C
    s="$1"
    out=""
    while [ -n "$s" ]; do
        rest="${s#?}"
        c="${s%"$rest"}"
        s="$rest"
        case $c in
            [A-Za-z0-9._~-]) out="$out$c" ;;
            *)
                # bash 3.2 (macOS /bin/sh) sign-extends bytes >= 0x80, so
                # `printf '%X' "'$c"` printed FFFFFFFFFFFFFFC3 for 0xC3.
                b=$(printf '%d' "'$c")
                [ "$b" -lt 0 ] && b=$((b + 256))
                out="$out$(printf '%%%02X' "$b")" ;;
        esac
    done
    printf '%s' "$out"
}

# Resolve the basename of the MAIN git repository root for "$1" (a cwd),
# following the worktree commondir pointer so every linked worktree of a
# repo collapses to one stable name. Mirrors the server's
# `discover_main_repo_root` (libgit2) but runs host-side, where the
# checkout is always visible — the server cannot do this when it runs in a
# container that has no access to the host filesystem (its own discovery
# fails and falls back to basename(cwd), so out-of-tree worktrees each
# became their own project). Prints the name, or nothing when cwd is not
# inside a git work tree (caller keeps its basename(cwd) fallback).
ai_memory_repo_root_project() {
    cwd="$1"
    [ -z "$cwd" ] && return 0
    command -v git >/dev/null 2>&1 || return 0
    # Only touch git when cwd is genuinely inside a working tree. Outside any
    # repo, or inside a bare repo, `--is-inside-work-tree` is not "true" and
    # we stay silent rather than guess.
    [ "$(git -C "$cwd" rev-parse --is-inside-work-tree 2>/dev/null)" = "true" ] || return 0
    # `--git-common-dir` is the shared `.git` dir: for a worktree it points
    # at the MAIN repo's `.git`, so its parent is always the main repo root.
    common=$(git -C "$cwd" rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || return 0
    [ -n "$common" ] || return 0
    root=$(dirname "$common")
    case "$root" in
        "" | /) return 0 ;;
    esac
    basename "$root"
}

# Normalise a git remote URL ("$1") into a repository identity, or print
# nothing when it names no network-reachable repository (a local path, a bare
# host). Port of `normalize_remote_url` in
# crates/ai-memory-core/src/repository_identity.rs, checked against the same
# fixture (crates/ai-memory-core/fixtures/remote_identity_cases.json) so the
# two cannot drift. Credentials are dropped here, on the host, so they never
# reach the server. Variables are prefixed: POSIX functions share the
# caller's scope.
ai_memory_normalize_remote() {
    _ai_rn_raw=$(printf '%s' "$1" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
    [ -n "$_ai_rn_raw" ] || return 0
    case "$_ai_rn_raw" in
        *://*)
            _ai_rn_has_scheme=1
            _ai_rn_scheme=$(printf '%s' "${_ai_rn_raw%%://*}" | tr '[:upper:]' '[:lower:]')
            _ai_rn_rest=${_ai_rn_raw#*://}
            ;;
        *)
            _ai_rn_has_scheme=""
            _ai_rn_scheme=""
            _ai_rn_rest=$_ai_rn_raw
            ;;
    esac
    [ "$_ai_rn_scheme" = "file" ] && return 0
    # Credentials: everything up to the LAST `@` before the path.
    _ai_rn_auth=${_ai_rn_rest%%/*}
    _ai_rn_tail=${_ai_rn_rest#"$_ai_rn_auth"}
    case "$_ai_rn_auth" in *@*) _ai_rn_auth=${_ai_rn_auth##*@} ;; esac
    _ai_rn_hp="$_ai_rn_auth$_ai_rn_tail"
    if [ -n "$_ai_rn_has_scheme" ]; then
        _ai_rn_host=${_ai_rn_hp%%/*}
        case "$_ai_rn_hp" in */*) _ai_rn_path=${_ai_rn_hp#*/} ;; *) _ai_rn_path="" ;; esac
        case "$_ai_rn_host" in
            *:*)
                case "${_ai_rn_host##*:}" in
                    *[!0-9]*) ;;
                    *) _ai_rn_host=${_ai_rn_host%:*} ;;
                esac
                ;;
        esac
        [ -n "$_ai_rn_host" ] && [ -n "$_ai_rn_path" ] || return 0
    else
        # scp-like `host:path`, or a filesystem path: a `:` before any `/`.
        case "$_ai_rn_hp" in *:*) ;; *) return 0 ;; esac
        _ai_rn_host=${_ai_rn_hp%%:*}
        case "$_ai_rn_host" in */*) return 0 ;; esac
        _ai_rn_path=${_ai_rn_hp#*:}
        # A one-character host is a Windows drive letter.
        [ "${#_ai_rn_host}" -gt 1 ] && [ -n "$_ai_rn_path" ] || return 0
        case "$_ai_rn_path" in *\\*) return 0 ;; esac
    fi
    _ai_rn_id=$(printf '%s/%s' "$_ai_rn_host" "$_ai_rn_path" \
        | tr '[:upper:]' '[:lower:]' \
        | sed -e 's#/*$##' -e 's#\.git$##' -e 's#/*$##' -e 's#//*#/#g')
    case "$_ai_rn_id" in */*) printf '%s' "$_ai_rn_id" ;; esac
}

# Print the Phase-5 style sent with every valid git-remote identity. Explicit
# marker/home-route values win; omission or invalid input sends `path`. Servers
# keep a truly omitted field as legacy `host_path` for old-client compatibility.
ai_memory_identity_style_qs() {
    _ai_is_value=$(printf '%s' "$1" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
    case "$_ai_is_value" in
        host_path) printf '&identity_style=host_path' ;;
        *) printf '&identity_style=path' ;;
    esac
    return 0
}

ai_memory_home_route() {
    _ai_hr_file="$1"; _ai_hr_cwd="$2"; _ai_hr_identity="$3"
    [ -f "$_ai_hr_file" ] || return 0
    [ "$(wc -c <"$_ai_hr_file")" -le 65536 ] || { printf 'invalid'; return 0; }
    LC_ALL=C awk -v cwd="$_ai_hr_cwd" -v home="$_amhome" -v identity="$_ai_hr_identity" '
        function invalid() { bad = 1 }
        function cleanpath(value,    n, raw, out, i, root, home_relative, rel_depth, j) {
            gsub(/\\/, "/", value)
            home_relative = substr(value,1,2) == "~/"
            if (home_relative) {
                raw = substr(value,3); n = split(raw,relative_parts,"/"); rel_depth = 0
                for (j=1; j<=n; j++) if (relative_parts[j] != "" && relative_parts[j] != ".") {
                    if (relative_parts[j] == "..") { if (!rel_depth) return ""; rel_depth-- }
                    else rel_depth++
                }
                value = home "/" raw
            }
            if (substr(value,1,2) == "//") {
                raw = substr(value,3); n = split(raw,a,"/")
                if (n < 2 || a[1] == "" || a[2] == "") return ""
                root = "unc:" tolower(a[1]) "/" tolower(a[2]); i = 3
            } else if (value ~ /^[A-Za-z]:\//) {
                root = "drive:" tolower(substr(value,1,1)); raw = substr(value,4); n = split(raw,a,"/"); i = 1
            } else if (substr(value,1,1) == "/") {
                root = "posix"; raw = substr(value,2); n = split(raw,a,"/"); i = 1
            } else return ""
            depth = 0; delete stack
            for (; i <= n; i++) if (a[i] != "" && a[i] != ".") { if (a[i] == "..") { if (depth) depth-- } else stack[++depth] = a[i] }
            out = root
            for (i=1; i<=depth; i++) out = out "/" (root == "posix" ? stack[i] : tolower(stack[i]))
            return out
        }
        function aliases_valid(value,    body,n,i,item) {
            if (length(value) > 512 || value ~ /\\/ || value !~ /^\[[^]]*\][[:space:]]*$/) return 0
            body=value; sub(/^\[/,"",body); sub(/\][[:space:]]*$/,"",body)
            if (body ~ /^[[:space:]]*$/) return 1
            if (body ~ /,[[:space:]]*$/) return 0
            n=split(body,items,","); if (n > 16) return 0
            for (i=1;i<=n;i++) {
                item=items[i]
                if (item !~ /^[[:space:]]*"[A-Za-z0-9][A-Za-z0-9._-]*"[[:space:]]*$/) return 0
                sub(/^[[:space:]]*"/,"",item); sub(/"[[:space:]]*$/,"",item)
                if (length(item) > 128) return 0
            }
            return 1
        }
        function finish(    normalized,n) {
            if (!kind) return
            count++
            if (count > 64 || length(selector) > 512 || raw_seen[selector]++) invalid()
            if (!route_workspace || !route_project || length(route_workspace) > 512 || length(route_project) > 512 || route_workspace !~ /^[a-z0-9][a-z0-9._-]*$/ || route_project !~ /^[a-z0-9][a-z0-9._-]*$/) invalid()
            if (route_identity_style && route_identity_style != "path" && route_identity_style != "host_path") invalid()
            if (route_aliases && !aliases_valid(route_aliases)) invalid()
            if (kind == "identity") {
                host=selector; sub(/\/.*/,"",host)
                if (selector != tolower(selector) || selector !~ /^[a-z0-9.-]+(\/[a-z0-9._-]+)+$/ || host ~ /^\./ || host ~ /\.$/ || identity_seen[selector]++) invalid()
                if (selector == identity) { identity_found = 1; identity_ws = route_workspace; identity_pr = route_project; identity_style = route_identity_style; identity_aliases = route_aliases }
            } else {
                normalized = cleanpath(selector)
                if (!normalized || normalized == "posix" || normalized ~ /^drive:[^\/]+$/ || normalized ~ /^unc:[^\/]+\/[^\/]+$/ || path_seen[normalized]++) invalid()
                target = cleanpath(cwd)
                if (normalized == target || index(target, normalized "/") == 1) {
                    n = split(normalized, parts, "/")
                    if (n > best_depth) { best_depth=n; best_ws=route_workspace; best_pr=route_project; best_style=route_identity_style; best_aliases=route_aliases; tie=0 }
                    else if (n == best_depth) tie=1
                }
            }
            kind=""; selector=""; route_workspace=""; route_project=""; route_identity_style=""; route_aliases=""; delete field_seen
        }
        BEGIN { count=0; bad=0; best_depth=0; tie=0 }
        {
            line=$0; sub(/\r$/, "", line)
            if (match(line, /^[[:space:]]*\[routes\.(identity|path)\."[^"\\]+"\][[:space:]]*$/)) {
                saw_route=1; finish(); header=line; sub(/^[[:space:]]*\[routes\./,"",header); kind=substr(header,1,index(header,".")-1); selector=header; sub(/^[^.]+\."/,"",selector); sub(/"\][[:space:]]*$/,"",selector); next
            }
            if (line ~ /^[[:space:]]*\[routes/ || line ~ /^[[:space:]]*routes[[:space:]]*=/ || line ~ /^[[:space:]]*routes\./ || line ~ /^[[:space:]]*route_[A-Za-z0-9_]+[[:space:]]*=/) {
                saw_route=1
                if (!kind || line ~ /^[[:space:]]*\[/) { finish(); invalid(); next }
                key=line; sub(/^[[:space:]]*/,"",key); sub(/[[:space:]]*=.*/,"",key)
                if (field_seen[key]++) { invalid(); next }
                value=line; sub(/^[^=]*=[[:space:]]*/,"",value)
                if (key == "route_aliases") { if (!aliases_valid(value)) invalid(); route_aliases=value }
                else {
                    if (length(value) > 514 || value ~ /\\/ || value !~ /^"[^"]+"[[:space:]]*$/) { invalid(); next }
                    sub(/^"/,"",value); sub(/"[[:space:]]*$/,"",value)
                    if (length(value) > 512) { invalid(); next }
                    if (key == "route_workspace") route_workspace=value
                    else if (key == "route_project") route_project=value
                    else if (key == "route_identity_style") route_identity_style=value
                    else invalid()
                }
                next
            }
            if (line ~ /^[[:space:]]*\[/) { finish(); next }
            if (kind && line !~ /^[[:space:]]*(#|$)/) invalid()
            if (!kind && line ~ /^[[:space:]]*(workspace|project|project_strategy|drop_subagent_captures|identity|identity_style|server)[[:space:]]*=/ && line !~ /^[[:space:]]*[A-Za-z0-9_]+[[:space:]]*=[[:space:]]*"[^"]*"[[:space:]]*$/) root_bad=1
        }
        END { finish(); if (saw_route && (bad || root_bad || tie)) print "invalid"; else if (identity_found) print identity_ws "\034" identity_pr "\034" identity_style "\034" identity_aliases; else if (best_depth) print best_ws "\034" best_pr "\034" best_style "\034" best_aliases }
    ' "$_ai_hr_file" | tail -n 1
}

ai_memory_aliases_json_value() {
    _ai_alias_tmp=$(mktemp "${TMPDIR:-/tmp}/ai-memory-aliases.XXXXXX") || return 0
    printf 'aliases = %s\n' "$1" >"$_ai_alias_tmp"
    ai_memory_aliases_json "$_ai_alias_tmp"
    rm -f "$_ai_alias_tmp"
}

ai_memory_aliases_json() {
    [ -f "$1" ] || return 0
    _ai_alias_body=$(ai_memory_strip_utf8_bom <"$1" | LC_ALL=C awk '
        BEGIN { table = 0; count = 0; bad = 0 }
        {
            line = $0
            sub(/\r$/, "", line)
            trimmed = line
            sub(/^[ \t]*/, "", trimmed)
            if (trimmed ~ /^\[/) table = 1
            if (trimmed ~ /^aliases[ \t]*=/) {
                count++
                if (table || count > 1 || trimmed !~ /^aliases[ \t]*=[ \t]*\[[^]]*\][ \t]*$/) {
                    bad = 1
                } else {
                    sub(/^aliases[ \t]*=[ \t]*\[/, "", trimmed)
                    sub(/\][ \t]*$/, "", trimmed)
                    body = trimmed
                }
            }
        }
        END {
            if (bad) print "invalid"
            else if (count == 1) print body
        }
    ')
    [ "$_ai_alias_body" = "invalid" ] && { printf 'invalid'; return 0; }
    [ -n "$_ai_alias_body" ] || return 0
    _ai_alias_trimmed=$(printf '%s' "$_ai_alias_body" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
    [ -n "$_ai_alias_trimmed" ] || return 0
    case "$_ai_alias_trimmed" in *,) printf 'invalid'; return 0 ;; esac
    _ai_alias_out=""
    _ai_alias_count=0
    _ai_alias_old_ifs=$IFS
    IFS=,
    for _ai_alias_raw in $_ai_alias_body; do
        IFS=$_ai_alias_old_ifs
        _ai_alias_count=$((_ai_alias_count + 1))
        [ "$_ai_alias_count" -le 16 ] || { printf 'invalid'; return 0; }
        case "$_ai_alias_raw" in *\\*) printf 'invalid'; return 0 ;; esac
        _ai_alias=$(printf '%s' "$_ai_alias_raw" | sed -n -E 's/^[[:space:]]*"([^"]*)"[[:space:]]*$/\1/p' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
        case "$_ai_alias" in
            ""|*[!A-Za-z0-9._-]*) printf 'invalid'; return 0 ;;
        esac
        [ "${#_ai_alias}" -le 128 ] || { printf 'invalid'; return 0; }
        case "$_ai_alias" in [A-Za-z0-9]*) ;; *) printf 'invalid'; return 0 ;; esac
        case "|$_ai_alias_out|" in *"|$_ai_alias|"*) ;; *)
            _ai_alias_out="${_ai_alias_out}|${_ai_alias}"
        esac
        IFS=,
    done
    IFS=$_ai_alias_old_ifs
    _ai_alias_json="["
    _ai_alias_sep=""
    _ai_alias_rest=${_ai_alias_out#|}
    IFS='|'
    for _ai_alias in $_ai_alias_rest; do
        _ai_alias_json="${_ai_alias_json}${_ai_alias_sep}\"${_ai_alias}\""
        _ai_alias_sep=,
    done
    IFS=$_ai_alias_old_ifs
    printf '%s]' "$_ai_alias_json"
}

ai_memory_git_remote_identity() {
    [ -n "$1" ] || return 0
    command -v git >/dev/null 2>&1 || return 0
    for _ai_gri_remote in upstream origin; do
        _ai_gri_url=$(git -C "$1" config --get "remote.$_ai_gri_remote.url" 2>/dev/null) || continue
        _ai_gri_value=$(ai_memory_normalize_remote "$_ai_gri_url")
        [ -n "$_ai_gri_value" ] && { printf '%s' "$_ai_gri_value"; return 0; }
    done
}

# Print `&identity=<v>&identity_src=<rung>` for the checkout at "$1", or
# nothing. "$2" is the marker's `identity`, "$3" its declared `project`, "$4"
# its `identity_style`, forwarded only with a remote identity.
# Mirrors `repository_identity` in hook_capture.rs: an explicit identity is
# sent; a declared project outranks the remote and routes by name, so git is
# not consulted; otherwise the `upstream` remote, else `origin`.
ai_memory_identity_qs() {
    _ai_id_cwd="$1"; _ai_id_explicit="$2"; _ai_id_project="$3"; _ai_id_style="$4"; _ai_id_aliases="$5"
    _ai_id_explicit=$(printf '%s' "$_ai_id_explicit" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
    if [ -z "$_ai_id_aliases" ] && [ -n "$_ai_id_explicit" ]; then
        _ai_id_value=$(printf '%s' "$_ai_id_explicit" | tr '[:upper:]' '[:lower:]')
        printf '&identity=%s&identity_src=explicit' "$(ai_memory_url_encode "$_ai_id_value")"
        return 0
    fi
    [ -z "$_ai_id_aliases" ] && [ -n "$(printf '%s' "$_ai_id_project" | tr -d '[:space:]')" ] && return 0
    _ai_id_value=$(ai_memory_git_remote_identity "$_ai_id_cwd")
    if [ -n "$_ai_id_value" ]; then
        printf '&identity=%s&identity_src=git_remote' "$(ai_memory_url_encode "$_ai_id_value")"
        ai_memory_identity_style_qs "$_ai_id_style"
    fi
}

# Build a query-string suffix from "$1" plus any marker file walked up from
# it. Returns the suffix with the leading `&`, or nothing when cwd is absent.
# `cwd` is always included so `GET /handoff` resolves the same basename project
# as the prior hook events even when no marker file exists.
ai_memory_marker_qs() {
    cwd="$1"
    if ai_memory_server_routed "$cwd"; then
        printf '%s' "$AI_MEMORY_SERVER_ROUTED_QS"
        return 0
    fi
    if [ -z "$cwd" ]; then
        ai_memory_managed_qs
        return 0
    fi
    qs="&cwd=$(ai_memory_url_encode "$cwd")"
    ws=""
    pr=""
    st=""
    ds=""
    dg=""
    # Provenance of `pr`, forwarded as `project_src` so the server can tell a
    # deliberate marker rescope from a host-derived repo-root name. Only the
    # latter may yield to session-sticky attribution (#394).
    ps=""
    idn=""
    isty=""
    pcon=""
    pcons=""
    hoff=""
    aliases=""
    routed=""
    # The nearest marker that declares more than `[capture]` (#668): a nested
    # capture-only marker (e.g. one that only sets ignore_paths) must not
    # shadow an outer marker's workspace/project/etc.
    marker=$(ai_memory_find_settings_marker "$cwd")
    ai_memory_home
    home_marker=""
    [ -n "$_amhome" ] && [ -f "$_amhome/.ai-memory.toml" ] && home_marker="$_amhome/.ai-memory.toml"
    if [ -z "$marker" ] || [ "$marker" = "$home_marker" ]; then
        route_identity=$(ai_memory_git_remote_identity "$cwd")
        route=$(ai_memory_home_route "$home_marker" "$cwd" "$route_identity")
        if [ "$route" = "invalid" ]; then
            printf '%s' '&ai_memory_invalid_home_routes=1'
            return 0
        fi
        if [ -n "$route" ]; then
            old_ifs=$IFS; IFS=$(printf '\034')
            set -- $route
            IFS=$old_ifs
            ws=$1; pr=$2; isty=${3:-}; route_aliases=${4:-}; ps=marker; routed=1
            [ -n "$route_aliases" ] && aliases=$(ai_memory_aliases_json_value "$route_aliases")
            marker="$home_marker"
            if [ -n "$route_identity" ]; then
                iq="&identity=$(ai_memory_url_encode "$route_identity")&identity_src=git_remote$(ai_memory_identity_style_qs "$isty")"
            fi
        fi
    fi
    if [ -n "$marker" ]; then
        [ -n "$routed" ] || ws=$(ai_memory_parse_toml_key "$marker" workspace)
        [ -n "$routed" ] || pr=$(ai_memory_parse_toml_key "$marker" project)
        [ -n "$routed" ] || st=$(ai_memory_parse_toml_key "$marker" project_strategy)
        ds=$(ai_memory_parse_toml_key "$marker" drop_subagent_captures)
        dg=$(ai_memory_parse_toml_flag "$marker" default_global)
        [ -n "$routed" ] || idn=$(ai_memory_parse_toml_key "$marker" identity)
        [ -n "$routed" ] || isty=$(ai_memory_parse_toml_key "$marker" identity_style)
        [ -n "$routed" ] || aliases=$(ai_memory_aliases_json "$marker")
        # `[profile] contribute` / `consume`, quoted or bare, always sent
        # explicitly once a marker resolved (0 when falsy, else 1): removing
        # the key re-enables; no marker sends nothing and the server keeps
        # what it stored.
        pcon=$(ai_memory_profile_flag "$(ai_memory_parse_toml_flag "$marker" contribute)")
        pcons=$(ai_memory_profile_flag "$(ai_memory_parse_toml_flag "$marker" consume)")
        # `[handoff] deliver_on_session_start = false` is sent only when
        # explicitly falsy; an absent key leaves the request unchanged.
        [ "$(ai_memory_profile_flag "$(ai_memory_parse_toml_flag "$marker" deliver_on_session_start)")" = 0 ] && hoff=0
        [ -n "$pr" ] && ps="marker"
    fi
    # Before repo-root can fill `pr`: a repo-root name is an inference, while
    # the identity chain's declared-project rung means a name in the marker.
    [ -n "${iq:-}" ] || iq=$(ai_memory_identity_qs "$cwd" "$idn" "$pr" "$isty" "$aliases")
    # Install-time default baked into the hook command by
    # `install-hooks --project-strategy` fills the strategy only when no marker
    # pins one. Explicit project/identity and home routing win; otherwise a
    # valid remote identity wins and repo-root is the remote-less fallback.
    if [ -z "$st" ] && [ -n "${AI_MEMORY_PROJECT_STRATEGY:-}" ]; then
        st="$AI_MEMORY_PROJECT_STRATEGY"
    fi
    # The repo-root strategy must be resolved here, on the host: a containerized
    # server cannot see this checkout, so its own libgit2 discovery fails and
    # falls back to basename(cwd). When repo-root is selected and no explicit
    # project is pinned, derive the main repo name now and send it as an explicit
    # `project` override. `project_strategy` is still forwarded so native servers
    # keep their existing resolution path.
    if [ -z "$pr" ]; then
        case "$st" in
            repo-root | repo_root)
                pr=$(ai_memory_repo_root_project "$cwd")
                [ -n "$pr" ] && ps="repo-root"
                ;;
        esac
    fi
    [ -n "$ws" ] && qs="${qs}&workspace=$(ai_memory_url_encode "$ws")"
    [ -n "$pr" ] && qs="${qs}&project=$(ai_memory_url_encode "$pr")"
    [ -n "$ps" ] && qs="${qs}&project_src=$(ai_memory_url_encode "$ps")"
    [ -n "$st" ] && qs="${qs}&project_strategy=$(ai_memory_url_encode "$st")"
    qs="${qs}${iq}"
    if [ -n "$aliases" ]; then
        case "$iq" in *'identity_src=git_remote'*)
            [ -n "$pr" ] || aliases=invalid
            ;;
            *) [ -n "$routed" ] && aliases="" || aliases=invalid ;;
        esac
        [ -n "$aliases" ] && qs="${qs}&aliases=$(ai_memory_url_encode "$aliases")"
    fi
    # Per-project drop_subagent_captures opt-in: forward to the server, which
    # interprets truthiness (1/true/...) and scopes the drop to this project.
    [ -n "$ds" ] && qs="${qs}&drop_subagent=$(ai_memory_url_encode "$ds")"
    [ -n "$dg" ] && qs="${qs}&default_global=$(ai_memory_url_encode "$dg")"
    [ -n "$pcon" ] && qs="${qs}&profile_contribute=$(ai_memory_url_encode "$pcon")"
    [ -n "$pcons" ] && qs="${qs}&profile_consume=$(ai_memory_url_encode "$pcons")"
    [ -n "$hoff" ] && qs="${qs}&handoff=0"
    qs="${qs}$(ai_memory_managed_qs)"
    printf '%s' "$qs"
}

# Build `&briefing=<v>[&briefing_budget=<v>]` from the `[briefing]` section
# of the marker walked up from "$1" (the opt-in key "$2", by default
# inject_on_session_start, + optional max_chars). Prints nothing when cwd is
# absent or the repo did not opt in.
# NOT part of ai_memory_marker_qs on purpose: agents that deliver the brief
# once per session (kimi-code, via the first user prompt — kimi discards
# SessionStart hook stdout) append this only on the first fetch, so the
# server does not recompose the brief on every request. The char-budget clamp
# is decided server-side.
ai_memory_briefing_qs() {
    cwd="$1"
    _ambkey="${2:-inject_on_session_start}"
    [ -z "$cwd" ] && return 0
    # Settings walk (#668): a nested capture-only marker must not shadow an
    # outer marker's [briefing] opt-in.
    marker=$(ai_memory_find_settings_marker "$cwd")
    [ -n "$marker" ] || return 0
    qs=""
    briefing=$(ai_memory_parse_toml_flag "$marker" "$_ambkey")
    case "$(printf '%s' "$briefing" | tr '[:upper:]' '[:lower:]')" in
        1|true|yes|on) ;;
        *) return 0 ;;
    esac
    budget=$(ai_memory_parse_toml_flag "$marker" max_chars)
    qs="&briefing=$(ai_memory_url_encode "$briefing")"
    [ -n "$budget" ] && qs="${qs}&briefing_budget=$(ai_memory_url_encode "$budget")"
    printf '%s' "$qs"
}

# The `[briefing] inject_on_subagent_start` pair for cwd "$1": the query a
# subagent start sends to `/brief`. Prints nothing without that
# opt-in, whatever `inject_on_session_start` says.
ai_memory_subagent_briefing_qs() {
    ai_memory_briefing_qs "$1" inject_on_subagent_start
}

# Path of the once-per-session "brief delivered" marker for "$1" (a session
# id or a caller-built fallback key), sanitized to a safe file name under
# the shared state dir.
ai_memory_briefed_file() {
    key=$(printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '_')
    printf '%s/briefed/%s' "$(ai_memory_state_dir)" "$key"
}

# Write a once-per-session briefing marker and keep only the 512 newest
# markers. All marker names are sanitized by ai_memory_briefed_file.
ai_memory_mark_briefed() {
    path="$1"
    [ -n "$path" ] || return 0
    dir=$(dirname "$path")
    mkdir -p "$dir" 2>/dev/null || return 0
    : > "$path" 2>/dev/null || return 0
    LC_ALL=C ls -1t "$dir" 2>/dev/null \
        | sed -n '513,$p' \
        | while IFS= read -r stale; do
            [ -n "$stale" ] && rm -f "$dir/$stale" 2>/dev/null || true
        done
}

# Local bridge state for agents whose hook payloads do not carry a session id.
# The value is intentionally non-secret; the server hashes non-UUID ids into its
# typed SessionId domain. `AI_MEMORY_SESSION_ID` may be supplied by advanced
# launchers to pin an externally managed run id.
ai_memory_state_dir() {
    if [ -n "${AI_MEMORY_DATA_DIR:-}" ]; then
        printf '%s' "$AI_MEMORY_DATA_DIR"
    elif [ -n "${XDG_DATA_HOME:-}" ]; then
        printf '%s/ai-memory' "$XDG_DATA_HOME"
    elif [ -n "${HOME:-}" ]; then
        case "$(uname -s 2>/dev/null || printf '')" in
            Darwin) printf '%s/Library/Application Support/ai-memory' "$HOME" ;;
            *) printf '%s/.local/share/ai-memory' "$HOME" ;;
        esac
    else
        printf '.ai-memory'
    fi
}

ai_memory_session_id_file() {
    agent="$1"
    printf '%s/hook-state/%s-session-id' "$(ai_memory_state_dir)" "$agent"
}

ai_memory_new_session_id() {
    agent="$1"
    now=$(date +%s 2>/dev/null || printf '0')
    printf '%s-%s-%s' "$agent" "$now" "$$"
}

ai_memory_session_id_qs() {
    agent="$1"; event="$2"
    if [ -n "${AI_MEMORY_SESSION_ID:-}" ]; then
        printf '&session_id=%s' "$(ai_memory_url_encode "$AI_MEMORY_SESSION_ID")"
        return 0
    fi
    file=$(ai_memory_session_id_file "$agent")
    sid=""
    if [ "$event" != "session-start" ] && [ -f "$file" ]; then
        sid=$(sed -n '1p' "$file" 2>/dev/null)
    fi
    if [ -z "$sid" ]; then
        sid=$(ai_memory_new_session_id "$agent")
        dir=$(dirname "$file")
        mkdir -p "$dir" 2>/dev/null || true
        printf '%s\n' "$sid" > "$file" 2>/dev/null || true
    fi
    printf '&session_id=%s' "$(ai_memory_url_encode "$sid")"
}

ai_memory_clear_session_id() {
    agent="$1"
    rm -f "$(ai_memory_session_id_file "$agent")" 2>/dev/null || true
}

# POST stdin to "$1" as JSON. Adds an
# `Authorization: Bearer` header when `AI_MEMORY_AUTH_TOKEN` is set.
# The 0.2s timeout is invariant 5's budget for a script hook
# (never block the agent), and the trailing `|| true` makes the
# function safe to call from `set -e` scripts. An undelivered event
# (unreachable server or 5xx) is spooled for a later drain instead of
# being dropped; a 4xx is a permanent rejection and is not retried.
# Stdout is the HTTP status code, not the response body — every caller
# in this bundle discards it.
# Path of the `Authorization:` header file `install-hooks --apply` writes
# (0600, inside the 0700 data dir). Printed only when readable.
ai_memory_auth_header_file() {
    _amhf="$(ai_memory_state_dir)/auth-header"
    [ -r "$_amhf" ] && printf '%s' "$_amhf"
}

# Mint the key before the first POST so an ambiguous delivery and its spool
# replay carry the same identity. The server can then discard a replay whose
# original response was lost after the observation committed.
ai_memory_ingest_key() {
    _amrnd=$(od -An -N8 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n')
    [ -n "$_amrnd" ] || _amrnd=$(printf '%s%s' "$(date +%s 2>/dev/null || printf '0')" "$$")
    printf 'sh%s' "$_amrnd"
}

ai_memory_url_with_ingest_key() {
    case "$1" in
        *\?ingest_key=* | *\&ingest_key=*) printf '%s' "$1" ;;
        *\?*) printf '%s&ingest_key=%s' "$1" "$(ai_memory_ingest_key)" ;;
        *) printf '%s?ingest_key=%s' "$1" "$(ai_memory_ingest_key)" ;;
    esac
}

# AI_MEMORY_CAPTURE_OWNER names an external producer of this session's capture
# events. Non-blank claims ownership; unset, empty and whitespace-only keep
# capture on. The value is only ever tested, never printed or sent.
ai_memory_capture_owned_externally() {
    case "${AI_MEMORY_CAPTURE_OWNER:-}" in
        *[![:space:]]*) return 0 ;;
        *) return 1 ;;
    esac
}

ai_memory_post_hook() {
    # Every shell hook produces its event here, and the spool and piggyback
    # drain hang off the result below, so this one check suppresses all three.
    # Delivery is untouched: an explicit ai_memory_drain_spool still ships the
    # backlog. Stdin is drained so the caller's pipe does not take an EPIPE.
    if ai_memory_capture_owned_externally; then
        cat >/dev/null 2>&1 || true
        return 0
    fi
    case "$1" in
        *"$AI_MEMORY_SERVER_ROUTED_QS"*|*'ai_memory_invalid_home_routes=1'*) cat >/dev/null; return 0 ;;
    esac
    _amurl=$(ai_memory_url_with_ingest_key "$1")
    _ambody=$(cat)
    _amhdr=$(ai_memory_auth_header_file || printf '')
    if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
        _amcode=$(printf '%s' "$_ambody" | curl -s --noproxy '*' --max-time 0.2 -H "X-AI-Memory-Client: hook-sh" -o /dev/null \
            -w '%{http_code}' -X POST "$_amurl" \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer $AI_MEMORY_AUTH_TOKEN" \
            --data-binary @- 2>/dev/null) || _amcode=000
    elif [ -n "$_amhdr" ]; then
        # `-H @file`: curl reads the header from disk, so the bearer never
        # appears in curl's argv the way an inline `-H` would (#552).
        _amcode=$(printf '%s' "$_ambody" | curl -s --noproxy '*' --max-time 0.2 -H "X-AI-Memory-Client: hook-sh" -o /dev/null \
            -w '%{http_code}' -X POST "$_amurl" \
            -H "Content-Type: application/json" \
            -H @"$_amhdr" \
            --data-binary @- 2>/dev/null) || _amcode=000
    else
        _amcode=$(printf '%s' "$_ambody" | curl -s --noproxy '*' --max-time 0.2 -H "X-AI-Memory-Client: hook-sh" -o /dev/null \
            -w '%{http_code}' -X POST "$_amurl" \
            -H "Content-Type: application/json" \
            --data-binary @- 2>/dev/null) || _amcode=000
    fi
    case "$_amcode" in
        2*) ai_memory_kick_drain ;;
        408|425|429) ai_memory_spool_event "$_amurl" "$_ambody" ;;
        4*) ;;
        *) ai_memory_spool_event "$_amurl" "$_ambody" ;;
    esac
    return 0
}

# GET "$1" with the same auth-header rules as `ai_memory_post_hook`.
# Used by `session-start.sh` to pull the cross-agent handoff before
# the resuming agent's first prompt. 1s budget — slightly more
# generous than POST because the result is *synchronously* fed to
# stdout (and prepended to the agent's context), so we want to avoid
# truncating a handoff that was almost ready.
# Every request in this bundle sends `X-AI-Memory-Client`: an unauthenticated
# server reached through a non-loopback host name refuses a handoff fetch
# without it, because a web page cannot add that header to a request it makes.
#
# The GET claims the newest open handoff in whatever project the server
# resolves. `ai_memory_marker_qs` adds `&cwd=` whenever the payload named a
# directory, so a URL without it names no project: the server would fall back
# to its default or the caller's last active project, and the claim could
# consume another repository's handoff. Fetch nothing then; the handoff stays
# open for memory_handoff_accept (parity with the native hook).
ai_memory_get_handoff() {
    case "$1" in
        *"$AI_MEMORY_SERVER_ROUTED_QS"*|*'ai_memory_invalid_home_routes=1'*) return 0 ;;
        *'&cwd='*) ;;
        *) return 0 ;;
    esac
    _amhdr=$(ai_memory_auth_header_file)
    if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
        curl -s --noproxy '*' --max-time 1.0 -H "X-AI-Memory-Client: hook-sh" "$1" \
            -H "Authorization: Bearer $AI_MEMORY_AUTH_TOKEN"
    elif [ -n "$_amhdr" ]; then
        curl -s --noproxy '*' --max-time 1.0 -H "X-AI-Memory-Client: hook-sh" "$1" -H @"$_amhdr"
    else
        curl -s --noproxy '*' --max-time 1.0 -H "X-AI-Memory-Client: hook-sh" "$1"
    fi
}

# GET the read-only subagent brief at URL "$1", with ai_memory_get_handoff's
# guards: a URL without `cwd`, or for a server-routed repository, is never
# sent. It keeps a name of its own because `/brief` claims nothing, while
# every ai_memory_get_handoff caller claims a baton.
ai_memory_get_brief() {
    ai_memory_get_handoff "$1"
}

# Encode stdin as a JSON string (with surrounding quotes). Used by hooks
# whose stdout contract is JSON rather than raw context text: Antigravity's
# PreInvocation hook and Claude Code's session-start hook (which wraps the
# handoff in hookSpecificOutput.additionalContext).
ai_memory_json_string() {
    awk '
        # BusyBox awk applies backslash processing to a gsub REPLACEMENT
        # string; gawk, mawk and one-true-awk pass it through literally. Every
        # replacement below carries a backslash, so on BusyBox all four escapes
        # were silently no-ops (#733): a backslash stayed bare, a quote stayed
        # bare, and -- not in the report, but the same root cause -- \t and \r
        # collapsed to the letters "t" and "r", corrupting content rather than
        # only breaking the framing.
        #
        # Detect the behaviour once instead of guessing at it, and pre-double
        # the replacements where they will be halved. Done with gsub rather
        # than a split/concat loop on purpose: concatenating per occurrence is
        # quadratic in the value length, which is the cost #727 was about.
        BEGIN {
            probe = "X"; gsub(/X/, "\\\\", probe)
            if (length(probe) == 1) {
                busybox = 1
                BS = "\\\\\\\\"; QT = "\\\\\""; TB = "\\\\t"; CR = "\\\\r"
                UP = "\\\\u"
            } else {
                busybox = 0
                BS = "\\\\"; QT = "\\\""; TB = "\\t"; CR = "\\r"
                UP = "\\u"
            }
            # JSON forbids a raw control character (U+0000..U+001F) inside a
            # string, but the four gsubs above only cover backslash, quote, tab
            # and CR — so a replayed tool result carrying e.g. an ANSI colour
            # escape (0x1b) reached stdout unescaped and Claude Code rejected
            # the whole SessionStart packet as invalid JSON (#732). Build a
            # \u00XX escape for every other control byte once; newline (0x0a) is
            # never inside a record, it is the record separator handled below.
            nc = 0
            for (c = 1; c < 32; c++) {
                if (c == 9 || c == 10 || c == 13) continue
                cc[++nc] = sprintf("%c", c)
                cr[nc] = sprintf("%s%04x", UP, c)
            }
            printf "\""
        }
        {
            gsub(/\\/, BS)
            gsub(/"/, QT)
            gsub(/\t/, TB)
            gsub(/\r/, CR)
            # After the backslash gsub, so the backslashes these introduce are
            # not doubled. Each control byte is a literal (none is a regex
            # metacharacter), and the pass is linear, not the per-char loop #727
            # replaced.
            for (k = 1; k <= nc; k++) gsub(cc[k], cr[k])
            printf "%s%s", sep, $0
            sep = "\\n"
        }
        END { printf "\"" }
    '
}

# --- offline spool -----------------------------------------------------
# A failed delivery is written to `<data_dir>/hook-spool/` in the same
# on-disk contract `ai-memory hook-drain` reads (same filenames, same
# `SpoolEntry` JSON, same 0600/0700 modes, tmp+rename), so an unreachable
# or erroring server costs latency instead of the event. The generated
# TypeScript integrations gained this in #580; the script bundle is the
# remaining capture path that POSTs and forgets.
#
# The backlog is drained at session boundaries and, after any successful
# 2xx POST, by the detached piggyback drain in ai_memory_kick_drain —
# never synchronously on the per-tool-call hot path, which must not block
# the agent.

ai_memory_spool_dir() {
    printf '%s/hook-spool' "$(ai_memory_state_dir)"
}

# Unix milliseconds. `date +%s%N` gives nanoseconds on GNU (and the width
# modifier `%3N` is not honoured everywhere, so it is not used); BSD/macOS
# date leaves a literal `N`. Anything that is not a long enough run of digits
# falls back to whole seconds, which keeps filenames ordered and parseable.
ai_memory_now_ms() {
    _amnow=$(date +%s%N 2>/dev/null || printf '')
    case "$_amnow" in
        '' | *[!0-9]*) _amnow='' ;;
    esac
    if [ -n "$_amnow" ] && [ "${#_amnow}" -ge 13 ]; then
        _amnow=$(printf '%s' "$_amnow" | cut -c1-13)
    else
        _amnow="$(date +%s 2>/dev/null || printf '0')000"
    fi
    printf '%s' "$_amnow"
}

# The bearer a drain should replay this event with, or empty for none.
ai_memory_spool_token() {
    if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
        printf '%s' "$AI_MEMORY_AUTH_TOKEN"
        return 0
    fi
    _amtf=$(ai_memory_auth_header_file || printf '')
    [ -n "$_amtf" ] || return 0
    sed -n 's/^[Aa]uthorization:[[:space:]]*[Bb]earer[[:space:]]*//p' "$_amtf" \
        | head -n 1 | tr -d '\r\n'
}

# Persist one undelivered event. Best-effort on top of best-effort capture:
# every failure path returns 0 so a hook never fails because of the spool.
ai_memory_spool_event() {
    _amsurl=$(ai_memory_url_with_ingest_key "$1")
    _amsbody="$2"
    _amsdir=$(ai_memory_spool_dir)
    mkdir -p "$_amsdir" 2>/dev/null || return 0
    chmod 700 "$_amsdir" 2>/dev/null || true
    _amstok=$(ai_memory_spool_token)
    _amsnow=$(ai_memory_now_ms)
    AI_MEMORY_SPOOL_SEQ=$((${AI_MEMORY_SPOOL_SEQ:-0} + 1))
    _amsname=$(printf '%013d-%s-%016x.json' "$_amsnow" "$$" "$AI_MEMORY_SPOOL_SEQ")
    (
        umask 077
        {
            printf '{"url":'
            printf '%s' "$_amsurl" | ai_memory_json_string
            printf ',"body":'
            printf '%s' "$_amsbody" | ai_memory_json_string
            printf ',"created_ms":%s' "$_amsnow"
            if [ -n "$_amstok" ]; then
                printf ',"auth_mode":"static","token":'
                printf '%s' "$_amstok" | ai_memory_json_string
            else
                printf ',"auth_mode":"none"'
            fi
            printf ',"attempts":0}'
        } >"$_amsdir/$_amsname.tmp" 2>/dev/null
    ) || return 0
    mv -f "$_amsdir/$_amsname.tmp" "$_amsdir/$_amsname" 2>/dev/null \
        || rm -f "$_amsdir/$_amsname.tmp" 2>/dev/null
    return 0
}

# Read one top-level string field out of a spool entry, undoing the escapes
# `ai_memory_json_string` produces. The regex is the JSON string grammar, so
# the match ends at the first quote that is not escaped, which is the only
# correct way to find the end. `match` itself cannot fail — the pattern accepts
# the empty string — so the terminator check on the line after it is what
# rejects an unterminated value, and dropping that line drops the check. An
# entry carrying a `\uXXXX` escape was written by a richer serializer (the
# native binary); this prints nothing for it so the caller leaves it to
# `ai-memory hook-drain`.
#
# Nothing accumulates: each segment goes straight to stdout. Appending into a
# string that grows to the whole value costs time quadratic in the number of
# appends, and that holds whether the step is one character or one
# escaped-backslash pair — a 2.2 MB entry of `grep` output over source, where
# every literal backslash is a pair, cost 36 s a pass that way under
# one-true-awk. A drain pass reads every eligible entry four times and one detached
# pass starts behind every delivery that succeeds, so the cost is paid over
# and over.
#
# Splitting on the escaped-backslash pairs first is what makes the unescaping
# safe: no segment can contain one, so inside a segment every backslash starts
# a real escape and no placeholder byte is needed, which keeps a raw control
# byte in the value (`ai_memory_json_string` does not escape those)
# round-tripping untouched. Validation is a pass of its own so that a declined
# value prints nothing at all — a partial read must never look like a whole
# one to `ai_memory_drain_spool`, which reads the field through `|| continue`.
ai_memory_json_field() {
    awk -v key="$1" '
        { text = text (NR > 1 ? "\n" : "") $0 }
        END {
            needle = "\"" key "\":\""
            start = index(text, needle)
            if (start == 0) exit 1
            rest = substr(text, start + length(needle))
            match(rest, /^(\\.|[^"\\])*/)
            if (substr(rest, RSTART + RLENGTH, 1) != "\"") exit 1
            parts = split(substr(rest, RSTART, RLENGTH), seg, /\\\\/)
            for (i = 1; i <= parts; i++)
                if (seg[i] ~ /\\[^ntr"\/]/) exit 1
            for (i = 1; i <= parts; i++) {
                gsub(/\\n/, "\n", seg[i])
                gsub(/\\t/, "\t", seg[i])
                gsub(/\\r/, "\r", seg[i])
                gsub(/\\"/, "\"", seg[i])
                gsub(/\\\//, "/", seg[i])
                printf "%s%s", (i == 1 ? "" : "\\"), seg[i]
            }
            exit 0
        }
    ' "$2"
}

# Deliver the queued backlog, oldest first. Bounded by count so a drain never
# becomes an unbounded upload. A 2xx or terminal 4xx retires the entry (delivered,
# or permanently rejected); transient 408/425/429 or anything else stops the pass
# and keeps the remainder for the next one. The bearer goes through a 0600 header file
# rather than curl's argv, for the reason #552 moved it off the command line.
ai_memory_drain_spool() {
    _amdmax=${1:-64}
    _amddir=$(ai_memory_spool_dir)
    [ -d "$_amddir" ] || return 0
    _amdn=0
    for _amdf in "$_amddir"/*.json; do
        [ -f "$_amdf" ] || break
        [ "$_amdn" -lt "$_amdmax" ] || break
        _amdn=$((_amdn + 1))
        # OIDC entries have no inline bearer. Leave them for the native drain,
        # which can resolve/refresh auth.json, rather than POSTing anonymously.
        _amdmode=$(ai_memory_json_field auth_mode "$_amdf" 2>/dev/null) || _amdmode=''
        [ "$_amdmode" = oidc ] && continue
        _amdurl=$(ai_memory_json_field url "$_amdf" 2>/dev/null) || continue
        [ -n "$_amdurl" ] || continue
        _amdbody=$(ai_memory_json_field body "$_amdf" 2>/dev/null) || continue
        _amdtok=$(ai_memory_json_field token "$_amdf" 2>/dev/null) || _amdtok=''
        if [ -n "$_amdtok" ]; then
            _amdhdr="$_amddir/.drain-header.$$"
            (umask 077; printf 'Authorization: Bearer %s\n' "$_amdtok" >"$_amdhdr") 2>/dev/null || continue
            _amdcode=$(printf '%s' "$_amdbody" | curl -s --noproxy '*' --max-time 2.0 -H "X-AI-Memory-Client: hook-sh" -o /dev/null \
                -w '%{http_code}' -X POST "$_amdurl" \
                -H "Content-Type: application/json" -H @"$_amdhdr" \
                --data-binary @- 2>/dev/null) || _amdcode=000
            rm -f "$_amdhdr" 2>/dev/null || true
        else
            _amdcode=$(printf '%s' "$_amdbody" | curl -s --noproxy '*' --max-time 2.0 -H "X-AI-Memory-Client: hook-sh" -o /dev/null \
                -w '%{http_code}' -X POST "$_amdurl" \
                -H "Content-Type: application/json" \
                --data-binary @- 2>/dev/null) || _amdcode=000
        fi
        case "$_amdcode" in
            408|425|429) return 0 ;;
            2*|4*) rm -f "$_amdf" 2>/dev/null || true ;;
            *) return 0 ;;
        esac
    done
    return 0
}

# Piggyback drain: a delivery that just succeeded proves the server is
# reachable, so flush the backlog behind it. Detached from the hook's own
# process so the agent never waits, and a no-op when nothing is queued —
# which is every call on a healthy install.
ai_memory_kick_drain() {
    _amkdir=$(ai_memory_spool_dir)
    [ -d "$_amkdir" ] || return 0
    set -- "$_amkdir"/*.json
    [ -f "$1" ] || return 0
    (ai_memory_drain_spool 64 >/dev/null 2>&1 &) 2>/dev/null || true
    return 0
}