@gaunt-sloth/core 2.0.0-alpha.9 → 2.0.0-beta.0

package/dist/utils/redactSecrets.js

@@ -0,0 +1,286 @@
+/**
+ * @packageDocumentation
+ * GS2-47 — a shared, reusable secret-redaction pass for diagnostic output.
+ *
+ * Built for `/debug-dump` ({@link file://./debugDump.ts}) but deliberately generic and
+ * dependency-free — it takes `env` as a PARAMETER rather than reading `process.env`, so the pass is
+ * pure, deterministic in tests, and reusable by GS2-48's crash-report handler (which hard-depends on
+ * this module). Nothing here reads ambient process state.
+ *
+ * DESIGN DECISION (settled by the coordinator, GS2-47): **PATTERN-ONLY** redaction — we do NOT scan
+ * for high-entropy strings. Rationale: pattern-only is safe to reason about and near-zero
+ * false-positive; entropy scanning catches marginally more but produces false-positive redactions
+ * the user has to squint through, degrading the dump's debug value. A high-entropy scanner is a
+ * DELIBERATELY-DEFERRED option (a config surface for it could be added later if ever warranted) and
+ * is intentionally NOT implemented here.
+ *
+ * Three techniques, in priority order:
+ *  1. [load-bearing] Known-secret VALUE substitution — collect the literal values of secret-named
+ *     env vars + inline config secrets, then substitute every occurrence across ALL artifacts. This
+ *     catches a leaked key wherever it surfaces (config, env, transcript, log) with no guessing.
+ *  2. Provider key/token PATTERNS — a tight, documented, prefix-anchored set of well-known key
+ *     shapes plus explicit auth-header contexts. We never blanket-redact long alphanumeric strings.
+ *  3. Sensitive config-FIELD masking — mask the VALUES of secret-named config keys while preserving
+ *     structure (the key stays; only the value becomes the marker).
+ *
+ * Fail-safe throughout: on any internal error the functions redact MORE (return the marker), never
+ * less — a redaction hiccup must never cause raw content to be emitted.
+ */
+/** The visible, greppable placeholder substituted for every redacted secret value. */
+export const REDACTED = '<redacted>';
+/**
+ * Minimum length for a collected VALUE to be treated as a substitutable secret literal (technique
+ * 1). Guards against redacting trivial values ("1", "on", a short model name) that happen to be the
+ * value of a secret-named env var — substituting those everywhere would gut the dump's debug value
+ * with false positives (exactly the trap the pattern-only decision avoids). Short sensitive *config*
+ * fields are still masked structurally by key name (technique 3), so nothing sensitive slips through
+ * this floor.
+ */
+const MIN_SECRET_LITERAL_LENGTH = 6;
+/** Max recursion depth for the config walks — a guard against pathological/deep object graphs. */
+const MAX_REDACT_DEPTH = 12;
+/**
+ * env-var NAME shapes whose VALUE is a secret to substitute everywhere (technique 1): `*_API_KEY`,
+ * `*_TOKEN`, `*_SECRET`, `*_KEY`, and anything containing `PASSWORD`. Case-insensitive.
+ */
+const SECRET_ENV_NAME_RE = /(?:_API_KEY|_TOKEN|_SECRET|_KEY)$|PASSWORD/i;
+/**
+ * Config-FIELD NAME shapes whose VALUE is masked in place (technique 3), matched case-insensitively
+ * at any depth. Mirrors `configCommand.ts`'s `redactConfigForPrint` set for cross-surface
+ * consistency. NOTE: `apiKeyEnvironmentVariable` also matches `api?key`, but it holds a var NAME
+ * (not a secret) and is what technique 1 reads to find the real key's value — so it is EXCLUDED via
+ * {@link NON_SECRET_KEY_NAMES}.
+ */
+const SECRET_KEY_RE = /(api[-_]?key|secret|token|password|passwd|authorization|bearer|credential)/i;
+/** Field names that match {@link SECRET_KEY_RE} but must NOT be masked (they hold a var name). */
+const NON_SECRET_KEY_NAMES = new Set(['apikeyenvironmentvariable']);
+/**
+ * GS2-66 (residual 1) — building blocks for the `Authorization`-header VALUE grammar. GS2-54 bounded
+ * the value to `<scheme?> <one token>` where a token is {@link AUTH_TOKEN}; a credential with a char
+ * OUTSIDE that charset (`clientid:secret`, `token="…"`, `k=v,k=v`, Digest `response="…"`) left a raw
+ * tail beside the marker. These fragments extend the value across the STRUCTURED credential
+ * components (colon-joined `id:secret`, quoted `k="v"`, comma/semicolon-separated param lists) WITHOUT
+ * re-introducing the greedy prose-swallow GS2-47 removed: horizontal whitespace only (`[ \t]`, never
+ * a newline), a tight colon (no surrounding ws), and a param-continuation (`,` or `;`) whose atom must
+ * be *param-shaped* (contain `=` or be quoted) so `Authorization: … ; then we retried` keeps its prose.
+ */
+// A credential "word": the same token charset the SigV4 / standalone-`Bearer` rules already use.
+const AUTH_TOKEN = String.raw `[A-Za-z0-9._~+/=-]+`;
+// A quoted credential value (`"…"` / `'…'`) that never spans a newline — `k="v"` params + bare quotes.
+const AUTH_QUOTED = String.raw `"[^"\n]*"|'[^'\n]*'`;
+// One credential atom: a token optionally glued to a quoted value (`token="…"`), or a bare quote.
+const AUTH_ATOM = `(?:${AUTH_TOKEN}(?:${AUTH_QUOTED})?|${AUTH_QUOTED})`;
+// A colon-joined chain (`clientid:secret`); the colon is TIGHT (no surrounding whitespace) so a
+// following `Header: value` pair or a prose colon on the same line is not chained in.
+const AUTH_COLON_CHAIN = `${AUTH_ATOM}(?::${AUTH_ATOM})*`;
+// A `,`- or `;`-separated PARAM continuation (`, key2=v2`; `;key2=v2`; Digest `, realm="…"`): the atom
+// after the separator must be param-shaped — `key=…` or quoted — so a `,`/`;` followed by prose is NOT
+// swallowed. (M1, GS2-71: `;` joined the accepted separators alongside `,`; the atom shape is unchanged,
+// so `Authorization: … ; then we retried` still keeps its prose — same as the `,` case always has.)
+const AUTH_PARAM = `(?:[A-Za-z0-9._~+/-]+=(?:${AUTH_QUOTED}|${AUTH_TOKEN})?|${AUTH_QUOTED})`;
+// The full value: an optional scheme word (`Bearer` / `ApiKey` / `Digest` / …) + horizontal ws, then
+// a colon-chain, then zero+ `,`- or `;`-separated params. The `(?!AWS4-HMAC-SHA256[ \t]+Credential=)`
+// lookahead excludes ONLY a genuine SigV4 header (scheme immediately followed by `Credential=`) — its
+// `SignedHeaders=…` is deliberately preserved, so it is owned solely by the Credential/Signature
+// rule. The guard is narrow ON PURPOSE: a malformed/bare `AWS4-HMAC-SHA256 <token>` (no
+// `Credential=`) still falls through here and IS redacted, so the "redact any scheme" contract holds.
+const AUTH_VALUE = `(?!AWS4-HMAC-SHA256[ \\t]+Credential=)(?:${AUTH_TOKEN}[ \\t]+)?${AUTH_COLON_CHAIN}` +
+    `(?:[ \\t]*[,;][ \\t]*${AUTH_PARAM})*`;
+// The header prefix (name + separator + optional opening quote), captured so `$1` is preserved. Its
+// `\s*` gaps CAN include a newline (over-redacts a value on the next line — SAFE direction, never a
+// leak); the VALUE above uses only horizontal ws and so never crosses a newline.
+const AUTH_HEADER_PREFIX = String.raw `(\bAuthorization["']?\s*[:=]\s*["']?)`;
+/**
+ * Provider key / auth-header PATTERNS (technique 2) — a tight, prefix-anchored set. Each entry is
+ * `[regex, replacement]`. Kept deliberately narrow (well-known key prefixes + explicit auth
+ * contexts); we do NOT blanket-redact long alphanumeric strings — that IS the entropy trap the
+ * pattern-only decision avoids. A long opaque token is only redacted when it sits in an auth context
+ * (`Bearer …` / `Authorization: …`), never on its own.
+ */
+const PROVIDER_PATTERNS = [
+    // OpenAI (`sk-…`) and Anthropic (`sk-ant-…`, also `sk-`-prefixed) secret keys.
+    [/\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}/g, REDACTED],
+    // Google API keys (`AIza…`).
+    [/\bAIza[0-9A-Za-z_-]{16,}/g, REDACTED],
+    // xAI (`xai-…`).
+    [/\bxai-[A-Za-z0-9_-]{16,}/g, REDACTED],
+    // Groq (`gsk_…`).
+    [/\bgsk_[A-Za-z0-9_-]{16,}/g, REDACTED],
+    // GS2-54 (gap 2) — GitHub tokens. Classic/scoped PATs share the `gh[oprsu]_` prefix (personal
+    // `ghp_`, OAuth `gho_`, user-to-server `ghu_`, server-to-server `ghs_`, refresh `ghr_`); the value
+    // is base62 (no `_`). Prefix-anchored + a length floor, same tight style as the provider keys —
+    // NOT a blanket long-alphanumeric redaction (that IS the entropy trap avoided).
+    [/\bgh[oprsu]_[A-Za-z0-9]{16,}/g, REDACTED],
+    // GS2-54 (gap 2) — GitHub fine-grained PATs (`github_pat_…`); the value carries an inner `_`, so
+    // its charset includes `_`. Distinct prefix from the classic rule above (`github_` ≠ `gh[oprsu]_`).
+    [/\bgithub_pat_[A-Za-z0-9_]{16,}/g, REDACTED],
+    // GS2-54 (gap 2) + GS2-66 (residual 2) — credentials embedded in a URL. Redact the whole userinfo
+    // (`user:password@` AND the colon-less bare-token form `opaquetoken@`, e.g. a PAT in a clone URL),
+    // KEEP the scheme + host so the artifact stays debuggable. GS2-54 required a `:` in the userinfo
+    // (`[^\s/@:]+:[^\s/@]+@`), so `https://opaquetoken@host` slipped through; the charset now allows the
+    // userinfo to include an internal `:` (or none) and simply stops at `@`. Bounded: userinfo can't
+    // contain `/` or whitespace, so it never swallows the rest of the URL/line. A URL WITHOUT userinfo
+    // (`https://host:port/path`) has no `@` after the authority and is left untouched.
+    [/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, `$1${REDACTED}@`],
+    // GS2-54 (gap 1) + GS2-66 (residual 1 & 4) — an `Authorization` header value
+    // (`Authorization: <scheme?> <credential>` / `"Authorization":"…"`): keep the header name +
+    // separator ($1), redact the value REGARDLESS OF SCHEME. Generalized beyond the old fixed
+    // `Bearer|Basic|Token|Digest|Negotiate` list so a non-standard scheme (`ApiKey <secret>`, an
+    // unknown scheme) no longer leaks its token beside the marker.
+    //
+    // GS2-66 extends the value across STRUCTURED credential components (see {@link AUTH_VALUE}):
+    // `clientid:secret`, `token="…"`, `k=v,k=v` / `k=v;k=v` lists and a Digest `response="…"` no longer
+    // leave a raw tail past the token charset. It still cannot swallow following PROSE: the credential
+    // body is horizontal-whitespace-only and a `,`/`;` param-continuation must be param-shaped (GS2-47
+    // invariant, preserved by GS2-71's M1 widening of the separator to `[,;]`).
+    //
+    // NEWLINE precision (residual 4): the *credential body* uses only `[ \t]` and so never crosses a
+    // newline — but the header-PREFIX `\s*` gaps CAN span `\n` (`Authorization:\n<token>`), which
+    // over-redacts a next-line value in the SAFE direction (never a leak), not something this rule
+    // guards against. An optional value-quote is consumed so JSON `"Authorization":"…"` works too.
+    //
+    // A genuine SigV4 header is EXCLUDED here via `(?!AWS4-HMAC-SHA256[ \t]+Credential=)` (were it
+    // consumed, its intentionally-kept `SignedHeaders=…` would be eaten): SigV4 is owned entirely by
+    // the next rule, which redacts its `Credential=…`/`Signature=…` and leaves the scheme +
+    // `SignedHeaders` visible. The guard is scoped to a real SigV4 shape so a malformed bare-token
+    // `AWS4-HMAC-SHA256 <token>` is NOT let through unredacted. Runs before the standalone-`Bearer`
+    // rule so a normal header collapses to a single marker.
+    [new RegExp(AUTH_HEADER_PREFIX + AUTH_VALUE, 'gi'), `$1${REDACTED}`],
+    // GS2-54 (gap 1) — AWS SigV4 authorization components. The header is comma-separated `key=value`
+    // pairs; redact the SENSITIVE `Credential=…` (access-key id) and `Signature=…` values wherever they
+    // appear (header value OR a presigned-URL `X-Amz-Credential=…&X-Amz-Signature=…` query), keeping the
+    // key name for debuggability. `SignedHeaders=…` is just header names and is intentionally NOT
+    // touched. The value charset excludes whitespace/comma/quote/`&`, so it stops at the component
+    // boundary and never swallows the next pair or trailing prose.
+    [/\b(Credential|Signature)=[A-Za-z0-9._~+/=-]+/gi, `$1=${REDACTED}`],
+    // A standalone `Bearer <token>` — keep the scheme word, redact only the credential. A long opaque
+    // token is redacted ONLY in this auth context, never on its own (that is the entropy trap avoided).
+    [/\b(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi, `$1${REDACTED}`],
+];
+/**
+ * Collect the literal secret VALUES to substitute everywhere (technique 1), from two sources:
+ *  - process-env vars whose NAME matches {@link SECRET_ENV_NAME_RE}, PLUS the specific var(s) named
+ *    by any `apiKeyEnvironmentVariable` in the config;
+ *  - non-empty inline secret field values in the config (technique 3's field names), so a key pasted
+ *    inline is scrubbed wherever it *also* surfaces (transcript, log, env), not only in config.json.
+ *
+ * `env` is a PARAMETER — never read ambiently — so the pass is pure, reusable (GS2-48) and
+ * deterministic in tests. Values shorter than {@link MIN_SECRET_LITERAL_LENGTH} are skipped. The
+ * result is returned longest-first so an overlapping-substring secret can't leave a shorter one
+ * partially intact. Never throws (a hostile config getter is swallowed — patterns + structural
+ * masking still apply).
+ */
+export function collectSecretValues(config, env) {
+    const values = new Set();
+    const add = (v) => {
+        if (typeof v === 'string' && v.length >= MIN_SECRET_LITERAL_LENGTH)
+            values.add(v);
+    };
+    // (a) env vars whose NAME looks secret → their VALUE is a literal to scrub.
+    try {
+        for (const [name, value] of Object.entries(env ?? {})) {
+            if (SECRET_ENV_NAME_RE.test(name))
+                add(value);
+        }
+    }
+    catch {
+        // ignore — a broken env object is not fatal to redaction.
+    }
+    // (b) walk the config for `apiKeyEnvironmentVariable` (→ read that env var's value) and inline
+    //     secret-named field values.
+    const seen = new WeakSet();
+    const walk = (node, depth) => {
+        if (node === null || typeof node !== 'object' || depth > MAX_REDACT_DEPTH)
+            return;
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item, depth + 1);
+            return;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key.toLowerCase() === 'apikeyenvironmentvariable' && typeof value === 'string') {
+                add(env?.[value]); // resolve the NAMED env var's VALUE (the var name itself is not a secret)
+            }
+            else if (SECRET_KEY_RE.test(key) && !NON_SECRET_KEY_NAMES.has(key.toLowerCase())) {
+                add(value);
+            }
+            walk(value, depth + 1);
+        }
+    };
+    try {
+        walk(config, 0);
+    }
+    catch {
+        // fail safe: a hostile getter threw — we simply have fewer literals; patterns + structural
+        // masking still cover the artifacts. Never rethrow (redaction must not break the dump).
+    }
+    return [...values].sort((a, b) => b.length - a.length);
+}
+/**
+ * Redact a STRING: substitute every known literal secret value (technique 1, longest-first), then
+ * apply the provider key/auth patterns (technique 2). Never throws — on any error it returns the
+ * fully-withheld marker (fail safe: redact MORE, never emit the raw text). Applying it twice is
+ * safe (re-redacting already-redacted text is a no-op).
+ */
+export function redactText(text, secrets) {
+    try {
+        let out = text;
+        for (const secret of secrets) {
+            if (secret)
+                out = out.split(secret).join(REDACTED); // literal — no regex escaping needed
+        }
+        for (const [re, replacement] of PROVIDER_PATTERNS) {
+            out = out.replace(re, replacement);
+        }
+        return out;
+    }
+    catch {
+        return REDACTED; // fail safe
+    }
+}
+/**
+ * Deep-redact an arbitrary value for serialization: mask the VALUES of secret-named fields
+ * (technique 3 — structure preserved: the key stays, only its value becomes the marker) and run
+ * {@link redactText} over every string leaf (techniques 1 + 2). Circular refs are broken; functions
+ * and bigints are rendered the way `safeStringify` would, so the result is JSON-safe. Pure — never
+ * mutates the input. `apiKeyEnvironmentVariable` is intentionally NOT masked (it is a var name).
+ *
+ * Intended for the CONFIG artifact (where field-name masking is wanted). Non-config artifacts use
+ * {@link redactText} over their stringified form instead (literal + pattern only), so a legitimate
+ * `token`/`secret`-named field in tool output is not blanket-masked.
+ */
+export function redactValue(value, secrets) {
+    const seen = new WeakSet();
+    const walk = (node, depth) => {
+        if (typeof node === 'string')
+            return redactText(node, secrets);
+        if (typeof node === 'function')
+            return `[Function: ${node.name || 'anonymous'}]`;
+        if (typeof node === 'bigint')
+            return node.toString();
+        if (node === null || typeof node !== 'object')
+            return node;
+        if (seen.has(node))
+            return '[Circular]';
+        if (depth > MAX_REDACT_DEPTH)
+            return '[Truncated]';
+        seen.add(node);
+        if (Array.isArray(node))
+            return node.map((item) => walk(item, depth + 1));
+        const out = {};
+        for (const [key, val] of Object.entries(node)) {
+            if (SECRET_KEY_RE.test(key) && !NON_SECRET_KEY_NAMES.has(key.toLowerCase())) {
+                out[key] = REDACTED; // mask the value, keep the key — shape is part of the debug signal
+            }
+            else {
+                out[key] = walk(val, depth + 1);
+            }
+        }
+        return out;
+    };
+    return walk(value, 0);
+}
+//# sourceMappingURL=redactSecrets.js.map

