feat: model-free tool CLI and MCP server for external coding agents

docs/docs/configure/agents.md

@@ -30,6 +30,8 @@ The agent for asking questions about your data. Truly read-only mode for safe da
 - **Schema/warehouse/finops**: All inspection tools available
 - **Workspace knowledge**: Loads workspace and project skills; reads workspace memory and views this checkout's memory audit log. Can read files bundled with skills, including global skills stored outside the project. Reloading memory syncs the local copy with the workspace, which can remove a local copy of a block the workspace archived. Saving memory is done with `builder`.
 - **Config overrides**: A permission config such as `"*": "allow"` cannot turn file edits, SQL writes (including data diffs of arbitrary queries), shell, memory saves, warehouse connection or MCP config changes, training imports, sample project setup, feedback submission, batch tool calls or delegation beyond `data-explorer` back on. A global `"*": "allow"` does turn on MCP and custom tools for analyst, including ones that write (for example a SQL MCP server); to keep them from analyst, put the `"*": "allow"` under `agent.builder` instead of the global config, or deny those tools under `agent.analyst.permission`.
+- **Reasoning effort**: On adaptive-thinking models the analyst requests `high` effort unless the agent or model options already choose one. Set `ALTIMATE_ANALYST_EFFORT` (`low`, `medium`, `high`, `xhigh`, `max`, or `off` to send none) to change it.
+- **Final answers**: `answer_commit` asks the interactive analyst once per turn to re-check any number that did not appear in tool output before the answer is committed.
 
 !!! tip
     Use `analyst` when exploring data to ensure no accidental writes. Switch to `builder` when you're ready to create or modify models.

docs/docs/configure/mcp-servers.md

@@ -6,6 +6,43 @@ description: "Configure Model Context Protocol (MCP) servers in Altimate Code to
 
 altimate supports the Model Context Protocol (MCP) for connecting to external tool servers.
 
+## Use Altimate Code tools from another MCP client
+
+Run `altimate-code mcp serve` to expose data tools over stdio. Your MCP client's model handles reasoning; this server runs tools directly without calling a model.
+
+Add this entry to your MCP client's configuration (for example, Claude Code's `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "altimate-code": {
+      "command": "altimate-code",
+      "args": ["mcp", "serve", "--connections", "/absolute/path/to/connections.json"]
+    }
+  }
+}
+```
+
+By default the server exposes `warehouse_list`, `warehouse_add`, `sql_execute`, `sql_materialize` and `answer_commit`, plus `impact_analysis`, `dbt_lineage`, `altimate_core_column_lineage`, `schema_detect_pii`, `data_diff`, `altimate_core_equivalence` and `sql_translate`. Pass `tables` to `sql_execute` to get those tables' columns and value profiles in the same call as its queries. Start with `--all-tools` to expose every data tool, the same set `altimate-code tool list` shows. Without `--connections`, the server reads the usual connection sources and re-reads them while none are configured, so a connections file written mid-session, or a connection added with `warehouse_add`, is picked up without a restart. A connections file is a JSON object keyed by connection name:
+
+```json
+{
+  "local": { "type": "sqlite", "path": "./analytics.sqlite" }
+}
+```
+
+Relative database paths resolve beside this file. With `--connections`, this file is the only source of connections: global and project `connections.json` files and `ALTIMATE_CODE_CONN_*` overrides are ignored. Omit `--connections` to use normal connection discovery: global and project `.altimate-code/connections.json` files, followed by `ALTIMATE_CODE_CONN_*` environment overrides. Set your client's working directory to the project when using project discovery.
+
+At startup the server lists each connection's name and type in its instructions, read from configuration only: it does not connect to remote or server databases or run queries on them. For local SQLite and DuckDB files (not behind an SSH tunnel) it also lists table names from one catalog query (no row counts); a file with more than 40 tables is noted as such instead. Call `warehouse_list` for columns and sample rows. Listing tools use catalog row estimates where available (including DuckDB); SQLite listings omit row counts. They never count rows by scanning each table.
+
+<!-- altimate_change start — MCP read-only limits and private output lifecycle -->
+
+Source writes are refused by default. Without `--allow-write`, source queries request database-enforced read-only execution on PostgreSQL, SQLite and DuckDB. For other connection types, read-only is enforced by SQL classification only; stored functions with side effects are not blocked — use a read-only database user. The server prints this caveat on stderr at startup and includes it in `warehouse_list` for each affected connection. Add `--allow-write` to enable SQL write permissions; existing hard safety blocks still apply (`DROP DATABASE`, `DROP SCHEMA` and `TRUNCATE` stay blocked). `warehouse_add` may write local connection configuration (the connections file and the operating system credential store) even in read-only mode. `sql_materialize` always requires a read-only source query and writes only into the server session's temporary `scratch` warehouse. Scratch tables disappear when the server exits. Large results may include a local spill file path that your client can open with any file reader. Spill files use a private directory and are deleted when the server exits. Local `tool_output.max_lines` and `tool_output.max_bytes` settings control output limits; remote agent configuration is not loaded.
+
+<!-- altimate_change end -->
+
+The server writes only MCP protocol messages to stdout and sends logs to stderr. It honors `ALTIMATE_TELEMETRY_DISABLED`.
+
 ## Local MCP Servers
 
 Run an MCP server as a local subprocess:

docs/docs/configure/skills.md

@@ -341,3 +341,7 @@ The skill list the agent sees marks each skill with where it was found:
 When more than one skill fits a task, the agent is told to load the one from the highest source in that order, and to fall back to a lower source only when nothing higher covers the task. So a skill your team added to the workspace is preferred over a similar skill another team left in the repository. The label comes from the skill's location, not from anything written in the skill.
 
 One exception: a project skill with exactly the same name as a workspace skill replaces it, and is listed as `project`. That keeps a skill you are editing in the repository, and may later publish, from being shadowed by the workspace's older copy.
+
+### Copies for Claude Code
+
+In a linked project that has a `.claude` directory, each workspace sync can also write the workspace skills into `.claude/skills/` so Claude Code finds them. Copies are written only when `ALTIMATE_CLAUDE_SKILL_SYNC=1` is set; the Altimate Code plugin for Claude Code sets it when it refreshes the workspace. The copies are marked as owned by Altimate Code and git-ignored, and they are withdrawn when you unlink the project or sign out (withdrawal runs whether or not the variable is set).

docs/docs/usage/cli.md

@@ -28,6 +28,7 @@ altimate --agent analyst
 | ----------- | ------------------------------ |
 | `run`       | Run a prompt non-interactively |
 | `check`     | Run deterministic SQL checks (no LLM required) -- see [SQL Check](check.md) |
+| `tool`      | Run the data tools without a model, optionally via a warm daemon -- see [Tool CLI](tool.md) |
 | `serve`     | Start the HTTP API server      |
 | `web`       | Start the web UI               |
 | `agent`     | Agent management               |

docs/docs/usage/tool.md

