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:

Adapter	Language	Repair strategy
Hermes (two calls)	Python	Mutate args pre-dispatch, then append repair notes to the result. Built and tested against this library's own 34-test Python suite and 21-test TypeScript parity suite.
OpenCode (plugin)	TypeScript	tool.execute.before hook, mutates args directly
Claude Code (hooks)	Bash + jq	PreToolUse block so the model retries, PostToolUse telemetry. Cannot mutate arguments: PreToolUse can only allow or block, so this adapter corrects by feedback, not in place.
DeepSeek Harness (hook bridge)	Bash + jq	PreToolUse command hook registered with a harness bridge plugin. Also cannot mutate arguments: the seam allows deny, not rewrite.

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

Pattern	What the model sends	What it should be
Null omission	{"cmd": "ls", "timeout": null}	{"cmd": "ls"}
Null preserved	{"name": null} where name is required	unchanged, so the validator reports it
Stringified array	{"files": "[\"a\",\"b\"]"}	{"files": ["a", "b"]}
Empty object	{"files": {}}	{"files": []}
Bare string	{"files": "main.ts"}	{"files": ["main.ts"]}
Markdown autolink	{"filePath": "/x/[f.md](http://f.md)"}	{"filePath": "/x/f.md"}

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 Repairs<br/>in Priority Order"]
        R --> RV{"Re-validate"}
        RV -->|"Pass"| D
        RV -->|"Fail"| E["Return Readable Error<br/>with Guidance"]
    end

    M["Model Output<br/>(raw tool call JSON)"] --> P
    D --> N["Tool Result<br/>+ 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.

Adapter	Location	Key mechanism
Hermes	SKILL.md	sanitize_tool_call_arguments pre-dispatch + repair notes.
OpenCode	adapters/opencode/	tool.execute.before TS plugin, mutates args directly
Claude Code	adapters/claude-code/	PreToolUse block + PostToolUse telemetry (bash + jq)
DeepSeek Harness	adapters/deepseek-harness/	PreToolUse command hook via a harness bridge plugin (bash + jq)

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 rather than a shared one.

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).
• 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.

Adapter	Dependencies
Hermes	Hermes Agent (any recent version), stdlib only for the library
OpenCode	TypeScript, OpenCode CLI
Claude Code	bash, jq
DeepSeek Harness	@deepseek-ai/dsh, bash, jq

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 configure in claude.json:

cp adapters/claude-code/*.sh .claude/hooks/
chmod +x .claude/hooks/*.sh

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/, 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, 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 adapters/deepseek-harness/pre_tool_use.sh ~/.dsh/tool-repair/pre_tool_use.sh
chmod +x ~/.dsh/tool-repair/pre_tool_use.sh

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

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "bash ~/.dsh/tool-repair/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/pre_tool_use.sh to ~/.dsh/tool-repair/pre_tool_use.sh, make it 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.

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

• Core repair library (5 repair rules)
• Hermes integration (two calls: repair_function_args pre-dispatch, deduplicate_repair_notes on the result)
• OpenCode adapter (TypeScript plugin)
• Claude Code adapter (bash + jq hooks)
• DeepSeek Harness adapter (bash + jq hook via a bridge plugin)
• 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.