package/dist/utils/redactSecrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redactSecrets.js","sourceRoot":"","sources":["../../src/utils/redactSecrets.ts"],"names":[],"mappings":"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"}

package/dist/utils/systemPromptNotes.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Shared code-mode system-prompt augmentations (GS2-27).
+ *
+ * These notes describe capabilities of the agent itself — the opt-in `run_shell_command` tool and
+ * the real filesystem cwd — rather than of any one graph builder, which is why they live in core
+ * rather than beside the agent that composes them: a note composed inside one backend is a note
+ * the next backend silently loses, the drift GS2-21 fixed for the main prompt.
+ */
+import type { McpServerInstruction } from '#src/core/types.js';
+import { type FilesystemToolsConfig } from '#src/config/filesystem-tools.js';
+/**
+ * EXT-26: the platform-agnostic tail shared by both {@link appendOsShellNote} branches.
+ *
+ * The recurring failure mode on non-POSIX hosts is not just wrong command NAMES but shell
+ * REDIRECTION quoting: a grouped/multi-line `echo` redirect on cmd.exe reported success yet wrote
+ * a 0-byte file. So on every platform we steer file creation/mutation to the built-in
+ * `write_file`/`edit_file` tools (which never touch the shell's quoting) and keep each shell
+ * command a single line. Kept short — this is prompt text an LLM reads, not documentation.
+ */
+export declare const OS_SHELL_GUIDANCE: string;
+/**
+ * EXT-26: append an OS + shell-dialect note to the composed code-mode system prompt.
+ *
+ * The model was never told its host OS or which shell `run_shell_command` uses, so on
+ * non-POSIX hosts it defaulted to POSIX idioms that fail (ran `ls` where cmd.exe has `dir`, a
+ * multi-line echo-redirect that wrote 0 bytes, a PowerShell here-string, `python -c` multi-line).
+ * This is ORTHOGONAL to the EXT-13/16/22 path-namespace notes: those say WHERE the model is (path
+ * form); this says WHAT shell it speaks (dialect). Backend-agnostic — the lean backend also exposes
+ * `run_shell_command`, so GS2-27 composes it in the shared path.
+ *
+ * The shell is derived from the SAME rule Node's `spawn(command, { shell: true })` uses — exactly
+ * how `run_shell_command` spawns (GthDevToolkit spawn) — so on `win32` it is cmd.exe (via
+ * `%ComSpec%`) and on POSIX it is `/bin/sh` (POSIX sh, NOT guaranteed bash). Computed from
+ * `process.platform` at call time so the text is correct per host. Returns the note alone when
+ * there is no base prompt. A single injection is authoritative (nothing in the base prompt
+ * contradicts shell dialect), so unlike EXT-22 no correction middleware is needed.
+ */
+export declare function appendOsShellNote(systemPrompt: string | undefined): string;
+/**
+ * EXT-13 (part b): append a real-cwd / path-model note to the composed code-mode system prompt.
+ *
+ * Code mode runs in REAL-path mode, so the filesystem tools and `run_shell_command` share one
+ * real-absolute-path namespace rooted at `cwd`. The shared `.gsloth.code.md` prompt already tells
+ * the model "the current working directory is provided to you separately"; this note is what
+ * provides it — without it the model assumes `/` is cwd and hands `/`-rooted paths to the real-fs
+ * shell. The cwd is injected dynamically (never baked into the .md). Backend-agnostic — the lean
+ * backend also runs real-fs code sessions and previously received NO cwd value, so GS2-27 composes
+ * it in the shared path. Returns the note alone when there is no base prompt.
+ */
+export declare function appendCwdNote(systemPrompt: string | undefined, cwd: string): string;
+/** GS2-35 — the configured Git co-author identity (both fields optional; each defaults on its own). */
+export interface CommitCoAuthor {
+    name?: string;
+    email?: string;
+}
+/**
+ * GS2-35/EXT-83: append the commit-writing rules to the composed code-mode system prompt.
+ *
+ * Gaunt Sloth has **no dedicated git-commit tool** — the agent commits by calling
+ * `run_shell_command` with `git commit`, composing the message (including any trailer) itself. That
+ * leaves three things it must be told, and all three live here because all three are about
+ * committing:
+ *
+ * 1. **WHO the co-author is.** Left unguided, models emit their own model name from trained habit,
+ *    which is factually wrong: the commit was produced by *Gaunt Sloth*, not by the model. The note
+ *    states the exact trailer to emit. EXT-83 — rather than enumerate model names not to write (a
+ *    denylist is stale the day a new vendor ships, and an enumeration beside a catch-all teaches the
+ *    model that the list is the rule), the correct name is SUPPLIED: the resolved
+ *    {@link ResolvedModelIdentity} decorates the DEFAULT name as `Gaunt Sloth (provider:model)`, so
+ *    the real model is named while the authorship stays Gaunt Sloth's.
+ * 2. **HOW the message reaches git.** A commit message passed inline in a double-quoted shell
+ *    argument is EXPANDED BY THE SHELL before git runs, so a message that quotes code the way
+ *    ordinary technical prose does is executed as a command. The note states that mechanism rather
+ *    than merely forbidding the construct — naming a construct without its mechanism has been
+ *    measured not to work. A file path carries no shell metacharacters, so the file form removes the
+ *    failure mode instead of asking the model to avoid it.
+ * 3. **HOW the change is staged.** Rule 2 leaves the message file untracked in the working tree at
+ *    `git add` time, so an unscoped `git add -A` / `git add .` / `git commit -a` sweeps it into the
+ *    commit and onto the pull request. The note states that mechanism, steers staging to named
+ *    paths, and allows the last resort for a change too large to enumerate only once the message
+ *    file is out of the tree — an escape hatch that kept the file would reintroduce exactly the
+ *    defect the rule closes. It binds at `git add` time, MID-flow while the model is still acting,
+ *    because the tidy-up step at the end is the one that gets dropped. The scratchpad sentence
+ *    beside it names NO path: the write tool refuses any path outside the working folder at every
+ *    approval mode, so naming one buys a refused call. EXT-97 is the interim mitigation; the
+ *    mechanism that owns the file end to end is EXT-93.
+ *
+ * **The clause that names the writing tool is gated on `filesystem`** (EXT-84), through the one
+ * shared derivation {@link isWriteFileToolRegistered} — the same interpretation that decides which
+ * tools are actually registered. Naming an unregistered tool while forbidding both the shell
+ * fallback and the inline flag leaves the model NO compliant path, and its likeliest recovery is
+ * the inline form this note exists to prevent. So when the write tool is registered the note names
+ * it literally (the overwhelmingly common case, and a literal name is what makes the instruction
+ * actionable); when it is not, the note names no tool, keeps both prohibitions and the file form,
+ * and supplies the compliant path that remains: do not commit, and hand the message back to the
+ * user. That branch states no availability claim of its own — the backends read the same
+ * `filesystem` value but register filesystem tools differently, so a note asserting "you have no
+ * file-writing tool" could be flatly false on one of them.
+ *
+ * The note's prose carries **no backtick and no other markup** — including no angle-bracket
+ * placeholder: it is the one piece of guidance whose subject is how to write a commit message, so
+ * quoting its own examples in backticks would demonstrate the exact style rule 2 exists to stop, and
+ * an angle-bracket placeholder copied literally is itself a shell input redirect. The `<email>` of
+ * the trailer line is the exception the RFC form requires, and is scoped out of the scan.
+ *
+ * The identity is config-driven (`commit.coAuthor` in {@link import('#src/config/types.js').GthConfig}).
+ * Each field falls back INDEPENDENTLY to the Gaunt Sloth account
+ * ({@link DEFAULT_COMMIT_CO_AUTHOR_NAME} / {@link DEFAULT_COMMIT_CO_AUTHOR_EMAIL}) — so a partial
+ * override (name only, or a config that bypassed the loader) still yields a complete trailer, and a
+ * fully-absent config yields the default account. Blank/whitespace values are treated as unset. An
+ * EXPLICITLY CONFIGURED name is emitted verbatim, with no identity spliced in — the user asked for
+ * that string; the identity decorates only the default. An unresolvable identity (`undefined`) falls
+ * back to the plain default name, never to a placeholder.
+ *
+ * Backend-agnostic: composed through the shared code path, so any backend injects it (the
+ * git-commit capability rides on `run_shell_command`, exposed in code mode). Returns the note alone
+ * when there is no base prompt.
+ */
+export declare function appendCommitCoAuthorNote(systemPrompt: string | undefined, coAuthor?: CommitCoAuthor, modelIdentity?: ResolvedModelIdentity, filesystem?: FilesystemToolsConfig): string;
+/**
+ * GS2-34/GS2-53 — the resolved active-model identity, as a STRUCTURED value.
+ *
+ * `hasProvider` is the authoritative "a real provider half was resolved" signal — carried
+ * explicitly rather than inferred from `identity.includes(':')`, because a bare model name can
+ * itself contain a colon (e.g. an Ollama/HF tag `gemma3:27b`) and would otherwise be mistaken for a
+ * `provider:model` string. It is true iff a non-empty provider (configured `type` OR a non-empty
+ * `_llmType()`) formed the leading `provider:` segment; false when `identity` is the bare model.
+ */
+export interface ResolvedModelIdentity {
+    /** `provider:model` when a provider resolved, otherwise the bare `model`. */
+    identity: string;
+    /** True iff a real provider formed the `provider:` segment (never merely a colon in the model). */
+    hasProvider: boolean;
+}
+/**
+ * GS2-34: resolve the active model identity from the effective config, for injection into the
+ * system prompt by {@link appendModelContextNote}.
+ *
+ * Both halves are read the SAME way the rest of gsloth already surfaces the active model:
+ *   - MODEL: `config.modelDisplayName` (the string the status line renders — set by the loader from
+ *     `llm.model`), falling back to the live model's own `model` field.
+ *   - PROVIDER: the configured `config.modelProviderType` (the raw `llm.type` the loader stashed —
+ *     `openrouter`/`deepseek`/`xai`/`anthropic`/…) when present, otherwise the live LangChain
+ *     model's `_llmType()` (the source the AG-UI `/info` endpoint reports). GS2-53 — preferring the
+ *     configured `type` is what stops a provider being labelled with the client it happens to be
+ *     built on: `_llmType()` is the model CLASS's own label and does not track the gth provider
+ *     namespace, so `huggingface` (a `ChatOpenAI` aimed at the HF router) reports `openai`, and
+ *     `google-genai` and `vertexai` both report `google`. It is also the safer source in general:
+ *     `_llmType()` is the model class's opinion, while the `type` is
+ *     the user's own declaration, so a provider swapped onto a different client (as `openrouter`
+ *     was) keeps its configured label without this file needing to know. The `type` is absent for
+ *     module configs (which
+ *     hand us an already-built LLM), where we fall back to `_llmType()` unchanged. The MODEL half is
+ *     always exact.
+ *
+ * Returns `{ identity: 'provider:model', hasProvider: true }` when both resolve, `{ identity:
+ * 'model', hasProvider: false }` when only the model resolves, and `undefined` when the model is
+ * unknown (a provider with no model is not a usable identity) — in which case {@link
+ * appendModelContextNote} injects nothing, leaving the prompt exactly as before. `hasProvider` is
+ * the authoritative provider-present flag (GS2-53), so a bare model whose NAME contains a colon
+ * (e.g. `gemma3:27b`) is correctly reported as `hasProvider: false`. `_llmType()` is called
+ * defensively (guarded) so a provider whose accessor throws can never break prompt assembly (and is
+ * skipped entirely when a configured `type` is present).
+ */
+export declare function resolveModelIdentity(config: {
+    llm?: {
+        _llmType?: () => string;
+        model?: string;
+    };
+    modelDisplayName?: string;
+    modelProviderType?: string;
+} | null | undefined): ResolvedModelIdentity | undefined;
+/**
+ * GS2-34: append the active model-identity note to the composed system prompt.
+ *
+ * The agent otherwise has no reliable knowledge of which `provider:model` is serving it, so it
+ * cannot answer "what model are you?" accurately or reason about its own capabilities/limits. This
+ * injects a single first-party line naming the resolved identity (see {@link resolveModelIdentity}).
+ *
+ * Injected in EVERY mode (chat/ask/code/exec), NOT gated to `code` like the cwd/os-shell/commit
+ * notes: "which model are you?" can be asked in any session, so the identity must be visible
+ * everywhere. Config-gated by `injectModelContext` (default ON): a caller passes an `undefined`
+ * `modelIdentity` — because the config opted out (`injectModelContext: false`) or because no model
+ * could be resolved — and the base prompt is returned UNCHANGED (no line), preserving the current
+ * prompt byte-for-byte.
+ *
+ * A short capability note from the GS2-6 model catalog is a DEFERRED follow-up (GS2-6 has not
+ * landed): this injects the bare `provider:model` identity only.
+ */
+export declare function appendModelContextNote(systemPrompt: string | undefined, modelIdentity: ResolvedModelIdentity | undefined): string | undefined;
+/**
+ * EXT-32: hard per-server cap on injected MCP instruction length.
+ *
+ * A connected MCP server could advertise a very long `instructions` string that would then ride
+ * along in EVERY turn's system prompt and bloat context. This is a simple defensive constant (no
+ * config-schema plumbing — that stays out of this node): text beyond the cap is dropped and a
+ * truncation marker is appended so the model knows it was clipped. Generous enough that realistic
+ * server instructions pass through untouched.
+ */
+export declare const MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER = 4000;
+/** EXT-32: truncation marker appended when a server's instructions exceed the per-server cap. */
+export declare const MCP_INSTRUCTIONS_TRUNCATION_MARKER = "\u2026 [truncated]";
+/**
+ * EXT-32: append connected MCP servers' discovery `instructions` to the composed system prompt.
+ *
+ * Each connected MCP server may return an `instructions` string in its `initialize` handshake that
+ * describes how to use its tools. We surface those to the model — but the text is **server-supplied
+ * and therefore a prompt-injection surface**, so it is:
+ *   - fenced in an explicit `[BEGIN/END MCP SERVER-PROVIDED CONTEXT]` block (never blended into
+ *     first-party prompt text),
+ *   - labelled per server (`--- Server: "name" ---`) so the model can attribute each block, and
+ *   - bracketed by a leading framing line AND a trailing first-party reassertion, so the LAST thing
+ *     the model reads is gsloth's own authority, not the server text — server instructions may not
+ *     override the system instructions, safety rules, or the user's directives.
+ *
+ * Backend-agnostic: composed through the shared path, so any backend injects it.
+ * Empty/absent contributes NOTHING: when no server supplied
+ * (non-whitespace) instructions the base prompt is returned unchanged — no empty header, no dangling
+ * label. Each server's text is trimmed and capped at {@link MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER}.
+ * Returns the block alone when there is no base prompt.
+ */
+export declare function appendMcpServerInstructionsNote(systemPrompt: string | undefined, instructions: McpServerInstruction[] | undefined): string | undefined;