@@ -0,0 +1,78 @@
+---
+title: "Tool CLI (Headless) — Altimate Code"
+description: "Call Altimate Code data tools from any shell, agent or CI job without an LLM. Optional warm daemon keeps connections and the schema cache ready."
+---
+
+# Tool CLI (Headless)
+
+Expose the data tools -- warehouse, SQL, schema, lineage, impact, PII, data-diff, FinOps and dbt -- as plain commands. The local data tools use no model or API key, so Claude Code, Codex and CI jobs can call them directly. Linked workspace tools authenticate to Altimate and `workspace_execute` may use backend models.
+
+## List tools
+
+```bash
+altimate-code tool list          # id and description
+altimate-code tool list --json   # id, description and JSON input schema
+```
+
+`tool` and `mcp serve` share one implementation, so compact schemas, `sql_execute` with `tables`, `query_from` chaining, spilled result files, read-only enforcement and `answer_commit` (with its `request` argument) are consistent in both. Their permission policies differ: the CLI requires `--allow-write` for local configuration writes such as `warehouse_add`, while `mcp serve` allows `warehouse_add` by default. `tool` exposes the full tool list. In a project linked to a workspace it also exposes `workspace_context`, `workspace_skill` and `workspace_execute`; the link is read from the project's saved state, with no network request. Pass `--workspace-tools` to add them to an unlinked project, or `--no-workspace-tools` to leave them out of a linked one.
+
+## Startup context
+
+```bash
+altimate-code tool context [--connections <file>] [--json]
+```
+
+Prints the analyst method and the connections known at startup (the same base instructions `mcp serve` sends, plus the linked workspace's name, skills and tools when workspace tools are enabled), so a shell agent gets it in one call.
+
+## Run a tool
+
+```bash
+altimate-code tool run sql_format --args '{"sql":"select a,b from t","dialect":"postgres"}'
+altimate-code tool run warehouse_list
+altimate-code tool run schema_inspect --args-file inspect.json --json
+echo '{"query":"select 1"}' | altimate-code tool run sql_execute --args -
+```
+
+| Option | Description |
+|---|---|
+| `--args '<json>'` | Tool arguments as a JSON object. `-` reads them from stdin. |
+| `--args-file <path>` | Read the arguments from a file. |
+| `--allow-write` | Allow writes. Without it, only reads run. |
+| `--no-daemon` | Run in this process instead of using the daemon. |
+| `--connections <file>` | Use only this connections JSON file instead of the project and global connection configs. Defaults to `$ALTIMATE_TOOL_CONNECTIONS`. |
+| `--workspace-tools` / `--no-workspace-tools` | Force the linked workspace tools on or off. Unset, they are on when the project is linked. |
+| `--json` | Print `{"status","title","output","metadata"}`. Otherwise only `output` is printed. |
+
+Arguments are validated against the tool's schema. An unknown tool, invalid arguments or a failing tool exits non-zero.
+
+Only the data tools are exposed. Coding tools (`bash`, `read`, `edit`, ...), `dbt_pr_review` (use `altimate-code review`), memory and training tools are not available here.
+
+## Permissions
+
+Runs are read-only by default. Reads such as `sql_execute` on a SELECT and `schema_inspect` are allowed; anything else is refused with `Permission denied: <kind>. Re-run with --allow-write to enable writes.` Tools that change local configuration (`warehouse_add`, `warehouse_remove`, `warehouse_install_driver`) also need `--allow-write`.
+
+`DROP DATABASE`, `DROP SCHEMA` and `TRUNCATE` stay blocked even with `--allow-write`.
+
+## Daemon
+
+`tool run` starts a background process per project directory and CLI version on first use, and reuses it afterwards so warehouse connections and the schema cache stay warm. If it cannot be reached within about 3 seconds, the call runs in-process. `scratch` tables created by `sql_materialize` live as long as the daemon does, with one exception: with `--connections`, an edit to that file is reloaded by replacing the registry entirely, which also closes and empties `scratch`, so a `--connections` daemon's `scratch` tables only live between connection file edits. Every caller in that directory shares the daemon, so concurrent agents share its `scratch` tables and its `answer_commit` history; use `--no-daemon` to keep a caller separate.
+
+The daemon reloads its connections when the global or project `connections.json` (or the `--connections` file) changed since its last reload. The check runs on a call that has no other call in flight, so an edit made while calls overlap is picked up by the next call that runs alone; calls that arrive during a reload wait for it.
+
+```bash
+altimate-code tool daemon status
+altimate-code tool daemon stop
+```
+
+`status` and `stop` locate the running daemon the same way `run` does: by project directory, CLI version, the `--connections` file (if any), whether workspace tools are on, and the caller's `ALTIMATE_CODE_CONN_*`, `ALTIMATE_DISABLE_SCHEMA_VALUES`, `ALTIMATE_INTEGRATIONS` and `ALTIMATE_DISABLE_WORKSPACE` environment variables. Run them with the same flags and variables as the call that started the daemon, or they will report no daemon running for this project even though one is.
+
+| Setting | Description |
+|---|---|
+| `ALTIMATE_TOOL_DAEMON=0` | Always run in-process. |
+| `ALTIMATE_TOOL_DAEMON_IDLE_MS` | Idle time before the daemon exits (default `600000`). |
+
+The daemon listens on a local socket (a named pipe on Windows) under the Altimate Code state directory and removes it on exit.
+
+## Claude Code routing
+
+For clients that cannot use the `altimate-code` MCP server, the Claude Code plugin adds CLI routing guidance at session start: `altimate-code tool context` followed by `altimate-code tool run` for data questions, and `altimate-code run` for long multi-step jobs. To persist the same guidance in the repository, run `altimate-code link --claude-md`; it writes a managed block to the project's `CLAUDE.md` and never changes content outside the `<!-- altimate-code:routing start -->` / `<!-- altimate-code:routing end -->` markers.

docs/mcp-workspaces.md

@@ -0,0 +1,31 @@
+# Workspaces for external coding clients (experimental)
+
+`altimate-code mcp serve --workspace-tools` adds workspace context, named skills and known read operations from the linked workspace's existing `datamate` engine. The default MCP server remains unchanged. This draft builds on the experimental MCP server; no rollout or merge is implied.
+
+The client must run in the intended project directory. Sign-in and linking may complete after connecting: `workspace_context` returns structured setup status and the catalog remains stable. `workspace_context` returns the current workspace, bounded project memory, a summary of skills/knowledge/integrations, and skill names. `workspace_skill` reads a named skill from the validated snapshot; refresh missing skills with `altimate-code workspace refresh`. It rejects traversal, symlinks, oversized skills and a changed snapshot/account.
+
+The engine is pinned with its existing `--datamate` option. Only knowledge, supported metadata reads and SQL reads are exposed; arbitrary tools, writes and engine memory mutations are excluded. SQL uses the existing classifier. Unsupported SQL argument schemas are withheld. The engine authenticates through its normal local configuration. Use read-only warehouse credentials: classification is not database isolation. Local SQL remains available if workspace authentication, linking or engine startup fails. An account/binding change invalidates stale receipts. Read fresh context and use the new receipt; reconnecting MCP is not required.
+
+For non-model clients:
+
+```
+altimate-code workspace-client list
+altimate-code workspace-client context --directory /absolute/project
+printf '%s' 'Use booked ARR for recurring revenue.' | altimate-code workspace-client remember --directory /absolute/project --token=<context-workspace-token> --id=metrics/arr
+```
+
+These commands output JSON. A context receipt binds account, workspace and project. `remember` requires that receipt, a valid memory id and 1–2,048 characters on stdin; it saves exactly one project block. It suppresses the ordinary fire-and-forget mirror, then uses the existing sync path with the explicitly selected binding. Requests pin credentials across async API/index operations. A backend failure after local persistence reports `savedLocally: true, cloudConfirmed: false`; retrying is a user decision. Confirmed cloud publication is reported only when the sync reports one successful write. No model-callable memory-write tool or bulk-sync operation is added.
+
+Workspace context adds bounded data to a client's prompt; skills load on demand. Explicit knowledge calls can use backend models, memory publication can invoke the existing backend extractor, and warehouse calls retain warehouse costs. There is no new reasoning agent or per-row model loop. A CLI link can normally backfill existing memory; clients that expose linking without a backfill confirmation must disable memory for that subprocess, as the Claude plugin does. Do not pass `--yes` unless replacing a link was explicitly requested.
+
+Verification covers unit contracts, a real stdio protocol fixture and existing SQLite MCP behavior. Production read-only testing listed visible workspaces and loaded matching context through a temporary local project. Production bindings and memory were not written. A non-empty cloud memory round trip and real workspace-engine SQL/knowledge calls remain rollout checks.
+
+## Automatic-client setup and stable gateway
+
+The opt-in workspace catalog is always `workspace_context`, `workspace_skill` and `workspace_execute`, including when initially unlinked. `workspace_context` reports `needs_auth`, `needs_workspace`, `disabled` or `unavailable` without returning raw credential errors. A ready context includes the workspace receipt. Context loads coalesce and cache for 30 seconds; identity is verified on every use. `refresh: true` bypasses that cache.
+
+Pass `include_tools: true` to request lazy engine discovery. The response includes `engineStatus` (`ready`, `needs_engine` or `unavailable`) and an operation catalog with the engine's actual input schemas. After explicit engine installation, request both `refresh: true` and `include_tools: true`. `workspace_execute` takes `workspace_token`, `operation` and an `arguments` object matching the returned schema. Unknown operations, invalid schemas, stale receipts and source-write SQL are refused. `workspace_skill` also requires `workspace_token`.
+
+This gateway intentionally changes the host permission surface: allowing `workspace_execute` permits its entire closed read-operation allowlist, including knowledge requests that can invoke backend models. It does not inherit per-operation approvals from the old dynamically discovered tool names. No workspace memory write is exposed as an MCP tool.
+
+`workspace-client context` returns the same structured setup status. `workspace-client engine-install` invokes the existing native installer; a UI must require an explicit user action before invoking it. The Claude pilot runs native sign-in and link actions from its first-use panel. Linking disables memory backfill for that subprocess. Authentication output stays outside model context. Default MCP startup without `--workspace-tools` is unchanged.

docs/mkdocs.yml

@@ -104,6 +104,7 @@ nav:
     - TUI: usage/tui.md
     - CLI: usage/cli.md
     - SQL Check: usage/check.md
+    - Tool CLI: usage/tool.md
     - Web UI: usage/web.md
     - CI: usage/ci-headless.md
     - IDE: usage/ide.md
@@ -186,6 +187,7 @@ nav:
     - TUI: usage/tui.md
     - CLI: usage/cli.md
     - SQL Check: usage/check.md
+    - Tool CLI: usage/tool.md
     - Web UI: usage/web.md
     - CI: usage/ci-headless.md
     - IDE: usage/ide.md