Summary
In published version 0.1.0, a command hook configured with onFailure: "block" permits a tool call when the hook prints valid JSON and exits with a nonzero status other than 2. A guard intended to block after a failure can therefore allow the protected action.
Environment
- Plugin:
@hamzaabili/[email protected]
- Actual-host reproduction: unmodified OpenCode V1 1.19.5 and V2 2.2.5
- OS: macOS, Apple Silicon; command executed through the plugin's POSIX shell path
- Runtime-level reproduction: Bun 1.4.3
- Source: trusted fixture project settings; no production configuration or credentials involved
Minimal configuration
Register this hook in a disposable fixture project and explicitly trust that fixture through the plugin's normal trust configuration:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "printf '%s' '{}'; exit 9",
"onFailure": "block"
}
]
}
]
}
}
Attempt a harmless shell tool call, such as writing a marker inside the disposable fixture directory. The tool executes on both tested hosts. The hook runs, exits 9, and its trace records status: "success" with blocked: false.
Control: change only the hook command to exit 9, keeping onFailure: "block". The same tool call is blocked on both hosts, with status: "error" and blocked: true.
Deterministic parser/decision reproduction
From a source checkout, the following script can be placed in a scratch file at the repository root and run with Bun. It does not execute a command or contact a model:
import { parseCommandOutput, mergeDecisions } from './src/output.ts'
const parsed = parseCommandOutput({
exitCode: 9,
stdout: '{}',
stderr: '',
timedOut: false,
truncated: false,
stdoutTruncated: false,
stderrTruncated: false,
})
const decision = mergeDecisions('PreToolUse', [{
sourceID: 'fixture',
sourceLabel: 'fixture',
event: 'PreToolUse',
status: parsed.status,
output: parsed.output,
message: parsed.message,
onFailure: 'block',
}])
console.log({ status: parsed.status, blocked: decision.blocked })
// Actual: { status: 'success', blocked: false }
// Expected: blocked is true because the selected failure policy applies
Expected behavior
For a hook with onFailure: "block", a command exit status other than 0 or 2 must count as a failure even when stdout contains valid JSON. Claude's documented failure policy explicitly covers JSON that would otherwise allow an action: Block the action when a hook fails.
Ordinary nonzero-exit JSON handling without onFailure: "block" can retain its separate native behavior; the regression concerns overriding an explicitly blocking failure policy.
Relevant code and regression coverage
parseCommandOutput classifies valid JSON as success before the failure policy is considered. mergeDecisions applies onFailure only to error/timeout statuses. See output parser and decision merger.
Useful regression cases are nonzero exit plus {}, nonzero exit plus an allow decision, nonzero exit with empty stdout, and exit 0 with an allow decision. The first cases should block only where the configured failure policy requires it.
Doctor and scope of verification
The runtime-only reproduction bypasses discovery and does not require doctor output. The separate actual-host reproductions verified that the trusted PreToolUse command executed and that the protected tool's marker was present in the JSON case and absent in the empty-output control. This report claims behavior on the named versions and does not claim a trust-store bypass or a hook sandbox escape.
Remediation
Fixed in 0.1.1. The command exit code is now carried into decision merging, so onFailure: "block" fails closed for any exit status other than 0 or 2, even when the hook prints valid JSON. Exit 0, exit 2, timeout/error, and the non-blocking JSON path are unchanged. Regression tests cover the JSON bypass, the exit-2 boundary, and the control path.
Release: https://github.com/Hamza-Abili/opencode-claude-hooks/releases/tag/v0.1.1
Credit: @j-256
Summary
In published version 0.1.0, a command hook configured with
onFailure: "block"permits a tool call when the hook prints valid JSON and exits with a nonzero status other than 2. A guard intended to block after a failure can therefore allow the protected action.Environment
@hamzaabili/[email protected]Minimal configuration
Register this hook in a disposable fixture project and explicitly trust that fixture through the plugin's normal trust configuration:
{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "printf '%s' '{}'; exit 9", "onFailure": "block" } ] } ] } }Attempt a harmless shell tool call, such as writing a marker inside the disposable fixture directory. The tool executes on both tested hosts. The hook runs, exits 9, and its trace records
status: "success"withblocked: false.Control: change only the hook command to
exit 9, keepingonFailure: "block". The same tool call is blocked on both hosts, withstatus: "error"andblocked: true.Deterministic parser/decision reproduction
From a source checkout, the following script can be placed in a scratch file at the repository root and run with Bun. It does not execute a command or contact a model:
Expected behavior
For a hook with
onFailure: "block", a command exit status other than 0 or 2 must count as a failure even when stdout contains valid JSON. Claude's documented failure policy explicitly covers JSON that would otherwise allow an action: Block the action when a hook fails.Ordinary nonzero-exit JSON handling without
onFailure: "block"can retain its separate native behavior; the regression concerns overriding an explicitly blocking failure policy.Relevant code and regression coverage
parseCommandOutputclassifies valid JSON as success before the failure policy is considered.mergeDecisionsappliesonFailureonly to error/timeout statuses. See output parser and decision merger.Useful regression cases are nonzero exit plus
{}, nonzero exit plus an allow decision, nonzero exit with empty stdout, and exit 0 with an allow decision. The first cases should block only where the configured failure policy requires it.Doctor and scope of verification
The runtime-only reproduction bypasses discovery and does not require doctor output. The separate actual-host reproductions verified that the trusted PreToolUse command executed and that the protected tool's marker was present in the JSON case and absent in the empty-output control. This report claims behavior on the named versions and does not claim a trust-store bypass or a hook sandbox escape.
Remediation
Fixed in
0.1.1. The command exit code is now carried into decision merging, soonFailure: "block"fails closed for any exit status other than 0 or 2, even when the hook prints valid JSON. Exit 0, exit 2, timeout/error, and the non-blocking JSON path are unchanged. Regression tests cover the JSON bypass, the exit-2 boundary, and the control path.Release: https://github.com/Hamza-Abili/opencode-claude-hooks/releases/tag/v0.1.1
Credit: @j-256