core

Overview ¶

Package core — AgentNew MCP tool. Mirrors `clawtool agent new` so a model can scaffold a Claude Code subagent persona from inside a conversation. Both surfaces share the same template renderer (internal/agentgen) so the output is byte-identical.

Terminology reminder (operator's 2026-04-27 ruling):

• **agent** = a USER-DEFINED PERSONA (this tool scaffolds one)
• **instance** = a configured upstream CLI bridge (claude / codex / gemini / opencode / hermes / openclaw / ...)

Don't confuse this with the legacy AgentList tool (agents_tool.go), which currently still surfaces *instances* under the legacy "agent" name. That rename is tracked separately.

Package core — SendMessage and AgentList MCP tools (ADR-014 Phase 1).

SendMessage routes a prompt to the resolved agent's transport and buffers the streaming reply for the MCP response. Full HTTP-grade streaming arrives with `clawtool serve` in Phase 2; the MCP wire here is request/response so we accept the buffer cap.

AgentList exposes the supervisor's registry snapshot — same shape as `clawtool send --list` and `GET /v1/agents`. Mirrors the v0.9 `RecipeList` pattern (read-only, structured, BaseResult-shaped).

Package core — atomic.go: shared file-mutation primitives for Edit and Write. These helpers guarantee no partial-write artifacts on crash and give us a single place to add safety polish (line-ending preservation, BOM handling) consistently across both tools.

Per ADR-007 we do not use a third-party "atomic write" library — Go's stdlib (`os.WriteFile` + `os.Rename`) is enough when used correctly. The platform invariant we rely on: rename(2) on the same filesystem is atomic, so writers never see a half-written file at the target path.

Package core implements clawtool's canonical core tools per ADR-005.

Quality bar reminder: each core tool must measurably beat the corresponding native built-in across the major agents. For Bash:

• timeout-safe: output is captured even when the process is killed
• predictable cwd: defaults to $HOME, never the daemon's cwd
• structured result: stdout/stderr/exit_code/duration_ms/timed_out returned as JSON even on timeout

v0.1 implements timeout-safe + structured result + cwd. Secret redaction and per-session command history land in v0.2.

Package core — Bash background-mode task registry (ADR-021 phase B, Codex's "long-running" recommendation). Mirrors BIAM's task vocabulary (pending / active / done / failed / cancelled) without reusing the SQLite store: bash subprocess output is volatile, signing every stdout chunk via Ed25519 (which BIAM would do) is the wrong default. Process-local in-memory registry, lifetime = clawtool serve process.

Package core — MCP surface for Bash background tasks. The underlying registry is in bash_bg.go; this file is the wiring layer mapping {BashOutput, BashKill} onto Get/Kill helpers and rendering the snapshot under the standard core-tool envelope.

Package core — Bridge* MCP tools (ADR-014 Phase 1).

Mirrors `clawtool bridge add/list/remove/upgrade` over MCP so a model can install / inspect / uninstall bridges mid-conversation ("kanka gemini bridge'i kur"). Same dispatch path as the CLI — both end up calling setup.Apply on the bridge's recipe.

Package core — BrowserFetch retrieves a URL through a real browser engine (Obscura, Chromium-via-CDP) so SPA / JS-rendered content lands in the agent's context. Sister tool to WebFetch (server-side via Mozilla Readability), which can't render React / Next.js / hydrated SPAs.

Per ADR-007 we wrap mature engines: Obscura (V8 + Chrome DevTools Protocol, Apache 2.0). We never re-implement page loading. clawtool adds: agent-friendly polish (size cap, structured result, optional JS evaluator, optional CSS-selector wait, post-render readability pass for clean prose).

Stateless: each call spins a fresh browser context. For interactive multi-step flows (login + cookie + click + capture) use BrowserAction.

Package core — BrowserScrape parallelises BrowserFetch across many URLs by wrapping `obscura scrape <url...> --concurrency N --eval ... --format json`. Use case: "give me the rendered headline from these 50 SPA blog posts", "bulk-snapshot a competitor's site map", etc.

Per ADR-007 we wrap Obscura's scrape subcommand (Apache-2.0 Rust engine, V8 + CDP) — clawtool never re-implements parallel fetching. Stateless: each URL gets its own browser context, no cookies, no shared session. For interactive work use BrowserAction.

Package core — Commit MCP tool. Wraps internal/checkpoint's Commit primitive (ADR-022) so an agent can land a Conventional Commits-validated, Co-Authored-By-blocked commit through one tool call instead of three Bash invocations.

This tool is what closes the operator's earlier gap: agents shell out to `Bash git commit -m "feat: …"` because there's no Commit tool, the messages aren't always conventional-shaped, and Bash has no way to refuse a Co-Authored-By trailer. Commit makes the right path the easy path.

Pre-commit guardrails layered through (in order):

1. Repo check — bails with a clear error if cwd isn't a Git repo.
2. internal/rules.Evaluate at EventPreCommit — operator's declarative invariants (e.g. "skill routing-map row updated" when a core tool changed). A Verdict.IsBlocked() = true is a hard refusal.
3. internal/checkpoint.ValidateMessage — Conventional Commits + Co-Authored-By block.
4. Optional dirtiness guard — refuses to commit if the working tree still has unstaged changes after staging (catches "you forgot to stage X" mid-flight).

Package core — Edit performs a precise search-and-replace on an existing file with safety polish:

• uniqueness check by default (refuses ambiguous edits)
• atomic temp+rename so a crash never leaves a half-written file
• line-ending preserve (LF / CRLF / CR detected from current content)
• BOM preserve
• binary refusal (symmetric with Read)

Per ADR-007 we wrap stdlib `os` for I/O and add our own polish layer. The search-and-replace shape mirrors what Claude Code's native Edit uses today (old_string / new_string / replace_all) — agents that learnt that interface get the same affordances against clawtool's stronger invariants.

Package core — Glob is the canonical wrapper around bmatcuk/doublestar.

Per ADR-007 we don't write a glob engine. doublestar is the de-facto double-star (`**`) glob library in Go, used by GoReleaser, k6, etc. This file's value is the polish layer: cwd-aware path resolution, uniform structured output, hard cap to protect agent context, and platform-stable separators (the wrapper always returns forward-slash paths regardless of OS — agents expect that).

ADR-021 phase B added .gitignore-aware traversal — when cwd is a Git worktree we ask `git ls-files --cached --others --exclude-standard -z` for the candidate set then run doublestar over it, which gives us the same ignore semantics as ripgrep (and keeps the operator's expected ".git/, vendor/, node_modules/ ignored by default" behaviour).

Package core — Grep wraps ripgrep when present, falls back to system grep.

Per ADR-007 we curate ripgrep as the default engine: it has the correct .gitignore semantics, --type aliases, fast Aho-Corasick matching, and a stable JSON output that is straightforward to parse. The fallback is system grep (-rn) so clawtool's Grep is never unavailable.

Output is uniform across engines so the agent never has to know which one ran. The `engine` field in the result lets users / tests verify.

Package core — typed manifest of clawtool's MCP tools (#173 Step 2 of Codex's #1 ROI refactor).

BuildManifest assembles a *registry.Manifest with one ToolSpec per shipped tool. Step 2 (this commit) ONLY adds entries for the youngest six tools — Commit, RulesCheck, AgentNew, BashOutput, BashKill, TaskNotify. server.go still calls each tool's RegisterX directly; the manifest is not yet consumed at boot. That hookup lands in Step 3, after the older tools (Bash / Read / Edit / Write / Grep / Glob / WebFetch / WebSearch / ToolSearch) get the same treatment.

Why incremental: a single big-bang manifest migration carries the risk that one register-fn signature mismatch (or one missed gate) breaks every tool at once. Doing it six tools at a time, with the surface_drift_test guarding cross-plane invariants, makes each step audit-able and rollback-able.

Why the youngest first: they have the freshest test coverage and the smallest blast radius if a migration mistake slips through. By the time we reach the older core (Bash / Read / Edit / Write) the registry harness is battle-tested.

Package core — Mcp* MCP tools (ADR-019). v0.17 fills in `McpNew` (real generator wrapper), `McpList` (real walker), and keeps thin stubs for `McpRun` / `McpBuild` / `McpInstall` that point at the CLI shortcut (those are inherently filesystem-side operations the model doesn't usually drive).

Package core — Portal* MCP tools (ADR-018). Read-only surface in v0.16.1: PortalList, PortalUse, PortalWhich, PortalUnset, PortalRemove, plus a deferred-feature stub for PortalAsk so the shape is discoverable before the v0.16.2 CDP driver lands.

PortalAdd is intentionally CLI-only — it spawns $EDITOR which has no meaning in an MCP context. Operators add portals from the terminal; agents discover and use them through MCP.

Package core — Read returns file content with stable line cursors, deterministic line counts, and per-format dispatch.

Per ADR-007 we wrap mature engines instead of writing parsers:

• text → stdlib bufio (line-walked, single-pass)
• pdf → pdftotext (poppler-utils) shell-out
• ipynb → native JSON cell parse
• docx → pandoc shell-out (universal office converter)
• xlsx → github.com/xuri/excelize/v2 (Microsoft/Alibaba/Oracle in prod)
• csv / tsv → stdlib encoding/csv (header + bounded preview)
• html → github.com/go-shiori/go-readability (Mozilla Readability port)
• json / yaml / toml / xml → text passthrough with format tag
• binary → refused with structured error

Adding a new format means: extend detectFormat, add a reader function, update CoreToolDocs's description, ship tests for the format. The readResult shape stays uniform so the agent never has to branch on which engine ran.

Package core — Recipe* MCP tools mirror the `clawtool recipe …` CLI surface so a model can run setup tasks from inside a conversation. Same registry, same Detect/Apply/Verify cycle.

Three tools per ADR-013:

RecipeList   — enumerate recipes, optionally filter by category.
RecipeStatus — Detect output for one recipe or all of them.
RecipeApply  — full Detect→Prereqs→Apply→Verify against a repo,
               with structured options.

All three return BaseResult-shaped output (pretty text + structured JSON) so chat UIs render them the same way as Bash/Read/etc.

Package core — RulesCheck MCP tool. Surfaces the rules engine (internal/rules) so an agent can ask "are the operator's invariants satisfied right now?" without first having to call the unattended-mode supervisor or wait for pre_commit time.

This tool is read-only: it loads .clawtool/rules.toml (or the XDG fallback), evaluates against a caller-supplied Context, and returns the Verdict (results + warnings + blocked). It does NOT hook into Edit/Write/Bash automatically — rule enforcement at tool-call time lands when the Tool Manifest Registry refactor (#173) gives us a middleware seam.

Package core — Sandbox* MCP tools (ADR-020). v0.18 ships the read-only surface (List / Show / Doctor) so models can discover the profile catalog and recommend the right one to operators. SandboxRun is intentionally CLI-only — letting a model spawn sandboxed commands has the wrong default.

Package core — SemanticSearch MCP tool (ADR-014 T6, design from the 2026-04-26 multi-CLI fan-out).

Concept queries ("how is auth rotated?") that Grep can't reach because the literal token isn't there. We wrap chromem-go's in-memory vector store + the configured embedding provider (OpenAI default, Ollama override). One Store per repo, lazily built on first Search call so cold-boot doesn't pay the embedding cost when the tool isn't being used.

Coexistence with Grep: Grep stays the literal regex tool; this is the conceptual one. Tool descriptions carry the routing hint so ToolSearch ranks each correctly per query.

Package core — session-scoped read tracking for the Read-before-Write guardrail (ADR-021). MCP session id is the key; we look it up via server.ClientSessionFromContext, never from a tool argument (Codex flagged this — model-supplied session ids can't be trusted).

Package core — file-IO helpers extracted to keep session_state.go pure. Mirrors the read.go IO surface but stays small enough to embed.

Package core — SkillNew MCP tool. Mirrors `clawtool skill new` so a model can scaffold a Claude Code skill from inside a conversation, without the user dropping to a shell. Both surfaces share the same template renderer (passed in at registration so we don't reach across packages — this file stays a leaf).

Spec compliance: agentskills.io. SKILL.md gets YAML frontmatter with `name` + `description` (required) plus optional `triggers`, followed by the body template. Same shape as the CLI emits.

Package core — TaskNotify MCP tool. Edge-triggered completion push that pairs with SendMessage(bidi=true). Subscribes to the in-process biam.Notifier so the caller wakes the instant ANY of the watched tasks reaches a terminal state — no SQLite poll, no external CLI hooks.

Architecture: the runner publishes a *biam.Task to Notifier when it flips a row to a terminal state (see internal/agents/biam/ runner.go). Here we register one channel per task_id, then `select` across all of them + the timeout context. First task wins; the rest stay subscribed until the caller polls them with TaskGet (their slot decays at next Publish or process exit).

Already-terminal tasks: we eagerly check the store BEFORE blocking, so a TaskNotify call against a task that already finished returns immediately rather than waiting for a Publish that already happened.

Package core — TaskGet / TaskWait / TaskList MCP tools (ADR-015 Phase 1). Surface the BIAM SQLite store the supervisor's async runner persists into, so a calling model can:

1. Fire SendMessage with bidi=true → receive task_id immediately.
2. Continue its own work without blocking on the upstream.
3. Pull back via TaskGet (snapshot) / TaskWait (block until terminal) when it actually needs the result.

All three tools are read-only and stateless beyond the BIAM store.

Package core — ToolSearch is the discovery primitive that makes a 50+ tool catalog usable per ADR-005. The agent calls ToolSearch with a natural-language query, gets ranked candidates, then binds to the right tool with its full schema via the regular tools/list output.

Package core — Verify MCP tool (ADR-014 T4, design from the 2026-04-26 multi-CLI fan-out).

Verify runs a repo's tests / lints / typechecks via whichever runner the repo declares (Make, pnpm, npm, go, pytest, ruby, cargo, just) and returns one structured pass/fail per check. Per ADR-007 we wrap maintained runners — `go test -json`, `pytest --json-report`, `cargo test --message-format json` — and fall back to the runner's plain output when the structured form isn't available on this host.

Buffered single payload (not stream): callers want the full pass/fail summary, not the live log fire hose. Bash already streams when that's what's wanted.

Package core — WebFetch retrieves a URL and renders the body in the best shape for an AI agent: clean article text for HTML, raw text for plain-text MIME types, structured rejection for binaries.

Per ADR-007 we wrap two mature engines:

• net/http stdlib client for transport (proxy, TLS, redirect handling are all stock — battle-tested across Go's user base);
• github.com/go-shiori/go-readability for HTML extraction (Mozilla Readability port, the same algorithm Firefox Reader View ships).

What clawtool adds: agent-friendly polish — a hard body cap so a runaway page can't blow context, structured result with content-type-aware `format`, citation metadata (final URL after redirects, fetched_at).

Package core — SSRF guard for WebFetch (ADR-021 phase B).

Without this, an agent could ask WebFetch for `http://169.254.169.254/` (AWS metadata), `http://localhost:5432/` (the operator's local Postgres), or any RFC1918 address (the operator's internal network). The guard blocks resolution to those address ranges BEFORE the GET is issued, and re-checks every redirect target so a public 302→private redirect chain is rejected too.

Per ADR-007 we don't ship our own DNS resolver — net.LookupIP is canonical. We only own the address-range allow/deny logic.

Package core — WebSearch is a pluggable web-search primitive. clawtool itself does no crawling or ranking; it adapts whichever search backend the user has configured (Brave today; Tavily / SearXNG planned) into a uniform `{results, backend, …}` shape.

Per ADR-007 we wrap, never reinvent. The backend interface is small on purpose so adding a new provider is one file (see websearch_brave.go for the canonical example).

Package core — Write creates or overwrites a whole file with given content. Sister tool to Edit; the boundary is intentional:

• Edit modifies a substring of an existing file. Refuses if the file is missing.
• Write replaces or creates the whole file. If the file already exists and has detectable line endings, those endings are preserved by default so existing tooling (CR LF on Windows, etc.) keeps working.

Per ADR-007 we wrap stdlib `os` for I/O. The polish layer is the same atomic-write primitive Edit uses, plus a parent-directory auto-create so agents don't need a separate `mkdir` step before writing.