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

package/.gsloth.review.md

@@ -8,6 +8,8 @@ Please categorize your feedback (e.g., "Bug," "Suggestion," "Nitpick").
 Important! In the end, conclude if you would recommend approving this PR or not.
 Use ✅⚠️❌ symbols to highlight your feedback appropriately.
 
+Important! Do not speculate about version numbers of dependencies and workflows, specifically about versions which you think do not exist yet — you have knowledge cut-off, and you can't know which versions were released since then.
+
 Finish with a short 1-2 sentence summary that captures the overall state of the review.
 
 Thank you for your thorough review!

package/README.md

@@ -1,34 +1,85 @@
 # @gaunt-sloth/core
 
-Core utilities and types for Gaunt Sloth.
+The foundation layer of Gaunt Sloth: the configuration system (`GthConfig`, config discovery and
+loading, the JSON schema), the LLM provider factory (anthropic, deepseek, google-genai, groq,
+huggingface, ollama, openai, openrouter, vertexai, xai, fake), the lean LangChain agent runtime
+(`GthAgentRunner`), session history, and the shared utility modules (`consoleUtils`,
+`systemUtils`, `fileUtils`, `llmUtils`, …).
 
-## Contents
+**When to depend on this package** — you are embedding a piece of Gaunt Sloth (or building your
+own front-end on its infrastructure) and need its config resolution and provider wiring without
+the CLI. Every other `@gaunt-sloth/*` package builds on it. If you just want to use Gaunt Sloth
+from the terminal, install the [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) app
+instead.
 
-- Configuration system (`GthConfig`, `RawGthConfig`, config loading and post-processing)
-- Agent infrastructure: `GthLangChainAgent`, `GthAgentRunner`
-- LLM provider wrappers: anthropic, deepseek, google-genai, groq, openai, openrouter, vertexai, xai, fake
-- Utility modules: `consoleUtils`, `debugUtils`, `fileUtils`, `llmUtils`, `systemUtils`, `stringUtils`, `aiignoreUtils`, `binaryOutputUtils`, `vertexaiUtils`, `globalConfigUtils`, `ProgressIndicator`
-- State and artifact storage: `artifactStore`
-- Shared constants and types
+## Installation
 
-AI vendor packages are not direct dependencies. Each vendor package is an optional peer dependency, resolved at runtime by whichever consumer (e.g. `gaunt-sloth`) pulls them in.
+AI vendor packages are optional peer dependencies — install the provider(s) your configuration
+uses alongside core:
 
-## Dependencies
-
-No other `@gaunt-sloth/*` packages.
+```bash
+npm install @gaunt-sloth/core @langchain/anthropic
+```
 
-## Exports
+## Embedding: resolve config into a live model
 
-All modules are exported via the `./` export map pattern (`./*.js`), e.g.:
+I want my script to honour the user's `.gsloth.config.*` (provider, model, API keys) instead of
+hard-coding a vendor SDK. With a `.gsloth.config.json` such as
+`{ "llm": { "type": "anthropic", "model": "claude-sonnet-4-5" } }` in the working directory:
 
 ```js
-import { GthAgentRunner } from '@gaunt-sloth/core/agentRunner.js';
-import { display } from '@gaunt-sloth/core/utils/consoleUtils.js';
+import { initConfig } from '@gaunt-sloth/core';
+
+const config = await initConfig({}); // discovers .gsloth.config.* up-tree from cwd
+// config.llm is a live LangChain chat model built from that config
+const response = await config.llm.invoke('Say hello');
+console.log(response.text);
 ```
 
