@moikapy/lich 0.3.1 → 0.4.0

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   create_agent,
   parse_agent_config,
   safe_json_parse
-} from "./chunk-P52U5M3L.js";
+} from "./chunk-MLFJW4JU.js";
 
 // src/cli.ts
 import { readFileSync as readFileSync2 } from "fs";
@@ -346,11 +346,11 @@ async function run_chat(config) {
   }
 }
 async function run_tui_entry(config) {
-  const { run_tui } = await import("./tui-K3EPRXTV.js");
+  const { run_tui } = await import("./tui-VYBJSGRV.js");
   return run_tui(config);
 }
 async function run_gateway_entry(config, platforms) {
-  const { run_gateway } = await import("./gateway-CWPVIU3W.js");
+  const { run_gateway } = await import("./gateway-XTYDYT67.js");
   return run_gateway(config, platforms.length === 0 ? ["webhook"] : platforms);
 }
 function is_main_module() {

package/dist/{gateway-CWPVIU3W.js → gateway-XTYDYT67.js}

@@ -2,7 +2,7 @@ import {
   create_agent,
   logger,
   sleep
-} from "./chunk-P52U5M3L.js";
+} from "./chunk-MLFJW4JU.js";
 
 // src/gateway/types.ts
 var ERROR_SNIPPET_CHARS = 300;
