Tool Repair Skill for Hermes and OpenCode

A harness-level fix for LLM tool calling. Catches the common JSON
formatting mistakes open models make and fixes them deterministically before
the tool executor ever sees them. Ships with adapters for four agent
frameworks:

Based on the approach that made DeepSeek V4 Pro outperform Opus 4.7 on tool
calling (see CommandCode's write-up on tool call repairs,
their deep dive,
and this video walkthrough).

The Problem

Open models (DeepSeek, GLM, Qwen, Kimi) make the same tiny JSON mistakes in tool calls over and over. Each mistake triggers a validation error. The model retries with the same bad format. The session degrades through 50+ wasted retry cycles. The model never learns because the error messages are opaque.

These mistakes are not random. They are a small finite set of patterns caused by the model's training distribution leaking through the tool boundary.

Harness vs Model

Most people frame this as a model problem: "DeepSeek is bad at tool calling, wait for the next version." That is wrong. It is a harness problem. The harness sits between the model and the tool executor. It decides what to do with the model's output: reject it and waste tokens retrying, or fix it silently and move on. A harness that repairs deterministically turns a bad-at-tool-calling model into a functional one in about 200 lines of code.

The model did not change. The harness got more forgiving in exactly the places it needed to be.

The Repair Rules This Applies

How It Works

flowchart TD
subgraph Harness["HARNESS BOUNDARY"]
direction TB
P["Parse JSON"] --> V{"Schema Valid?"}
V -->|"Yes"| D["Execute Tool"]
V -->|"No"| W["Walk Issue List by Path"]
W --> R["Apply Repairsin Priority Order"]
R --> RV{"Re-validate"}
RV -->|"Pass"| D
RV -->|"Fail"| E["Return Readable Errorwith Guidance"]
end

M["Model Output(raw tool call JSON)"] --> P
D --> N["Tool Result+ Repair Note"]
E --> N
N --> B["Back to Model"]

Everything inside the HARNESS BOUNDARY box is your agent framework. The model provides the raw JSON and receives the result. All repair logic, validation, and correction notes are handled at the harness layer.

Key design rule: a repair only fires when it is unambiguously the right thing, so legitimate data survives. The rules that could touch arbitrary content are narrow on purpose. A string is only parsed as an array when it parses as one; an auto-link is only unwrapped when the link text equals the URL's own path component; an array-shaped repair only fires when the schema says the field is an array; a null is only dropped when the schema neither requires the field nor admits null for it. So writeFile content that happens to be JSON-shaped, a real [click](https://example.com) link, and bracketed prose like [1, 2] and [3, 4] all pass through untouched, and the test suite asserts each of those cases.

Components

tool_repair.py (the core library)

Standalone Python module with no dependencies beyond stdlib. Main entry point:

from agent.tool_repair import repair_function_args

repaired_args, repair_notes = repair_function_args(
function_name="readFile",
function_args={"path": "/tmp/test.txt", "limit": None},
tool_schema=None,  # optional JSON schema for type-aware repairs
)
# repaired_args = {"path": "/tmp/test.txt"}
# repair_notes = ["[repair: null values removed for optional fields]"]

Can be imported and used by any agent framework, not just Hermes.

Hermes Agent integration (two calls)

The library is built and tested: 34 Python tests, 21 TypeScript parity tests, and
CI runs both plus the module self-test. Integrating it into a Hermes harness is
two calls at the harness layer, between the model's output and the tool
executor:

1. agent/agent_runtime_helpers.py. sanitize_tool_call_arguments() is a harness function that walks tool calls before dispatch. Call repair_function_args() on the parsed dict after json.loads() has already succeeded. If repairs trigger, write the fixed JSON back to the call's arguments.

2. agent/tool_dispatch_helpers.py. make_tool_result_message() is a harness function that builds the tool result before it goes back to the model. Call deduplicate_repair_notes() there to append the repair notes to the result content.

The model reads the repair note alongside the successful result and adapts on the next turn. The harness did the fixing. The model just benefits from seeing what was fixed.

Hermes plugin manifest

references/plugin.yaml declares the hook surface (transform_llm_output) and plugin-architecture.md sketches the wiring. The pre_tool_call hook today can block a call but cannot modify arguments, so the two-call integration above is what you write; plugin-architecture.md describes the hook surface that would make it a config toggle instead.

Adapted For Other Frameworks

This repo ships adapters for two other agent frameworks in the adapters/
directory. Each adapter wraps the same core tool_repair.py library with the
harness-specific wiring.

OpenCode has the cleanest integration because its tool.execute.before hook
supports argument mutation. Claude Code and DeepSeek Harness are the most
limited: both can only block a call, not mutate it, so they waste a turn when
they detect a pattern. The DeepSeek Harness adapter reads the harness' own
payload keys (tool_name, tool_input), which is why it is a separate script,
but its detectors are not a second copy: adapters/shared/detect.sh is sourced
by all three shell hooks, so a change to a select cannot land in one adapter
and miss the others the way it did in v1.0.1 and v1.0.5.

See each adapter's README for setup instructions.

Safety Guarantees

• String-valued content is not at risk. The stringified-array rule only fires on a string that parses as a JSON array, and the auto-link rule only fires when the link text equals the URL's own path component. Prose like [1, 2] and [3, 4] and a real link like [click](https://example.com) pass through untouched, which the test suite asserts.
• Non-JSON tool data is unaffected. The repair layer only examines tool call arguments (the JSON dict describing what the tool should do), not tool results, binary content, images, or multimodal data.
• Schema-aware array repairs. Array-specific repairs (empty-object-to-array, bare-string-wrap) only fire when the tool JSON schema confirms the field expects an array type. Without a schema, only safe universal repairs run (null-strip, stringified-array-parse, autolink-unwrap).
• A bracketed string that does not parse is never wrapped into an array element. [not json] is either prose or a broken array serialization, and turning it into ["[not json]"] produces a valid-looking call full of garbage. It is left for the validator to report. A malformed or boolean JSON Schema is walked past rather than raising.
• The caller's dict is not mutated. repair_function_args deep-copies its input, so the documented write-back pattern (if fixed != parsed) actually fires, and a tool call that needs no repair produces no write-back.
• Repair notes deduplicate. If a repair note was already appended on a previous turn, it won't get stacked again.

