marim-harness 0.1.0__tar.gz

marim_harness-0.1.0/.env.example

@@ -0,0 +1,178 @@
+# Copy this file to .env and fill in your values. .env is gitignored.
+# Real shell environment variables take priority over .env.
+
+# --- OpenRouter (default provider) ---
+OPENROUTER_API_KEY=
+
+# Optional: override the default model (anthropic/claude-sonnet-4-6)
+# MARIM_MODEL=anthropic/claude-sonnet-4-6
+
+# --- Local provider (any OpenAI-compatible server) instead of OpenRouter ---
+# The model picker (and `marim models list`) discovers models from the server's
+# /v1/models endpoint, so MARIM_MODEL is optional once the server is reachable.
+# Ollama:
+# MARIM_PROVIDER=local
+# MARIM_MODEL=qwen2.5-coder
+# MARIM_BASE_URL=http://localhost:11434/v1
+# MARIM_API_KEY=local
+# LM Studio (note the 1234 port; start the server from the Developer tab):
+# MARIM_PROVIDER=local
+# MARIM_BASE_URL=http://localhost:1234/v1
+# MARIM_API_KEY=lmstudio
+
+# --- Multiple providers at once ---
+# Any provider whose credentials are present is auto-detected and its models are
+# merged into one tagged picker list (filter by id, name, or provider). Set
+# several at once; MARIM_PROVIDER selects the default (startup model + the target
+# for a typed model id with no provider prefix). Pick another provider's model in
+# the picker, or type a qualified id like:  local:qwen2.5-coder
+
+# --- Claude subscription via the claude CLI (Claude Code) ---
+# Use a Claude Pro/Max subscription via the `claude` CLI (Claude Code must be
+# installed and logged in). In this provider marim delegates the whole turn to
+# `claude -p`: Claude runs its own tools/loop, so marim's own tools, approval
+# gating, LSP, and MCP do not apply. `auto`/`ask` map to acceptEdits, `plan` to
+# read-only plan. MARIM_MODEL is optional (sonnet/opus/haiku; default: CLI's own).
+# MARIM_PROVIDER=claude-cli
+# MARIM_MODEL=sonnet
+# MARIM_CLAUDE_CLI_BIN=claude   # override the binary if not on PATH
+
+# --- Context window & budget ---
+# Compaction/masking trigger at min(budget, 0.8 × the model's context window).
+# The window is discovered from the provider (catalog / LM Studio probe); the
+# budget is your spend ceiling in tokens. 0 = unbudgeted (window-only).
+# Replaces the deprecated MARIM_MAX_CONTEXT_TOKENS (same meaning).
+# MARIM_CONTEXT_BUDGET=100000
+# Manual window override (tokens) for servers discovery can't read, e.g. a
+# non-LM-Studio local server; always wins over discovery.
+# MARIM_CONTEXT_WINDOW=131072
+# Per-model budgets: comma-separated fnmatch pattern=tokens pairs matched
+# against the model id, first match wins; =0 means unbudgeted for that model.
+# MARIM_CONTEXT_BUDGETS=anthropic/claude-opus*=60000,openrouter/*free*=0
+
+# --- Web search (SearXNG) ---
+# The web_search tool queries this SearXNG instance. Override to point at your
+# own/self-hosted instance; defaults to https://searxng.marim.dev. The instance
+# must have the JSON output format enabled (SearXNG disables it by default).
+# MARIM_SEARXNG_URL=https://searxng.marim.dev
+
+# --- Google (Gemini) ---
+# MARIM_PROVIDER=google
+# MARIM_MODEL=gemini-2.5-flash
+# GOOGLE_API_KEY=            # or GEMINI_API_KEY / MARIM_API_KEY
+
+# --- Session & UI ---
+# Initial approval mode for interactive sessions: ask (default), auto, or plan.
+# Ignored when set from a project .env — a cloned repo must not self-elevate.
+# MARIM_DEFAULT_MODE=ask
+# DEBUG logging to the log file (also enables spawn timing lines).
+# MARIM_DEBUG=1
+# Detached fan-out: spawn_agent with `background` unset auto-detaches in the
+# TUI (live cards + job handles) instead of running inline. On by default.
+# MARIM_DETACH_FANOUT=1
+# Desktop notifications: on by default; pick events from turn_complete,
+# error, approval_needed, ask_user, job_done (default: all but job_done).
+# MARIM_NOTIFICATIONS=0
+# MARIM_NOTIFICATION_EVENTS=approval_needed,ask_user
+# Autonomous wake: finished background jobs start a new turn to deliver their
+# reports while you're away; the depth cap bounds chained wakes.
+# MARIM_AUTONOMOUS_WAKE=1
+# MARIM_WAKE_DEPTH_CAP=8
+
+# --- Command policy (bash tool) ---
+# Comma-separated command prefixes to always allow / always block, checked
+# before the built-in policy.
+# MARIM_COMMAND_ALLOWLIST=git status,ls
+# MARIM_COMMAND_DENYLIST=rm -rf
+
+# --- Trust (project-local executable config) ---
+# Project-local hooks (.marim/hooks.json), MCP servers (.marim/mcp.json), and
+# project-scope plugins launch code from the repo on startup. They load only
+# when this is set — leave it unset for repos you don't fully trust.
+# MARIM_TRUST_PROJECT_HOOKS=1
+
+# --- LSP ---
+# Language-server integration: MARIM_LSP gates the manager + diagnostics on
+# write/edit; MARIM_LSP_TOOLS gates the six navigation tools. Both on by
+# default; 0 disables.
+# The four bundled language plugins (python, typescript, cpp, java; see
+# docs/lsp-plugins.md) always load regardless of trust. Third-party plugins
+# that add a language via an `lsp` manifest block follow the same
+# MARIM_TRUST_PROJECT_HOOKS gate as project-local hooks/MCP servers above.
+# MARIM_LSP=1
+# MARIM_LSP_TOOLS=1
+
+# --- Forge (Gitea/GitHub) ---
+# Forge (Gitea/GitHub) tools via the tea CLI; on by default. Set to 0 to disable.
+# MARIM_FORGE=1
+
+# --- Scratchpad ---
+# Session scratchpad: a per-session /tmp directory the agent uses for
+# intermediate files (advertised in the prompt; writes there skip approval
+# in ask mode). 1 (default) or 0.
+# MARIM_SCRATCHPAD=1
+
+# --- Dynamic workflows ---
+# Dynamic workflows (the run_workflow tool; needs the [workflows] extra). Default on.
+# MARIM_WORKFLOWS=1
+# Ceiling (seconds) on the wall-clock budget one run_workflow call may request
+# via its timeout_secs parameter. Default 1800 (30 min).
+# MARIM_WORKFLOW_TIMEOUT=1800
+
+# --- Compaction / observation masking ---
+# Elide bulky, stale tool observations at compaction time (keep the newest N
+# payloads; only bodies over the char floor are masked). On by default.
+# MARIM_MASK_OBSERVATIONS=0
+# MARIM_MASK_KEEP_RECENT=4
+# MARIM_MASK_MIN_CHARS=200
+
+# --- Sub-agents ---
+# Cap concurrent spawn model-runs (default 8; 0 = unbounded) / per-spawn request
+# budget (default 50) / persisted transcript size in messages (default 2000).
+# MARIM_SUBAGENT_CONCURRENCY=8
+# MARIM_SUBAGENT_REQUEST_LIMIT=50
+# MARIM_SUBAGENT_TRANSCRIPT_CAP=2000
+# Sub-agent model tiers: the model each tier routes to (qualified provider:model_id).
+# A read-only spawn defaults to cheap, a mutating one to high; a spec's `tier:` or
+# the spawner's tier= override picks explicitly. Unset ⇒ inherit the main model.
+# MARIM_SUBAGENT_TIER_CHEAP=local:ornith-1.0-9b
+# MARIM_SUBAGENT_TIER_MED=openrouter:anthropic/claude-sonnet-4-6
+# MARIM_SUBAGENT_TIER_HIGH=openrouter:anthropic/claude-opus-4
+# Master switch for tier routing. 0 ⇒ every spawn inherits the main model while
+# the tier slugs above stay configured (toggle back on to restore routing). The
+# TUI settings checkbox applies this live. Default on.
+# MARIM_SUBAGENT_TIERING=1
+
+# --- Advisor ---
+# A model the agent can consult mid-task for strategic guidance (the advisor
+# tool): qualified provider:model_id, or a bare slug for the default provider.
+# Unset = no advisor (the tool is not offered to the model).
+# MARIM_ADVISOR_MODEL=openrouter:anthropic/claude-opus-4.8
+# Output cap per consultation (default 2048).
+# MARIM_ADVISOR_MAX_TOKENS=2048
+# Per-turn call cap. Unset or 0 = unlimited.
+# MARIM_ADVISOR_MAX_USES=3
+
+# --- Thinking level (reasoning effort) ---
+# Reasoning effort applied to the model via ModelSettings.thinking. One of:
+# off, minimal, low, medium, high, xhigh. Unset or 'off' = no reasoning effort
+# (marim's default). /think overrides it per session, live.
+# MARIM_THINKING=medium
+
+# Claude Code model for `backend: claude-cli` sub-agents (alias or full id).
+# MARIM_CLAUDE_CLI_MODEL=sonnet
+# Proactive memory: the agent saves/recalls notes unprompted (off by default).
+# MARIM_PROACTIVE_MEMORY=1
+
+# --- MCP tool search ---
+# Defer a large MCP/plugin tool surface behind a searchable index instead of
+# advertising every tool: on, off, or auto (defer above the threshold).
+# MARIM_TOOL_SEARCH=auto
+# MARIM_TOOL_SEARCH_THRESHOLD=15
+
+# --- Misc ---
+# Combined `job(action, …)` tool instead of the four jobs/job_output/
+# wait_for_job/cancel_job tools (for models that handle fewer tools better).
+# MARIM_JOB_TOOL_COMBINED=1
+# Where pasted-image bytes are cached (content-addressed, per session).
+# MARIM_IMAGE_CACHE_DIR=~/.marim/image-cache

