Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## 0.1.1 (Unreleased)

- Let a Stop hook with `continue: false` finish the turn. `decision: "block"` still asks OpenClaw to revise, and `continue: false` outranks a block on the same hook. Thanks @SebTardif.
- Pass an empty string when an MCP command tool is called without `args`, matching `babelfish_task_start`. Thanks @SebTardif.
- Refresh the MCP SDK to 1.31.0, Vitest to 5.0.2, Node typings, transitive dependencies, and pinned CodeQL actions to 4.38.2 while retaining Node.js 22.19 support; clear two dependency audit advisories.
- Bound MCP tool inspection to 50 pages and one pagination deadline, rejecting repeated cursors while preserving finite listings. Thanks @SebTardif.
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ Installing an already installed name requires `--force`; a rejected duplicate le
| Prompt and terminal commands | User-invoked skills or top-level CLI commands when the source format supports them. Hermes MCP command tools accept optional `args`: omitted arguments, `{}`, or an empty `args` string pass `""`; explicit text is preserved. |
| Compatible hooks | Matching lifecycle, prompt, tool, compaction, and subagent hooks. Discovery permits 50 unique hook files and eight nested directories. Command-hook stdin is capped at 1 MiB; oversized decision events fail closed. String commands use a login shell; `args` or a `command` array spawn without a shell. |
| Compatible middleware | Matching prompt-build and tool-result middleware |
| Stop hook decisions | On upgrade, installed Claude Code and Codex Stop hooks with `continue: false` finish the turn rather than request revision. This takes precedence over a block on the same hook only; a separate blocking hook still requests revision in either order. Pre-tool and prompt blocking is unchanged. |
| Unsupported behavior | Recorded during generation and reported at Gateway startup |

Support differs by source app and surface. See the [compatibility reference](docs/compatibility.md) for the full matrix, source-specific behavior, configuration, and example plugins.
Expand Down
8 changes: 7 additions & 1 deletion docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Bundle paths must stay inside the plugin root, including after resolving skill-r
| Session start hooks | Full | Full | Full | Additional context is injected into the next agent turn |
| Session end hooks | Full | Full | Full | Codex hooks must be declared by its supported manifest or conventional path |
| User-prompt hooks | Partial | Partial | Partial | Additional context maps; prompt replacement and hard stop do not |
| Stop/finalization hooks | Full | Full | Full | Hermes finalization is observer-only; Codex and Claude continue/block decisions map directly |
| Stop/finalization hooks | Full | Full | Full | Hermes finalization is observer-only. Codex and Claude `decision: "block"` asks OpenClaw to revise. `continue: false` allows finalization and outranks a block on the same hook. |
| Pre/post compaction hooks | N/A | Full | Full | Observation hooks run around OpenClaw compaction |
| Subagent lifecycle hooks | Full | Full | Full | Mapped to OpenClaw subagent start/end hooks |
| Prompt or agent hook handlers | N/A | No | Partial | Claude prompt handlers use the active OpenClaw model; Codex prompt handlers and multi-turn agent handlers remain listed only |
Expand All @@ -45,6 +45,12 @@ Bundle paths must stay inside the plugin root, including after resolving skill-r

## Claude Code

For installed Claude Code and Codex Stop hooks, upgrading changes
`continue: false` from requesting revision to finishing the turn. Precedence is
per hook: a separate hook's block still requests revision in either order.
Exit-2 and oversized-input Stop decisions also still request revision.
Pre-tool and prompt hooks continue to treat `continue: false` as blocking.

Babelfish reads `.claude-plugin/plugin.json`, declared or conventional skill, command, agent, output-style, hook, and MCP paths. Existing `SKILL.md` directories are copied intact. Markdown commands, agents, and output styles are converted to user-invoked OpenClaw skills.

Command hooks run with `${CLAUDE_PLUGIN_ROOT}` set to the installed plugin directory. String `command` handlers run through a login shell. When `args` is set (Claude Code exec form), or when `command` is a string array, Babelfish spawns the executable directly without a shell. Single-turn `prompt` handlers use the active OpenClaw agent and model when `plugins.entries.babelfish.llm` allows both agent and model overrides. Without those trust flags they are reported but not executed. Multi-turn `agent` handlers are unsupported.
Expand Down
3 changes: 3 additions & 0 deletions src/bundle-plugins.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -274,6 +274,9 @@ describe("bundle plugins", () => {

it("normalizes hook decisions", () => {
expect(hookBlock({ decision: "block", reason: "no" })).toEqual({ block: true, reason: "no" });
expect(hookBlock({ continue: false, stopReason: "halt" })).toEqual({ block: true, reason: "halt" });
expect(hookBlock({ continue: false, stopReason: "halt", decision: "block", reason: "revise" }))
.toEqual({ block: true, reason: "halt" });
expect(hookUpdatedInput({ hookSpecificOutput: { updatedInput: { value: 2 } } })).toEqual({ value: 2 });
});

Expand Down
115 changes: 115 additions & 0 deletions src/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -288,3 +288,118 @@
}
}, 30_000); // Covers cold Python and multiple Windows supervisor launches.
});