Dependencies

The core library (tool_repair.py) needs nothing beyond Python standard library.

No pip packages, no npm modules, no external services for the core library.

How to Install

Core library (any framework)

cp references/tool_repair.py /your/project/tool_repair.py

from tool_repair import repair_function_args
fixed, notes = repair_function_args("my_tool", {"some_field": None})

Hermes Agent

Copy the library, then add the two calls described in Components:

cp references/tool_repair.py /path/to/hermes/agent/tool_repair.py

Or prompt your agent:

> Clone https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode.git, copy references/tool_repair.py into the Hermes agent directory, then call repair_function_args inside sanitize_tool_call_arguments after json.loads() succeeds and deduplicate_repair_notes in make_tool_result_message. There is no Hermes config key for this; it needs those two code changes.

OpenCode

Copy the TypeScript adapter into your OpenCode plugins directory:

cp -r adapters/opencode/* ~/.config/opencode/plugins/

Or prompt your agent:

> Clone https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode.git and copy the TypeScript plugin from adapters/opencode/ to ~/.config/opencode/plugins/.

Claude Code

Copy the hook scripts and the shared detectors, then configure in claude.json:

mkdir -p .claude/hooks
cp -r adapters/claude-code adapters/shared .claude/hooks/
chmod +x .claude/hooks/claude-code/*.sh

The hooks read their detectors from adapters/shared/detect.sh, one copy
shared with the DeepSeek Harness adapter and the telemetry hook, so the
directory layout has to come with them. Set TOOL_REPAIR_SHARED_DIR if you
install them somewhere else.

Or prompt your agent:

> Clone https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode.git, copy the hook scripts from adapters/claude-code/ to .claude/hooks/, copy adapters/shared/ next to them, make them executable, and add the pre_tool_use and post_tool_use hook entries to claude.json.

{
"hooks": {
"pre_tool_use": {
"matcher": "*",
"command": "bash .claude/hooks/pre_tool_use.sh"
},
"post_tool_use": {
"matcher": "*",
"command": "bash .claude/hooks/post_tool_use.sh"
}
}
}

DeepSeek Harness

Copy the hook plus the shared detectors it reads, then register it with one of
the bridge plugins the harness ships (@deepseek-ai/dsh-hooks-claude-code or
@deepseek-ai/dsh-hooks-codex):

mkdir -p ~/.dsh/tool-repair
cp -r adapters/deepseek-harness adapters/shared ~/.dsh/tool-repair/
chmod +x ~/.dsh/tool-repair/deepseek-harness/pre_tool_use.sh

Write ~/.dsh/tool-repair/hooks.json:

{
"hooks": {
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{ "type": "command", "command": "bash ~/.dsh/tool-repair/deepseek-harness/pre_tool_use.sh" }
]
}
]
}
}

And add the bridge to ~/.dsh/cordis.patch.yml:

- id: hooks-claude-code
name: '@deepseek-ai/dsh-hooks-claude-code'
config:
configPath: ~/.dsh/tool-repair/hooks.json

Or prompt your agent:

> Clone https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode,
> copy adapters/deepseek-harness/ and adapters/shared/ into
> ~/.dsh/tool-repair/ keeping the layout, make
> ~/.dsh/tool-repair/deepseek-harness/pre_tool_use.sh executable, write a hooks.json
> registering it as a PreToolUse command hook, and add a
> @deepseek-ai/dsh-hooks-claude-code entry pointing at it in
> ~/.dsh/cordis.patch.yml.

Note which bridge you are running. The Claude Code bridge forwards the whole
arguments object, so every field is inspected. The Codex bridge forwards
tool_input: {command: commandOf(exec.arguments)} — one string — so only
command-shaped defects are detected there and the hook says so on stderr
every time. See adapters/deepseek-harness/README.md for the Codex bridge
variant, the verification steps, and the limitations.

Clone the repo

git clone https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode.git
cd tool-repair-skill-for-hermes-and-opencode

Usage

From any Python project

import json
from tool_repair import repair_function_args

def dispatch_tool(name, args_json):
args = json.loads(args_json)
if isinstance(args, dict):
fixed_args, notes = repair_function_args(name, args)
if notes:
print(f"Repaired {name}: {notes}")
args_json = json.dumps(fixed_args)
# proceed with the tool call

In Hermes Agent

Two calls, in sanitize_tool_call_arguments and make_tool_result_message, as
shown in Components. There is no config key for this; it is harness code.

Roadmap

• [x] Core repair library (5 repair rules)
• [x] Hermes integration (two calls: repair_function_args pre-dispatch, deduplicate_repair_notes on the result)
• [x] OpenCode adapter (TypeScript plugin)
• [x] Claude Code adapter (bash + jq hooks)
• [x] DeepSeek Harness adapter (bash + jq hook via a bridge plugin)
• [x] Schema-aware repairs (array fields, and required/nullable null safety)
• [ ] Per-model repair telemetry (dashboard tab)
• [ ] Model-specific repair profiles (DeepSeek, GLM, Kimi quirks)

License

MIT. Free to use, modify, and distribute. This is a direct implementation of patterns discovered by the CommandCode team. Credit for the original insight goes to them.