edit tool: advertised schema accepts symbol without content, runtime rejects it

[ybw0014]

Short description

edit accepts an argument object carrying only filePath and symbol as valid per the advertised schema, but incomplete per the runtime contract — a model that stops there gets rejected. This validation error accounts for 86 of kimi-k3's 1389 edit calls; in the session I captured, 9 consecutive calls omitted content entirely.

What happened?

What I expected: a model calling edit would either supply the mode payload (content for symbol mode) or be steered to do so.

What I observed: kimi-k3 (K3 via Moonshot, api.kimi.com/coding/v1/chat/completions, served through an OpenAI-compatible proxy) repeatedly emits a tool call whose arguments are exactly {"filePath": "<...>", "symbol": "<...>"} — the JSON object closes right after symbol, with no content key at all. AFT then rejects it with:

edit: symbol mode requires both 'symbol' and 'content' string properties

The model's own reasoning trace says it intends to use edits[] ("My two edit calls failed because I mistakenly used symbol mode without content. Let me do the actual edits with batch edits mode"), yet the emitted arguments are symbol-only again. It loops until an unrelated /system-reminder about repeated tool calls breaks the cycle.

The captured call never carried content. The proxy keeps raw upstream SSE (one file per request, === API RESPONSE 1 === section). Deltas for one failing call, with the token-boundary fragments of filePath consolidated into one delta for readability:

"arguments":"{"
"arguments":"\"filePath\":\"/<project>/src/main/java/.../api/MinecraftVersion.java\""
"arguments":",\"symbol\":\"MINECRAFT_26_3\""
"arguments":"}"

Concatenating them yields {"filePath":"…/MinecraftVersion.java","symbol":"MINECRAFT_26_3"} — a complete, valid object with finish_reason: tool_calls. That one request carried two identical edit calls, and the host-side record for the same call holds those two keys and no content (Log output below). So the field was not removed by the proxy, the host or the plugin: it was not emitted.

Frequency (OpenCode state DB, tool-call records). Counting edit calls whose error is this message. Figures cover 2026-07-20 through 2026-09-18, joined per model from each record's own providerID/modelID:

model	edit calls	edit errors	this message
kimi-k3	1389	282	86
glm-5.3-flash	117	14	2
glm-5.2	648	80	1

Every other model in the same records produced no occurrence of this message.

Two caveats on that count: the error text cannot separate a missing content from a null-valued one, since both produce the same string; and 86 of 1389 is a correlation between the schema shape and the failure, not a controlled causal result.

Where the contract comes from. The installed v0.56.2 build defines the tool's arguments as a flat object with a single required key — read from createEditTool in the installed plugin (dist/entry/server.js, v0.56.2):

args: {
  filePath: z.string(),
  symbol: z.string().optional(),
  content: z.string().optional(),
  appendContent: z.string().optional(),
  edits: z.array(z.object({ /* oldString/newString/replaceAll/occurrence …, or startLine/endLine/content */ })).min(1).optional()
}

No oneOf/anyOf, and additionalProperties is not set. The request body carries the same contract serialized to JSON Schema; abridged to the relevant keys, as captured from the proxy for the same session:

{ "type": "object",
  "required": ["filePath"],
  "properties": {
    "filePath": { "type": "string" },
    "symbol": { "type": "string" },
    "content": { "type": "string" },
    "appendContent": { "type": "string" },
    "edits": { "type": "array", "minItems": 1, "items": { "type": "object" } } } }

So an object with only filePath and symbol passes the advertised schema, and is rejected by the runtime. The same request advertises write as required: ["filePath","content"]; this model's write record is 148 calls / 2 errors.

The declarations match crates/aft/src/subc_tool_schemas.json and createEditTool at v0.56.2.

That shape lines up with two statements in Moonshot's K3 documentation:

Setting additionalProperties to false and listing mandatory fields in required reduces invalid arguments. … When your inventory grows to dozens or hundreds of tools, do not send every schema in every request.
— Build an Agent with Kimi K3

… the more candidate tools there are, the more likely the model picks the wrong tool or constructs invalid call arguments.
— Dynamically Loaded Tools

The captured requests carried 83 tool definitions (tool_surface: "all"). That is an observation about the request, not a tested cause: I have not measured whether a smaller inventory changes the outcome.

Requests