describe("Stop hook finalization", () => {
async function finalize(
decision: Record<string, unknown> | Record<string, unknown>[],
options: { event?: Record<string, unknown>; hookEvent?: string; exitCode?: number } = {},
) {
const installDir = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-stop-hermes-"));
const bundleRoot = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-stop-root-"));
const previous = process.env.OPENCLAW_BABELFISH_HERMES_PLUGIN_DIR;
const previousRoot = process.env.OPENCLAW_BABELFISH_ROOT;
const pluginRoot = path.join(bundleRoot, "codex", "stop-hooks");
await fs.mkdir(path.join(pluginRoot, ".codex-plugin"), { recursive: true });
const decisions = Array.isArray(decision) ? decision : [decision];
for (const [index, result] of decisions.entries()) {
await fs.writeFile(
path.join(pluginRoot, `hook-${index}.mjs`),
`process.stdin.resume(); process.stdin.on("end", () => { console.log(${JSON.stringify(JSON.stringify(result))}); process.exitCode = ${options.exitCode ?? 0}; });`,
);
}
await fs.writeFile(
path.join(pluginRoot, ".codex-plugin", "plugin.json"),
JSON.stringify({
hooks: { [options.hookEvent ?? "Stop"]: [{ hooks: decisions.map((_, index) => ({
type: "command",
command: [process.execPath, `hook-${index}.mjs`],
})) }] },
}),
);
process.env.OPENCLAW_BABELFISH_HERMES_PLUGIN_DIR = installDir;
process.env.OPENCLAW_BABELFISH_ROOT = bundleRoot;
try {
vi.resetModules();
const module = await import("./index.js");
const hooks = new Map<string, (event: unknown, ctx: unknown) => unknown>();
module.default.register({
on: (name: string, handler: (event: unknown, ctx: unknown) => unknown) => {
hooks.set(name, handler);
},
registerTool: () => undefined,
registerCommand: () => undefined,
registerCli: () => undefined,
registerAgentToolResultMiddleware: () => undefined,
logger: { warn: () => undefined },
});
const handler = options.hookEvent === "PreToolUse" ? "before_tool_call"
: options.hookEvent === "UserPromptSubmit" ? "before_agent_run"
: "before_agent_finalize";
return await hooks.get(handler)?.(options.event ?? {}, {});
} finally {
if (previous === undefined) delete process.env.OPENCLAW_BABELFISH_HERMES_PLUGIN_DIR;
else process.env.OPENCLAW_BABELFISH_HERMES_PLUGIN_DIR = previous;
if (previousRoot === undefined) delete process.env.OPENCLAW_BABELFISH_ROOT;
else process.env.OPENCLAW_BABELFISH_ROOT = previousRoot;
await fs.rm(installDir, { recursive: true, force: true });
await fs.rm(bundleRoot, { recursive: true, force: true });
}
}

it("finalizes when a Stop hook sets continue false", async () => {
await expect(finalize({ continue: false, stopReason: "finished" })).resolves.toBeUndefined();
});

it("revises when a Stop hook sets decision block", async () => {
await expect(finalize({ decision: "block", reason: "tests failed" })).resolves.toEqual({
action: "revise",
reason: "tests failed",
retry: { instruction: "tests failed" },
});
});

it("lets continue false outrank a Stop block on the same hook", async () => {
await expect(finalize({
continue: false,
decision: "block",
reason: "keep going",
stopReason: "halt",
})).resolves.toBeUndefined();
});

it.each([false, true])("retains a separate Stop block (block first: %s)", async (blockFirst) => {
const decisions = [
{ continue: false, stopReason: "finished" },
{ decision: "block", reason: "separate guard" },
];
await expect(finalize(blockFirst ? decisions.reverse() : decisions)).resolves.toEqual({
action: "revise",
reason: "separate guard",
retry: { instruction: "separate guard" },
});
});

it("retains revision for exit-2 Stop hooks", async () => {
await expect(finalize({ continue: false }, { exitCode: 2 })).resolves.toMatchObject({
action: "revise",
reason: expect.stringContaining("Stop hook"),
});
});

it("retains revision for oversized Stop input", async () => {
await expect(finalize({ continue: false }, {
event: { text: "x".repeat(1024 * 1024) },
})).resolves.toMatchObject({
action: "revise",
reason: expect.stringContaining("1048576-byte payload limit"),
});
});

it.each(["PreToolUse", "UserPromptSubmit"])("still blocks %s for continue false", async (hookEvent) => {
await expect(finalize({ continue: false, stopReason: "halt" }, { hookEvent })).resolves.toEqual(
hookEvent === "PreToolUse"
? { block: true, blockReason: "halt" }
: { outcome: "block", reason: "halt", message: "halt" },
);
});
});
10 changes: 7 additions & 3 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -617,9 +617,13 @@ function registerRunHooks(api: OpenClawApi): void {
});
api.on("before_agent_finalize", async (event, ctx) => {
const imported = await bundleHooks("Stop", event, ctx);
const block = imported.map(hookBlock).find((decision) => decision.block);
return block
? { action: "revise", reason: block.reason, retry: { instruction: block.reason ?? "Continue." } }
// Claude Code: continue false stops the turn and outranks a Stop decision.
const revise = imported
.filter((result) => result.continue !== false)
.map(hookBlock)
.find((decision) => decision.block);
return revise
? { action: "revise", reason: revise.reason, retry: { instruction: revise.reason ?? "Continue." } }
: undefined;
});
api.on("before_compaction", async (event, ctx) => {
Expand Down
Loading