marim_harness-0.1.0/.gitea/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      # Install uv via the official script rather than a marketplace action, so
+      # the job doesn't depend on the Gitea runner mirroring third-party actions.
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      # Cache uv's download/build cache (compiled wheels for grpcio, cryptography,
+      # pydantic-core, …) so a cold matrix leg doesn't rebuild them every run. Keyed
+      # on uv.lock; first-party actions/* already resolve here (see checkout above).
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-py${{ matrix.python-version }}-
+
+      - name: Sync dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check src tests
+
+      - name: Type-check (pyright)
+        run: uv run pyright
+
+      - name: Test (pytest)
+        run: uv run pytest
+
+      # Catch packaging regressions (missing metadata, broken includes) before a
+      # release does. One leg is enough — the artifacts are version-independent.
+      - name: Build sdist + wheel
+        if: matrix.python-version == '3.12'
+        run: uv build
+
+      # Pinned to v3: upload-artifact@v4 uses the @actions/artifact v2 API, which
+      # the Gitea act_runner (GHES-like) does not support — it fails the step with
+      # "GHESNotSupportedError". v3 uses the older artifact protocol Gitea implements.
+      - name: Upload coverage
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-py${{ matrix.python-version }}
+          path: coverage.xml
+
+      # Trim cache to only what this run actually used, keeping the saved cache lean.
+      - name: Prune uv cache
+        if: always()
+        run: uv cache prune --ci

