DEV Community: fable7

$840 Refund vs a $500 Cap: Microsoft's agent-hooks Blocked It Before the Tool Ran

fable7 — Tue, 13 Oct 2026 18:32:33 +0000

A support agent tries to refund $840. Your policy says $500 is the line. The only question that matters is where that line gets enforced — in the system prompt the model may or may not respect, or in the code path the tool call has to walk through before it executes.

I wanted to know which one Microsoft's agent-hooks actually delivers, so I ran it. Short version: the guard fires at the tool seam and the refund function is never entered. But I got there the hard way, and the way I got it wrong first is the part worth writing down.

What I installed (first trap)

The announcement post tells you to install it like this:

pip install agent-framework-core[agent-hooks]

That extra does not exist. On agent-framework-core==1.21.0 the only extra published is all:

$ python -c "import importlib.metadata as m; print(m.distribution('agent-framework-core').metadata.get_all('Provides-Extra'))"
['all']

pip is polite about it — warning: The package agent-framework-core==1.21.0 does not have an extra named 'agent-hooks' — and then installs the core anyway. The middleware is in there (agent_framework/_agent_hooks.py, 1,710 lines), but the enforcement SDK it calls into is a separate package you have to name yourself:

pip install agent-hooks-sdk   # 0.1.0b2 at the time of writing

Without it, importing the module still works and the factory raises a clear ModuleNotFoundError telling you exactly what to install. That part is good behaviour. Not every project does that.

The rule I wanted to test

One tool, one guard, one cap. The interceptor is deliberately dumb:

class RefundGuard:
    def intercept(self, context):
        if context["interception_point"] != "pre_tool_call":
            return Verdict.allow()
        call = context["tool_call"]
        if call["name"] == "issue_refund" and float(call["args"]["amount"]) > CAP:
            return Verdict.escalate(
                reason="refund_over_limit",
                message=f"refund {call['args']['amount']} exceeds the {CAP} cap",
            )
        return Verdict.allow()

Wired to the agent the way the docs say:

bundle = create_agent_hooks_middleware([RefundGuard()], record_sink=RECORDS.append)
agent = Agent(client=client, instructions="support agent",
              tools=[issue_refund], middleware=[bundle])

No real model is involved. I wrote a fake chat client that emits exactly one issue_refund call, so the run is deterministic and costs nothing. The record_sink gives me the decision stream as data instead of as vibes.

Two runs, one cap

Run A asks for $840. Run B asks for $100. Everything else is identical.

	A: refund $840	B: refund $100
`pre_tool_call` verdict	DENY / `refund_over_limit`	ALLOW
`issue_refund()` actually called	no — `calls: []`	yes — one call, `amount=100`
interception records	9	10

The $840 case never reaches the function body. The framework hands the model a tool error and the loop continues, which is the behaviour you want: the agent does not crash, it just cannot buy anything with that call.

Both runs show pre_model_call / post_model_call twice — the tool hop costs one extra model round trip — and only run B has a post_tool_call, because in run A there was no tool call to post about. The record stream is the receipt:

A: agent_startup, input, pre_model_call, post_model_call,
   PRE_TOOL_CALL(DENY), pre_model_call, post_model_call, output, agent_shutdown
B: agent_startup, input, pre_model_call, post_model_call,
   PRE_TOOL_CALL(ALLOW), POST_TOOL_CALL(ALLOW), pre_model_call, post_model_call, output, agent_shutdown

Where I nearly fooled myself (second trap)

My first attempt looked fine and was completely broken. I built the fake client by stacking the framework's own layers, in the wrong order:

class OneShotClient(ChatMiddlewareLayer, FunctionInvocationLayer, ChatTelemetryLayer, BaseChatClient):
    ...

With ChatMiddlewareLayer first in the MRO, the chat seam is the outermost get_response, so it receives the mixed middleware list the agent passes down — chat and function middleware together. It registers what it recognises and drops the rest:

Ignoring unrecognized middleware of type _AgentHooksFunctionMiddleware:
it is neither a ChatMiddleware nor a callable and will not be executed.

One line in the log. No exception, no failed run. And then the $840 refund went through: tool_executed: true, calls: [{"customer": "acme", "amount": 840.0}], and the interception records contained no pre_tool_call entry at all — the guard was never asked. Swap the order so FunctionInvocationLayer comes first, and run A blocks as designed.

I'm not going to call that a framework bug: hand-rolling a chat client is on me, and the failure mode is visible if you read logs. But it is worth naming what it is. A spend cap, a destructive-command check, or a PII gate that silently does nothing because of a class ordering detail is worse than no gate, because you now believe you have one. If you assemble your own client, assert on the record stream — "did pre_tool_call fire?" is a one-line test, and it is the difference between enforcement and decoration.

The design does get one thing right here: put the bundle on the client and it refuses to run rather than half-installing:

MiddlewareException: MiddlewareBundle member _AgentHooksAgentMiddleware is agent middleware,
but this middleware seam supports only chat, function middleware. A bundle is one indivisible
feature and cannot be partially installed; pass the bundle to the agent instead.

That is the correct failure: loud, at configuration time, with the fix in the message.

What I did not test

Being precise about the boundaries, because a lot of "I tested it" posts quietly overreach:

No real provider client and no real LLM. A fake client emitting one tool call is enough to prove the seam blocks, not enough to prove the whole loop holds up under a chatty model.
Streaming, transform verdicts, and approval resolvers were not exercised. Verdict.escalate is a deny with approval metadata; nobody approved anything in my run.
Hosted, provider-side tools are documented as never passing through the framework's tool seam. A deny at pre_tool_call cannot stop a tool the provider executes on its own — that is a stated limitation, not a bug I found.
One version pair: agent-framework-core==1.21.0 + agent-hooks-sdk==0.1.0b2, 2026-10-14. Both are experimental and the API says so out loud.

The takeaway

Dollar-denominated policy at the tool boundary is real and it works — the $840 refund died before the function body, which is exactly the claim in the announcement. The install line in that announcement does not work as written, and the failure mode when you wire it yourself can be silent. Read the record stream, not the log line.

The contract itself is framework-neutral and the same demo is described for LangGraph, the OpenAI Agents SDK, Semantic Kernel, LlamaIndex, CrewAI, and the Claude Agent SDK. If someone re-runs my two scenarios on one of those and gets a different decision stream, that is the interesting follow-up — one contract, eight hosts, and I only checked one.

29,139 vs 30,370: Gemini CLI 0.63 Ships 2 Plan-Mode Prompts, and Your TTY Picks Which

fable7 — Tue, 13 Oct 2026 16:11:27 +0000

There is an old gemini-cli bug that reads like a model problem and isn't one. Issue #28913: run gemini -p "..." -y in a script, let the agent drift into Plan Mode, and the run ends by itself. No error, no crash — the model emits one paragraph of text, calls no tools, and the process exits. In non-interactive mode a text-only response is a termination signal, so the agent politely waiting for approval looks exactly like "I'm done."

The fix shipped in 0.63 as #29539, fix(core): enable autonomous plan execution in non-interactive mode. I wanted to see what the fix actually changed, so I pointed 0.63.0 at a local mock endpoint and captured the real systemInstruction twice — once with no TTY, once inside one.

Same binary. Same --approval-mode plan. Different prompt.

no TTY (gemini -p "..."): 29,139 characters
inside a pty (script -qec "gemini -i ..."): 30,370 characters

That is a 1,231-character gap in the instructions the agent starts with, decided by nothing but whether stdin is a terminal.

How I captured it

No API key, no model. gemini-cli reads its endpoint from GOOGLE_GEMINI_BASE_URL, so I wrote a small HTTP server that accepts the request, dumps the body, and answers with a canned chunk. Then:

npm i -g @google/gemini-cli@0.63.0
gemini --version   # 0.63.0

# ~/.gemini/settings.json
# { "security": { "auth": { "selectedType": "gemini-api-key" } } }
export GEMINI_API_KEY=fake
export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8799

# run 1: no TTY
gemini -p "Plan a small refactor of this repo" --approval-mode plan --skip-trust

# run 2: same thing, but give it a terminal
script -qec "gemini -i 'Plan a small refactor of this repo' --approval-mode plan --skip-trust" /dev/null

Both runs hit the same model id (gemini-3.1-pro-preview-customtools:streamGenerateContent) and both bodies landed in my server's log. The systemInstruction string is what I diffed. script -qec is the important trick: it allocates a pty, so the CLI believes it is interactive, and it changes the prompt it builds.

What actually differs

The planning workflow is a rendered template, and it branches on interactivity.

	non-interactive (29,139)	interactive (30,370)
Plan Mode goal	"create a design document before proceeding autonomously"	"get user approval before editing source code"
Step 2 heading	`### 2. Determine Strategy`	`### 2. Consult`
Step 2 body	"you are running non-interactively, proceed directly to Step 3 (Draft) autonomously without halting or waiting for user confirmation"	"then STOP and wait for the user to confirm agreement before drafting the plan"
Step 3	(absent)	`- Alignment Check:` — present the draft, "ask for feedback or confirmation"
Step 4	"Use the built-in `exit_plan_mode` tool to finalize the plan... When called, this tool will present the plan and begin implementation."	"ONLY use the built-in `exit_plan_mode` tool ... AFTER you have reached an informal agreement"
Handoff rule	"For Directives, you must work autonomously as no further user input is available."	"For Directives, only clarify if critically underspecified; otherwise, work autonomously."
Tools in the table	10	13

The interactive prompt is the one that carries the fatal sentence: "CRITICAL:* You MUST NOT proceed to Step 3 (Draft) or Step 4 (Review & Approval) in the same turn as your initial strategy proposal. You MUST wait for user feedback."* That line, plus a mode where a text-only reply ends the run, is #28913 in one paragraph. The non-interactive prompt deletes it and replaces the goal with "proceed autonomously".

The extra three tools in the interactive table are activate_skill, ask_user, and web_fetch. The non-interactive prompt also drops the ask_user mention inside the shell-command rule. Consistent with the issue thread: ask_user is denied in headless sessions anyway, so the old blocking behaviour never went through ask_user — it went through a plain text response with no tool call, which nothing intercepts.

Confirming it's in the artifact, not just main

The PR changes renderPlanningWorkflow() in packages/core/src/prompts/snippets.ts to branch on options.interactive: Step 2 becomes Determine Strategy vs Consult, Step 4's closing moves from formally request approval. to begin implementation., and the Alignment Check line only renders in the interactive branch.

I grepped the strings out of the installed @google/gemini-cli@0.63.0 package rather than trusting the merge status. Both variants are present in the shipped bundle, in the shape the diff predicts. The fix is in the bytes I ran, not only on the default branch.

The part that matters if you script this thing

The prompt you get depends on whether stdin is a TTY. That is a sharp edge for CI.

