@garuda-agent/garuda 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,142 @@
 # Changelog
 
+## 0.18.0 (2026-11-04)
+
+- Biome 2.6.2 (with @inquirer/prompts 8.7.4, react 19.3.1 and smol-toml 1.9.1, from Dependabot's
+  group update). Biome 2.6 formats Markdown and YAML by default: Markdown formatting is off (the
+  docs keep their own layout), and pnpm's lockfiles are left out.
+- Dependabot: `@types/node` stays on the oldest supported Node line (no major updates); each other
+  major update comes as its own pull request.
+- The Homebrew formula in the repository names 0.17.0 and its tarball hash.
+- Eval evidence, part 1 (T11a): the report gives the pass rate over all attempts with a 95%
+  interval (a cluster bootstrap over tasks, so repeats of one task count together), the tasks that
+  passed every run or none, the median and p95 of steps, tokens and time, the cost per accepted
+  change (all attempts divided by the passes), and unexpected changes (files that a run changed
+  but the task did not need; a new `allowChanges` field widens a task's scope). `--shuffle` and
+  `--seed` set the run order. `report.json` is version 2, with Garuda's version and commit, the
+  model, the OS, the seed, the run order and a hash of each task. A run whose every attempt failed
+  with an error gives no interval ("No scored run"), a task with only error runs is not counted as
+  "passed none", and an authentication error (401 or 403, for example a refused API key) stops the
+  eval at the first run instead of failing every run the same way.
+- `garuda eval compare <a> <b>` (T11a part 2): two reports of the same tasks side by side, the
+  difference of the pass rates (B − A) with a paired 95% interval, and each arm's cost per accepted
+  change, unexpected changes and median time. It refuses reports whose tasks differ, and a
+  difference whose interval contains 0 is "no clear difference". The run report now says when its
+  interval is only a rough guide (fewer than 10 tasks, or every draw gave the same rate).
+- The Claude Code baseline (T11b): `garuda eval --agent claude-code` runs `claude -p` on the same
+  tasks with the same scratch folders, time limit and grading, so `garuda eval compare` can set
+  Garuda against Claude Code. Claude Code runs with every tool allowed, so only in the OS sandbox,
+  with network only to `api.anthropic.com`, a new config folder per run, and the API key in its
+  environment only. Its turns, tokens and cost come from its JSON result. `eval compare` prints a
+  zero difference as "0 pts" and says when every draw gave the same difference. The user's first
+  live baseline run found that the proxy for `api.anthropic.com` started only in a Garuda turn, so
+  Claude Code had no network: the runner now starts it first (`Runtime.prepareCommands`). An eval
+  now also stops at the first run that cannot reach the API (a refused connection, an unknown
+  host, a certificate error), as it does for a refused key.
+- `garuda eval compare` also compares the cost per accepted change: the ratio B/A with a paired
+  95% interval, and a verdict ("B costs more", "B costs less" or "no clear difference"). An unknown
+  cost gives no ratio. The hard-coupon task allows changes in the coupon module and the API routes
+  (`allowChanges`): both agents made them in the first baseline runs. Its task hash changes, so
+  compare new hard-suite runs only with new ones.
+- A held-out set (T11c): 10 new, harder tasks in TypeScript, Python and Java, apart from every
+  suite. `--split heldout` runs them, `--split all` runs them with the dev tasks, and a plain
+  `garuda eval` never does (a held-out id with `-t` is refused with the fix). They cover a defect
+  whose cause is in another file (3), a refactor across modules (2), tests that a mutation check
+  must find good enough (2), conventions from the repository's `AGENTS.md` that a hidden test
+  checks (2), and a vague request (1). Each task's hash is recorded in the tests: a changed task
+  must change its hash on purpose, and a tuning result seen before the change is invalid.
+  `report.json` records the split. `--list` shows the held-out set. The compare note now says
+  "the same pass-rate difference".
+- The first held-out run (Haiku 5.5, 3 runs a task: 27/30) found a fault in one task:
+  the export-dates task (now `med-export-dates`) failed 0/3 only because the agent, with the right fix each time, added a CSV
+  test to the protected test file. Its hidden test decides, so the visible tests are no longer
+  protected, and a new test is in scope there and in the two conventions tasks. The hashes of these
+  three tasks change: compare held-out runs only with runs made after this change.
+- A harder held-out set (T11c, second version). The first set was at its ceiling for Haiku 5.5,
+  so it is now a dev suite, `-s medium` (ids `med-…`), and 10 new tasks took its place. Each has a
+  trap: a quick fix that passes the visible tests fails the hidden test or the mutation check (a
+  cache key without the currency, a new idempotency key per retry, invoice shares and yen, a
+  command registry with unchanged output, settings by the README's rules, 6 subtle mutants in two
+  test-writing tasks, a migration and a reset endpoint by `AGENTS.md`, and a slow search that must
+  keep every result). Their ids start with `held-out-`. The tests prove each trap. Compare
+  held-out runs only with runs made after this change. The run report's id column now fits the
+  longest id, so the columns after it line up.
+- The second held-out run (Haiku 5.5, 3 runs a task: 28/30) found two faults, both in the checks.
+  `held-out-conventions-migration` failed 2/3 with correct work: the agent named the field
+  `dueAt` (as `created_at` suggests), and the hidden test read `dueDate`, which the prompt never
+  named. The prompt now names it. The report gave "The check failed:" with nothing after it: a
+  guard stopped the check with no output. Each guard now prints what is missing, and a check with
+  no output reports its exit code. Four held-out hashes change.
+- Tests: `test/evals.test.ts` self-tests the basic and hard suites only (the medium tasks ran twice
+  there), with 60 s for each task. The user's `pnpm check` timed out on `hard-rounding` at 5 s,
+  then on the LSP reference sample. `vitest.config.ts` now gives every test 30 s, the limit that
+  the release checks used, so `pnpm check` agrees with them.
+- The third held-out run, with the Claude Code baseline, ran an old build: `dist/` was older than
+  the checkout, so the old tasks ran, and `report.json` named the checkout's commit, not the
+  build's. A build now records the commit it came from (tsup sets it), `report.json` gives it as
+  `garuda.commit` and adds `garuda.checkout` when the checkout differs, and `garuda eval` warns
+  at the start: "This build is from commit …, but the checkout is at …: run pnpm build first."
+- Held-out prompts with visible tests now say "You may add tests in new files, but do not change
+  the existing test files": in the same run the agent appended a correct test to a protected test
+  file after "do not change the existing ones". Five held-out hashes change.
+- Same run, same (old) tasks, Haiku 5.5: Garuda 26/30, Claude Code 27/30, no clear difference in
+  the pass rate; Claude Code cost ×1.50 per accepted change (paired interval ×1.35 to ×1.71).
+- Design (T11; T11a and T11b built, T11c–d not yet): eval evidence — intervals and consistency over repeated runs, cost per
+  accepted change, unexpected changes, a Claude Code baseline runner, a held-out task split, and a
+  proposer loop that edits only a prompt addendum (`docs/lld/eval-evidence.md`).
+
+- An eval A/B of one MCP server: `garuda eval --mcp <server>` allows that one server from your
+  own `~/.garuda/mcp.json` (no other server, and none from a project file), and
+  `--mcp-prepare <command>` runs a command in each scratch folder, in the sandbox, before the agent
+  starts; what it writes is not counted as the agent's change. For Graphify:
+  `--mcp graphify --mcp-prepare "graphify update ."`. Each run records its MCP tool calls; the
+  report and `eval compare` show them ("the agent never used the server" when none), compare notes
+  when the arms' servers differ, and `report.json` records the server and the command. A server
+  that does not start, or a failed prepare command, stops the eval at the first run. The Claude
+  Code baseline refuses both options.
+- The prepare command now runs before the agent's runtime starts, so a note that it writes into
+  `GARUDA.md` reaches the agent (the user's first Graphify run: the agent never called the server,
+  and a note written later would not have been read). A `~/.garuda/mcp.json` whose `"servers"` is a
+  list now gets a message that shows the right form, not "expected record, received array".
+- Docs: Graphify as an example MCP server in the tools guide (install, `mcp.json`, the note in
+  `GARUDA.md`, and what we measured: ×1.28 cost per accepted change on the hard suite, no change in
+  passes). Garuda does not include it. The T11d design gets the user's keep rule: an edit with the
+  same passes stays when its cost per accepted change is clearly lower.
+- Tests: `waitUntil` waits up to 20 s by default (it was 5 s), under the 30 s test limit. The
+  user's `pnpm check` failed the M5 Ctrl-C test on a busy machine. Two test files had their own
+  copy with 4 or 5 s (a second M5 Ctrl-C test then failed the same way); they use `waitUntil`
+  now, and a test refuses a new copy.
+
+- The proposer loop (T11d): `garuda eval tune --addendum <file>` improves a prompt addendum. A
+  proposer model (default `claude-opus-5-5`) reads the dev runs that failed, or each task's cost
+  when all passed, and writes a new version; it stays when no task goes from all runs to none and
+  it passes 2 more runs (`--margin`) or as many at a clearly lower cost per accepted change (the
+  user's rule). Texts that ask to skip or edit tests or checks, or to leave the sandbox, are
+  refused before a run; the proposer never sees the held-out tasks; `--max-cost` (default $20)
+  stops before a round that would pass it. At the end the held-out set compares no addendum with
+  the final one. Garuda never edits the file: the versions, inputs, reports and history go to
+  `.garuda/evals/tune-<id>/`. `garuda eval --addendum <file>` runs any suite with an addendum.
+- `eval tune` after the user's first run (Haiku 5.5 agent, Opus 5.5 proposer, $0.65): the kept
+  version cut the held-out cost per accepted change to ×0.81 (×0.75 to ×0.88), all runs passing.
+  The run also found four faults, now fixed: two of three proposals were refused for phrases in
+  rules against cheating ("never modify tests to make them pass") or about reading ("skip tests
+  you won't run"), so a negation now clears a phrase and a refused text gets one more try in the
+  round; the held-out comparison said the reports had no task hashes; runs went one at a time
+  (about 16 minutes a score), so `--parallel` (default 4) runs them together; and nothing printed
+  during a score, so each run prints a line. Two runs of one task at the same time can no longer
+  take the same session file name (also for `garuda eval --parallel`).
+
+- The system prompt tells the agent how to work in few steps: batch tool calls that do not depend
+  on each other, find before reading, no exploration with bash, all edits in one step, one narrow
+  test run, fix the code not the tests, stop when done. The rules come from the first
+  `garuda eval tune` run: on the held-out set, with every run passing, they cut the cost per
+  accepted change to ×0.81 (95% interval ×0.75 to ×0.88) with Haiku 5.5 and ×0.87 (×0.79 to
+  ×0.95) with Sonnet 5.5. The tuned text's rules against `remember` and for one-sentence answers
+  are left out: they served the evals, not users. The prompt's own wording, measured against
+  0.17.0's prompt on the held-out set (3 runs a task, seed 7): with Sonnet 5.5, 30/30 both and
+  ×0.90 (×0.84 to ×0.96); with Haiku 5.5, 30/30 and 29/30 (one miss of the invoice refund trap)
+  and ×0.88 (×0.79 to ×1.02), so the Haiku saving is likely but not shown with confidence.
+
 ## 0.17.0 (2026-10-27)
 
 - macOS: no command process outlives the command (IPI-04). Seatbelt has no process namespace, so a

package/README.md

@@ -7,7 +7,7 @@ Website and docs: https://madhu-sv.github.io/garuda/
 Garuda is a coding agent for the terminal, and for editors over the Agent Client Protocol. It reads
 and edits your code, runs commands in an OS sandbox, and keeps an audit log of its permission
 decisions. It works with Claude and with OpenAI-compatible models, local ones too. This is version
-0.17.0. Release notes: [CHANGELOG.md](CHANGELOG.md).
+0.18.0. Release notes: [CHANGELOG.md](CHANGELOG.md).
 
 ## What Garuda does on your machine
 

package/SECURITY.md

@@ -6,7 +6,7 @@ Garuda runs commands and edits files for a model, so we take security reports se
 
 | Version | Supported |
 | --- | --- |
-| 0.17.x | Yes |
+| 0.18.x | Yes |
 | Older | No |
 
 ## Node and dependencies

package/dist/{acpCommand-7EY3NHPG.js → acpCommand-IUZPLPLI.js}

@@ -1,33 +1,33 @@
 #!/usr/bin/env node
+import {
+  chooseModel,
+  keepProviderKeys,
+  loadModelsConfig,
+  providerKeySource,
+  resolveModel
+} from "./chunk-2FIV2VZP.js";
 import {
   Runtime,
   auditDirFor
-} from "./chunk-2DYMJMRQ.js";
+} from "./chunk-NHWHG3SW.js";
+import "./chunk-65NUEOI7.js";
 import "./chunk-G2AX7MGS.js";
 import "./chunk-A2QAIRQL.js";
 import {
   FileSessionStore
-} from "./chunk-735BKABA.js";
-import {
-  chooseModel,
-  keepProviderKeys,
-  loadModelsConfig,
-  providerKeySource,
-  resolveModel
-} from "./chunk-JRVWH27M.js";
-import "./chunk-U65DQZDB.js";
-import "./chunk-J4346IDH.js";
+} from "./chunk-UKIE4AAM.js";
+import "./chunk-7KBOIPUT.js";
 import {
   loadSearchConfig
 } from "./chunk-B25VL4RU.js";
 import "./chunk-23FXBNBB.js";
 import {
   VERSION
-} from "./chunk-BSK5T2ZG.js";
+} from "./chunk-C57GHLKP.js";
 import "./chunk-5DEWP3YX.js";