marim_harness-0.1.0/.gitea/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+# Publish to PyPI when a version tag is pushed. Cut a release with:
+#   git tag v0.1.0 && git push origin v0.1.0
+# Requires a repository secret PYPI_API_TOKEN (a PyPI API token scoped to the
+# marim-harness project). Trusted publishing (OIDC) isn't available from a
+# self-hosted Gitea, so a token it is.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Install uv via the official script rather than a marketplace action, so
+      # the job doesn't depend on the Gitea runner mirroring third-party actions.
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Sync dependencies
+        run: uv sync --python 3.12
+
+      # Re-run the full check sequence on the tagged commit — a tag can point
+      # anywhere, so don't assume a green CI run already covered it.
+      - name: Lint (ruff)
+        run: uv run ruff check src tests
+
+      - name: Type-check (pyright)
+        run: uv run pyright
+
+      - name: Test (pytest)
+        run: uv run pytest
+
+      # Refuse to publish a version that doesn't match the tag — catches the
+      # classic "tagged v0.2.0 but pyproject still says 0.1.0" mistake.
+      - name: Check tag matches project version
+        run: |
+          version=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "pyproject version ($version) != tag ($tag)" >&2
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token "${{ secrets.PYPI_API_TOKEN }}"

marim_harness-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+
+# Tool caches / generated reports
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.VSCodeCounter/
+
+# Coverage artifacts from the test runner
+.coverage
+coverage.xml
+htmlcov/
+
+# Python build / packaging artifacts (uv build, pip wheel, etc.)
+build/
+dist/
+*.egg-info/
+
+# Node / Playwright — the e2e-tests workflow runs @playwright/test via npx.
+node_modules/
+/test-results/
+/playwright-report/
+/blob-report/
+.last-run.json
+
+# OS / editor cruft.
+.DS_Store
+*.swp
+
+# marim's per-project working dir: offloaded fetch bodies, sub-agent/output
+# spill, the last-provider-error payload, and generated test reports — all local
+# scratch. Ignored wholesale; commit a specific file with a negation (e.g.
+# `!.marim/mcp.json`) if a project ever needs to track project-local config.
+.marim/
+
+# Git worktrees created by --worktree / the /worktree command.
+.worktrees/
+
+# Claude Code host config — per-machine and duplicated by marim's own plugins.
+# marim never reads .claude/ (see test_ignores_claude_agents_dir) nor the root
+# .mcp.json (it uses .marim/mcp.json; see mcp/config.py). The playwright agents
+# + MCP server ship as the examples/playwright plugin, the source of truth.
+.claude/
+.mcp.json
+# Stray Playwright seed scaffolded at the repo root by `playwright init-agents`.
+# The e2e workflow's real seed lives at tests/seed.spec.ts (still trackable);
+# only the misplaced root copy is ignored.
+/seed.spec.ts
+
+# Playwright e2e workspace scaffolded by `playwright init-agents` (the planner's
+# specs/plan.md output dir). Scaffold, not marim source — the workflow itself
+# lives in the examples/playwright plugin. Ignored wholesale.
+/specs/