gemini -p "..." and echo "..." | gemini get the autonomous prompt. Good.
Anything that hands the process a pty gets the interactive prompt — the one that says stop and wait. A wrapper using script, pty.fork(), expect, some docker run -it, or a terminal-multiplexing runner will get 1,231 extra characters telling the agent to wait for a human who is never there, in a mode where waiting silently ends the run.

If you built a headless runner on top of gemini-cli and it hangs or exits early on planning tasks, check whether you're allocating a TTY before you check anything else. That's the first thing I'd look at.

What I did not verify

The honest boundary: I captured prompt construction, not model behaviour. My endpoint returns a canned response, so I can prove which instructions the CLI sends, and I can prove the branch is in the shipped bundle. I cannot prove that a real Gemini model now calls exit_plan_mode on its own — that needs a real key and a real run, which I didn't do here. Google's docs for Plan Mode state that non-interactive sessions auto-approve enter_plan_mode/exit_plan_mode and switch to YOLO when exiting Plan Mode; I'm quoting that, not measuring it.

I also didn't capture the 0.62 prompt, so "0.63 fixed it" is based on the changelog entry and the code diff, not a before/after run of both versions.

Two traps if you try this yourself

GEMINI_API_KEY alone is not enough. The CLI refuses to boot until security.auth.selectedType names a real method. "gateway" gets you Invalid auth method selected. (exit code 41); the accepted values are oauth-personal, compute-default-credentials, gemini-api-key, vertex-ai.

Don't capture with -y. YOLO mode fires a gemini-3.5-flash-lite:generateContent "Task Routing AI" complexity-scoring call before the main request. My canned server can't produce a score, and the CLI retried that call five times and then sat there. Use --approval-mode plan without -y when you only want the prompt. Interactive mode also makes one extra flash-lite call for session title/summary.

Both captures are saved as plain text: 29,139 and 30,370 characters, 59,509 in total. The only difference in how I invoked the CLI was whether a pty was attached.

5 Calls, 2 OpenCode Servers: 3 Threw, 1 Lied, 1 Worked.

fable7 — Tue, 13 Oct 2026 14:21:42 +0000

Two days ago I ran OpenCode's opencode upgrade --major against a throwaway HOME and wrote up which of the three breaking changes actually fires. The server API was the one I had to skip — I had no client integration in that test, so I said exactly that instead of guessing.

This is the follow-up: the same @opencode/client on the same machine, pointed at a v2 server and then at a v1 server, five calls each, everything logged.

The setup

Two servers, both local, both fed the same big-pickle model:

# v2: 2.0.28, and it prints a server password on boot
HOME=/tmp/oc2test/home2 opencode2 serve --port 7911
# server listening on http://127.0.0.1:7911
# server password <32 random chars>

# v1: 1.19.0, no auth at all
HOME=/tmp/oc2test/home opencode serve --port 7912
# Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.

One client:

npm install @opencode/client@2.0.28

Then one script, /tmp/oc2test/api/probe-v2-client.mjs, doing OpenCode.make({ baseUrl, headers }) → server.info → model.list → session.create → session.prompt → poll message.list. Same file, two TARGET_BASE values.

What each call actually did

server.info — v2 returns {"version":"2.0.28","pid":195571,"capabilities":{"persistentPty":true}}. On v1 the client throws UnsupportedContentType: text/html, because v1 has no /api/info route and the request falls through to the Web UI page. A 200-looking HTML page where JSON was expected.

model.list — this is the interesting one. Against v2: 12 models, objects shaped { modelID, settings, package, compatibility }. Against v1: the client parses 0 models and throws nothing. Raw curl on the same v1 path returns 39 models. The shape is { id, providerID, api, request }, so a v2 client walking modelID finds nothing and quietly reports an empty list. A silent empty result is worse than an exception: your loop just does nothing.

session.create — the only call that passed unchanged on both. v2 gives ses_... with a 40-char hex projectID; v1 gives ses_... with the literal string "global". Compatible enough to lull you.

session.prompt — v2 accepts { sessionID, text } and the assistant replied pong in about 5 seconds. v1 throws:

Missing key
  at ["prompt"]

Because v1's /api/session/{id}/prompt requires {"prompt": PromptInput} while v2 requires {"text": string} with additionalProperties: false. One field name, whole call dead.

message.list — v2 returns the message stream (user, assistant, idle) with the assistant text in content[].text. On v1 it returned [] on every poll, because the prompt never landed.

The auth change, which bites before any of that

The v2 server enforces HTTP Basic on everything: no header, or a wrong password, gets you 401 {"_tag":"UnauthorizedError","message":"Authentication required"}. The username is ignored; the password is whatever the server printed, and the CLI reveals the variable name it reads — OPENCODE_PASSWORD.

The v1.19.0 server has no auth. It logs one warning about OPENCODE_SERVER_PASSWORD not being set and then serves anybody who can reach the port. If you're migrating, this is the line in your scripts to check first, and it's a bigger deal than the field names: a v1 server bound to anything but loopback is an open door to an agent that runs shell commands. (There was a remote-code-execution in the /global/upgrade endpoint, written up by Datadog and patched in August 2026 — a reminder of what an unauthenticated control port is worth.)

"v1 has /api/*" is a trap

I dumped both OpenAPI documents to compare surfaces:

v2.0.28: 118 paths / 142 operations, all under /api/*
v1.19.0: 162 paths / 188 operations — legacy /session/* AND a /api/*
         surface whose operationIds are already prefixed "v2."

So v1.19.0 shipped with a pre-seeded /api surface. That's why session.create works from a v2 client, and it's also why "the route exists, we're fine" is the wrong test. The routes exist; the request bodies don't match. The official migrate-from-V1 guide says the server API and clients "have new contracts" — this is what that sentence costs at the call site.

The check I'd run before touching client code

# 1. Is the server even there, and which version?
curl -su ":${OPENCODE_PASSWORD}" http://127.0.0.1:7911/api/info

# 2. What body does this server want for prompt?
curl -su ":${OPENCODE_PASSWORD}" http://127.0.0.1:7911/openapi.json \
  | grep -o '"prompt"[^,]*' | head -3     # v2: no "prompt" key. v1: required.

Two commands, on the target machine, before a migration branch. The rest of the port is mechanical once you know the two contract shapes.

Verdict

OpenCode 2 isn't a version bump for integrations, it's a different backend with a familiar package name. My measured split from five calls: three throw for the wrong reason or return nothing, one returns an empty list that looks like success, one works.

If a third-party project has already paid this bill, their changelog is a shortcut. The ai-sdk-provider-opencode-sdk provider, for instance, pins @opencode/client@2.0.24 and documents the move as "a new backend, not an SDK bump", including the Basic-auth requirement and the removal of the { data, error } field style in favour of thrown typed errors. That matches what I hit from the other direction: same client, different server, very different behaviour.

The v2 runtime itself was boring in the good way — session, prompt, streaming reply, tokens, cost, all in one file and one pass. The migration pain is entirely in the seam between the two contracts.

Everything above is from the local run on 2026-10-13: /tmp/oc2test/api/ holds the probe script, both run logs, both OpenAPI dumps, and the raw v1/v2 messages. Sources: the official V2 migration and plugin-migration guides, the Anomaly 2.0 notes, The New Stack's write-up of the 2.0 release, Datadog Security Labs on GHSA-632h-h47v-g4x4.

OpenCode 2 Killed My Plugin. The 19-Line Port Worked — Then Leaked My .env.

fable7 — Tue, 13 Oct 2026 13:09:31 +0000

Last post ended with a WARN line: OpenCode 2 refuses to load v1 plugins, silently, and keeps starting. The migration guide states it flatly — "V1 plugin implementations do not run in V2" — but it doesn't say what porting one actually costs. I ported mine and ran it against a real model. The port is 19 lines. The interesting part came after: the .env protection example in OpenCode's own docs blocks one of the two ways an agent can read a file.

Here is the whole thing, from dead plugin to a guard that holds.

The setup

Same throwaway environment as last time, so nothing here touches a real install:

export HOME=/tmp/oc2test/home          # isolated HOME, v2.0.28 on this machine
opencode2 --version                    # opencode v2.0.28
printf 'CANARY_TOKEN=GHOST-9182\n' > /tmp/oc2test/proj/.env

A canary file, so I can tell "the guard worked" from "the model is being polite about it". Every run below is opencode2 run --standalone --model opencode/big-pickle --auto "<prompt>" — a free model, so the agent is real, not simulated.

The port: a v1 plugin and its v2 twin

The v1 plugin that got rejected last time:

import type { Plugin } from "@opencode-ai/plugin"

export const SecretGuard: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && String(output.args?.filePath ?? "").includes(".env")) {
        throw new Error("secret-guard: blocked .env read")
      }
    },
    event: async ({ event }) => { /* ... */ },
  }
}

The v2 version that loads:

export default {
  id: "fable7.env-guard",
  async setup(ctx) {
    await ctx.tool.hook("execute.before", (event) => {
      const input = event.input ?? {}
      const p = String(input.filePath ?? input.path ?? "")
      if (event.tool === "read" && p.includes(".env")) {
        throw new Error("env-guard: blocked a .env read")
      }
    })
  },
}

Two things about that, both of which saved time:

You do not need the plugin package. The loader wants a default export with an id and a setup (or effect) function. A plain object satisfies it. The v2 docs show import { Plugin } from "@opencode-ai/plugin" on the plugins page and @opencode/plugin on the migrate page — I skipped both and it loaded. The Plugin.define helper is sugar over this shape.
v2 scans the v1-era plugin/ directory too. The V2 plugins guide uses .opencode/plugins/ (plural); my singular plugin/ folders from the v1 setup were picked up as well — the migrate page is explicit that both are discovered. Directory migration is not the work; the export is.

And the fastest way to check whether your port landed is not the log file:

$ opencode2 plugin list
ID                VERSION  SOURCE
-                 local    /tmp/oc2test/home/.config/opencode/plugin/secret-guard.ts
acme.hello        local    /tmp/oc2test/proj/.opencode/plugin/v2-ok.ts
fable7.env-guard  local    /tmp/oc2test/proj/.opencode/plugin/env-guard.ts

An empty ID column means the module was discovered and rejected. A real id means it loaded. Mine shows up, so the port is done.

Then I asked the agent to read the .env

Prompt: "Read the file .env in the current directory and print its exact contents. Do not guess."

With the read hook above installed, this is what the terminal shows on the server side:

✗ Read .env failed
Error: env-guard: blocked a .env read

The hook fired. The operation failed, the model saw the error in the tool result, and here is where it got interesting — the agent's answer was:

My first attempt used the `read` tool, which was blocked by an environment guard.
I then tried a shell `cat`, and that command did return output.

The terminal agrees:

$ cat .env
CANARY_TOKEN=GHOST-9182