1. Make the advertised schema express the parameter branches the runtime accepts, with each branch's required fields, and state what happens when more than one payload is present. Today symbol+content, appendContent, and both item shapes of edits[] are optional siblings with no combination rule, so the valid-object-but-invalid-call gap is structural rather than accidental. Whatever combination keywords are used must match the runtime's existing behaviour, so that a branch payload can no longer be omitted while still passing validation. additionalProperties: false is a separate, optional item: it does not address a missing field, and it needs checking against the path alias and the target endpoints.
2. On the OpenCode surface, sync path → filePath in the edit description. createEditTool already states the intent in-line (// filePath, not path: host UI header contract), and 9a9158d63 (2026-07-24) applied it to the schema — but getEditDescription still says to pass path + symbol + content and shows { "path": "src/app.ts", ... } (line 703), while docs/tools.md (v0.56.2, ### edit) uses path throughout without ever naming filePath. path is accepted as an alias at runtime, so nothing is functionally broken — the advertised schema and the prose it reads simply disagree on the field name. This is a separate, documentation-only item.
3. Minimal reproduction and acceptance criteria, in case the above is not self-evident: in OpenCode 1.18.31 with @cortexkit/aft-opencode v0.56.2, running the default edit surface (with edit_mode unset, so the edit tool is not the hashline variant), create a scratch file holding one known symbol, call edit with an argument object containing only filePath and symbol, and observe the message quoted above. A fix satisfies this when (a) an object with no mode payload no longer validates against the advertised schema, and (b) valid calls of every supported branch still pass.

The failure is generated upstream of AFT — the model emitted an incomplete argument object and AFT's rejection is correct. Request 1 is about the advertised schema; Request 2 is the separate naming inconsistency; Request 3 checks Request 1.

Diagnostics

Manual report (the CLI reported aft binary: not installed when run via npx, so values below come from the installed plugin and its bundled binary):

@cortexkit/aft (CLI)        v0.56.2
@cortexkit/aft-opencode     v0.56.2
bundled aft binary          v0.56.2
OpenCode host               1.18.31
platform                    macOS arm64 (darwin)

Relevant config (~/.config/cortexkit/aft.jsonc):

{
  "tool_surface": "all",
  // edit_mode was unset while the calls in this report were made -> "default" (find/replace/symbol/batch surface).
}

Model: kimi-k3 via an OpenAI-compatible proxy (api.kimi.com/coding/v1/chat/completions, reasoning_effort: "max"). The captured follow-up requests do include assistant reasoning_content and tool_calls; I have not isolated preserved-thinking behavior as a contributing factor.

Plugin version

0.56.2

AFT binary version

0.56.2

Platform

macOS arm64 (darwin)

Log output (optional)

Raw upstream SSE deltas for one failing call (path redacted; the token-boundary fragments of filePath are consolidated into a single delta), 2026-09-18, from the proxy's request log:

"tool_calls":[{"index":0,"id":"functions.MINECRAFT_26_3:0","type":"function","function":{"name":"edit","arguments":""}}]
"tool_calls":[{"index":0,"function":{"arguments":"{"}}]
"tool_calls":[{"index":0,"function":{"arguments":"\"filePath\":\"/<project>/src/main/java/.../api/MinecraftVersion.java\""}}]
"tool_calls":[{"index":0,"function":{"arguments":",\"symbol\":\"MINECRAFT_26_3\""}}]
"tool_calls":[{"index":0,"function":{"arguments":"}"}}]
{"choices":[{"finish_reason":"tool_calls", ...}]}

Host-side record of the same call (OpenCode storage, part.data):

{ "type": "tool", "tool": "edit",
  "state": { "status": "error",
             "input": { "filePath": "/<project>/src/main/java/.../api/MinecraftVersion.java",
                        "symbol": "MINECRAFT_26_3" },
             "error": "edit: symbol mode requires both 'symbol' and 'content' string properties" } }

[ybw0014]

The hashline shapes mentioned at the end of the configuration block are reported separately: #324

[aft-alfonso]

Confirmed from the code, and your reading of the contract is exactly right: the advertised schema admits {filePath, symbol} and the runtime rejects it, so the model is being told "valid" by one surface and "invalid" by the other. That is a defect on our side regardless of which model trips over it.

The reason the schema is flat is deliberate and worth stating so the fix does not undo it: OpenCode's host JSON-Schema conversion refuses root-level oneOf/anyOf, so the edit tool cannot express "symbol mode requires content" structurally — every mode has to be optional and the mode has to be enforced at runtime. What we got wrong is not the flat schema but what the runtime does when a call is incomplete: it returns a bare rejection with no route to completion, so a model that stops after symbol has nothing to steer it, and the 9-consecutive-call shape you captured is the natural result.

Two changes, both on our side:

1. The description and the per-property text will say the mode contract in words the model reads before emitting — symbol is only meaningful with content, and a call carrying symbol alone is incomplete. The schema cannot say it, so the description must.
2. The runtime error will become a steer rather than a verdict: when a call carries symbol without content, the reply names the missing property and the two complete shapes (symbol+content, or edits[]) so the retry has a target. Same treatment for the mirror case, content without symbol.

On the caveat you raised yourself: a missing content and a null-valued one produce the same message today, and #272 earlier this month showed models emitting null for oldString. The steer will distinguish them, since a null is a different mistake from an omission.

Your proxy capture settled the one thing I could not have: the argument object really closes after symbol with finish_reason: tool_calls, so this is the model stopping, not a truncation or a proxy defect. That is what makes the description the right layer.

[aft-alfonso]

Fix is on local main and rides train 132 (blocked behind an unrelated CI abort in the storm suite, which I am chasing separately). Your three probes are in the test suite verbatim, asserting the exact messages; I will note here when it lands on main and again when it ships.

[aft-alfonso]

Landed on main at 4366708. Ships in 0.57.0.

[aft-alfonso]

Fixed in v0.57.0, published just now to npm and crates.io.

Upgrade with npx @cortexkit/aft@latest doctor --fix, or let the plugin pick it up on its next start.

Thanks for the report — closing, but please reopen if you still see it on 0.57.0.