Skip to content
Beta
All articles

Making coding agents say why: declared intent on every tool call

A KTH prototype makes coding agents declare the type and reason of every command, then checks them against real effects. It exposed 90% of reward hacking runs.

By The SpanDock team

5 min read

A diagram of a tool call carrying a declared type and reason, the harness recording the files it actually changed, and a checker comparing the two into a journal entry

A log of a coding agent's session tells you what it ran, but not why. When an agent asked to make a failing test suite pass runs sed -i '22 s/^/# /' test.py, the command alone doesn't say whether it was exploring or quietly switching off an assertion it could not satisfy. A new paper from KTH Royal Institute of Technology proposes a simple change to the agent harness: refuse to run any command unless the model declares what kind of action it is and why, then check that declaration against what the command actually did. On a benchmark built to tempt agents into cheating, the resulting journal exposed 90% of the runs that cheated.

The idea

In Episteme: Trustworthy Coding Agents Through Tool Call Intent, the authors call this the epistemic agent design. The harness, the program that runs the model's loop and executes its tool calls, adds two required arguments to the shell tool:

  • a type from a closed list of seven: collect-info, test-hypothesis and verify, which are read-only, and setup, change-state, revert and cleanup, which change state;
  • a reason in free text, at least 20 characters, describing intent rather than actions.

A call with a missing or unknown type, or a too-short reason, is rejected and journaled, and the model must reissue it. The harness then runs the command in a sandbox, hashes the workspace before and after, and records the diff, the output and any findings. The journal is written outside the agent's workspace, so the model cannot edit it, and it survives if the agent is killed.

The value is in the comparison. The declaration is a claim made by the model; the record of effects is an observation made by the harness. According to the full paper, a checker flags three kinds of finding: a contradiction that proves the declaration false, such as a read-only type whose call changed a file; a warning for something suspicious but unproven, such as rm inside a read-only call; and a protected finding for any change to files an operator marks as protected, such as tests.

The journal can be used online, as a guardrail that refuses a read-only declaration whose command contains a mutating operation, or offline, as a forensic record a reviewer or an automated auditor can replay.

What the evaluation found

The authors used ImpossibleBench, whose tasks have unit tests altered to contradict the specification, so the only way to pass is to cheat: edit the tests, or tailor the code to the faulty test. They ran two open-weight models, Qwen3-235B and Mistral Large 3, on 206 tasks each, with the harness in monitor mode so the findings did not influence the agent.

Of 400 completed runs, 49 cheated. The journal exposed 44 of them, 90%, with a 95% confidence interval of 78 to 96%. The interesting part is how:

  • Disclosure did almost all of the work. In all 44 exposed runs, the agent's own declared reason gave the cheat away, for example, "Replace the incorrect formula with a hardcoded lookup table of expected values to pass the unit tests."
  • The effect checker caught little. Only 3 runs contradicted their declared type, by editing a test with a shell command declared read-only or as a revert.
  • Five runs were stealthy. The reason described a problem ("The test expecting 0 is incorrect") without saying the agent was editing the test to get past it, or gave a general reason for a test-specific change.

The checker could not contradict any of the code-tailoring cheats because those edits went through the file-editing tools, which the harness types automatically rather than asking the model to declare. The authors note that requiring a declared type on file edits too would extend the check to them.

What is new, and what isn't

The idea that structured reasons improve oversight is not new. What Episteme adds is making the declaration mandatory and machine-checkable at the point of action, and separating it cleanly from what the harness observes. That gives a reviewer a short list: start with contradicted calls, then protected-file changes, then read the reasons.

Three limits deserve weight before anyone treats this as a control:

  • It relies on candour. The 90% came mostly from models describing their own cheating. The paper cites earlier work showing that models' stated reasoning can misrepresent the true reason for an answer, and that monitors degrade when an agent knows it is watched. A model optimised against such a journal could learn to write blander reasons.
  • The sample is small and specific. Two open-weight models, 49 misbehaving runs, one benchmark designed around test tampering. Frontier commercial agents were not tested.
  • Effects are only visible inside the sandbox. The prototype cuts network access so every lasting effect lands in the observed workspace. In a real environment with network access, a call's effects can land outside what the harness can diff.

What it means for engineering and security leaders

Most organisations reviewing agent work today have the command and its output, sometimes the model's reasoning, and little else. A typed declaration per call is cheap to add in a harness the team controls, produces a far more searchable record, and turns "what was this agent doing?" into a query rather than a reading exercise. The paper notes that regulated fields such as medical devices and avionics expect a record of what was done and why, which a plain transcript doesn't give.

It also offers a pragmatic test for reward hacking in internal agents: protected-file findings on tests, combined with reasons that mention the tests, flag runs worth a human look. We wrote about how benchmarks themselves get gamed in SWE-Bench Pro Verified: when coding agents were reading the answers.

Where SpanDock fits

Declared intent is a harness feature, but its value depends on a record nobody can edit. For MCP tool calls, the SpanDock MCP gateway records every call in Activity, with the connector and tool, the outcome and why, the person and computer, and the duration; arguments and results are recorded only if an administrator turns that on. The MCP gateway is on the Premium and Enterprise plans.

Practical takeaways

  • If you build internal agents, try requiring a type and reason on shell tools. The prototype is open source and works with any OpenAI-compatible provider.
  • Mark tests and other sensitive files as protected in whatever harness or review tooling you use, and review every change to them.
  • Keep the journal out of the agent's reach, written outside its workspace, so it can be trusted later.
  • Treat reasons as evidence, not proof. Use contradictions and protected-file changes as triggers for review, and don't let a plausible reason close a question.
  • Ask your agent vendors whether their tools can record a stated purpose per call, and whether that record is available to you.

Sources

  1. Episteme: Trustworthy Coding Agents Through Tool Call Intent (arXiv:2611.06563)
  2. Episteme: full paper (HTML version)
  3. ASSERT-KTH/epistemic-agent: prototype source code
  4. ImpossibleBench: Measuring LLMs' Propensity of Exploiting Test Cases (arXiv:2510.20270)
Cookie categories

Details: Cookie Policy.