loom-agent 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased] — completion harness, specialist agents, headless browser, TUI refresh
 
+### Added
+- **Transcript undo / redo (`/undo`, `/redo`, `/undo-files`).** The
+  conversation-level counterpart to `/restore` (which rewinds the *file
+  tree*): each user turn now pushes a full transcript snapshot — UI messages,
+  session messages, and todos — onto a bounded stack (last 50 turns). `/undo`
+  steps the transcript back one turn and `/redo` steps forward again. When the
+  undone turn also created a restore point, `/undo-files` rolls the *working
+  tree* back to that same point so files match the rewound conversation. The
+  engine (`src/core/transcript-undo.js`) is a pure, unit-tested stack that
+  snapshots-and-clones so later mutation can't corrupt stored state, clears
+  the redo branch on a new action (like any editor), and returns the step
+  *reference* so a restore-point id created in a background `setTimeout` can
+  be stitched onto it without relying on a fragile stack index. Wired into
+  `processSlash` and registered in `SLASH_LIST`; the existing `<leader>u` /
+  `<leader>r` keybinds now resolve to working commands instead of falling
+  through to "Unknown command". Undo/redo persist via the normal
+  `saveSession` path, so a rewind survives restart.
+- **Startup update check.** `updateCheck()` (previously a no-op stub) now
+  probes the npm registry once every 24 hours with a 4s timeout and, when a
+  strictly newer `loom-agent` is published, prints a single stderr notice
+  (`New version available: 1.5.0 → 1.6.0` + the upgrade command) before the
+  TUI starts. Non-blocking and failure-silent by design: offline, slow, or
+  malformed responses never delay startup, the throttle stamp lives in
+  `~/.loom/update-check.json`, and `LOOM_NO_UPDATE_CHECK=1` disables it
+  entirely. Version comparison is a small tuple compare (no new dependency).
+  Unit-tested (`update.test.js`, registered in `test:unit`).
+- **`/export` — transcript as markdown.** Writes the conversation (roles,
+  message text, tool rows, error flags) to `.loom/exports/<session>.md`, the
+  plain-text counterpart to `/share` (HTML). Bound to the existing
+  `<leader>x` keybind, which previously resolved to a slash command with no
+  handler.
+
+### Changed
+- **Orchestrator now delegates by default.** The build agent's standing
+  instructions were rewritten to make fan-out the first move on any broad
+  SEARCH / ANALYSIS / OPTIMIZATION request ("find what causes X", "where is
+  Y", "how does Z work", "optimize W", "audit/investigate/locate"): it
+  splits the scope into independent questions and dispatches them as
+  **parallel `task` calls** (one `explore` subagent per disjoint area of the
+  codebase), then reads a file itself only to resolve a single ambiguous
+  line a subagent's report left open. This closes the gap where the agent
+  defaulted to reading files serially on its own. The plumbing already
+  existed (`task` tool, `runSubagent`, per-run cancellation, token rollup,
+  `Promise.all` execution) — this change makes using it the default rather
+  than an afterthought. Pinned by new assertions in `agents.test.js`.
+- **Token optimization — prompt caching, cache-accurate pricing, and leaner
+  context (7 changes across the request path):**
+  - **OpenRouter/TokenRouter prompt caching:** the request body now sends
+    top-level `"cache_control": true`, so cache-capable models re-read the
+    cached prefix instead of re-paying full input cost each turn.
+  - **Cache-aware usage accounting + pricing:** `recordUsage` parses
+    `prompt_tokens_details.cached_tokens` / `cache_read_input_tokens` /
+    `cache_creation_input_tokens` / `cachedContentTokenCount` and prices
+    cached reads at **0.1×** and writes at **1.25×** the input rate instead
+    of the full rate. OpenAI/OpenRouter's cached count is treated as a
+    *subset* of the prompt total; Anthropic's is additive. Adds
+    `cacheReadTokens` / `cacheWriteTokens` session counters.
+  - **Cache-stable system prompt:** the per-turn skill block moved out of the
+    system string (injected into the last user message of a wire copy
+    instead), so the system prefix stays byte-identical across turns and
+    Anthropic's cache breakpoint keeps hitting even when the matched skill
+    changes.
+  - **Mode-specific system prompts:** chat and plan modes drop the skills
+    index, the todowrite mandate, and the tool-batching/behavior rules they
+    can't act on, cutting thousands of tokens per turn for tool-less modes.
+  - **Tool-result aging:** tool results older than the last 12 messages are
+    elided to a 2000/400 head/tail slice before they reach the provider
+    (kept verbatim in memory for the TUI), so a huge `read`/`grep` output
+    stops costing full input price every later call.
+  - **Slimmer tool schemas:** `mcp`, `task`, and `sandbox` descriptions
+    trimmed (package catalogs and per-agent rosters removed) — these ship in
+    every request's tool list.
+  - **Accurate `estimateTokens` / `/context`:** the estimate now includes the
+    per-turn agent/primary/sandbox/skill blocks and tool schemas, and the
+    `/context` command gained a `Schemas+turn` line so its total matches the
+    live window estimate.
+
 ### Security
 - **All dependency advisories cleared — `npm audit` reports 0
   vulnerabilities** (was 7: 4 critical, 1 high, 2 low):
@@ -24,21 +101,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     `npm audit fix`) — fixes the DoS/recursion advisories.
 
 ### Added