@@ -749,4 +749,4 @@ function install_signal_handlers(bus, adapters) {
 export {
   run_gateway
 };
-//# sourceMappingURL=gateway-CWPVIU3W.js.map
+//# sourceMappingURL=gateway-XTYDYT67.js.map

package/dist/index.d.ts

@@ -37,6 +37,8 @@ interface Tool {
     name: string;
     description: string;
     parameters: JsonSchemaObject;
+    /** Per-tool executor timeout override in ms; unset tools get the 30s default. */
+    timeout_ms?: number;
     execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
 }
 interface Toolset {
@@ -55,6 +57,12 @@ interface Toolset {
 /** Runtime info handed to every hook call. */
 interface HookContext {
     work_dir: string;
+    /**
+     * This plugin's own per-run state sub-map. Every hook invocation receives
+     * a ctx exposing only the invoking plugin's bag; the bag is swapped fresh
+     * at each run start. Absent only on hand-built contexts outside the runner.
+     */
+    state?: Map<string, unknown>;
 }
 /** Argument passed to before_tool_call hooks. */
 interface BeforeToolCallInfo {
@@ -69,6 +77,9 @@ interface BeforeToolCallResult {
 /** Argument passed to after_tool_call hooks. */
 interface AfterToolCallInfo extends BeforeToolCallInfo {
     result_summary: string;
+    /** Structured executor outcome; gate on this, never parse result_summary. */
+    ok: boolean;
+    error?: string;
 }
 interface RunEndInfo {
     stopped_reason: string;
@@ -445,6 +456,7 @@ declare class Agent {
     private readonly hook_runner;
     constructor(config: AgentConfig, plugins?: readonly LoadedPlugin[]);
     run(options: AgentRunOptions): Promise<AgentRunResult>;
+    /** Per-run deps: the built-once ToolContext threads through every tool execution. */
     private loop_deps;
     /** Best-effort on_run_start fan-out; hook errors are logged, never fatal. */
     private call_plugin_run_start;
@@ -503,7 +515,11 @@ declare function register_builtin_tools(registry: ToolRegistry, context?: ToolCo
  *
  * before_tool_call hooks run in registration order and may veto a call (first
  * blocker wins; the wrapped executor is never called). Hook errors are warned
- * and skipped, never fatal. after_tool_call hooks observe the result summary.
+ * and skipped, never fatal. after_tool_call hooks observe the result summary
+ * plus the executor's structured ok/error fields. Every hook invocation
+ * receives a ctx exposing only its own plugin's state sub-map: the bag is a
+ * module-internal WeakMap keyed on the plugin object, swapped fresh at each
+ * call_run_start and shared by the lifecycle and per-tool ctx build sites.
  */
 
 /** Structural ToolRunner shape accepted from the wrapped executor. */
@@ -511,27 +527,25 @@ interface WrappedToolRunner {
     execute(name: string, args: Record<string, unknown>, context?: ToolContext): Promise<ToolResult>;
 }
 /**
- * All hook arrays are pre-flattened at construction so the per-call hot path
- * does no concat; hooks always run in plugin registration order.
+ * Hooks stay attached to their plugin (no flattening) so each invocation can
+ * be handed a ctx exposing only that plugin's sub-map; hooks always run in
+ * plugin registration order.
  */
 declare class HookedToolRunner {
     private readonly wrapped;
-    private readonly before_hooks;
-    private readonly after_hooks;
-    private readonly run_start_hooks;
-    private readonly run_end_hooks;
-    constructor(wrapped: WrappedToolRunner, hooks: readonly PluginHooks[]);
+    private readonly hooked_plugins;
+    constructor(wrapped: WrappedToolRunner, plugins: readonly Plugin[]);
     /** Run before hooks in order; the first {block: true} verdict wins. */
     private run_before_hooks;
     /** Fire-and-forget in spirit but awaited here so runs settle cleanly. */
     private run_after_hooks;
     execute(name: string, args: Record<string, unknown>, context?: ToolContext): Promise<ToolResult>;
-    /** Best-effort on_run_start fan-out used by Agent.run; never throws. */
+    /** Best-effort on_run_start fan-out used by Agent.run; never throws. Swaps in a fresh state sub-map per hooked plugin first. */
     call_run_start(info: {
         input_chars: number;
-    }, ctx: HookContext): Promise<void>;
+    }, base: HookContext): Promise<void>;
     /** Best-effort on_run_end fan-out used by Agent.run; never throws. */
-    call_run_end(info: RunEndInfo, ctx: HookContext): Promise<void>;
+    call_run_end(info: RunEndInfo, base: HookContext): Promise<void>;
 }
 
 /**

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   plugin_errors_summary,
   register_builtin_tools,
   run_agent
-} from "./chunk-P52U5M3L.js";
+} from "./chunk-MLFJW4JU.js";
 export {
   Agent,
   AgentEmitter,

package/dist/{tui-K3EPRXTV.js → tui-VYBJSGRV.js}

@@ -4,7 +4,7 @@ import {
 import {
   create_agent,
   truncate_text
-} from "./chunk-P52U5M3L.js";
+} from "./chunk-MLFJW4JU.js";
 
 // src/tui.tsx
 import { render } from "ink";
@@ -430,4 +430,4 @@ async function run_tui(config) {
 export {
   run_tui
 };
-//# sourceMappingURL=tui-K3EPRXTV.js.map
+//# sourceMappingURL=tui-VYBJSGRV.js.map

package/docs/architecture/overview.md

@@ -28,7 +28,7 @@ flowchart TB
     CLIENTS["openai_compat / anthropic / ollama<br/>HTTP clients"]
     EXEC["ToolExecutor<br/>(src/tools/executor.ts)"]
     REG["ToolRegistry<br/>(src/tools/registry.ts)"]
-    BUILTIN["12 builtin tools<br/>(src/tools/builtin/*)"]
+        BUILTIN["builtin tools<br/>(src/tools/builtin/*)"]
     COMP["ContextCompressor<br/>(src/context/compressor.ts)"]
     SESSION["SessionStore<br/>(src/session/store.ts)"]
 
@@ -59,18 +59,20 @@ structural interfaces ([`src/agent/loop.ts`](../../src/agent/loop.ts)):
 
 - `ChatFn` - `(messages, tools, options?) => Promise<ChatResult>` (declared in
   `src/context/compressor.ts`, since compression needs the same shape).
-- `ToolRunner` - `{ execute(name, args) => Promise<ToolResult> }`.
+- `ToolRunner` - `{ execute(name, args, context?) => Promise<ToolResult> }`.
 
 `run_conversation` receives a `LoopDeps` object holding a `ChatFn`, a
-`ToolRunner`, a `definitions()` callback for tool schemas, and an optional
-emitter. The `Agent` class (`src/agent/agent.ts`) is the composition root: its
-`loop_deps()` method wires the real implementations -
+`ToolRunner`, a `definitions()` callback for tool schemas, an optional
+emitter, and an optional per-run `tool_context` threaded to every tool
+execution. The `Agent` class (`src/agent/agent.ts`) is the composition root:
+its `loop_deps()` method wires the real implementations -
 
 ```ts
 chat: (messages, tools, chat_options) => this.router.chat_with_failover(messages, tools, chat_options),
 tools: this.executor,
 definitions: () => this.registry.definitions(),
 emitter: this.events,
+tool_context,
 ```
 
 (src/agent/agent.ts, `loop_deps()`)
@@ -166,7 +168,7 @@ Walkthrough of a single `Agent.run({ input })` call
 | `src/tools/guard.ts` | Path confinement, timeouts, clamping, arg coercion. |
 | `src/tools/registry.ts` | Name-keyed tool registry; duplicate rejection. |
 | `src/tools/executor.ts` | Never-throw execution with timeout and abort. |
-| `src/tools/builtin/*` | The 12 builtin tools (see [tools](./tools.md)). |
+| `src/tools/builtin/*` | Builtin tools, including `run_tests` (see [tools](./tools.md)). |
 | `src/gateway/bus.ts` | Conversation-keyed runner over one shared `Agent`. |
 | `src/gateway/runner.ts` | Adapter construction, signal handling, process lifetime. |
 | `src/gateway/{telegram,discord,twitch,webhook}.ts` | Platform adapters. |

package/docs/architecture/plugins.md

@@ -23,7 +23,7 @@ flowchart LR
     K -- yes --> M["LoadedPlugin collected"]
     M --> N["Agent constructor"]
     N --> O["registry merge:\nplugin tools appended\n(dup tool name → warn+skip)"]
-    N --> P["hook concat:\nPluginHooks[] in config order"]
+    N --> P["hooked plugins kept\nwhole (per-plugin state channel)"]
     P --> Q["HookedToolRunner wraps\nToolExecutor when hooks exist"]
     E --> R["warn + continue"]
     H --> R
@@ -53,14 +53,66 @@ sequenceDiagram
     else no blocker
         H->>E: execute(name, args, context?)
         E-->>H: ToolResult
-        H->>A: await hook({...info, result_summary}, ctx)
-        note over A: summary = 300 chars of output/error
+        H->>A: await hook({...info, result_summary, ok, error?}, ctx)
+        note over A: summary = 300 chars of output/error; ok/error are structured
         H-->>L: ToolResult unchanged
     end
 ```
 
 Lifecycle fan-outs live on the same wrapper: `Agent.run` calls `call_run_start({input_chars})` before `run_conversation` and `call_run_end({stopped_reason, turns_used})` after it (including the abort/throw path, via `finally`). Both are best-effort: hook throws are logged at `warn` and the run proceeds.
 
+## Builtin gatekeeper
+
+`Agent` constructs `gatekeeper_plugin` in code, before config plugins, and
+pushes it as a synthetic `LoadedPlugin` through tool registration and the
+hook runner. The config loader never sees it. Construction failure means
+`git_commit` is not in the registry at all. "No gatekeeper → no `git_commit`"
+is that trusted path: with the gatekeeper off, a config plugin may still name
+a tool `git_commit` (the documented plugin-trust floor). While the gatekeeper
+is registered, first-wins keeps its tool.
+
+`LICH_ALLOW_SELF_COMMIT` is read from process env at construction. The spec
+value is `1`. Unset or any other value is fail-closed.
+
+Per-run state starts `tests_ok=false`, `dirty=true`, `commits=0` (swapped at
+`call_run_start`). `after_tool_call` updates only on structured `ok`:
+
+- `write_file` / `edit_file` success → `dirty=true`
+- `run_tests` success → `tests_ok=true`, `dirty=false`
+- `git_commit` success → `commits++`
+
+`before_tool_call` vetoes `git_commit` unless
+`allow_self_commit && tests_ok && !dirty && commits < 1`. The reason names
+the failed condition: `self_commit_disabled`, `tests_not_ok`,
+`worktree_dirty`, `commit_budget_exhausted`. The model sees
+`blocked_by_plugin: <reason>`.
+
+`terminal` is vetoed on a hardcoded denylist match; the reason is
+`git_denylist: <pattern>`. Patterns: flag-tolerant `commit` and `push`
+(`commit`, `-commit`, `--commit`, `push`, `-push`, `--push`) plus
+any-occurrence `commit-tree` and `update-ref`. No `remote` pattern. One
+commit per run, hardcoded.
+
+`git_commit` args are `{message, paths}` with 1–50 paths relative to
+`work_dir`. It rejects `""`, `.`, anything resolving to `work_dir`, and
+secret-ish basenames (`.env`, `.env.local`, `*.pem`, `*.p12`, `id_rsa*`).
+Unreachable `HEAD` is fail-closed. Recipe: scoped `git add -- <paths>`, then
+`git commit --only` with explicit identity `-c` flags. `timeout_ms` is 60000.
+It never pushes.
+
+**Attestation:** clean state attests no `write_file`/`edit_file` since the
+last green `run_tests`; it does NOT attest absence of terminal-mediated
+writes — that sits with the documented terminal floor.
+
+Floors, stated not closed:
+
+- Terminal floor: raw `terminal` can run arbitrary git; the denylist is
+  best-effort. The boundary is human review of the local repo; push is
+  human-only.
+- Plugin-trust floor: `.lich/config.json` `plugins` is persistent arbitrary
+  code at next process start. Review config diffs.
+- One lich process per repo (the `run_tests` mutex is process-local).
+
 ## Design decisions
 
 - **Explicit entries, no directory scan.** v1 loads only the files you list in `config.plugins`. Directory scanning would make runs depend on whatever happens to sit in a folder — non-reproducible, and a footgun for tools that write into `.lich/`. Explicit entries make the agent's tool surface a function of the config alone.
@@ -74,7 +126,8 @@ Lifecycle fan-outs live on the same wrapper: `Agent.run` calls `call_run_start({
 | --- | --- | --- |
 | `Plugin` | type | `{name, version?, tools?, hooks?}` — what a plugin module exports. |
 | `PluginHooks` | type | The four optional lifecycle hooks with their signatures. |
-| `HookContext` | type | `{work_dir}` passed to every hook. |
+| `HookContext` | type | `{work_dir, state?}` passed to every hook; `state` is the invoking plugin's own per-run bag. |
+| `AfterToolCallInfo` | type | Tool name/args plus the 300-char `result_summary` and structured `ok`/`error` fields. |
 | `LoadedPlugin` | type | `{plugin, entry}` — a loaded plugin and its source path. |
 | `load_plugins` | function | `(entries, base_dir) => {plugins, errors}` — dynamic import + shape validation. |
 | `plugin_errors_summary` | function | Joins error entries into one warn-able string. |

package/docs/architecture/tools.md

@@ -118,9 +118,10 @@ args, context?)`:
    defaults (falling back to `process.cwd()`) plus the configured `env`.
 3. **Cancelled fast path**: if the context signal is already aborted, return
    `{ ok: false, output: "", error: "cancelled" }` without running the tool.
-4. **Signal merge + 30 s timeout**: a fresh `AbortController` is aborted by
+4. **Signal merge + timeout**: a fresh `AbortController` is aborted by
    the external signal (an `abort` listener), by the `with_timeout` deadline
-   (`DEFAULT_TOOL_TIMEOUT_MS = 30000`), and the merged signal is what the tool
+   (the tool's own `timeout_ms` when declared, else
+   `DEFAULT_TOOL_TIMEOUT_MS = 30000`), and the merged signal is what the tool
    receives. The external listener is removed in a `finally`.
 5. **Output clamping**: successful results pass through `clamp_result`
    (`clamp_output`, 20 000 chars).
@@ -137,8 +138,9 @@ form back with `parse_tool_message_content` (src/tui/state.ts).
 
 ## Builtin catalog
 
-Twelve tools, registered by `register_builtin_tools`
-([`src/tools/builtin/index.ts`](../../src/tools/builtin/index.ts)):
+Registered by `register_builtin_tools`
+([`src/tools/builtin/index.ts`](../../src/tools/builtin/index.ts)).
+Docs tools join the list only when a docs root resolves.
 
 | Tool | Key args | Implementation insight |
 | --- | --- | --- |
@@ -154,6 +156,7 @@ Twelve tools, registered by `register_builtin_tools`
 | `process_list` | `filter?`, `max_results?` | Reads `/proc` synchronously: numeric dirs are pids, `cmdline` is NUL-separated; missing entries (process died mid-scan) read as empty. |
 | `disk_usage` | `path?`, `max_entries?` | One `du -sb` subprocess per depth-1 entry with a 10 s timeout; sorted desc with a `TOTAL` row; `du` missing yields `du_unavailable`. |
 | `env_get` | `keys?`, `prefix?`, `reveal?` | Values are hidden unless `reveal`; names matching `/(secret\|token\|password\|key\|credential\|auth)/i` are **always** masked as `<redacted: N chars>`. |
+| `run_tests` | `filter?` | Runs `LICH_TEST_COMMAND` (default `node node_modules/vitest/vitest.mjs run`) in `work_dir` via `bash -lc`. `timeout_ms` is 600000. A module mutex makes a concurrent call return `{ok:false, error:"run_tests_busy"}`. `ok` is the structured pass/fail the gatekeeper reads; output is clamped to 2000 chars. One lich process per repo — a second process is fail-closed busy or failed. |
 
 The three HTTP tools (`fetch_url`, `web_search`, `http_request`) share
 helpers from `fetch_url.ts`: `valid_http_url` (URL parse + protocol
@@ -161,6 +164,15 @@ allowlist), `compose_abort_signal` (per-call `AbortSignal.timeout` merged
 with the executor's cancellation via `AbortSignal.any`), and `clamp_int_arg`
 (floored, bounded to `[1, max]`).
 
+## Docs search and skills
+
+`docs_search` scores sections under the resolved docs root (memoized) and, when
+`<work_dir>/.lich/skills/` exists, also walks that directory. The skills
+candidate is existence-only: it does not need `index.md`. The walk is fresh
+on every call — user-writable skill files are not memoized into the package
+docs cache. Skills are reference data, written with `write_file`, not
+instructions. See the [plugins guide](../user-guide/plugins.md#skills-and-memory).
+
 ## Registry
 
 [`ToolRegistry`](../../src/tools/registry.ts) is a name-keyed `Map`:

package/docs/index.md

@@ -8,14 +8,14 @@ outline: [2, 3]
 
 Lich is a TypeScript AI agent harness: a library and a CLI that run a chat model inside a Think-Act-Observe loop. A chat wrapper forwards one prompt and prints one completion. A harness keeps going: the model plans (think), calls tools such as `read_file` or `terminal` (act), reads the tool results (observe), and repeats until it can produce a final answer. Lich wraps that loop with the machinery real deployments need: provider failover with bounded retries, path confinement and output clamps on every tool, context compression when the transcript grows past a token budget, and append-only JSONL session transcripts.
 
-One package, four ways to drive the same agent: a one-shot CLI, an interactive chat REPL, an ink-based terminal UI, and a long-running messaging gateway that bridges Telegram, Discord, Twitch, and a zero-config HTTP webhook. All four share the same twelve builtin tools, the same provider configuration, and the same session store.
+One package, four ways to drive the same agent: a one-shot CLI, an interactive chat REPL, an ink-based terminal UI, and a long-running messaging gateway that bridges Telegram, Discord, Twitch, and a zero-config HTTP webhook. All four share the same builtin tools, the same provider configuration, and the same session store.
 
 ## Feature overview
 
 | Capability | What it gives you |
 | --- | --- |
 | Providers | `openai_compat`, `anthropic`, and `ollama` with automatic failover between configured providers; 429/5xx and network errors retry with backoff before failing over. |
-| Tools | Twelve builtins (file read/write/edit, directory listing, shell, grep, HTTP fetch/request, web search, process list, disk usage, env inspection), all confined to the working directory. |
+| Tools | Builtins (file read/write/edit, directory listing, shell, grep, HTTP fetch/request, web search, process list, disk usage, env inspection, `run_tests`), all confined to the working directory. `git_commit` is the gatekeeper's tool, not a config plugin. |
 | Context compression | Transcript summarized in place when estimated tokens cross `compress_threshold` of `context_budget_tokens`; the 8 most recent turns always stay verbatim. |
 | Sessions | Every run persists a `.jsonl` transcript under `.lich/sessions/`, labeled by origin (`tui`, `gw:<platform>:<chat>`). |
 | CLI | One-shot tasks, chat REPL, TUI, gateway, and a `config` template command, all with flag/env/config-file configuration. |
@@ -33,7 +33,7 @@ One package, four ways to drive the same agent: a one-shot CLI, an interactive c
 | [TUI guide](user-guide/tui.md) | Run the terminal UI and use slash commands and the status bar. |
 | [Gateway guide](user-guide/gateway.md) | Wire Telegram, Discord, Twitch, and the HTTP webhook to one agent. |
 | [Library guide](user-guide/library.md) | Embed the agent in TypeScript with events and multi-turn history. |
-| [Plugins guide](user-guide/plugins.md) | Add your own tools and lifecycle hooks to the agent. |
+| [Plugins guide](user-guide/plugins.md) | Add your own tools and lifecycle hooks, and run the self-improvement loop. |
 | [Architecture overview](architecture/overview.md) | Understand how the harness works inside. |
 
 ## How it works

package/docs/user-guide/cli.md

@@ -129,6 +129,19 @@ Minimal per-provider examples:
 
 Listed providers form a failover chain: the router walks them in order, retrying `rate_limit`/`network` errors (bounded backoff) on the current provider before moving on, and failing over immediately on `auth`, `overflow`, and `bad_request`.
 
+## Self-improvement environment
+
+These are process-env knobs, not config fields. They are assembled in code and
+never accepted as a config passthrough.
+
+| Variable | Meaning |
+| --- | --- |
+| `LICH_ALLOW_SELF_COMMIT` | Set to `1` to allow one gated `git_commit` per run. Unset or any other value is fail-closed. Read at agent construction. |
+| `LICH_TEST_COMMAND` | Command `run_tests` runs in `work_dir` (default `node node_modules/vitest/vitest.mjs run`). An optional `filter` argument is appended. |
+
+Veto reasons, the terminal git denylist, skills, and `MEMORY.md` are in the
+[plugins guide](plugins.md#self-improvement-loop).
+
 ## Session files
 
 Each run writes `.lich/sessions/<timestamp36>-<counter>[-label].jsonl` where the label is the run origin: `-tui`, or `-gw-<platform>-<chat_id>` for gateway conversations. One-shot and chat runs get no label. Records are JSON lines of two kinds: `{"ts","kind":"meta","meta":{...}}` (run start, budget exhaustion) and `{"ts","kind":"message","message":{...}}` for each system/user/assistant/tool message.

package/docs/user-guide/library.md

@@ -47,7 +47,7 @@ const result = await run_agent(
 
 ## Agent class
 
-`new Agent(config)` (or `create_agent(raw)`) builds the provider router, registers the twelve builtin tools (filtered by `tools_enabled`), and exposes:
+`new Agent(config)` (or `create_agent(raw)`) builds the provider router, registers the builtin tools (filtered by `tools_enabled`) plus the gatekeeper's `git_commit`, and exposes:
 
 | Member | Type | Purpose |
 | --- | --- | --- |
@@ -141,6 +141,8 @@ const config = {
 
 Listed providers form a failover chain tried in order: `rate_limit`/`network` errors retry with backoff (3 attempts) on the current provider before failing over; `auth`, `overflow`, and `bad_request` fail over immediately. The last error is rethrown when all providers fail.
 
+`LICH_ALLOW_SELF_COMMIT` and `LICH_TEST_COMMAND` are process-env knobs, not config fields. See the [CLI environment](cli.md#self-improvement-environment).
+
 ## Custom tool filtering
 
 `tools_enabled` accepts `"all"` (default) or an array of builtin tool names to register; everything else stays unregistered and invisible to the model:

package/docs/user-guide/plugins.md

@@ -47,11 +47,11 @@ All hooks are awaited. Hook errors are logged as warnings and skipped — a brok
 | Hook | Signature | Purpose |
 | --- | --- | --- |
 | `before_tool_call` | `(info: {tool_name, args}, ctx) => {block?: boolean, reason?: string} \| void` | Runs before each tool call in plugin registration order. Return `{block: true, reason}` to veto. |
-| `after_tool_call` | `(info: {tool_name, args, result_summary}, ctx) => void` | Runs after each tool call with a 300-char result summary. |
+| `after_tool_call` | `(info: {tool_name, args, result_summary, ok, error?}, ctx) => void` | Runs after each tool call with a 300-char summary plus structured `ok`/`error`. |
 | `on_run_start` | `(info: {input_chars}, ctx) => void` | Runs once before the conversation loop starts. |
 | `on_run_end` | `(info: {stopped_reason, turns_used}, ctx) => void` | Runs once after the loop ends with the outcome. |
 
-`ctx` is `{work_dir: string}` — the agent's working directory.
+`ctx` is `{work_dir, state?}` — the agent's working directory plus that plugin's per-run bag.
 
 ## Tool authoring
 
@@ -115,6 +115,59 @@ Failures are contained at every layer:
 - **Bun** runs TypeScript plugin files natively — `.ts` entries just work (`bun src/cli.ts ...` from a clone).
 - **Node** (the built `dist/cli.js`) uses the native ESM loader, which does not compile TS. For node deployments, compile your plugin or ship it as `.mjs`/plain JS and list that file in `plugins`.
 
+## Self-improvement loop
+
+The agent can write a tool, prove it with `run_tests`, and commit it with
+`git_commit` — one commit per run, and only when you opt in. The gatekeeper
+is constructed in code (not listed in `config.plugins`). If it does not
+register, `git_commit` is absent. A config plugin naming `git_commit` is
+inside the plugin-trust floor only when the gatekeeper is off; while it is
+on, first-wins keeps the gatekeeper's tool.
+
+Set `LICH_ALLOW_SELF_COMMIT=1` before startup. Unset, or any other value, is
+fail-closed. `git_commit` is vetoed unless every condition holds; the reason
+names the first failure, and the model sees `blocked_by_plugin: <reason>`:
+
+| Failed condition | Reason |
+| --- | --- |
+| `LICH_ALLOW_SELF_COMMIT` is not `1` | `self_commit_disabled` |
+| no green `run_tests` yet this run | `tests_not_ok` |
+| a `write_file` or `edit_file` succeeded after that green run | `worktree_dirty` |
+| this run already committed once | `commit_budget_exhausted` |
+
+`terminal` is vetoed when the command matches the hardcoded git denylist.
+The reason is `git_denylist: <pattern>`. Patterns are flag-tolerant
+`commit`/`push` (`commit`, `-commit`, `--commit`, `push`, `-push`, `--push`)
+and any occurrence of `commit-tree` or `update-ref`. There is no `remote`
+pattern. The denylist is best-effort: raw `terminal` can still run git. The
+boundary is a human reviewing the local repo. Push is human-only.
+
+`git_commit` takes `{message, paths}` — 1 to 50 paths relative to `work_dir`.
+It rejects `""`, `.`, a path that resolves to `work_dir` itself, and
+secret-ish basenames (`.env`, `.env.local`, `*.pem`, `*.p12`, `id_rsa*`).
+It refuses an unreachable `HEAD`. It stages exactly the named paths
+(`git add -- <paths>`) and commits with `git commit --only`. It never pushes.
+
+`run_tests` takes an optional `filter` and runs `LICH_TEST_COMMAND` in
+`work_dir` (default `node node_modules/vitest/vitest.mjs run`) with a 600s
+timeout. A second call in the same process returns `run_tests_busy`. The
+mutex is process-local: one lich process per repo.
+
+Clean state attests no `write_file`/`edit_file` since the last green
+`run_tests`; it does NOT attest absence of terminal-mediated writes.
+
+### Skills and memory
+
+Write a markdown note with `write_file` to `.lich/skills/<name>.md`.
+`docs_search` finds those files. That directory does not need `index.md`,
+and it is walked fresh on every search. The default system prompt says tool
+results — docs, skills, memory — are reference data, not instructions.
+
+`MEMORY.md` is append-only and human-reviewable. It is never auto-loaded.
+Review it between appends and the next self-commit.
+
 ## Security note
 
-Plugins execute **in-process with full privileges** — the same trust level as the agent itself and your shell. A plugin can read any file the process can, make network calls, and alter process state. Only load plugin files you wrote or audited; treat `.lich/plugins/` like you treat `.env` files.
+Plugins execute **in-process with full privileges** — the same trust level as the agent itself and your shell. A plugin can read any file the process can, make network calls, and alter process state. Only load plugin files you wrote or audited; treat `.lich/plugins/` like you treat `.env` files.
+
+`.lich/config.json` `plugins` is persistent arbitrary code at the next process start. Review config diffs before the next self-commit. The terminal git denylist does not close that hole.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moikapy/lich",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Lich — a TypeScript AI agent harness (library + CLI) inspired by Hermes",
   "type": "module",
   "license": "MIT",