tool-feedback-protocol

Tool Feedback Protocol

This project is harnez-tracked (issues/ present). Rate a tool call — Read, Edit, Bash, Grep, whatever just ran — only when:

• it failed (non-zero exit, error result, exception), or
• it succeeded but didn't produce the expected outcome (a fix that didn't fix, a search that missed the target, a build that passed but the feature still didn't work).

Routine successful calls (a Read that returned the right file, a Grep that found the match) don't need a rating — this is the signal-carrying subset, not every call.

harnez rate <tool_name> <1-5> "<1-line outcome summary>" "<project_folder>/<ticket_name>"

Example:

harnez rate Grep 1 "search missed the target function, wrong file" harnez/117-harnez-rate-command

Score 5 = flawless, 3 = partial success / required adjustment, 1 = total failure / useless output.

Silence is otherwise ambiguous — it could mean "all fine" or "forgot the protocol." If a harnez tip nudges you after a long quiet stretch and nothing has failed, confirm with a lean heartbeat instead of staying silent or inventing a fake per-tool score:

harnez rate --ok

No tool name, score, or ticket required; it records a distinct, lightweight confirmation, kept out of failure-rate metrics. Don't call it proactively on a fixed schedule — only in response to the tip, so this stays rare.

Some commands are expected to fail — probing whether a server is down, deliberately reproducing a bug, a negative-case test. Don't launder a real failure into "expected" after the fact; declare the intent on the command itself, at call time (issue 226):

• Cheapest, for any shell command: make the wrapping call's own exit code 0, e.g. curl -sf http://maybe-down-host/health || echo "expected failure: exit=$?". harnez exec (the invisible Bash PreToolUse rewrite) records the wrapping command's exit code, so it never enters FailureCount/UnratedFailureCount to begin with — nothing else to do, and no harnez rate call needed either.
• If you need the command's real exit code preserved and returned (e.g. your own $?-dependent logic downstream needs it), prefix instead: HARNEZ_EXPECT_FAILURE=1 curl -sf http://maybe-down-host/health. harnez exec detects the marker and records the row's call_type as an expected failure — the true exit code is still returned to you and stored in telemetry, only the failure-signal classification changes.

Commands run through harnez exec have a 60s default timeout. Set intent on the command when it needs a different bound: HTO=0 <command> removes the limit, and HTO=10m <command> sets one. The longer HARNEZ_TIMEOUT name also works. Use it at the start of compound and piped bash -c commands as well. Timeout precedence is explicit prefix, the Bash tool's native timeout/background setting, repo exec.timeout, then 60s. A timeout message shows the HTO=0 opt-out.

Why this, and why now (not at session end): the score is a judgment only the acting agent can make in the moment — a mechanized PostToolUse hook can log that a call happened, but not whether it helped. Rating right after the call, while the outcome is still fresh, is what makes the signal trustworthy; batching ratings from memory at the end of a session produces noise. This is the same "exercised as a literal template every time" mechanism that makes the git-commit-trailer convention reliably followed — a standing policy statement without a concrete trigger and worked example gets skipped.

If this project has no issues/ tracker, this protocol doesn't apply — skip it rather than inventing a ticket path.