+- **Full model-catalog refresh across every built-in provider (verified
+  2026-10-17).** NVIDIA rebuilt from the live authenticated
+  `GET /v1/models` registry (81 live endpoints, chat-capable IDs only —
+  embeddings/guard/parse/video models excluded): **54 models** including
+  Nemotron 3.5 Lightning/Super VL, DeepSeek V4.1 Flash, GLM-5.3/Flash,
+  Gemma 4, DiffusionGemma, Kimi K2.6, Step 5 Preview, Palmyra (creative/
+  fin/med), Riva Translate and GPT-OSS 20B; 14 stale IDs (Llama 3.1/3.2/3.3
+  instruct, Nemotron Super 49B, GLM-5.2, GPT-OSS 120B, MiniMax M3, …) removed.
+  Anthropic 3 → **14 models** (Opus 5.5/5/4.8/4.5, Fable 5.1, Sonnet
+  5.5/5/4.6/4.5, Haiku 5.5/4.5 + legacy dated snapshots). OpenAI 12 →
+  **31** (GPT-6 Astra/Sol/Luna, GPT-5.6/5.5/5.4 families incl. Pro and
+  Codex, o3/o4 legacy, GPT-4.1/4o). Google 7 → **15** (Gemini 4 Argon,
+  3.1 Pro Preview, 3.8→3.5 Flash lines, latest-aliases, Gemma 4 31B/26B
+  A4B). OpenRouter 11 → **42** curated live slugs (Claude 5.5, GPT-6/5.6,
+  Gemini 4/3.x, Kimi K3, Qwen3.5/Coder, GLM-5.3, Grok 4.7, Llama 4,
+  Mistral Large 4, plus verified `:free` tiers). Context windows and
+  $/1M prices cross-checked against models.dev and the OpenRouter public
+  catalog.
+- **Provider resilience — retries with backoff and honest error classes
+  (`src/providers/anthropic.js`, `openai-compat.js`).** Anthropic requests
+  retry 429/529/5xx up to 4 tries with jitter, honoring `Retry-After`;
+  openai-compat retries 429/502/503/529 exponentially (first retry is
+  immediate unless `Retry-After` says otherwise). Provider errors now carry
+  `.status`/`.retryAfterMs` so the session loop can act on them: rate limits
+  **wait and retry** (honoring `Retry-After`, capped 30s) before falling back
+  to model switching, `isQuotaError` (402/insufficient balance) still
+  auto-switches models, and `isContextOverflowError` **compacts and retries
+  once per turn**. Mid-stream SSE `error` events and fully-truncated streams
+  now throw instead of silently yielding an empty answer; Anthropic
+  `stop_reason` maps through to `finish_reason` (`max_tokens`→`length`,
+  `tool_use`→`tool_calls`) and tool results carry `is_error` on both the wire
+  and the history row (`isError`).
+- **Session-loop resilience + context hygiene (`src/core/session.js`).**
+  `_normalizeHistory()` slices every provider call from the first user row
+  (no more leading orphan assistant/tool rows), compaction summaries are
+  stored as **user-role rows** — openai-compat drops `role:'system'` history
+  rows, so the summary used to silently vanish before the model ever saw it —
+  `estimateTokens()` counts the system prompt and tool schemas,
+  `contextEstimate()` backs a live `/context` window, and auto-compaction
+  triggers at the context threshold mid-turn (once per turn). Failed tool
+  outcomes are marked `isError` in history.
+- **Two new tools — `todoread` and `tasks`** — read the current todo list,
+  and list/output/kill background tasks (`bg:*` handles, auto-gone after
+  10min finished). Tool results are capped at **100k chars** (head + tail
+  with a `[…truncated N chars…]` marker) across text, errors, and MCP
+  payloads; `read` detects binaries and caps at 512KB / 2000 lines; `bash`
+  takes `timeoutMs` (default 60s) and is killed by Ctrl-C; `webfetch`
+  aborts with the session; `edit` gains a multi-edit `edits` array (each
+  entry enforces a unique match — the single `oldString` path keeps its
+  replace-first behavior).
+- **MCP tools are permission-gated** — new `mcp` permission key (default
+  `ask`); patterns match the full tool name (`mcp__github__*`, exact names,
+  denies), and `todoread` maps to the `read` rule.
+- **Project steering reads `AGENTS.md` (`src/core/memory.js`)** — global
+  LOOM.md plus cwd `LOOM.md`/`.loom/LOOM.md`/`AGENTS.md` and up to 3 parent
+  directories (per-file 12k, project-section 24k caps), with `CLAUDE.md` as
+  a fallback when no LOOM/AGENTS file exists.
+- **Hooks: `userPromptSubmit` and `subagentStop` (`src/core/hooks.js`).**
+  `userPromptSubmit` runs before a prompt hits the model and can block the
+  prompt (`decision:"block"` or a non-zero exit with stderr) or inject
+  `<user-prompt-submit-hook>` context; `subagentStop` fires after a
+  subagent finishes; `postToolUse` now receives `tool_response` (capped 4k).
+- **TUI/CLI:** a `/compact` slash command (also Ctrl+X c), `/context` shows
+  a live context-window estimate (tokens / window / %), background-task
+  completions surface as toasts, and per-turn autosave keeps saved sessions
+  current. `loom`'s `/compact` now uses the real `session.compact()`.
+- **Easier connector installs — `loom add connector` + a visible "+ Add
+  connector…" row (`src/mcp/connector-presets.js`, `connectorAddLineCmd`).**
+  The connector preset catalog moved from the TUI into the core layer so the
+  shell and the TUI picker share one source. From the shell (or
+  `/connectors add`), a preset name plus `-e KEY=V` flags expands to the full
+  one-liner — `loom add connector supabase -e SUPABASE_ACCESS_TOKEN=xxx` —
+  and missing keys fail with the exact `-e` flag and where to get the token
+  instead of persisting a broken server. Leftover tokens append as trailing
+  args (`… supabase --project-ref abcdef`), and anything that is not a preset
+  name falls through to the generic `[-e KEY=V] <name> [--] <command>
+  [args...]` form. The `/connectors` and `/mcp` browsers now pin a "+ Add …"
+  row under the list (Enter opens the preset picker; `A` still works), and
+  the one-line add editor accepts a bare preset name.
 - **Docker sandbox with a guided `/sandbox` wizard (`src/core/sandbox.js`,
   `SandboxModal`).** `/sandbox` (or `/sandbox setup`) opens a three-step
   modal: (1) Docker check — if missing, shows the platform install link with
   an "open download page" action and remembers the pending install; (2) OS
   pick — Alpine (~250 MB, apk), Debian Slim (~600 MB, apt) or Ubuntu
