feat(engine): hand MCP deferral to anthropic's server-side tool search

.github/workflows/ci.yml

@@ -23,20 +23,27 @@ jobs:
       - uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
-          # Production code is stdlib-only, enforced by the absence of
-          # non-test imports (`go list -deps ./cmd/...` must never contain a
-          # third-party package). Test-only dependencies are allowed;
-          # currently just pgregory.net/rapid, which is why go.sum exists.
+          # Production dependencies must remain pure Go. Module caching covers
+          # both production adapters and test-only support packages.
           cache: true
 
+      - name: Check formatting
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            printf 'gofmt required for:\n%s\n' "$unformatted"
+            for file in $unformatted; do
+              gofmt -d "$file"
+            done
+            exit 1
+          fi
+
       - run: go build ./...
 
       - run: go test -race ./...
 
       - run: go vet ./...
 
-      - run: test -z "$(gofmt -l .)"
-
       - name: Inspector unit tests
         # The session inspector is a single build-free HTML file; its pure
         # helpers (SSE parser + formatters) are unit-tested with node's built-in
@@ -47,14 +54,6 @@ jobs:
         # test file, which the runner then runs directly.
         run: node --test tools/inspector/*_test.mjs
 
-      - name: Monitor unit tests
-        # tools/monitor is the same pattern as the inspector above: a single
-        # build-free HTML file whose pure helpers (SSE parser, activity
-        # reducer, transcript fold, route codec, formatters) are extracted
-        # from a TESTABLE region and unit-tested with node's built-in test
-        # runner. Same glob-not-directory rationale as the inspector step.
-        run: node --test tools/monitor/*_test.mjs
-
       - name: Hub unit tests
         # tools/hub's pure logic has been unit-tested by hub_test.mjs since
         # its introduction (AGENTS.md's "Development hub" section documents

.github/workflows/claude-code-review.yml

@@ -39,16 +39,18 @@ jobs:
             Use the /code-review skill to review this pull request.
 
             This is a Go agent harness (engine, provider transcoders, plugin
-            protocol). Read AGENTS.md first and review with these priorities:
+            protocol). Read the root AGENTS.md first. Then read every scoped
+            AGENTS.md that governs a changed path. Review with these priorities:
             - Race conditions, deadlocks, missing synchronization — the engine,
               plugin host, and streams are heavily concurrent
             - Protocol correctness (plugin JSON-RPC framing, hook chaining
               semantics, manifest/lazy-spawn invariants)
             - Transcoding correctness (canonical <-> provider wire formats,
               ProviderData replay/drop rules, tool-call ID stability)
-            - Startup-speed regressions: any init-time network, disk, or
-              subprocess work is a bug per AGENTS.md
-            - Testing rules from AGENTS.md: TDD, no raw sleeps, synctest for
+            - Startup-speed regressions: init-time network or subprocess work,
+              and disk reads beyond the permitted user/project config path,
+              are bugs per the root and cmd/harness scoped AGENTS.md files
+            - Testing rules from the root AGENTS.md: TDD, no raw sleeps, synctest for
               timer logic
             - Bugs, logic errors, nil/zero-value pitfalls, unchecked errors
 

.github/workflows/fuzz.yml

@@ -69,7 +69,7 @@ jobs:
           cache: true
 
       - name: Restore fuzz corpus cache
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           # Go's fuzzing engine persists interesting inputs it discovers
           # under GOCACHE/fuzz, separate from the committed seed corpus in
@@ -90,7 +90,7 @@ jobs:
 
       - name: Upload failing corpus entries
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           # A fuzzing failure writes the minimized failing input under
           # testdata/fuzz/<Target>/ in the repo tree (this is distinct from

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Bonventre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -7,7 +7,9 @@ A fast, extensible, composable agent harness in Go.
 - **Composable** — headless engine, event streams, client/server, MCP both directions
 - **Model-fluid** — swap providers/models mid-session or per-subagent with no migration
 
-See [AGENTS.md](AGENTS.md) for architecture and design decisions.
+See [AGENTS.md](AGENTS.md) for repository-wide rules and the scoped
+instruction index. Each major subsystem has its own concise `AGENTS.md`.
+See [docs/README.md](docs/README.md) for technical documentation.
 
 ## Configuration
 
@@ -56,5 +58,35 @@ and `api_key_env` above, so `"model": "openrouter/anthropic/claude-sonnet-5"`
 works as soon as `OPENROUTER_API_KEY` is set. Any `openrouter` entry in
 config — even a partial one — overrides the built-in default entirely.
 
-An unrecognized `type`, or an `openai-compat` entry missing `base_url`, fails
-config loading loudly rather than silently registering nothing.
+An endpoint that speaks the OpenAI **Responses** API rather than
+chat-completions uses `type: "openai"`, which builds the same native adapter
+the built-in `openai` family uses. It works under any map key, so a second
+Responses endpoint can sit beside the built-in one, and `responses_path`
+points it at an endpoint that does not serve `/v1/responses`:
+
+```json
+{
+  "providers": {
+    "vendor": {
+      "type": "openai",
+      "base_url": "https://api.vendor.example",
+      "api_key_env": "VENDOR_API_KEY",
+      "responses_path": "/backend/responses"
+    }
+  }
+}
+```
+
+`"model": "vendor/some-model"` then routes there, passing `some-model`
+through as the model id. `responses_path` defaults to `/v1/responses` and is
+also accepted on the built-in `openai` entry; it is rejected on any other
+kind of entry, since no other adapter reads it.
+
+An unrecognized `type`, an `openai-compat` or `openai` entry missing
+`base_url`, or a `responses_path` on an entry that builds neither Responses
+adapter, fails config loading loudly rather than silently registering
+nothing.
+
+## License
+
+Harness is licensed under the [MIT License](LICENSE).

cmd/harness/AGENTS.md

@@ -0,0 +1,73 @@
+# Harness command instructions
+
+These rules apply to `cmd/harness/`. Harness does not merge ancestor files.
+If root guidance is not active, locate the Git root and read
+`<repo-root>/AGENTS.md`. Resolve repository paths from that root.
+
+## Composition root
+
+Keep the command package thin. It resolves config, constructs providers and
+managers, and composes the engine, server, and embedded local tools.
+
+Do not move engine behavior into command handlers. Do not make `server` import
+`tools/*`; inject pages and dependencies through options.
+
+## Startup budget
+
+Keep `harness --version` on the millisecond startup path.
+
+- Do not add network access at startup.
+- Before first output, limit disk reads to the user and project config files.
+- Do not start a long-lived plugin process before its first hook or tool call.
+  A bounded manifest probe can run for a missing or stale cache entry.
+- Do not start MCP servers or provider clients before first use.
+- Do not scan skills or project instructions at `NewSession`.
+- Do not add `init()` side effects.
+- Keep plugin manifests and model metadata local and static on the hot path.
+- Keep production dependencies pure Go.
+
+Run the startup budget tests after a change to command initialization.
+
+## Config and environment resolution
+
+The command layer resolves environment variables. The engine must not read
+operator environment variables directly.
+
+Keep one decision point for each config precedence rule. Preserve explicit
+zero, negative opt-out, and unset distinctions.
+
+Validate adapter-only fields against the adapter that an entry builds, not the
+provider map key alone. Fail loudly on an unreadable or unknown value.
+
+Keep run and serve wiring in parity for shared engine settings.
+
+## Provider construction
+
+A provider-map key is the model-reference family. Pass that family into native
+Responses clients so opaque data cannot cross endpoints.
+
+Do not validate credentials during registry construction. The first provider
+request owns credential validation.
+
+## Hub composition
+
+`cmd/harness` may import `tools/hub`. The server may
+not.
+
+Only allow empty-token unauthenticated service when `resolveUnauthenticated`
+proves loopback or receives the explicit non-loopback opt-in. Keep the two
+warning messages distinct.
+
+## GC and pprof diagnostics
+
+Use `runtime/metrics` for GC pause observation. Do not use
+`runtime.ReadMemStats` in the watcher.
+
+Never import `net/http/pprof`. Keep the command-level default-mux regression
+test because the binary import graph is wider than the server package.
+
+## Tests
+
+Test flag and environment precedence as tables. Cover malformed values and
+explicit zero values. Do not use a live provider or a real deployment command
+in ordinary command tests.

cmd/harness/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

cmd/harness/append_system_prompt_test.go

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/majorcontext/harness/config"
+)
+
+func TestAppendSystemSegments(t *testing.T) {
+	tests := []struct {
+		name string
+		cfg  *config.Config
+		flag string
+		want []string
+	}{
+		{"unset", nil, "", nil},
+		{"config", &config.Config{AppendSystemPrompt: []string{"one", "two"}}, "", []string{"one", "two"}},
+		{"flag", nil, "flag", []string{"flag"}},
+		{"both", &config.Config{AppendSystemPrompt: []string{"one", "two"}}, "flag", []string{"one", "two", "flag"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := appendSystemSegments(tt.cfg, tt.flag); !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("appendSystemSegments = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

cmd/harness/cache_ttl_parity_test.go

@@ -14,8 +14,7 @@ import (
 // a provider package — but until now nothing but a comment kept them in step.
 // config.validateCacheTTL accepts against one copy and anthropic.
 // resolveCacheTTL accepts against the other, so a value added to one list
-// alone would be accepted at load and then rejected at the first Stream call,
-// or vice versa: the silent-drift class this PR set out to remove.
+// alone would be accepted at load and then rejected at the first Stream call.
 //
 // cmd/harness is the right home for the check because it is the one package
 // that already imports both, and it is the seam that carries a configured

cmd/harness/claude_code_test.go

@@ -0,0 +1,84 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/majorcontext/harness/config"
+	"github.com/majorcontext/harness/engine"
+	"github.com/majorcontext/harness/message"
+	"github.com/majorcontext/harness/provider/claudecode"
+)
+
+// TestRegistryClaudeCodeCLIRegistersStubUnderKey proves a claude-code-cli
+// entry registers a claudecode.Client under its providers-map key, exactly
+// like registerOpenAICompatProviders does for its own type — this is what
+// makes Session.ModelSupported accept a swap to a claude-code model ref
+// (see registerClaudeCodeProviders' own doc comment).
+func TestRegistryClaudeCodeCLIRegistersStubUnderKey(t *testing.T) {
+	reg := registry(&config.Config{Providers: map[string]config.Provider{
+		"claude-code": {Type: config.TypeClaudeCodeCLI, BinaryPath: "/usr/local/bin/claude"},
+	}})
+	if _, ok := reg["claude-code"].(claudecode.Client); !ok {
+		t.Fatalf("claude-code provider is %T, want claudecode.Client", reg["claude-code"])
+	}
+	ref, err := message.ParseModelRef("claude-code/sonnet")
+	if err != nil {
+		t.Fatalf("ParseModelRef: %v", err)
+	}
+	if _, err := reg.For(ref); err != nil {
+		t.Errorf("reg.For(%s): %v, want a registered adapter", ref, err)
+	}
+}
+
+// TestClaudeCodeConfigForTranslatesProviderFields proves
+// claudeCodeConfigFor carries BinaryPath/ExtraArgs/PermissionMode from a
+// config.Provider entry into engine.ClaudeCodeConfig — the one translation
+// point between the file-config Provider type and the engine's own
+// backend-agnostic Config (engine deliberately does not import config; see
+// claudeCodeConfigFor's own doc comment).
+func TestClaudeCodeConfigForTranslatesProviderFields(t *testing.T) {
+	cfg := &config.Config{Providers: map[string]config.Provider{
+		"claude-code": {
+			Type:           config.TypeClaudeCodeCLI,
+			BinaryPath:     "/opt/claude/bin/claude",
+			ExtraArgs:      []string{"--mcp-config", "/tmp/mcp.json"},
+			PermissionMode: "acceptEdits",
+		},
+	}}
+	got := claudeCodeConfigFor(cfg, claudecode.Family)
+	want := engine.ClaudeCodeConfig{
+		BinaryPath:     "/opt/claude/bin/claude",
+		ExtraArgs:      []string{"--mcp-config", "/tmp/mcp.json"},
+		PermissionMode: "acceptEdits",
+	}
+	if got.BinaryPath != want.BinaryPath || got.PermissionMode != want.PermissionMode {
+		t.Errorf("claudeCodeConfigFor = %+v, want %+v", got, want)
+	}
+	if len(got.ExtraArgs) != len(want.ExtraArgs) {
+		t.Fatalf("ExtraArgs = %+v, want %+v", got.ExtraArgs, want.ExtraArgs)
+	}
+	for i := range want.ExtraArgs {
+		if got.ExtraArgs[i] != want.ExtraArgs[i] {
+			t.Errorf("ExtraArgs[%d] = %q, want %q", i, got.ExtraArgs[i], want.ExtraArgs[i])
+		}
+	}
+}
+
+// TestClaudeCodeConfigForAbsentEntryYieldsZeroValue proves a config with no
+// matching entry (or a nil *config.Config, the same defensive shape every
+// other cmd/harness helper here handles) yields the zero ClaudeCodeConfig
+// rather than panicking — engine.newSession's own BinaryPath default
+// ("claude") then applies.
+func TestClaudeCodeConfigForAbsentEntryYieldsZeroValue(t *testing.T) {
+	assertZero := func(t *testing.T, got engine.ClaudeCodeConfig) {
+		t.Helper()
+		if got.BinaryPath != "" || got.PermissionMode != "" || len(got.ExtraArgs) != 0 {
+			t.Errorf("claudeCodeConfigFor = %+v, want the zero value", got)
+		}
+	}
+	assertZero(t, claudeCodeConfigFor(nil, claudecode.Family))
+	cfg := &config.Config{Providers: map[string]config.Provider{
+		"anthropic": {APIKeyEnv: "X"},
+	}}
+	assertZero(t, claudeCodeConfigFor(cfg, claudecode.Family))
+}

cmd/harness/create_phase_logger_test.go

@@ -8,8 +8,7 @@ import (
 	"time"
 )
 
-// TestCreatePhaseLoggerEmptiesMapOnTotal is a regression test for the
-// phase-accumulator leak (PR #87 review): a create that reports every
+// TestCreatePhaseLoggerEmptiesMapOnTotal verifies that a create that reports every
 // intermediate phase before "total" must leave byID empty afterward, not
 // just render a sensible summary line.
 func TestCreatePhaseLoggerEmptiesMapOnTotal(t *testing.T) {
@@ -42,13 +41,9 @@ func TestCreatePhaseLoggerEmptiesMapOnTotal(t *testing.T) {
 	}
 }
 
-// TestCreatePhaseLoggerHandlesTotalWithoutIntermediatePhases is the
-// regression case the leak actually manifested as: a saturated storage
-// volume makes Persist fail on every create, so handleCreate's defer (see
-// server/handlers.go) reports "new_session" then jumps straight to "total"
-// with no persist/register/emit_created in between. The summary line must
-// still render — with the missing phases simply absent — and the map entry
-// must still be reclaimed, not orphaned.
+// TestCreatePhaseLoggerHandlesTotalWithoutIntermediatePhases verifies that a
+// failed create can report "total" directly. The summary omits missing phases
+// and removes the map entry.
 func TestCreatePhaseLoggerHandlesTotalWithoutIntermediatePhases(t *testing.T) {
 	var buf bytes.Buffer
 	logger := slog.New(slog.NewTextHandler(&buf, nil))