-import "./chunk-ZAE25JM2.js";
-import "./chunk-ATW7BNIG.js";
 import "./chunk-PZS3V6P3.js";
+import "./chunk-QANRZW7W.js";
+import "./chunk-ATW7BNIG.js";
 import "./chunk-AOGFYUKG.js";
 import "./chunk-B4SJY7KT.js";
 import "./chunk-BHZ6G65V.js";
@@ -47,7 +47,7 @@ async function acpCommand(options) {
 `);
       return 1;
     }
-    const { setupCommand, terminalIO } = await import("./setupCommand-GBQIVYJC.js");
+    const { setupCommand, terminalIO } = await import("./setupCommand-YMF6I3MD.js");
     return setupCommand({}, { io: await terminalIO() });
   }
   const output = protocolOutput(process.stdout, process.stderr);
@@ -190,4 +190,4 @@ export {
   prepare,
   protocolOutput
 };
-//# sourceMappingURL=acpCommand-7EY3NHPG.js.map
+//# sourceMappingURL=acpCommand-IUZPLPLI.js.map

package/dist/{chunk-JRVWH27M.js → chunk-2FIV2VZP.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   writeFileAtomic
-} from "./chunk-U65DQZDB.js";
+} from "./chunk-65NUEOI7.js";
 import {
   keepSecretForRedaction,
   lookupModel
-} from "./chunk-J4346IDH.js";
+} from "./chunk-7KBOIPUT.js";
 import {
   isLoopbackHost
 } from "./chunk-ATW7BNIG.js";
@@ -228,6 +228,9 @@ async function keepProviderKeys(names, home) {
   }
   return stored.warning;
 }
+function providerKeyValue(name) {
+  return providerKey(process.env, name);
+}
 function providerKey(env, name) {
   if (name === void 0) return void 0;
   return keptKeys.get(name)?.value ?? env[name];
@@ -326,6 +329,7 @@ export {
   setDefaultModel,
   providerKeySource,
   keepProviderKeys,
+  providerKeyValue,
   resolveModel
 };
-//# sourceMappingURL=chunk-JRVWH27M.js.map
+//# sourceMappingURL=chunk-2FIV2VZP.js.map

package/dist/{chunk-TJIWD7R7.js → chunk-4BVCYCQT.js}

@@ -6,10 +6,10 @@ import {
 import {
   gateProjectSettings,
   isCostIncomplete
-} from "./chunk-735BKABA.js";
+} from "./chunk-UKIE4AAM.js";
 import {
   totalTokens
-} from "./chunk-J4346IDH.js";
+} from "./chunk-7KBOIPUT.js";
 import {
   TrustStore
 } from "./chunk-5DEWP3YX.js";
@@ -350,4 +350,4 @@ export {
   msUntil,
   finishJob
 };
-//# sourceMappingURL=chunk-TJIWD7R7.js.map
+//# sourceMappingURL=chunk-4BVCYCQT.js.map

package/dist/{chunk-U65DQZDB.js → chunk-65NUEOI7.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   knownModels
-} from "./chunk-J4346IDH.js";
+} from "./chunk-7KBOIPUT.js";
 
 // src/model/catalog.ts
 import { mkdir, readFile, writeFile } from "fs/promises";
@@ -140,4 +140,4 @@ export {
   loadCatalog,
   mergedModels
 };
-//# sourceMappingURL=chunk-U65DQZDB.js.map
+//# sourceMappingURL=chunk-65NUEOI7.js.map

package/dist/{chunk-J4346IDH.js → chunk-7KBOIPUT.js}

@@ -146,6 +146,7 @@ export {
   knownModels,
   lookupModel,
   WEB_SEARCH_USD,
+  costOf,
   responseCost,
   totalTokens,
   contextSize,
@@ -153,4 +154,4 @@ export {
   keepSecretForRedaction,
   Redactor
 };
-//# sourceMappingURL=chunk-J4346IDH.js.map
+//# sourceMappingURL=chunk-7KBOIPUT.js.map

package/dist/chunk-C57GHLKP.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+// src/version.ts
+var VERSION = "0.18.0";
+
+export {
+  VERSION
+};
+//# sourceMappingURL=chunk-C57GHLKP.js.map