+When the configured provider has no API key anywhere — not in `llm.apiKey`, not in
+`llm.apiKeyEnvironmentVariable`, not in any variable that provider accepts — `initConfig` rejects
+with a `MissingProviderKeyError` carrying `provider` and `envVars`, so a caller running several
+configs can report which one lacked a secret and carry on with the rest. Use
+`isMissingProviderKeyError(error)` to recognise it.
+
+All config keys (providers, prompts, tools, per-command settings) are documented in
+[the configuration guide](https://github.com/pukeko-robotics/gaunt-sloth/blob/main/docs/configuration/index.md).
+
+## Exports
+
+- `@gaunt-sloth/core` (the root export) is the public API: config
+  (`initConfig`, `GthConfig`, defaults), constants, core types, the lean agent factory, model
+  discovery, and session history.
+- **A type the Zod schema declares is re-exported, so a value you can set is a value you can name.**
+  Some types in this package's public surface are declared by the schema rather than beside the
+  interface that uses them; those are re-exported from the root and from
+  `@gaunt-sloth/core/config.js` — `GthOutputHeaderRung`, the type of `GthConfig`'s `output.header`,
+  and `RawConfigValidationResult`, the interface `ConfigLayerValidationReport` extends. The schema's
+  runtime surface (`rawGthConfigSchema`, `generateConfigJsonSchema`, `validateRawGthConfig`,
+  `KNOWN_TOP_LEVEL_KEYS`, the deprecation scanners) is validator internals and is not part of the
+  root export; reach it through the deep path below if you need it.
+- **The approval and shell types are covered by the same rule, so a typed `ToolApprovalCallback`
+  needs no deep path.** Everything a `PendingToolInterrupt` hands that callback, and the tool
+  annotations `GthAgentInterface` reports, can be named from the root and from
+  `@gaunt-sloth/core/core/types.js`: `ApprovalSubject` with its `ShellApprovalSubject`,
+  `ToolApprovalSubject` and `McpToolApprovalSubject` variants, the rater's `ShellSafetyVerdict`,
+  `RaterOutcome` and `RaterNegotiationRound`, and `DeclaredToolAnnotations`. What
+  `GthAgentInterface` takes beyond those is config and follows the bullet above — `GthConfig` is
+  named from the root, not from that deep path.
+  These stay declared under `core/approvals/` and `core/shell/`, beside the code that decides them,
+  and the runtime surface there — the matcher and rater functions, and the closed vocabularies those
+  types are derived from — is not part of the root export.
+- `@gaunt-sloth/core/<path>.js` deep paths (e.g. `@gaunt-sloth/core/config.js`,
+  `@gaunt-sloth/core/utils/consoleUtils.js`) mirror the internal `dist/` layout 1:1 and are a
+  deliberate part of the contract — the other `@gaunt-sloth/*` packages and downstream consumers
+  import them directly. They are supported at your own risk: internal files can move between
+  alpha/minor versions without a deprecation cycle. Prefer the root export where it suffices.
+
+This package ships no binaries.
+
 ## Related packages
 
-- [`@gaunt-sloth/core`](../core) — Core utilities, config, and agent infrastructure (this package)
-- [`@gaunt-sloth/agent`](../agent) — Agent runtime: built-in tools, filesystem toolkit, middleware registry, API server, AG-UI, MCP, and A2A integration
-- [`@gaunt-sloth/review`](../review) — Review and Q&A modules with standalone CLI
-- [`gaunt-sloth`](../app) — Main CLI application
+- [`@gaunt-sloth/agent`](https://www.npmjs.com/package/@gaunt-sloth/agent) — Agent runtime: built-in tools, filesystem toolkit, middleware registry, API server, AG-UI, MCP, and A2A integration ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/agent))
+- [`@gaunt-sloth/review`](https://www.npmjs.com/package/@gaunt-sloth/review) — Review engine with content/requirement sources (GitHub, Jira, file, text) and standalone CLI ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/review))
+- [`@gaunt-sloth/batch`](https://www.npmjs.com/package/@gaunt-sloth/batch) — Batch / eval / workflow runtime ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/batch))
+- [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) — Main CLI application ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/app))

package/dist/config/colour.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CFG-30 — the single place that decides whether Gaunt Sloth emits ANSI colour.
+ *
+ * Everything this decision depends on arrives as an argument: no `process.env`, no `stdout`, no
+ * config merge. That keeps the ladder unit-testable rung by rung without touching process globals,
+ * and keeps the one mutation site ({@link setUseColour}, called from `mergeConfig`) unchanged.
+ */
+/** Everything the colour decision depends on. See {@link resolveUseColour}. */
+export interface UseColourInput {
+    /**
+     * Raw `FORCE_COLOR` environment value; `undefined` when the variable is not set at all.
+     * The empty string is a SET value (`FORCE_COLOR=` on the command line) and means colour on.
+     */
+    forceColor?: string;
+    /** Raw `NO_COLOR` environment value; `undefined` when the variable is not set at all. */
+    noColor?: string;
+    /**
+     * `useColour` as the user actually wrote it — read from the RAW config, BEFORE `DEFAULT_CONFIG`
+     * is merged in. `undefined` means the user set nothing, which is what rung 3 tests for; after the
+     * default merge an explicit `true` is indistinguishable from the default `true`, so this value
+     * must be captured pre-merge or the rung collapses.
+     */
+    explicitUseColour?: boolean;
+    /** Whether stdout is a terminal. Rung 4's auto-detection; stdout, not stdin. */
+    stdoutIsTTY: boolean;
+}
+/**
+ * Resolve the effective colour setting from the four-rung precedence ladder, highest wins:
+ *
+ *   1. `FORCE_COLOR` is set — `"0"` or `"false"` turn colour OFF, ANY other value (including the
+ *      empty string) turns it ON. This rung outranks everything below it, `NO_COLOR` included.
+ *   2. `NO_COLOR` is set and non-empty — colour OFF (the no-color.org convention: the variable's
+ *      presence is the signal, its value is not, but an empty value does not count as set).
+ *   3. `useColour` was set explicitly in config — use it verbatim.
+ *   4. Otherwise auto-detect — colour ON when stdout is a terminal, OFF when it is piped or
+ *      redirected, so captured output stays clean without any configuration.
+ */
+export declare function resolveUseColour(input: UseColourInput): boolean;

package/dist/config/colour.js

@@ -0,0 +1,36 @@
+/**
+ * CFG-30 — the single place that decides whether Gaunt Sloth emits ANSI colour.
+ *
+ * Everything this decision depends on arrives as an argument: no `process.env`, no `stdout`, no
+ * config merge. That keeps the ladder unit-testable rung by rung without touching process globals,
+ * and keeps the one mutation site ({@link setUseColour}, called from `mergeConfig`) unchanged.
+ */
+/**
+ * Resolve the effective colour setting from the four-rung precedence ladder, highest wins:
+ *
+ *   1. `FORCE_COLOR` is set — `"0"` or `"false"` turn colour OFF, ANY other value (including the
+ *      empty string) turns it ON. This rung outranks everything below it, `NO_COLOR` included.
+ *   2. `NO_COLOR` is set and non-empty — colour OFF (the no-color.org convention: the variable's
+ *      presence is the signal, its value is not, but an empty value does not count as set).
+ *   3. `useColour` was set explicitly in config — use it verbatim.
+ *   4. Otherwise auto-detect — colour ON when stdout is a terminal, OFF when it is piped or
+ *      redirected, so captured output stays clean without any configuration.
+ */
+export function resolveUseColour(input) {
+    // Rung 1 — FORCE_COLOR, the deliberate "I know what I am doing" override. Checked first so a
+    // user can force colour through a NO_COLOR inherited from their shell profile or a CI image.
+    if (input.forceColor !== undefined) {
+        return !(input.forceColor === '0' || input.forceColor === 'false');
+    }
+    // Rung 2 — NO_COLOR (no-color.org), honoured by chalk, ripgrep, fd and delta.
+    if (input.noColor !== undefined && input.noColor !== '') {
+        return false;
+    }
+    // Rung 3 — the user's own config. Only reachable with an explicit value, never the default.
+    if (input.explicitUseColour !== undefined) {
+        return input.explicitUseColour;
+    }
+    // Rung 4 — auto-detect.
+    return input.stdoutIsTTY;
+}
+//# sourceMappingURL=colour.js.map

package/dist/config/colour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colour.js","sourceRoot":"","sources":["../../src/config/colour.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAqB;IACpD,6FAA6F;IAC7F,6FAA6F;IAC7F,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,GAAG,IAAI,KAAK,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC;IACrE,CAAC;IAED,8EAA8E;IAC9E,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACxD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4FAA4F;IAC5F,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC,iBAAiB,CAAC;IACjC,CAAC;IAED,wBAAwB;IACxB,OAAO,KAAK,CAAC,WAAW,CAAC;AAC3B,CAAC"}

package/dist/config/configDiscovery.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @packageDocumentation
+ * The catchable error a config **load** raises when the configuration itself cannot be used. The
+ * cases, all one class on purpose:
+ *
+ * - an explicitly-named identity profile (or an `extends` base) that resolves to no config;
+ * - a `--config` path that does not exist;
+ * - a config layer present but malformed — a removed pre-2.0 shape, a bad approvals rule grammar,
+ *   a schema mismatch, an unresolvable `approvals.rater`;
+ * - a config that read fine but names no usable model — no `llm` block, no `llm.type`, an
+ *   `llm.type` with no provider module, or a provider module that cannot build from a JSON spec;
+ * - a provider instance that could not be constructed for a reason other than a missing API key
+ *   (that one is {@link MissingProviderKeyError}, which carries the key details);
+ * - no configuration file anywhere at all.
+ *
+ * Deliberately dependency-free (no imports beyond types) so the config barrel, the loader and
+ * downstream consumers can all reach it without an import cycle — the same shape
+ * `providerKeys.ts` uses for {@link MissingProviderKeyError}.
+ *
+ * **Why this is an error object and not a process exit.** Loading configuration is a *library*
+ * operation, and a library that terminates the process denies every caller the chance to classify
+ * the failure. `gth eval` in particular distinguishes a **harness** error (exit 2 — the suite could
+ * not be evaluated) from a **product** failure (exit 1 — the SUT ran and failed); a `process.exit(1)`
+ * inside config discovery collapses that contract, reporting a typo in `--judge` exactly as it
+ * reports a genuine regression. Callers that legitimately want to terminate — the CLI entry points —
+ * catch it at their top level, where the exit code is chosen deliberately.
+ *
+ * One class covers every case above on purpose: no caller needs to tell them apart (all of them mean
+ * "this configuration cannot be used"), and the fields carry whichever detail applies. Sub-classing
+ * per case would only push the callers back to the marker-list problem this class exists to end —
+ * a consumer that wants the underlying failure reads `cause`.
+ */
+/** What a config load knows about the configuration it could not use. */
+export interface ConfigDiscoveryDetails {
+    /**
+     * The explicitly-requested identity profile that did not resolve, when that is the failure.
+     * Undefined for a malformed-config failure, which is about a file rather than a profile name.
+     */
+    identityProfile?: string | undefined;
+    /**
+     * Human-readable source of the offending config layer (e.g. `.gsloth.config.json`,
+     * `.gsloth.config.json (global)`, `<name> (extends base)`), when a layer was read and rejected.
+     */
+    sourceLabel?: string | undefined;
+}
+/**
+ * A configuration could not be used: a named identity profile has no config, or a config layer is
+ * malformed.
+ *
+ * Thrown (never exited on) by the config loader, so `gth eval`, `gth batch`, the AG-UI/ACP servers
+ * and any embedding consumer can classify the failure and choose their own exit code.
+ */
+export declare class ConfigDiscoveryError extends Error implements ConfigDiscoveryDetails {
+    /** Duck-typed marker so {@link isConfigDiscoveryError} works across duplicated module copies. */
+    readonly gthConfigDiscoveryError: true;
+    readonly identityProfile: string | undefined;
+    readonly sourceLabel: string | undefined;
+    constructor(message: string, details?: ConfigDiscoveryDetails, options?: {
+        cause?: unknown;
+    });
+    /**
+     * Serialize the machine-readable half. `JSON.stringify(error)` would otherwise drop `message`
+     * (an Error's `message` is a non-enumerable own property), which is exactly the field a report
+     * consumer shows a human next to the profile or the file that failed.
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+    } & ConfigDiscoveryDetails;
+}
+/**
+ * True when `value` is a {@link ConfigDiscoveryError}.
+ *
+ * Duck-typed on the marker property rather than `instanceof` on purpose: a consumer that ends up
+ * with two copies of `@gaunt-sloth/core` on disk (a `file:` dep, a hoisting split) would fail an
+ * `instanceof` check against a genuinely-correct error and mis-handle a config failure as an
+ * unexpected crash — exactly the distinction this error exists to make.
+ */
+export declare function isConfigDiscoveryError(value: unknown): value is ConfigDiscoveryError;

package/dist/config/configDiscovery.js

@@ -0,0 +1,80 @@
+/**
+ * @packageDocumentation
+ * The catchable error a config **load** raises when the configuration itself cannot be used. The
+ * cases, all one class on purpose:
+ *
+ * - an explicitly-named identity profile (or an `extends` base) that resolves to no config;
+ * - a `--config` path that does not exist;
+ * - a config layer present but malformed — a removed pre-2.0 shape, a bad approvals rule grammar,
+ *   a schema mismatch, an unresolvable `approvals.rater`;
+ * - a config that read fine but names no usable model — no `llm` block, no `llm.type`, an
+ *   `llm.type` with no provider module, or a provider module that cannot build from a JSON spec;
+ * - a provider instance that could not be constructed for a reason other than a missing API key
+ *   (that one is {@link MissingProviderKeyError}, which carries the key details);
+ * - no configuration file anywhere at all.
+ *
+ * Deliberately dependency-free (no imports beyond types) so the config barrel, the loader and
+ * downstream consumers can all reach it without an import cycle — the same shape
+ * `providerKeys.ts` uses for {@link MissingProviderKeyError}.
+ *
+ * **Why this is an error object and not a process exit.** Loading configuration is a *library*
+ * operation, and a library that terminates the process denies every caller the chance to classify
+ * the failure. `gth eval` in particular distinguishes a **harness** error (exit 2 — the suite could
+ * not be evaluated) from a **product** failure (exit 1 — the SUT ran and failed); a `process.exit(1)`
+ * inside config discovery collapses that contract, reporting a typo in `--judge` exactly as it
+ * reports a genuine regression. Callers that legitimately want to terminate — the CLI entry points —
+ * catch it at their top level, where the exit code is chosen deliberately.
+ *
+ * One class covers every case above on purpose: no caller needs to tell them apart (all of them mean
+ * "this configuration cannot be used"), and the fields carry whichever detail applies. Sub-classing
+ * per case would only push the callers back to the marker-list problem this class exists to end —
+ * a consumer that wants the underlying failure reads `cause`.
+ */
+/** Marker property carried by every {@link ConfigDiscoveryError}; see {@link isConfigDiscoveryError}. */
+const CONFIG_DISCOVERY_MARKER = 'gthConfigDiscoveryError';
+/**
+ * A configuration could not be used: a named identity profile has no config, or a config layer is
+ * malformed.
+ *
+ * Thrown (never exited on) by the config loader, so `gth eval`, `gth batch`, the AG-UI/ACP servers
+ * and any embedding consumer can classify the failure and choose their own exit code.
+ */
+export class ConfigDiscoveryError extends Error {
+    /** Duck-typed marker so {@link isConfigDiscoveryError} works across duplicated module copies. */
+    gthConfigDiscoveryError = true;
+    identityProfile;
+    sourceLabel;
+    constructor(message, details = {}, options) {
+        super(message, options);
+        this.name = 'ConfigDiscoveryError';
+        this.identityProfile = details.identityProfile;
+        this.sourceLabel = details.sourceLabel;
+    }
+    /**
+     * Serialize the machine-readable half. `JSON.stringify(error)` would otherwise drop `message`
+     * (an Error's `message` is a non-enumerable own property), which is exactly the field a report
+     * consumer shows a human next to the profile or the file that failed.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            identityProfile: this.identityProfile,
+            sourceLabel: this.sourceLabel,
+        };
+    }
+}
+/**
+ * True when `value` is a {@link ConfigDiscoveryError}.
+ *
+ * Duck-typed on the marker property rather than `instanceof` on purpose: a consumer that ends up
+ * with two copies of `@gaunt-sloth/core` on disk (a `file:` dep, a hoisting split) would fail an
+ * `instanceof` check against a genuinely-correct error and mis-handle a config failure as an
+ * unexpected crash — exactly the distinction this error exists to make.
+ */
+export function isConfigDiscoveryError(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[CONFIG_DISCOVERY_MARKER] === true);
+}
+//# sourceMappingURL=configDiscovery.js.map

package/dist/config/configDiscovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configDiscovery.js","sourceRoot":"","sources":["../../src/config/configDiscovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,yGAAyG;AACzG,MAAM,uBAAuB,GAAG,yBAAyB,CAAC;AAgB1D;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,iGAAiG;IACxF,uBAAuB,GAAG,IAAa,CAAC;IACxC,eAAe,CAAqB;IACpC,WAAW,CAAqB;IAEzC,YACE,OAAe,EACf,OAAO,GAA2B,EAAE,EACpC,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAiC,CAAC,uBAAuB,CAAC,KAAK,IAAI,CACrE,CAAC;AACJ,CAAC"}

package/dist/config/defaults.d.ts

@@ -1,22 +1,21 @@
+/**
+ * @packageDocumentation
+ * Default Gaunt Sloth configuration ({@link DEFAULT_CONFIG}). Extracted verbatim from
+ * the former `config.ts` god-file; values are unchanged.
+ */
 import { StatusLevel } from '#src/core/types.js';
 /**
  * Default config
  */
 export declare const DEFAULT_CONFIG: {
-    readonly contentSource: "file";
-    readonly requirementSource: "file";
-    /**
-     * Path to project-specific guidelines.
-     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
-     * for example, to AGENTS.md
-     */
-    readonly projectGuidelines: ".gsloth.guidelines.md";
+    readonly contentSource: 'file';
+    readonly requirementSource: 'file';
     /**
      * Whether to include the current date in the project review instructions or not.
      */
     readonly includeCurrentDateAfterGuidelines: false;
-    readonly projectReviewInstructions: ".gsloth.review.md";
-    readonly filesystem: "none";
+    readonly filesystem: 'none';
+    readonly builtInTools: string[];
     readonly debugLog: false;
     readonly consoleLevel: StatusLevel.INFO;
     /**
@@ -30,8 +29,8 @@ export declare const DEFAULT_CONFIG: {
      */
     readonly commands: {
         readonly pr: {
-            readonly contentSource: "github";
-            readonly requirementSource: "github";
+            readonly contentSource: 'github';
+            readonly requirementSource: 'github';
             readonly rating: {
                 readonly enabled: true;
                 readonly passThreshold: 6;
@@ -50,24 +49,24 @@ export declare const DEFAULT_CONFIG: {
             };
         };
         readonly ask: {
-            readonly filesystem: "read";
+            readonly filesystem: 'read';
         };
         readonly chat: {
-            readonly filesystem: "read";
+            readonly filesystem: 'read';
         };
         readonly code: {
-            readonly filesystem: "all";
+            readonly filesystem: 'all';
         };
         readonly exec: {
-            readonly filesystem: "all";
+            readonly filesystem: 'all';
         };
         readonly api: {
-            readonly filesystem: "read";
+            readonly filesystem: 'read';
             readonly port: 3000;
             readonly cors: {
-                readonly allowOrigin: "http://localhost:3000";
-                readonly allowMethods: "POST, GET, OPTIONS";
-                readonly allowHeaders: "Content-Type, Accept";
+                readonly allowOrigin: 'http://localhost:3000';
+                readonly allowMethods: 'POST, GET, OPTIONS';
+                readonly allowHeaders: 'Content-Type, Accept';
             };
         };
     };
@@ -75,6 +74,7 @@ export declare const DEFAULT_CONFIG: {
     readonly writeOutputToFile: false;
     readonly writeBinaryOutputsToFile: true;
     readonly useColour: true;
+    readonly useMouse: true;
     readonly streamSessionInferenceLog: true;
     readonly canInterruptInferenceWithEsc: true;
     readonly aiignore: {

package/dist/config/defaults.js

@@ -3,7 +3,6 @@
  * Default Gaunt Sloth configuration ({@link DEFAULT_CONFIG}). Extracted verbatim from
  * the former `config.ts` god-file; values are unchanged.
  */
-import { PROJECT_GUIDELINES, PROJECT_REVIEW_INSTRUCTIONS } from '#src/constants.js';
 import { StatusLevel } from '#src/core/types.js';
 /**
  * Default config
@@ -11,18 +10,20 @@ import { StatusLevel } from '#src/core/types.js';
 export const DEFAULT_CONFIG = {
     contentSource: 'file',
     requirementSource: 'file',
-    /**
-     * Path to project-specific guidelines.
-     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
-     * for example, to AGENTS.md
-     */
-    projectGuidelines: PROJECT_GUIDELINES,
+    // GS2-43: prompt segments (backstory/guidelines/system/chat/code/exec/review) are configured
+    // via the optional `prompts` object and DEFAULTED AT THE READ SITE (`readPromptSegment` falls
+    // back to each segment's default-named file), so `prompts` is intentionally absent here.
     /**
      * Whether to include the current date in the project review instructions or not.
      */
     includeCurrentDateAfterGuidelines: false,
-    projectReviewInstructions: PROJECT_REVIEW_INSTRUCTIONS,
     filesystem: 'none',
+    // Enabled built-in tools. `gth_checklist` (the lean agent's planning/todo tool) and `gth_grep`
+    // (the permission-light content-search tool, GS2-51) are on by default across commands; a user
+    // `builtInTools` setting replaces this set entirely. Both are named to coexist with the deep
+    // backend's own `write_todos`/`grep` built-ins. Cast keeps it a mutable `string[]` under the
+    // surrounding `as const`.
+    builtInTools: ['gth_checklist', 'gth_grep'],
     debugLog: false,
     consoleLevel: StatusLevel.INFO, // Default to INFO level, not debug
     /**
@@ -81,6 +82,7 @@ export const DEFAULT_CONFIG = {
     writeOutputToFile: false,
     writeBinaryOutputsToFile: true,
     useColour: true,
+    useMouse: true,
     streamSessionInferenceLog: true,
     canInterruptInferenceWithEsc: true,
     aiignore: {

package/dist/config/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa,EAAE,MAAM;IACrB,iBAAiB,EAAE,MAAM;IACzB;;;;OAIG;IACH,iBAAiB,EAAE,kBAAkB;IACrC;;OAEG;IACH,iCAAiC,EAAE,KAAK;IACxC,yBAAyB,EAAE,2BAA2B;IACtD,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,WAAW,CAAC,IAAI,EAAE,mCAAmC;IACnE;;;;;;;;OAQG;IACH,QAAQ,EAAE;QACR,EAAE,EAAE;YACF,aAAa,EAAE,QAAQ;YACvB,iBAAiB,EAAE,QAAQ;YAC3B,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,IAAI;YACV,IAAI,EAAE;gBACJ,WAAW,EAAE,uBAAuB;gBACpC,YAAY,EAAE,oBAAoB;gBAClC,YAAY,EAAE,sBAAsB;aACrC;SACF;KACF;IACD,YAAY,EAAE,IAAI;IAClB,iBAAiB,EAAE,KAAK;IACxB,wBAAwB,EAAE,IAAI;IAC9B,SAAS,EAAE,IAAI;IACf,yBAAyB,EAAE,IAAI;IAC/B,4BAA4B,EAAE,IAAI;IAClC,QAAQ,EAAE;QACR,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,SAAS;KACpB;CACO,CAAC;AAEX;;;GAGG;AACH,oEAAoE;AACpE,cAA2B,CAAC"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa,EAAE,MAAM;IACrB,iBAAiB,EAAE,MAAM;IACzB,6FAA6F;IAC7F,8FAA8F;IAC9F,yFAAyF;IACzF;;OAEG;IACH,iCAAiC,EAAE,KAAK;IACxC,UAAU,EAAE,MAAM;IAClB,+FAA+F;IAC/F,+FAA+F;IAC/F,6FAA6F;IAC7F,6FAA6F;IAC7F,0BAA0B;IAC1B,YAAY,EAAE,CAAC,eAAe,EAAE,UAAU,CAAa;IACvD,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,WAAW,CAAC,IAAI,EAAE,mCAAmC;IACnE;;;;;;;;OAQG;IACH,QAAQ,EAAE;QACR,EAAE,EAAE;YACF,aAAa,EAAE,QAAQ;YACvB,iBAAiB,EAAE,QAAQ;YAC3B,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,IAAI;YACV,IAAI,EAAE;gBACJ,WAAW,EAAE,uBAAuB;gBACpC,YAAY,EAAE,oBAAoB;gBAClC,YAAY,EAAE,sBAAsB;aACrC;SACF;KACF;IACD,YAAY,EAAE,IAAI;IAClB,iBAAiB,EAAE,KAAK;IACxB,wBAAwB,EAAE,IAAI;IAC9B,SAAS,EAAE,IAAI;IACf,QAAQ,EAAE,IAAI;IACd,yBAAyB,EAAE,IAAI;IAC/B,4BAA4B,EAAE,IAAI;IAClC,QAAQ,EAAE;QACR,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,SAAS;KACpB;CACO,CAAC;AAEX;;;GAGG;AACH,oEAAoE;AACpE,cAA2B,CAAC"}

package/dist/config/filesystem-tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ * The single interpretation of the `filesystem` config value: **which filesystem tools it
+ * registers**.
+ *
+ * `filesystem` is a union — `'all'`, `'read'`, `'none'`, or a `string[]` of tool names — so any
+ * two-value check ("is it `read` or `none`?") is wrong by construction. The toolkit filter in
+ * `@gaunt-sloth/agent` (`filterFilesystemTools`) and the system-prompt notes in this package both
+ * need the answer, and they must never derive it separately: a prompt that names a tool the filter
+ * did not register tells the model to call something that does not exist. {@link
+ * isFilesystemToolRegistered} is that one derivation; both call it.
+ */
+import { type BuiltInToolAccess } from '#src/config/tool-descriptions.js';
+/** The `filesystem` config union: an allow-list of tool names, or one of the three modes. */
+export type FilesystemToolsConfig = string[] | 'all' | 'read' | 'none';
+/**
+ * The filesystem tool that creates a file from supplied content.
+ *
+ * Exported as a constant because prompt text names it literally: the note telling the model how to
+ * write a commit message interpolates this, so the name the model is told and the name the
+ * registration check asks about cannot drift apart.
+ */
+export declare const WRITE_FILE_TOOL_NAME = "write_file";
+/**
+ * Whether a filesystem tool is registered under the given `filesystem` config.
+ *
+ * `access` is the tool's own read/write class — the runtime `gthFileSystemType` the toolkit stamps
+ * on each tool, or {@link BUILT_IN_TOOL_ACCESS} for a caller that has only a name. A tool with no
+ * class is never covered by `'read'`; it can still be named explicitly in the array form.
+ *
+ * The array form is an allow-list of tool NAMES which may also carry the `'read'` and `'all'`
+ * keywords, so `['read', 'write_file']` means "every read tool, plus write_file". A value that is
+ * neither a known mode nor an array leaves the toolset unrestricted, matching the filter's own
+ * fallback, so an absent or malformed value never silently strips the model's tools.
+ */
+export declare function isFilesystemToolRegistered(filesystemConfig: FilesystemToolsConfig | undefined, toolName: string | undefined, access: BuiltInToolAccess | undefined): boolean;
+/**
+ * Whether {@link WRITE_FILE_TOOL_NAME} is registered under the given `filesystem` config — the
+ * question the commit-message guidance asks before it names the tool.
+ */
+export declare function isWriteFileToolRegistered(filesystemConfig: FilesystemToolsConfig | undefined): boolean;

package/dist/config/filesystem-tools.js

@@ -0,0 +1,56 @@
+/**
+ * @packageDocumentation
+ * The single interpretation of the `filesystem` config value: **which filesystem tools it
+ * registers**.
+ *
+ * `filesystem` is a union — `'all'`, `'read'`, `'none'`, or a `string[]` of tool names — so any
+ * two-value check ("is it `read` or `none`?") is wrong by construction. The toolkit filter in
+ * `@gaunt-sloth/agent` (`filterFilesystemTools`) and the system-prompt notes in this package both
+ * need the answer, and they must never derive it separately: a prompt that names a tool the filter
+ * did not register tells the model to call something that does not exist. {@link
+ * isFilesystemToolRegistered} is that one derivation; both call it.
+ */
+import { BUILT_IN_TOOL_ACCESS } from '#src/config/tool-descriptions.js';
+/**
+ * The filesystem tool that creates a file from supplied content.
+ *
+ * Exported as a constant because prompt text names it literally: the note telling the model how to
+ * write a commit message interpolates this, so the name the model is told and the name the
+ * registration check asks about cannot drift apart.
+ */
+export const WRITE_FILE_TOOL_NAME = 'write_file';
+/**
+ * Whether a filesystem tool is registered under the given `filesystem` config.
+ *
+ * `access` is the tool's own read/write class — the runtime `gthFileSystemType` the toolkit stamps
+ * on each tool, or {@link BUILT_IN_TOOL_ACCESS} for a caller that has only a name. A tool with no
+ * class is never covered by `'read'`; it can still be named explicitly in the array form.
+ *
+ * The array form is an allow-list of tool NAMES which may also carry the `'read'` and `'all'`
+ * keywords, so `['read', 'write_file']` means "every read tool, plus write_file". A value that is
+ * neither a known mode nor an array leaves the toolset unrestricted, matching the filter's own
+ * fallback, so an absent or malformed value never silently strips the model's tools.
+ */
+export function isFilesystemToolRegistered(filesystemConfig, toolName, access) {
+    if (filesystemConfig === 'none')
+        return false;
+    if (filesystemConfig === 'all')
+        return true;
+    if (filesystemConfig === 'read')
+        return access === 'read';
+    if (!Array.isArray(filesystemConfig))
+        return true;
+    if (filesystemConfig.includes('all'))
+        return true;
+    if (filesystemConfig.includes('read') && access === 'read')
+        return true;
+    return filesystemConfig.some((name) => name !== 'read' && name !== 'all' && name === toolName && !!toolName);
+}
+/**
+ * Whether {@link WRITE_FILE_TOOL_NAME} is registered under the given `filesystem` config — the
+ * question the commit-message guidance asks before it names the tool.
+ */
+export function isWriteFileToolRegistered(filesystemConfig) {
+    return isFilesystemToolRegistered(filesystemConfig, WRITE_FILE_TOOL_NAME, BUILT_IN_TOOL_ACCESS[WRITE_FILE_TOOL_NAME]);
+}
+//# sourceMappingURL=filesystem-tools.js.map

package/dist/config/filesystem-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-tools.js","sourceRoot":"","sources":["../../src/config/filesystem-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAA0B,MAAM,kCAAkC,CAAC;AAKhG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CACxC,gBAAmD,EACnD,QAA4B,EAC5B,MAAqC;IAErC,IAAI,gBAAgB,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,gBAAgB,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,gBAAgB,KAAK,MAAM;QAAE,OAAO,MAAM,KAAK,MAAM,CAAC;IAC1D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,gBAAgB,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,gBAAgB,CAAC,IAAI,CAC1B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAC/E,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,gBAAmD;IAEnD,OAAO,0BAA0B,CAC/B,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,CAAC,oBAAoB,CAAC,CAC3C,CAAC;AACJ,CAAC"}