-  (~900 MB, apt); (3) live build with streamed logs. Setup pulls the chosen
-  `node:20-*` image, creates the single shared `loom-sandbox` container with
-  the project mounted at `/workspace`, installs essentials (git, bash, curl,
-  ripgrep, coreutils) plus a headless Chromium where offered (best-effort).
-  The container is global — every session and every agent routes commands
-  through it — and `ensureProjectMount()` re-creates it cheaply when the
-  active project changes. Isolation: project dir only, no host network, no
-  `--privileged`. The bash tool routes through `docker exec` when enabled;
-  `LOOM_SANDBOX=0` is a hard kill-switch. Saying "docker is ready" after
-  installing reopens the wizard at the OS step.
+  (~900 MB, apt); (3) live build with a real progress UI: per-stage
+  checklist (pull → create → start → essentials → browser → ready), a
+  percentage bar driven by actual docker-pull layer bytes, and streamed
+  install logs. Setup is fully asynchronous — the TUI never freezes — and
+  the wizard can be esc'd while setup continues in the background. Setup
+  pulls the chosen `node:20-*` image, creates the single shared
+  `loom-sandbox` container with the project mounted at `/workspace`,
+  installs essentials (git, bash, curl, ripgrep, coreutils) plus a headless
+  Chromium where offered (best-effort). Isolation: project dir only, no host
+  network, no `--privileged`. The container idles in the background; the
+  dedicated **`sandbox` tool** runs one command inside it only when the
+  agent decides isolation is needed (see Changed). `LOOM_SANDBOX=0` is a
+  hard kill-switch. Saying "docker is ready" after installing reopens the
+  wizard at the OS step.
 - **Drive-to-completion harness (`src/core/session.js`).** When the model ends
   a turn with todos still pending/in_progress (the "stops between tasks"
   failure), the loop injects a continuation listing the unfinished items — up
@@ -64,6 +224,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   reads allow, interactive click/fill/press ask.
 
 ### Fixed