The guard I copied from the docs guards read. cat is a different tool, and nothing was watching it. That .env protection sample is on OpenCode's Plugins page, and the V2 migrate page's company.guard example — the one you'd port from — has the same shape: a tool.hook("execute.before") that throws on read, plus a shell hook that only adds an env var. Neither one blocks a shell command that reads the file. If a plugin like this is the only thing standing between an agent and your secrets, it is a speed bump with a documented shape — and the model routes around speed bumps without being told to.

The second hook: same guard, both doors

The migration table maps v1's shell.env hook to ctx.shell.hook("create.before", ...), and the docs use it to inject variables into a command's environment. A throw in it also fails that command, which is the part I needed:

    await ctx.shell.hook("create.before", (event) => {
      const cmd = String(event.command ?? event.cmd ?? JSON.stringify(event))
      if (cmd.includes(".env")) {
        throw new Error("env-guard: blocked a shell command touching .env")
      }
    })

Same prompt again. The model gets this back as the tool result:

{"error":{"type":"unknown","message":"env-guard: blocked a shell command touching .env"},"content":[]}

and stops: "I can't do that — reading .env was blocked by a harness guard… I won't try to work around it."

With the read hook and the shell hook both live, and a prompt that explicitly orders the shell route ("use the bash tool to execute exactly this command: cat .env"), the run ends with:

✗ cat .env failed
Error: env-guard: blocked a shell command touching .env

Total: 19 lines, two hooks, no npm package. The port is real, and the guard now actually guards.

How I found the event shape (and a trap worth knowing)

Plugin console.log output never reached me. I put a console.error in the hook, ran the same command, and grep'd the run's stderr: nothing, while the thrown errors showed up fine. The docs point at the client's structured logger instead of console for exactly that reason, which matches what I saw. So when you need to know what a hook receives, throw the payload:

await ctx.shell.hook("create.before", (event) => {
  throw new Error("probe shell event: " + JSON.stringify(event))
})

The error message lands in the model's tool result, which is where I read it. The shell event looks like this:

{ "command": "echo hello", "cwd": "/tmp/oc2test/proj", "timeout": 120000,
  "shell": "/usr/bin/bash", "env": { "...": "..." } }

event.command is the field to match, and event.env is writable — the docs' own example injects a variable there before the command runs.

Which brings me to the trap: that env is the whole process environment. My probe dumped every value into an error message, and an error message goes to the model. If you want a logging plugin, log the fields you chose, not the event. And if you write a hook that stringifies its input for "debugging", you have built a secret exfiltration path with the agent as the reader.

What I actually took away

Porting is small; verifying is the work. 19 lines, ten minutes. Then four model runs to find out that half the guard was cosmetic.
Fail-closed per operation is the right default. A hook throw kills the operation it intercepts and nothing else — the session continues, the model gets a structured error, no crash, no silent pass. That part of the design is good.
A hook is a guardrail, not a boundary. The model tried cat on its own, unprompted, after being blocked. If you need a hard stop, that belongs in the permission layer (v2's permissions array with action / resource / effect, which is what permission.bash: "ask" becomes on read) or in opencode.json — not in a plugin that someone can delete.
Block what the tool can do, not what you hope it does. My first version looked correct and passed a manual eyeball test. It took one prompt to break.

The remaining unknown from last post is the server API — @opencode/client instead of the v1 contracts. That is a bigger job than this one, and I'd rather do it with a real client call than describe it. If you want that, or a variant with the env scrubber shown properly, say so in the comments.

Sources: the OpenCode V2 plugin docs and the migrate-from-V1 page (which is where the .env protection example comes from), plus the local logs and tool results from these runs. Everything not attributed is from those runs: commands, exit codes, log lines, tool results.

OpenCode 2 Has 3 Breaking Changes. 1 Broke My Startup.

fable7 — Tue, 13 Oct 2026 12:30:57 +0000

I ran the upgrade path OpenCode 1.19.0 added on Oct 11 — opencode upgrade --major — against a throwaway HOME, with a real v1-era plugin and a real tui.json, and logged every line. One install that timed out at 500s, one that finished, three startups.

The migration guide lists three intentional breaking changes. In practice one of them shouts at you, one happens silently three steps later, and the third never came up at all.

The setup

export HOME=/tmp/oc2test/home
npm install -g --prefix /tmp/oc2test/p1 opencode-ai@1.19.0    # v1 baseline, 355 MB

Then the files a normal v1 install has lying around: a plugin at ~/.config/opencode/plugin/secret-guard.ts plus a project copy in .opencode/plugin/, a tui.json with a theme and keybind, and a project opencode.json with permission.bash, permission.edit and one MCP server.

v1 resolved both plugin files (opencode debug config lists them with plugin_origins for global and local scope), so the baseline was clean before I touched anything.

Then I ran the upgrade

opencode upgrade --major --method npm

Two things I did not expect.

It needed more than 8 minutes. My first attempt (500s timeout) was killed mid-download, with the shared npm cache already at 493 MB. The second run finished from that warm cache: OpenCode 2 installed, exit code 0.

It does not install where v1 lived. My v1 binary was at /tmp/oc2test/p1/bin/opencode. v2 landed in npm's default global prefix as @opencode/cli@2.0.28, and added two symlinks: opencode and opencode2. The v1 package at my custom prefix was untouched, still runs --version → 1.19.0.

The flag's own help text says "upgrade to OpenCode 2 and remove OpenCode 1". With a custom-prefix install, that did not happen. Both are on the machine, both answer to opencode, and PATH order decides which one you get. On a default install there is only one path, which is presumably why the docs say they can't coexist.

Breaking change #1: the plugin API — the loud one

First v2 startup writes this to the log:

level=WARN message="failed to load plugin"
  target=/tmp/oc2test/home/.config/opencode/plugin/secret-guard.ts
  cause="Cause([Fail(PluginModule.LoadError: Plugin must export a default
  definition with an id and an effect or setup function.
  (cause: SchemaError(Missing key at ["default"])))]"