marim_harness-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to marim-harness are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project adheres to [Semantic Versioning](https://semver.org/) —
+pre-1.0, minor versions may contain breaking changes.
+
+## [Unreleased]
+
+Everything so far — `0.1.0` will be the first tagged release. Highlights of
+what exists today:
+
+- **Interactive TUI** (Textual): streaming responses, tool-call cards, live
+  token counter, inline approval / ask-user / plan panels, sub-agents screen,
+  settings, model picker, themes.
+- **Headless mode**: one-shot prompts with `text`, `json`, or `stream-json`
+  output; `marim serve` HTTP daemon (REST + WebSocket) in the `[serve]` extra.
+- **Providers**: OpenRouter (default), any local OpenAI-compatible server
+  (Ollama, LM Studio), Google Gemini, and a `claude-cli` provider that
+  delegates turns to Claude Code on a Claude subscription.
+- **Permission modes** (`auto` / `ask` / `plan`), a configurable shell command
+  policy, and workspace-confined file tools.
+- **Sessions**: per-workspace persistence, resume, compaction with observation
+  masking, checkpoints and `/rewind` backed by git snapshots.
+- **Sub-agents**: parallel spawns with granted tool reach, model tiers
+  (`cheap`/`med`/`high`), nesting with a depth ceiling, detached fan-out with
+  live cards, and an optional `claude -p` backend.
+- **Dynamic workflows**: a gated `run_workflow` tool executing model-authored
+  scripts in a pydantic-monty sandbox (`[workflows]` extra).
+- **Integrations**: MCP servers (global / project / plugin scope), LSP
+  navigation + diagnostics via pluggable providers (Python, TypeScript, C++,
+  Java bundled), Gitea/GitHub forge tools via the `tea` CLI, lifecycle hooks
+  (Claude-Code-compatible), plugins, skills, and persistent memory.
+- **Embeddable**: `HarnessBuilder` composes the same agent loop as a library
+  with explicit config and no env reads (see `docs/embedding.md` and
+  `docs/sdk/`).
+- **Extras**: advisor model, thinking levels, desktop notifications, image
+  input, background jobs with autonomous wake, session scratchpad.

marim_harness-0.1.0/CLAUDE.md

@@ -0,0 +1,234 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`marim-harness` is a terminal coding agent built on [Pydantic AI](https://ai.pydantic.dev/)
+and [Textual](https://textual.textualize.io/). It reads/searches/edits files and runs
+commands in a workspace, with an interactive TUI and a headless one-shot mode. The
+console scripts are `marim` and `marim-harness` (both → `marim_harness.__main__:main`).
+
+## Commands
+
+```bash
+uv sync                          # install deps (creates .venv)
+uv run pytest                    # full test suite (coverage is on by default via pyproject)
+uv run pytest tests/test_agent.py            # one file
+uv run pytest tests/test_agent.py::test_name # one test
+uv run pytest --no-cov tests/test_x.py       # skip coverage for a fast single run
+uv run ruff check src tests      # lint
+uv run ruff check --fix src tests
+uv run pyright                   # type-check (standard mode, src only)
+uv run marim serve --port 8642   # HTTP daemon (REST + WebSocket); needs the [serve] extra
+```
+
+CI (`.gitea/workflows/ci.yml`) runs ruff → pyright → pytest on Python 3.10, 3.12,
+and 3.14 (plus a `uv build` packaging check on the 3.12 leg). Match that order
+locally before claiming work is done. `requires-python` is `>=3.10`, so avoid
+3.11+ only syntax.
+
+Set `MARIM_DEBUG=1` for DEBUG logging. Provider config lives in env vars / `.env`
+(see `.env.example`): `MARIM_PROVIDER` (`openrouter`|`local`|`google`|`claude-cli`), `MARIM_MODEL`,
+`OPENROUTER_API_KEY`, etc. Default provider is OpenRouter, default model
+`anthropic/claude-sonnet-4-6`. `claude-cli` delegates each turn to the `claude` CLI on a
+Claude subscription — marim acts as a launcher (Claude runs its own tools/loop), so marim's
+own tools/approval/LSP/MCP do not apply in that provider. Claude's own Agent/Task
+sub-agents, however, are demuxed out of the stream (`subagents/cli_demux.py`) and
+rendered as first-class cards in the sub-agents screen, for both the main-loop
+provider and `backend: claude-cli` spawns. Interrupted `claude-cli` spawns
+resume via the CLI's own `--resume` (the session id is checkpointed in the
+spawn's sidecar meta).
+
+## Architecture
+
+The dependency flow is **`__main__` → `interfaces/cli/router` → `default_cmd` →
+`runtime/bootstrap.py`'s `build_harness` → `Harness`**. The two front-ends (TUI and
+headless) both go through `build_harness`, so they wire up models, sessions, MCP,
+hooks, and LSP identically — keep new wiring there, not duplicated per interface.
+
+The turn-execution engine lives in the **`runtime/`** package: `harness.py`
+(`Harness`, `build_collaborators`, `build_services`), `controller.py`
+(`TurnController`, the approval/persist loop), `context.py` (per-turn context
+helpers), `deps.py`, `permissions.py` (`Mode`), `errors.py`, `instructions.py`,
+`builder.py`, and `bootstrap.py`. Imports target submodules directly (`from
+.deps import Deps`); the package root deliberately re-exports nothing, keeping
+the deps/services cycle below from leaking through `__init__` at import time.
+
+`HarnessBuilder` (`builder.py`) is the embedding front door — explicit model,
+explicit tool/session/sub-agent composition, no `MARIM_*` env reads; see
+`docs/embedding.md`. `bootstrap.build_harness` is the CLI preset built on top
+of that same builder (env config, workspace scanning, TUI/headless wiring).
+New construction wiring (a tool group, a config knob) goes in the builder;
+env/discovery reading stays in bootstrap, so the two paths cannot drift.
+
+### The core turn loop (`runtime/harness.py`)
+
+`Harness` owns the Pydantic AI `Agent` and drives one user turn to completion.
+`Harness.run_turn` → `_run_with_approval` is the heart of the system. Key invariants
+encoded there (read the docstrings before touching):
+
+- **Approval rounds.** The agent's `output_type` is `[str, DeferredToolRequests]`.
+  Gated tools (`write_file`, `edit_file`, `bash`) defer; `_run_with_approval` loops,
+  resolving each deferred batch via `resolve_approvals` against the current `Mode`
+  (`auto`/`ask`/`plan`), then continues the run with the results.
+- **Resumability.** A persisted history must never end with a `ToolCallPart` lacking
+  its `ToolReturnPart` — every provider rejects that on the next request.
+  `_repair_unanswered_tool_calls` self-heals such histories; an aborted turn is
+  flushed via `_flush_resumable` (with a tight deadline so Ctrl-C stays snappy).
+  The dirty history held during an approval round is deliberately **not** persisted —
+  `resumable` is the rollback baseline and is refreshed only after a clean persist.
+- **Prompt assembly.** `_assemble_prompt` prepends per-turn context (task checklist,
+  finished-job digests, the prior turn's actionable error note, SessionStart /
+  UserPromptSubmit hook output) and wraps the injected prefix in a `<turn-context>`
+  envelope so a resumed session can recover just what the user typed
+  (`strip_turn_context`). The system prompt is kept stable to preserve prompt caching.
+- **Error notes.** `_actionable_error_note` surfaces only failures the *model* can act
+  on (4xx client errors, usage limits, malformed responses) and stays silent on infra
+  (429/5xx), cancels, and render bugs. Full provider payloads spill to
+  `.marim/last-provider-error.json`.
+
+### Construction & the deps/services cycle
+
+`build_collaborators` (in `runtime/harness.py`) builds the whole collaborator graph
+(agent, MCP, LSP, session, checkpoints, hooks, subagents) in dependency order. There
+is one unavoidable late binding: `Deps` and `HarnessServices` form a reference cycle — `TurnHooks` and the
+sub-agent runners hold `deps`, while tools reach back through `ctx.deps.services`.
+`build_services` performs that single binding. `HarnessConfig` bundles all optional
+knobs; `Harness.__init__` still accepts legacy `**kwargs` as a shorthand for
+building one (pass `config=` *or* kwargs, not both — mixing raises `TypeError`).
+
+`Deps` (`runtime/deps.py`) is the `RunContext` payload threaded through every tool. All
+UI-facing collaboration is **optional callbacks** that headless leaves as `None`
+(each reader guards with `is None`). The TUI wires them in one place via
+`Harness.bind_ui` — don't poke `harness.deps`/`harness.session` field-by-field from
+the interface layer.
+
+### Tools (`tools/`)
+
+Tool implementations are module-level functions in `tools/provider.py` so they can be
+registered two ways from one source of truth: onto the main agent (gated tools behind
+`requires_approval=True`) and onto sub-agents (registered *plain* — reach is decided
+up front by which names are granted, never by mid-run prompting). `spawn_agent`
+is granted to a sub-agent only when it could still nest within the depth ceiling
+(`depth + 1 < SUBAGENT_MAX_DEPTH`, default 3) — see `SubagentRunner.build`; at
+the leaf depth the tool is absent, so nesting is bounded, not forbidden. Nested
+spawns render in the sub-agents screen as an indented tree (a child card streams
+into its parent's transcript pane). Tool docstrings are the model-facing tool
+descriptions — they are part of the product; write them with that in mind.
+`names.py` is the leaf module holding tool-name sets (`GATED_TOOLS`, `LSP_TOOLS`, etc.)
+to avoid import cycles.
+
+### Supporting subsystems (one concern each)
+
+- `session/` — `SessionStore` (persists to `$XDG_DATA_HOME/marim-harness/sessions`),
+  `SessionManager`, `SessionController` (compaction/autoname), `CheckpointManager`
+  (rewind via `GitSnapshotter`, honoring `.gitignore`).
+- `mcp/` — Model Context Protocol server config + lifecycle; servers can be granted
+  selectively to sub-agents. Project-local `.marim/mcp.json` servers launch code on
+  connect, so they load only when the project is trusted (the same
+  `MARIM_TRUST_PROJECT_HOOKS` gate as project hooks); global/plugin servers always load.
+- `lsp/` — multilspy-backed language servers, now assembled from **LSP providers**
+  (`provider.py`: `LspProvider` + `LspRegistry`) rather than a hard-coded set. Four
+  bundled language plugins (`lsp/bundled/{python,typescript,cpp,java}`) ship in-tree
+  and always load; third-party plugins add languages via an `lsp` manifest block
+  (declarative `command`/`args` only) under the same `MARIM_TRUST_PROJECT_HOOKS` gate
+  as MCP. `backend:`/named-`diagnostics:` keys are a bundled-only seam to in-tree tuned
+  code (`basedpyright.py`, ruff/pyright via `checks.py`). Declarative servers launch
+  through `GenericStdioServer` (`generic.py`). Two switches still gate the whole thing:
+  `lsp_enabled` (manager + diagnostics-on-edit) and `lsp_tools_enabled` (the six nav
+  tools). marim never downloads server binaries — it probes PATH and surfaces the
+  provider's install hint.
+- `forge/` — Gitea/GitHub integration via a `ForgeBackend` seam. `TeaBackend`
+  shells out to the `tea` CLI (`--output json`); five forge-agnostic tools
+  (`tools/forge_tools.py`) list/view PRs, check CI, and open/check out PRs, with
+  create/checkout gated for approval. Attached at build time only when
+  `MARIM_FORGE` is on (default) and a backend is available (`tea` on PATH + a
+  configured login). A `gh` backend is a future drop-in behind the same protocol.
+- `hooks/` — Claude-Code-compatible lifecycle hook engine (session/prompt/tool/
+  compaction events). Observe-only except SessionStart/UserPromptSubmit (inject
+  context) and PreCompact (may block a *manual* /compact via exit 2 or
+  `{"decision":"block"}`; block verdicts on auto compaction are logged and
+  ignored). Project-local hooks run only when trusted
+  (`MARIM_TRUST_PROJECT_HOOKS`).
+- `plugins/` — bundles skills + sub-agents + hooks + MCP + `AGENTS.md`; hooks/MCP load
+  only for *trusted* plugins. Namespaced `plugin:item`. See `docs/plugins.md`.
+- `workspace/` — fs primitives, memory (`remember`/`recall`), skills, sub-agent specs,
+  git worktrees, snapshots, and the session scratchpad (a per-session /tmp dir for
+  intermediate files: advertised in the prompt, reachable by the file tools as an
+  extra guard root, auto-approved in ask mode, gated by `MARIM_SCRATCHPAD`). (The
+  root-level `compaction.py` builds the summarizer/titler aux agents and the
+  token-budget compaction helpers.)
+- `subagents/` — `runner.py` (`SubagentRunner`: spawn-lifecycle coordinator),
+  `run_driver.py` (model-loop retry/overflow/contention recovery),
+  `cli_spawn.py` (`claude -p` execute/resume orchestration), `masking.py`
+  (per-spawn context masking of stale tool observations), and `cli_backend.py`
+  (the optional `claude -p` CLI backend it delegates to). Re-exported as
+  `marim_harness.subagents.SubagentRunner`. Native spawns pick a model by **tier** (`cheap`/`med`/`high`, in `subagents/tiers.py`): resolved from the spawner's `tier=` override → the spec's `tier:` frontmatter → tool reach (read-only→cheap, mutating→high), mapped to `MARIM_SUBAGENT_TIER_*`; unset tiers inherit the main model and a `model=` slug stays a bounded escape hatch.
+- `workflows/` — dynamic workflows: the gated `run_workflow` tool executes a
+  model-authored Python script in a pydantic-monty sandbox (`engine.py`);
+  `agent()`/`log()` host functions delegate to `SubagentRunner.run` through
+  the `services.run_workflow` seam. Schema validation of agent() reports is
+  engine-level (`schema.py`, jsonschema). Never cancel the Monty VM task —
+  aborts flow through host functions (see engine.py's module docstring).
+  Optional extra `[workflows]`; `MARIM_WORKFLOWS` gates it.
+- `advisor.py` (root) — the advisor: an `advisor()` tool on the main agent
+  forwards the full transcript to a separately-configured model
+  (`MARIM_ADVISOR_MODEL`, any provider) and returns strategic guidance.
+  Live seam is `services.advise` (a pydantic-ai `prepare` hook omits the tool
+  when it's `None`, so `/advisor <model>`/`/advisor off` toggle without a
+  rebuild — at the cost of one prompt-cache break per toggle). Session
+  persistence mirrors `store.model` (`"off"` sentinel = explicitly disabled);
+  per-turn call cap `MARIM_ADVISOR_MAX_USES` rides on `Deps`. Main loop only
+  (sub-agents have tiering); the tool doesn't exist under the claude-cli
+  main-loop provider (marim's tools don't apply there), but a claude-cli
+  *advisor* model works via the `aux_model_for` clone.
+- `thinking.py` (root) — thinking level (reasoning effort): one ordered
+  vocabulary (`off/minimal/low/medium/high/xhigh`) and three pure helpers —
+  `parse_thinking_level` (env/CLI/`/think` coercion), `settings_for` (fold a
+  level into `ModelSettings.thinking`; `off`/unset OMITS the key, byte-identical
+  to pre-thinking behavior), and `resolve_thinking` (sub-agent precedence:
+  spawn override → spec `thinking:`/`effort:` → inherited session level). The
+  main loop applies it per turn in `TurnController._turn_model_settings`; the
+  level persists on `SessionStore.thinking` and lives on `Harness.thinking_level_id`
+  (read lazily by the controller closure and the sub-agent runner, so `/think`
+  switches without a rebuild). Seeded by `MARIM_THINKING` / `--think`; TUI
+  `/think` command + Settings row. Under the `claude-cli` main provider it's a
+  documented no-op (marim's `ModelSettings` don't reach Claude Code). Detection
+  (`catalog.supports_thinking`) is best-effort UI annotation only — it never
+  blocks a level.
+- `interfaces/tui/` — Textual app, widgets, `styles.tcss`, streaming render;
+  `interactions/` — inline approval/ask-user/plan-card panels (mounted above the
+  status bar, not modals, so the transcript stays scrollable) sharing an
+  `InteractionPanel` base; `subagents/` — the sub-agents screen: master list,
+  full-bleed view, inline card, persistent transcript pane, pure stats.
+  `interfaces/cli/` — router + per-command modules (lazily imported so
+  `config`/`models` don't pay for `pydantic_ai`).
+
+## Conventions
+
+- Use `uv` for everything (`uv run …`, `uv sync`). Don't invoke `pip` or a bare
+  `python`/`pytest`.
+- Ruff line length is 100; lint set is `E,F,I,UP,B,SIM,C901` (import sorting
+  enforced; pyupgrade, bugbear, and flake8-simplify also on).
+- Cyclomatic complexity is capped at 10 (`C901`, mccabe). CI rejects any function
+  above it. When a function trips the ceiling, extract cohesive branch-clusters into
+  named helpers (or a small state value-object where locals mutate across the region)
+  — do not add a blanket `# noqa: C901`. Note: this bounds *branch count*, not length;
+  a long, straight-line, well-commented function is fine.
+- Keep pure decision/parse helpers (command policy, snapshot diffing, arg coercion,
+  path-guard resolution, and the extracted module-level helpers inside the effectful
+  modules) side-effect-free and unit-tested directly. The effectful I/O itself lives in
+  `tools/impl/` (`fs.py` writes, `shell.py` spawns, `fetch.py` opens sockets) — that is
+  the real I/O *core*, not a pure layer; it is exercised directly against a tmp
+  workspace. Above it, the tool layer (`fs_tools.py`, `edit_tools.py`, `net_tools.py`)
+  is thin `ctx.deps`-unwrapping wiring. Follow that three-way split when adding behavior.
+- The codebase favors long, explanatory comments on *why* a non-obvious invariant
+  holds (especially around resumability and the deps/services cycle). Preserve them
+  when editing nearby code.
+- Follow `coding-guidelines.md` for code design principles: control complexity,
+  prefer straight-line flow, model the domain when it pays off, encapsulate
+  collections with behavior, limit deep navigation, name for clarity, optimize for
+  cohesion, treat large state as a smell, and encapsulate behavior over data.
+  It's guidance, not dogma — break a rule when the tradeoff is clear and
+  document why.