+- **Unit tests no longer read the developer's real `~/.loom` config**
+  (`src/core/session.test.js`, `agents.test.js`). `session.test.js` never set
+  `LOOM_CONFIG_DIR`, and the config-merge test in `agents.test.js` DELETED
+  the variable instead of restoring its temp dir — so once the local config
+  picked a dynamic models.dev provider (or any provider the test process
+  hadn't merged), every `new Session()` failed with `Unknown provider` and
+  the whole `bun run test:unit` stage went red (36 failures). Both files now
+  run hermetically against a temp config dir (restored/cleaned in
+  `afterAll`).
 - **Agent loop no longer stops in the middle of work** (`src/core/session.js`
   continuation guards — opencode/Claude-Code parity):
   - **Truncation auto-continue.** `finish_reason=length` (output budget
@@ -82,6 +251,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     todos are surfaced to the UI whenever the guard engaged.
 
 ### Changed
+- **Sandbox commands are now routed through Docker when the agent decides it
+  needs the sandbox** — instead of quietly running on the host:
+  - `bash` gained an opt-in **`sandbox: true`** parameter; the same command
+    then runs via `docker exec loom-sandbox sh -lc "<command>"`
+    (`workdir /workspace`). If the sandbox isn't set up the call FAILS with
+    the `/sandbox` setup hint — it never silently falls back to the host.
+  - The system prompt now states the exact routing (build-mode tool list +
+    a per-turn **"Sandbox (Docker, ready)"** block, resolved lazily so
+    `/sandbox setup|on|off` applies from the next turn): sandbox-intended
+    commands go through the `sandbox` tool or `bash {sandbox:true}`, ordinary
+    commands stay on the host.
+  - The `sandbox` tool description spells out the `docker exec … sh -lc`
+    shape, and the tool now flows through the same permission gate as bash
+    (dangerous commands prompt; user-approved calls carry `_approved`).
+- **Sandbox is now opt-in per command, not a global router.** Enabling the
+  sandbox no longer hijacks the bash tool — every host command keeps running
+  on your machine (Windows included) exactly as before. Instead, a dedicated
+  **`sandbox` tool** appears; the agent calls it only when isolation is
+  genuinely needed (you asked for the sandbox, the command is risky, or a
+  Linux-only environment is required). Each call revives the container if it
+  stopped (e.g. after a Docker Desktop restart) and re-mounts the current
+  project, then runs just that one command via `docker exec`. The container
+  idles in the background between calls; `/sandbox off` disables the tool
+  (not the host), `/sandbox on` re-enables it. The setup wizard's build step
+  also became fully non-blocking: docker pull streams per-layer progress
+  into a live percentage bar, package installs stream their output, and the
+  TUI stays responsive throughout (esc lets setup finish in the background).
+- **Every docker status check is now spawn-based (non-blocking).** The last
+  synchronous `execFileSync` calls — `detectDocker()` (wizard open, setup
+  start, "docker is ready" resume), `sandboxStatus()` (session start,
+  `/sandbox status`, `/sandbox on`), and `/sandbox rm` — blocked the whole
+  event loop for up to 10–30 s while Docker Desktop answered, freezing the
+  TUI (no cursor, no renders) and swallowing live progress updates. New
+  async twins (`detectDockerAsync`, `sandboxStatusAsync`, `sandboxPending`)
+  stream results back via promises; the wizard shows a spinner during the
+  check instead of hanging; the session-start pending reminder is now a
+  config-only read (zero docker calls).
 - **Slash popup decluttered.** The autocomplete popup and command palette
   now show a short one-line description per command — argument syntax is no
   longer appended (it lives in `/help` and the README table). Duplicate

package/README.md

@@ -21,11 +21,11 @@ An AI-powered coding agent for the terminal with multi-provider support and a fu
 - Full OpenTUI interface with slash commands, autocomplete, and ESC-to-interrupt
 - Build / Plan / Chat modes 
 - OpenCode-style agents — primary agents (`build`/`plan`/`chat`) plus delegating subagents (`explore`, `scout`, `general`) invoked automatically via the `task` tool or manually via `@agent` mentions
-- LOOM.md project memory file 
-- Multi-provider: Anthropic, OpenAI, NVIDIA, Google Gemini, OpenRouter, Local (Ollama)
-- Built-in tools: read, write, edit, bash, grep, glob, webfetch, todowrite
+- LOOM.md / AGENTS.md project memory (cwd + parent directories) 
+- Multi-provider: Anthropic, OpenAI, NVIDIA, Google Gemini, OpenRouter, Local (Ollama) — with automatic retries (Retry-After aware), rate-limit waits, quota-driven model switching, and compact-and-retry on context overflow
+- Built-in tools: read, write, edit (multi-edit), bash (timeouts + interrupt), grep, glob, webfetch, todowrite, todoread, tasks — results capped at 100k chars
 - Agentic tool loop (multiple tool calls per turn)
-- MCP (Model Context Protocol) server integration
+- MCP (Model Context Protocol) server integration — MCP tools are permission-gated (`mcp` rule, default ask)
 - Drag-to-copy selections, paste support
 - Session memory, /undo, /redo, /compact, /reset, /fork
 - One-shot print mode: `loom -p "query"`
@@ -33,6 +33,7 @@ An AI-powered coding agent for the terminal with multi-provider support and a fu
 - OpenCode-style agent harness: main orchestrator agent delegates to specialist subagents (`research`, `coder`, `reviewer`, `tester`, `web`, `explore`, `scout`) via the `task` tool, and a drive-to-completion loop keeps working while todos are still open
 - Headless browser tool (`browser`) — navigate, click, fill, read the DOM, and screenshot real pages from the `web` agent
 - Usage & billing tracking per session + lifetime
+- Hooks: `userPromptSubmit` (block or inject context before a prompt runs) and `subagentStop` in `.loom/hooks.json`
 
 ## Prerequisites
 
@@ -128,7 +129,7 @@ Zed (add to `~/.config/zed/settings.json`, then Command Palette → `agent: new
 Full transport spec, JetBrains/Neovim configs, the protocol walkthrough, and a
 self-test client (`node scripts/acp-smoke.js`) live in **[docs/acp.md](docs/acp.md)**.
 
-## Slash Commands (36 total)
+## Slash Commands (37 total)
 
 | Command | Args | Description |
 |---------|------|-------------|
@@ -154,16 +155,17 @@ self-test client (`node scripts/acp-smoke.js`) live in **[docs/acp.md](docs/acp.
 | `/graph` | — | Memory graph |
 | `/skills` | `install\|remove` | Manage skills |
 | `/mcp` | `add\|remove\|toggle` | Manage MCP servers |
-| `/connectors` | `add\|remove\|toggle` | Manage connectors |
+| `/connectors` | `add\|remove\|toggle` | Manage connectors — presets (supabase, railway, vercel, …) or one-liners; also `loom add connector` |
 | `/permissions` | `reset\|auto` | Permission rules |
 | `/subagents` | — | Subagent runs |
-| `/context` | — | Context window usage |
+| `/context` | — | Context window usage (live estimate) |
+| `/compact` | — | Summarize older messages to free context |
 | `/think` | `off\|low\|medium\|high` | Thinking budget |
 | `/approve` | — | Approve plan → Build |
 | `/tasks` | — | Background tasks |
 | `/share` | — | Export chat as HTML |
 | `/worktree` | `<name>` | New git worktree |
-| `/sandbox` | `setup\|status\|on\|off\|rm` | Docker sandbox |
+| `/sandbox` | `setup\|status\|on\|off\|rm` | Docker sandbox (opt-in `sandbox` tool; host untouched) |
 | `/style` | `[preset\|text]` | Output style preset |
 | `/vim` | — | Toggle vim editing |
 | `/remember` | `<fact>` | Save a fact to LOOM.md |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loom-agent",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/toshalkumbhar8979-design/loomcode.git"
@@ -24,7 +24,7 @@
     "dev": "node --watch src/index.js",
     "setup": "node src/setup.js",
     "test": "bun run src/tui/test-interactive.tsx && bun run test:unit && bun run lint:core",
-    "test:unit": "bun test src/core/agents.test.js src/core/hooks.test.js src/core/custom-commands.test.js src/core/background-tasks.test.js src/core/memory.test.js src/core/subagent-log.test.js src/core/session.test.js src/core/sandbox.test.js src/tools/index.test.js src/tools/security.test.js src/providers/providers.test.js src/providers/caching.test.js src/providers/caching-thinking.test.js src/providers/registry.test.js src/mcp/mcp-client.test.js src/mcp/mcp-manager.test.js src/core/session-store.test.js src/skills/skills-manager.test.js src/core/usage.test.js src/core/permissions.test.js src/core/format.test.js src/acp/acp-server.test.js src/tui/keybinds.test.ts",
+    "test:unit": "bun test src/core/agents.test.js src/core/hooks.test.js src/core/custom-commands.test.js src/core/background-tasks.test.js src/core/memory.test.js src/core/subagent-log.test.js src/core/session.test.js src/core/sandbox.test.js src/tools/index.test.js src/tools/security.test.js src/providers/providers.test.js src/providers/caching.test.js src/providers/caching-thinking.test.js src/providers/registry.test.js src/mcp/mcp-client.test.js src/mcp/mcp-manager.test.js src/core/session-store.test.js src/skills/skills-manager.test.js src/core/usage.test.js src/core/permissions.test.js src/core/format.test.js src/acp/acp-server.test.js src/tui/keybinds.test.ts src/core/transcript-undo.test.js src/core/update.test.js",
     "lint:core": "node node_modules/typescript/bin/tsc -p tsconfig.core.json",
     "smoke:acp": "node scripts/acp-smoke.js",
     "tui": "bun bin/loom-tui.js",

package/src/core/agents.js

@@ -62,7 +62,7 @@ const BUILTIN_AGENTS = {
     id: 'build', name: 'Build', mode: 'primary',
     description: 'Main orchestrator agent: full development work with all tools, drives tasks to completion.',
     tools: ['*'],
-    prompt: 'You are the MAIN ORCHESTRATOR agent. For non-trivial, multi-step work: (1) capture the plan as a todowrite list up front, (2) keep working until every item is completed or explicitly cancelled — never stop mid-task with a summary while todos remain, (3) delegate independent/parallelizable packages via the task tool (research for deep investigation, coder for isolated implementation, reviewer for review, tester for tests, web for browser work, explore for fast code search), (4) verify your work (run tests/typecheck/lint the project actually uses) before declaring done, (5) finish with a terse summary of what changed.',
+    prompt: "You are the MAIN ORCHESTRATOR agent. You DELEGATE heavy lifting to subagents via the task tool and synthesize their reports — you are rarely the one reading raw files. For any task that is a SEARCH, ANALYSIS, or broad OPTIMIZATION (\"find what causes X\", \"where is Y\", \"how does Z work\", \"optimize W\", \"audit/investigate/locate\"), FAN OUT FIRST: split the scope into independent questions and dispatch them as parallel task calls in a single message — one explore agent per disjoint area of the codebase (parallel calls run concurrently). Only read/grep a file YOURSELF when you need one specific line a subagent's report left ambiguous. Then: (1) for non-trivial multi-step work capture the plan as a todowrite list up front, (2) keep working until every item is completed or explicitly cancelled — never stop mid-task with a summary while todos remain, (3) dispatch implementation/verification packages too: coder for isolated implementation, reviewer for review, tester for tests, research for deep multi-source investigation, web for browser work, (4) verify your work (run tests/typecheck/lint the project actually uses) before declaring done, (5) finish with a terse summary of what changed and which subagent reports you folded in.",
   },
   plan: {
     id: 'plan', name: 'Plan', mode: 'primary',
@@ -335,6 +335,19 @@ async function runSubagent(opts) {
   const durationMs = Date.now() - t0;
   const interrupted = !!resp.interrupted;
 
+  // subagentStop hook — fires when a subagent turn ends (success, error,
+  // interrupt). Fire-and-forget: a slow/broken hook must never wedge the
+  // parent turn.
+  try {
+    const hooks = require('./hooks');
+    Promise.resolve(hooks.runHook('subagentStop', {
+      agent: agent.id,
+      runId,
+      reason: resp.type || 'end',
+      interrupted,
+    })).catch(() => {});
+  } catch {}
+
   if (parent) {
     parent.tokensIn += child.tokensIn;
     parent.tokensOut += child.tokensOut;

package/src/core/cli.js

@@ -304,8 +304,14 @@ class LoomCLI {
   }
 
   async cmdCompact() {
-    this.session.messages = this.session.messages.slice(-10);
-    console.log('Conversation compacted - keeping last 10 messages.');
+    // Real compaction: summarize the older messages with the model (falls
+    // back to head-truncation when no provider/key is available).
+    const res = await this.session.compact();
+    if (res.compacted) {
+      console.log(`Compacted (${res.method}): removed ${res.removed} messages, ~${res.tokensAfter} tokens remain.`);
+    } else {
+      console.log('Nothing to compact — the conversation is still short.');
+    }
   }
 
   cmdUndo() {
@@ -540,6 +546,7 @@ if (args.includes('--help') || args.includes('-h')) {
     console.log('  loom --auto             Auto-approve permission prompts');
     console.log('  loom acp                ACP server (JSON-RPC over stdio, for editor plugins)');
     console.log('  loom add mcp <spec>     Add an MCP server (same syntax as /mcp add)');
+    console.log('  loom add connector <spec>  Add a connector (preset like supabase, or one-liner)');
     console.log('  loom -s <session-id>    Resume a saved session');
     console.log('  loom --version           Show version');
     console.log('  loom --help              Show this help');
@@ -576,6 +583,27 @@ if (args.includes('--help') || args.includes('-h')) {
     process.exit(ok ? 0 : 1);
   }
 
+  // loom add connector <spec> — same engine as /connectors add. A preset name
+  // (supabase, nextjs, railway, vercel, netlify, cloudflare) expands with
+  // -e KEY=V flags; anything else is the generic one-liner form. Exits 0 on
+  // success.
+  if (args[0] === 'add' && (args[1] === 'connector' || args[1] === 'connectors')) {
+    const spec = args.slice(2);
+    if (!spec.length) {
+      const { CONNECTOR_PRESETS } = require('../mcp/connector-presets');
+      console.log('Usage: loom add connector <preset> [-e KEY=V]...');
+      console.log('   or: loom add connector [-e KEY=V] <name> [--] <command> [args...]');
+      console.log('Presets: ' + CONNECTOR_PRESETS.map(p => p.id).join(', '));
+      console.log('Example: loom add connector supabase -e SUPABASE_ACCESS_TOKEN=xxx');
+      process.exit(1);
+    }
+    const { connectorAddLineCmd } = require('./plugin-cmd');
+    const msg = connectorAddLineCmd(spec.join(' '));
+    const ok = typeof msg === 'string' && msg.startsWith('Added');
+    console.log(ok ? msg : 'Error: ' + msg);
+    process.exit(ok ? 0 : 1);
+  }
+
   if (sessionId && sIndex !== -1) {
     const data = loadSession(sessionId);
     if (data && data.messages && data.messages.length) {

package/src/core/hooks.js

@@ -2,27 +2,33 @@
 // agent loop (Claude Code-style). Config lives in config.json:
 //
 //   "hooks": {
+//     "userPromptSubmit": "node .loom/hooks/ctx.js", // may BLOCK the prompt or inject context
 //     "preToolUse":  "node .loom/hooks/guard.js",   // may BLOCK the tool call
-//     "postToolUse": "node .loom/hooks/audit.js",   // informational
-//     "stop":        "node .loom/hooks/notify.js"   // fires when a turn ends
+//     "postToolUse": "node .loom/hooks/audit.js",   // informational (gets tool_response)
+//     "stop":        "node .loom/hooks/notify.js",  // fires when a turn ends
+//     "subagentStop": "node .loom/hooks/done.js"    // fires when a subagent finishes
 //   }
 //
-// Contract: the command receives JSON on stdin ({ hook, tool, input } for
-// pre/post, { hook, reason } for stop) plus LOOM_HOOK / LOOM_TOOL /
+// Contract: the command receives JSON on stdin ({ hook, tool, input,
+// tool_response } for pre/post, { hook, prompt } for userPromptSubmit,
+// { hook, reason } for stop/subagentStop) plus LOOM_HOOK / LOOM_TOOL /
 // LOOM_TOOL_INPUT env vars (Windows one-liner friendly). Exit code non-zero,
-// or stdout containing {"decision":"deny","reason":"..."}, blocks a
-// preToolUse hook's tool call. A 10s timeout counts as a failure-to-run
-// (allowed through) rather than a deny — hooks must not wedge the loop.
+// or stdout containing {"decision":"deny"|"block","reason":"..."}, blocks a
+// preToolUse tool call or a userPromptSubmit prompt. userPromptSubmit stdout
+// may also carry {"hookSpecificOutput":{"additionalContext":"..."}} (or a
+// top-level additionalContext) which is appended to the user's message.
+// A 10s timeout counts as a failure-to-run (allowed through) rather than a
+// deny — hooks must not wedge the loop.
 const { spawn } = require('child_process');
 const { loadConfig } = require('../config/settings');
 
-/** @typedef {'preToolUse'|'postToolUse'|'stop'} HookName */
+/** @typedef {'preToolUse'|'postToolUse'|'stop'|'userPromptSubmit'|'subagentStop'} HookName */
 
 /**
  * Run one configured hook.
  * @param {HookName} name
- * @param {{ tool?: string, input?: object, reason?: string }} payload
- * @returns {Promise<{ blocked: boolean, reason?: string, ran: boolean }>}
+ * @param {{ tool?: string, input?: object, reason?: string, prompt?: string, tool_response?: string, agent?: string, runId?: string, interrupted?: boolean }} payload
+ * @returns {Promise<{ blocked: boolean, reason?: string, ran: boolean, additionalContext?: string }>}
  */
 async function runHook(name, payload) {
   let cmd = '';
@@ -61,20 +67,28 @@ async function runHook(name, payload) {
     child.on('error', () => { clearTimeout(timer); done({ blocked: false, ran: false }); });
     child.on('close', (code) => {
       clearTimeout(timer);
-      // Structured deny wins over exit codes; plain non-zero also blocks preToolUse.
+      // Structured deny wins over exit codes; plain non-zero also blocks
+      // preToolUse and userPromptSubmit.
       let denyReason = null;
+      let additionalContext = null;
       const m = out.match(/\{[\s\S]*\}/);
       if (m) {
         try {
           const j = JSON.parse(m[0]);
-          if (j && j.decision === 'deny') denyReason = String(j.reason || 'blocked by hook');
+          if (j && (j.decision === 'deny' || j.decision === 'block')) {
+            denyReason = String(j.reason || 'blocked by hook');
+          }
+          const ctxText = j && (j.additionalContext
+            || (j.hookSpecificOutput && j.hookSpecificOutput.additionalContext));
+          if (ctxText) additionalContext = String(ctxText);
         } catch {}
       }
-      if (name === 'preToolUse' && (denyReason || code !== 0)) {
+      const blockable = name === 'preToolUse' || name === 'userPromptSubmit';
+      if (blockable && (denyReason || code !== 0)) {
         done({ blocked: true, reason: denyReason || ('hook exited ' + code), ran: true });
         return;
       }
-      done({ blocked: false, ran: true });
+      done({ blocked: false, ran: true, additionalContext: additionalContext || undefined });
     });
   });
 }

package/src/core/memory.js

@@ -1,6 +1,9 @@
-// Memory — layered LOOM.md files injected into every session's system prompt.
-// Layers: global (~/.loom/LOOM.md) then project (<cwd>/LOOM.md). Any file may
-// pull in others with `@relative/path.md` lines (depth-capped, cycle-safe).
+// Memory — layered steering files injected into every session's system prompt.
+// Layers: global (~/.loom/LOOM.md), then project steering: LOOM.md and
+// AGENTS.md in <cwd> plus up to 3 parent directories (monorepo repos carry
+// steering at the root). CLAUDE.md loads only when the cwd has neither
+// LOOM.md nor AGENTS.md (back-compat shim). Any file may pull in others with
+// `@relative/path.md` lines (depth-capped, cycle-safe).
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -8,6 +11,10 @@ const os = require('os');
 const MAX_IMPORT_DEPTH = 3;
 // Cap each layer so a runaway memory file can't eat the context window.
 const MAX_CHARS_PER_LAYER = 12000;
+// Hard cap for the whole project section (4 dirs × 2 filenames worst case).
+const MAX_CHARS_PROJECT = 24000;
+// How many directories up from cwd carry steering files.
+const MAX_PARENT_DEPTH = 3;
 
 function globalMemoryPath() {
   const base = process.env.LOOM_CONFIG_DIR || path.join(os.homedir(), '.loom');
@@ -40,6 +47,35 @@ function loadFile(file, depth, seen) {
   return out.join('\n').trim();
 }
 
+/**
+ * Collect project steering files: cwd + up to MAX_PARENT_DEPTH parents,
+ * LOOM.md then AGENTS.md per directory, nearest first. Returns
+ * [{ file, body }] with imports expanded.
+ * @returns {Array<{file: string, body: string}>}
+ */
+function collectProjectSteering() {
+  const chunks = [];
+  const seen = new Set();
+  let dir = process.cwd();
+  for (let depth = 0; depth <= MAX_PARENT_DEPTH; depth++) {
+    const names = depth === 0
+      ? ['LOOM.md', '.loom/LOOM.md', 'AGENTS.md']
+      : ['LOOM.md', 'AGENTS.md'];
+    for (const name of names) {
+      const p = path.join(dir, name);
+      const abs = path.resolve(p);
+      if (seen.has(abs)) continue;
+      seen.add(abs);
+      const body = loadFile(p, 0, new Set());
+      if (body) chunks.push({ file: abs, body });
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return chunks;
+}
+
 /**
  * Build the full memory block: "## Global memory" + "## Project memory"
  * sections with imports expanded. Empty string when no memory exists.
@@ -49,9 +85,21 @@ function loadMemory() {
   const parts = [];
   const g = loadFile(globalMemoryPath(), 0, new Set());
   if (g) parts.push('## Global memory\n\n' + g.slice(0, MAX_CHARS_PER_LAYER));
-  let p = loadFile(path.join(process.cwd(), 'LOOM.md'), 0, new Set());
-  if (!p) p = loadFile(path.join(process.cwd(), '.loom', 'LOOM.md'), 0, new Set());
-  if (p) parts.push('## Project memory\n\n' + p.slice(0, MAX_CHARS_PER_LAYER));
+  let chunks = collectProjectSteering();
+  // CLAUDE.md parity: only when no LOOM.md/AGENTS.md steering exists in cwd
+  // or its parents — a repo that already steers via LOOM/AGENTS wins.
+  if (!chunks.length) {
+    const p = path.join(process.cwd(), '.claude', 'CLAUDE.md');
+    const body = loadFile(p, 0, new Set());
+    if (body) chunks.push({ file: p, body });
+  }
+  if (chunks.length) {
+    const content = chunks
+      .map((c) => '### ' + c.file + '\n\n' + c.body.slice(0, MAX_CHARS_PER_LAYER))
+      .join('\n\n')
+      .slice(0, MAX_CHARS_PROJECT);
+    parts.push('## Project memory\n\n' + content);
+  }
   return parts.join('\n\n');
 }