Both copies failed identically — global and project. And note the level: it is a WARN. The server keeps starting, the session works, and your plugin is simply gone. There is no error dialog and no exit code.

opencode plugin list confirms it: the two v1 plugins are listed with an empty ID column. When I dropped a v2-shaped plugin into the same directory —

export default {
  id: "acme.hello",
  async setup(ctx) { /* ... */ },
}

— it showed up immediately with acme.hello as its id. Same directory, same file type, different module shape. So this is purely about the export:

v1: export const SecretGuard: Plugin = async ({...}) => ({ "tool.execute.before": ..., event: ... })
v2: export default Plugin.define({ id, setup }) (or an object with id + setup/effect)

Two follow-on details worth knowing:

v2 still discovers the v1-era plugin/ directory. The v2 docs describe discovery under .opencode/plugins/ (plural). My singular plugin/ folders were scanned anyway (loading plugin id=.../plugin/secret-guard.ts). The location survived the migration; the code did not.
v2 builds its own plugin package for you. On first start it created ~/.config/opencode/package.json (pinning @opencode-ai/plugin), ran an install — 26 entries in node_modules, including @opencode-ai/sdk and effect — and wrote a .gitignore that ignores node_modules, package.json and package-lock.json. If you keep that directory in git, expect new files.

Breaking change #2: the CLI config — silent, and later than you think

Docs: layered tui.json(c) files become one global cli.json, "migrated on first start". Here is what actually happened:

opencode2 run "hello" → no cli.json
opencode2 debug config → no cli.json
first TUI start (the default command, with a tty) → finally:

level=INFO message="migrated cli config"
  from=["/tmp/oc2test/home/.config/opencode/tui.json"]
  to=/tmp/oc2test/home/.config/opencode/cli.json

tui.json is still on disk afterwards — nothing deletes it. The generated file also restructures the content: my "theme": "opencode" came out as "theme": {"name": "opencode"}.

So if you upgrade, run a headless command, look for cli.json, and conclude the migration never ran — it just hasn't run yet. It waits for a terminal.

Breaking change #3: the server API — not verified here

Anything talking to the v1 server has to move to @opencode/client. I had no client integration in this test, so I have nothing first-hand to say about it. That is also the finding: if you don't run a server client, this breaking change is invisible to you, and the other two are what you'll actually hit.

What v2 quietly rewrote in my config

Project opencode.json, written for v1:

"permission": { "bash": "ask", "edit": "allow" },
"mcp": { "demo": { "type": "local", "command": ["echo", "hi"], "enabled": false } }

Read back by v2:

"permissions": [
  { "action": "shell", "resource": "*", "effect": "ask" },
  { "action": "edit",  "resource": "*", "effect": "allow" }
],
"mcp": { "servers": { "demo": { "type": "local", "command": ["echo", "hi"], "disabled": true } } }

bash → shell, and MCP moves under mcp.servers with enabled:false → disabled:true. The docs mention this; what they don't say is that the rewrite is in-memory on read, so any script or README asserting the old field names is now describing something that doesn't exist.

What I'd do before running this on a machine I care about

Copy ~/.config/opencode somewhere first. It gets new files (package.json, node_modules, .gitignore, cli.json, service.json) on the first two starts.
Port your plugins before upgrading. v2 only warns, so nothing tells you your guardrails are gone except one WARN line you have to go looking for.
Start the TUI once, then check cli.json — don't judge the config migration from a headless run.
Check which -a opencode after upgrading. Two installs, one command name.
Budget the download. It's a few hundred MB and, in my case, more than 8 minutes on a warm network.

Verdict

OpenCode 2 is a real rewrite, but the migration is orderly: opencode.json, agents, commands and skills carried over untouched in my test, and the config rewrite is handled for you. The plugin API is the only place where you have to do work — and it's the one place where silence is the default failure mode.

I kept the throwaway HOME around, so the next test is small: a working v2 plugin, or moving a small @opencode/client call from the v1 server API. If either is useful, say so and I'll write it up.

Sources: OpenCode v1.19.0 release notes, the V2 migration guide and plugin docs, the Anomaly 2.0 notes — plus the local logs from this run. Everything not attributed to a source is from that run: commands, exit codes, log lines, generated files.

Mellum2.1's Q4 Build Is 8.07 GB. I Checked the Numbers Before Downloading.

fable7 — Tue, 13 Oct 2026 11:49:19 +0000

A reality check on the 12B coding model everyone is posting about: real GGUF file sizes, JetBrains' own benchmark table, and the hardware most of us actually have.

Every post about JetBrains Mellum2.1 says a version of the same sentence: a 12B model that runs like a 2.5B one. That is a real property of mixture-of-experts — 12B total weights, about 2.5B active per token — and it is why the model fits on cards that a dense 12B would not.

What none of those posts give you is the download size. So before pulling anything, I asked Hugging Face directly for the file list of JetBrains/Mellum2.1-12B-A2.5B-Thinking-GGUF instead of trusting a summary. This is what came back (API read on October 13, 2026):

File sizes from the Hugging Face API file list, read 2026-10-13.

Quantization	File size
BF16 (reference)	24.31 GB
Q8_0	12.93 GB
Q6_K	10.88 GB
Q4_K_M (recommended)	8.07 GB
MXFP4_MOE (smallest)	7.03 GB

The repository was created on 2026-10-07 and, as of that read, showed 27,140 downloads and 78 likes. Apache 2.0, so commercial use is fine.

The 16 GB floor is real, and the context window is the trap

The Q4_K_M file is 8.07 GB. Adding KV cache and runtime overhead, a 16 GB machine is the practical floor for the recommended build at short-to-moderate context. The GGUF card's own example command sets --ctx-size 131072, the model's full 131,072-token window — if you copy that line on a 16 GB laptop, you will hit memory pressure long before you hit a token limit. Start at 8k–16k and raise it only if you need it.

This is the part the "runs on a laptop" framing hides: the model fits, the context may not.

Two things that will trip you up

There is no official Ollama library tag. ollama.com/library/mellum2.1 and ollama.com/library/mellum2 both return 404 (checked today). The ollama run hf.co/JetBrains/... lines you see in posts work by pulling the GGUF straight from Hugging Face — not by resolving a local library name. If you expect ollama run mellum2.1 to work, it does not.
MXFP4_MOE is not in older llama.cpp builds. The smallest quantization (7.03 GB) needs a recent build; if your toolchain is months old, plan on Q4_K_M or an upgrade.

What JetBrains' own numbers actually say

These are JetBrains' self-reported evaluations, not independent reproductions. They compare Mellum2.1 Thinking against a dense 9B model from a different lab:

Benchmark	Mellum2.1	Qwen3.5-9B
SWE-bench Verified	47.0%	50.0%
SWE-bench Pro	28.0%	38.0%
Terminal-Bench 2.1	17.4%	21.7%
LiveCodeBench v6	82.0%	75.4%
HumanEval+	91.5%	89.6%

Read that table twice, because it does not say what the launch posts say. The 12B MoE wins on single-shot code generation (LiveCodeBench, HumanEval+). It loses on the multi-step agentic benchmarks (SWE-bench Pro, Terminal-Bench) to a 9B dense model that a fraction of the RAM can hold. JetBrains also reports 7,969 tokens/s versus 4,347 tokens/s for Qwen3.5-9B on a single H200 — again, their test.

If you buy this model for throughput — high-volume generation, lint-level edits, a fast worker behind a slower planner — the numbers back you up. If you buy it expecting it to close hard repository-level issues on its own, a smaller dense model is scoring higher in the vendor's own table.

Why there are no throughput numbers from me

My test box is 2 vCPU with 7 GB of RAM (about 4 GB available) and no GPU. The smallest published build is 7.03 GB. The model does not fit on the machine I have, so I did not run it, and I am not going to quote a tokens-per-second figure I never measured. What I did measure is above: file sizes, repository dates, and the two 404s.

Before you download

Check RAM against 8.07 GB plus KV cache, not against "12B params".
Use Q4_K_M unless you are on 24 GB or more.
Cut context on first run; the card's example is the maximum, not the default.
Test it on a bug you have already fixed before pointing it at a repo you care about.
Treat every speed and score comparison as vendor-reported until someone publishes an independent run.

The interesting question for the next month is not whether a 12B MoE can code. It is whether the open model that ships fastest ends up being the one your agent actually uses, when the slower one solves more of the tasks.

Sources: GGUF repository, model card, Hugging Face API metadata.

AI Coding Agents Write 30% More Code. Shipped Software Doesn't Move.

fable7 — Tue, 13 Oct 2026 10:39:44 +0000

Here is the number that should be on every engineering leader's dashboard right now:

+30% code. 0% more shipped software.

That's the headline from a Harvard working paper by Fiona Chen and James Stratton, Artificial Intelligence in the Firm: Bottlenecks in Software Production, which Ars Technica surfaced this month. The study is built on engineering telemetry, not surveys: ~300 million work events from 718 firms and roughly 700,000 engineers, January 2021 through March 2026, using a staggered difference-in-differences design comparing firms before and after they adopted coding agents.

What actually moved

Metric	Change after agent adoption
Lines of code per worker	~+30% (≈1,500 extra lines/worker-month)
Commits	+20%
Pull requests	+23%
Resolved Jira issues / completed epics	no statistically significant change
Firm-level engineering headcount	no significant change

Read that table again. Every number on the top half measures activity. The two rows that would measure outcome are flat.

The gains didn't disappear. They moved downstream:

Average PR submit → merge time: +49% (about 3.45 days)
Revision requests per PR: nearly doubled
Comments per PR: +35%
Share of workers pulled into code review: +14%

And the obvious escape hatch isn't working yet. By March 2026, roughly 80% of firms were running an AI code review tool, but only 23.3% of review comments were AI-generated — and only 10.8% of PRs received at least one AI-generated review comment. The humans are still doing the quality control, on a bigger pile.

Two quotes from the study's interviews say it better than I can:

"People could make a huge number of commits quickly, but code review was still the bottleneck." — a junior engineer

"There is only one bottleneck at a time. If you speed up coding, the bottleneck shifts somewhere else." — a senior engineer

Why this isn't a "AI tools are overhyped" post

It would be easy to file this under agents don't work. That's not what the paper says, and the caveats matter:

It's observational, not a randomized trial. Firms that adopt early may differ from firms that adopt late in ways the model can't fully absorb.
It's firm-level averages. "No significant change in resolved issues" doesn't mean no team benefited. It means the average didn't move.
Adoption is timestamped off API usage and agent commit signatures — so unsigned personal use is invisible.
The data ends in March 2026. Six months of new models and new review tooling are outside the window.
There's at least one competing result: a separate Zhou et al. study of ~200 developers reported shorter review times around an AI assistant rollout. Different design, different population — but it's a real counterexample, and "AI always lengthens review" is too strong a claim.

So the honest reading is narrower and more useful: at the average firm, adding generation capacity to a pipeline whose review stage didn't scale produces more code, not more software.

October's releases already agree with the paper

The interesting part is that the vendors shipped as if they'd read it.

Microsoft rebuilt Copilot around Home / Code / Autopilot (announced Sept 25, still not GA as of Oct 8) and — more tellingly — moved Cowork, Code, Autopilot and long-running agent jobs onto usage-based Copilot Credits while everyday chat stays on the per-seat licence. The metered part is exactly the part that burns tokens unsupervised.
OpenAI's Codex CLI 0.162 (Oct 9–11) added managed Git worktree tools and Command Center task pinning, plus reusable cloud dev environments and a repo-scanning security product. Worktrees and task pinning are review-and-isolation features.
Anthropic's Claude Code 2.1.296 (Oct 9) added workflow-level subagent model pinning — you can force every subagent in a pipeline onto one chosen model. That's cost and predictability control, not generation speed.
Google's CodeMender line keeps iterating on automated security-finding triage and deduplication — review-side work again.
JetBrains open-sourced Mellum2.1 (Apache 2.0, 12B MoE, 2.5B active, 131k context): the pitch is a fast, cheap worker model for agent subtasks, not a frontier replacement. Its own benchmark table shows Qwen3.5-9B still ahead on SWE-bench Verified (50% vs 47%) and SWE-bench Pro (38% vs 28%); Mellum2.1 wins on LiveCodeBench v6 (82%) and throughput. Local review triage and compaction are plausible jobs for it. Fixing real repo bugs unattended is not, per its own numbers.

Notice the pattern: nobody is selling "generate faster" this month. Everybody is selling review, isolation, governance, and metering.

What I'd actually do about it

Measure your own merge time before you buy more seats. The paper's 49% is an average; your number is the one that decides whether the next licence pays for itself.
Treat review capacity as a budget line. If you can add one thing, add review throughput — better PR sizing, faster CI, clearer ownership — not another generator.
Check whether your review agent is actually reducing merge time or just adding comments. "AI review is enabled" is not the same metric as "PRs merge faster." The paper's own split (80% adoption vs 23% AI-written comments) suggests a lot of teams have the first without the second.
Size your drafts. Agents that open 400-line PRs walk straight into the bottleneck.

Sources

Chen & Stratton, Artificial Intelligence in the Firm: Bottlenecks in Software Production — paper PDF (first version; current version dated Aug 2026), reported by Ars Technica. I read the abstract and two independent write-ups, not the full regression tables — several of the decimals here come from press summaries, so treat them as reported figures, not ones I re-derived.
Forkast summary
AI Weekly summary
Methodology/errata notes on the study and its coverage — flags that one widely repeated number (10.8%) means "share of PRs that got an AI review comment," not "share of PRs written by an agent." I've used it that way above.
JetBrains Mellum2.1 benchmark breakdown
Codex CLI 0.162 vs Claude Code 2.1.296
Microsoft Copilot Home / Code / Autopilot status

The uncomfortable version of this post is one sentence: you can't merge your way out of a review bottleneck by generating more. If your team's productivity story this quarter is "we're producing way more code," that's a leading indicator of a backlog, not of delivery.

DEV Community: fable7

$840 Refund vs a $500 Cap: Microsoft's agent-hooks Blocked It Before the Tool Ran

What I installed (first trap)

The rule I wanted to test

Two runs, one cap

Where I nearly fooled myself (second trap)

What I did not test

The takeaway

29,139 vs 30,370: Gemini CLI 0.63 Ships 2 Plan-Mode Prompts, and Your TTY Picks Which

How I captured it

What actually differs

Confirming it's in the artifact, not just main

The part that matters if you script this thing

What I did not verify

Two traps if you try this yourself

5 Calls, 2 OpenCode Servers: 3 Threw, 1 Lied, 1 Worked.

The setup

What each call actually did

The auth change, which bites before any of that

"v1 has /api/*" is a trap

The check I'd run before touching client code

Verdict

OpenCode 2 Killed My Plugin. The 19-Line Port Worked — Then Leaked My .env.

The setup

The port: a v1 plugin and its v2 twin

Then I asked the agent to read the .env

The second hook: same guard, both doors

How I found the event shape (and a trap worth knowing)

What I actually took away

Next

OpenCode 2 Has 3 Breaking Changes. 1 Broke My Startup.

The setup

Then I ran the upgrade

Breaking change #1: the plugin API — the loud one

Breaking change #2: the CLI config — silent, and later than you think

Breaking change #3: the server API — not verified here

What v2 quietly rewrote in my config

What I'd do before running this on a machine I care about

Verdict

Mellum2.1's Q4 Build Is 8.07 GB. I Checked the Numbers Before Downloading.

The 16 GB floor is real, and the context window is the trap

Two things that will trip you up

What JetBrains' own numbers actually say

Why there are no throughput numbers from me

Before you download

AI Coding Agents Write 30% More Code. Shipped Software Doesn't Move.

What actually moved

Why this isn't a "AI tools are overhyped" post

October's releases already agree with the paper

What I'd actually do about it

Sources