Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

fix: quiet one-line Stop reminder via Claude Code feedback channel (v1.58.2) (#202)

Serg Eroshef6212cd247d0
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index c63fc9b2..ba48a904 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.58.1",
+ "version": "1.58.2",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index a23e0493..967e1791 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.58.1",
+ "version": "1.58.2",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 714a7d7d..750ac39b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.58.2] - 2026-09-26
+
+A quieter end-of-turn reminder in Claude Code.
+
+When a turn changed files but recorded no brain event, the Stop guardrail continued the turn with `decision: "block"`. Claude Code renders that as a red "Stop hook error" and prints the whole reason, about 25 lines, in the user's transcript on every guarded turn.
+
+### Changed
+
+- **The Stop guardrail uses Claude Code's non-error feedback channel and one line of text.** In Claude Code the hook now returns `hookSpecificOutput.additionalContext` for the Stop event (supported since Claude Code 2.1.163), which continues the turn as "Stop hook feedback" instead of a hook error. Codex documents only `decision: "block"` for Stop, where the reason becomes the continuation prompt, so Codex, Grok Build and unrecognised runtimes keep that shape. In every runtime the text is now a single line (`STOP_GUARDRAIL_TEXT`): "Open Second Brain: this turn changed files but recorded no brain event. Call brain_feedback, brain_apply_evidence or brain_note if one fits (brain-memory skill); otherwise just finish." The guardrail still fires at most once per turn through `stop_hook_active`, and the per-runtime cadence lines are gone. The opencode plugin has no Stop guardrail and is unchanged.
+- **The `brain-memory` skill has an "End-of-turn check" section** with the decision the one-line reminder asks for, which the Stop reason used to spell out. The Codex plugin copy is regenerated.
+- **Claude Code is recognised on Stop when its transcripts live outside `~/.claude`** (a custom `CLAUDE_CONFIG_DIR`): a Stop payload with `stop_hook_active` and `last_assistant_message` but no Codex `turn_id` resolves to Claude Code, so such installs get the feedback channel too.
+- **The `brain-memory` skill documents `result: outdated`** for `brain_apply_evidence`, next to `applied` and `violated`.
+
## [1.58.1] - 2026-09-26
Session capture off the hook path, and registry scanner hygiene.
@@ -7716,6 +7729,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[1.58.2]: https://github.com/itechmeat/open-second-brain/compare/v1.58.1...v1.58.2
[1.58.1]: https://github.com/itechmeat/open-second-brain/compare/v1.58.0...v1.58.1
[1.58.0]: https://github.com/itechmeat/open-second-brain/compare/v1.57.1...v1.58.0
[1.57.1]: https://github.com/itechmeat/open-second-brain/compare/v1.57.0...v1.57.1
diff --git a/hooks/README.md b/hooks/README.md
index c4752249..a5df92ea 100644
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -25,7 +25,7 @@ hook payload shape, not on the runtime.
| `PostToolUse` | `brain_feedback` | Replays successful `brain_feedback` tool input immediately through the same signal/dedup boundary. |
| `PostToolUse` | `Write\|Edit\|MultiEdit\|apply_patch` | Emits `additionalContext` pointing at the three Brain writer tools. The full reminder is shown once per Claude Code session; later writes get a one-line nudge (Codex one-shot runs always get the full text). |
| `PostCompact` | `manual\|auto` | Records a post-compact lifecycle observation only. Current Claude Code has no PostCompact hook event and rejects `additionalContext` under that name - re-injection moved to the SessionStart `compact` matcher; the registration stays as a silent no-op for older runtimes. |
-| `Stop` | (every Stop) | If the turn produced a durable artifact and none of `brain_feedback` / `brain_apply_evidence` / `brain_note` landed, returns `decision: "block"` once, then lets the second Stop pass. |
+| `Stop` | (every Stop) | If the turn produced a durable artifact and none of `brain_feedback` / `brain_apply_evidence` / `brain_note` landed, continues the turn once with a one-line reminder, then lets the second Stop pass. Claude Code gets `hookSpecificOutput.additionalContext` (shown as "Stop hook feedback", not a hook error); Codex, Grok Build and unrecognised runtimes get `decision: "block"` with the same line as `reason`. |
| `SubagentStop` | `*` | Records a non-blocking lifecycle observation for a delegated sub-agent's close, attributed to `<delegator>-sub-<agent-id>` from the `agent_id` the event carries. The sibling `agent_transcript_path` is deliberately not persisted - it is a machine-local host path, and the sub-agent's turns reach memory through `o2b brain import-session`, which reads `isSidechain` and `agentId` off the transcript itself. |
| `SessionEnd` | `*` | Records a non-blocking lifecycle observation for session close. |
@@ -34,6 +34,16 @@ flag: it fires at most once per turn, so the agent can deliberately
decide that an edit was trivial and skip logging by just finishing
again. No deadlocks.
+The reminder is one line on purpose (`STOP_GUARDRAIL_TEXT` in
+`lib/messages.ts`): Claude Code prints Stop hook output in the user's
+transcript, and until v1.58.2 a `decision: "block"` reason of about 25
+lines showed up there as a red "Stop hook error" on every guarded turn.
+What to do when it fires is documented for the model in the
+`brain-memory` skill ("End-of-turn check"). Stop hooks cannot use a
+channel that is hidden from the user entirely; the model-only channel is
+the PostToolUse `additionalContext` reminder that already follows each
+write.
+
## JSONL sidecar
Every event the writer lands in `Brain/log/<date>.md` is mirrored to
@@ -191,7 +201,8 @@ codex exec --skip-git-repo-check 'create a tiny /tmp/x/note.md ...'
Expect the stream to show `hook_started` / `hook_response` events
around each Write and around the Stop event; the agent's first reply
-gets `decision: "block"` and it has to either log or send a second
+gets the one-line reminder (Claude Code: Stop `additionalContext`;
+Codex: `decision: "block"`) and it has to either log or send a second
finishing message.
## Unit tests
diff --git a/hooks/lib/detect.ts b/hooks/lib/detect.ts
index 95586484..035743a9 100644
--- a/hooks/lib/detect.ts
+++ b/hooks/lib/detect.ts
@@ -186,9 +186,13 @@ const CODEX_TRANSCRIPT_NEEDLE = "/.codex/sessions/";
* 2. `transcript_path` substring (`/.claude/projects/`, `/.claude/sessions/`).
* 3. `transcript_path` substring (`/.codex/sessions/`).
* 4. Claude Code distinctive triple (`session_id` + `cwd` + `tool_use_id`).
- * 5. Codex apply_patch shape (`tool_name === "apply_patch"` with
+ * 5. Claude Code Stop shape: `hook_event_name === "Stop"` with
+ * `stop_hook_active` and `last_assistant_message` but no `turn_id`
+ * (Codex adds `turn_id` to every Stop payload). Catches a Claude Code
+ * install whose transcripts live outside `~/.claude` (`CLAUDE_CONFIG_DIR`).
+ * 6. Codex apply_patch shape (`tool_name === "apply_patch"` with
* a patch body in `tool_input.input`).
- * 6. `"unknown"`.
+ * 7. `"unknown"`.
*
* `normalizeHookPayload` preserves grok's original camelCase keys, so this
* works whether it runs before or after normalization. Malformed payloads
@@ -228,6 +232,15 @@ export function detectHookRuntime(
return "claudecode";
}
+ if (
+ p["hook_event_name"] === "Stop" &&
+ typeof p["stop_hook_active"] === "boolean" &&
+ "last_assistant_message" in p &&
+ !("turn_id" in p)
+ ) {
+ return "claudecode";
+ }
+
if (p["tool_name"] === "apply_patch") {
const ti = p["tool_input"];
if (ti !== null && typeof ti === "object") {
diff --git a/hooks/lib/messages.ts b/hooks/lib/messages.ts
index 6b9d5fe9..64204c0f 100644
--- a/hooks/lib/messages.ts
+++ b/hooks/lib/messages.ts
@@ -88,47 +88,41 @@ export function postWriteReminder({ toolName, filePath, runtime }: PostWriteRemi
return parts.join("\n");
}
-function stopGuardrailCadenceLine(runtime: HookRuntime): string {
- switch (runtime) {
- case "claudecode":
- return "_This guardrail fires at most once per turn β€” send another reply (with or without a brain-event call) to clear it._";
- case "codex":
- return "_This `codex exec` is about to end β€” call `brain_feedback` / `brain_apply_evidence` / `brain_note` now or finish silently; no further guardrail will fire._";
- case "grok":
- return "_This guardrail fires at most once per turn β€” send another reply (with or without a brain-event call) to clear it._";
- case "unknown":
- return "";
- }
-}
+/**
+ * End-of-turn guardrail text (v1.58.2). One line on purpose: Claude Code
+ * renders it in the user's transcript and Codex turns it into a
+ * continuation prompt, so every extra line is noise the operator reads
+ * on each guarded turn. The full contract lives in the `brain-memory`
+ * skill ("End-of-turn check") and in the PostToolUse reminder the model
+ * already received after the write.
+ */
+export const STOP_GUARDRAIL_TEXT =
+ "Open Second Brain: this turn changed files but recorded no brain event. " +
+ "Call brain_feedback, brain_apply_evidence or brain_note if one fits " +
+ "(brain-memory skill); otherwise just finish.";
-export function stopGuardrailReason(runtime: HookRuntime = "unknown"): string {
- const cadence = stopGuardrailCadenceLine(runtime);
- const parts: string[] = [
- "Open Second Brain hook: this turn touched files",
- "(Write / Edit / MultiEdit / apply_patch / search_replace) but did not call any of:",
- "",
- "- `brain_feedback` β€” new taste correction the user expressed in this",
- " turn (one signal per file, see the `brain-memory` skill)",
- "- `brain_apply_evidence` β€” evidence trail when an active preference",
- " in `Brain/preferences/` scopes to the artifact you just produced",
- "- `brain_note` β€” one-line narrative milestone (release shipped, PR",
- " merged, fact discovered) that fits neither of the first two",
- "",
- ];
- if (cadence !== "") parts.push(cadence, "");
- parts.push(
- "Pick whichever fits this turn:",
- "- a new rule the user just stated β†’ `brain_feedback`",
- "- an active preference applied, violated, or made obsolete by the",
- " change β†’ `brain_apply_evidence` with",
- " `result: applied | violated | outdated`",
- "- a durable narrative milestone β†’ `brain_note`",
- "",
- "If the change is trivial and not worth recording, just send your",
- "reply again β€” this guardrail fires at most once per turn and the",
- "second Stop passes through silently.",
- );
- return parts.join("\n");
+export type StopGuardrailOutput =
+ | {
+ readonly hookSpecificOutput: {
+ readonly hookEventName: "Stop";
+ readonly additionalContext: string;
+ };
+ }
+ | { readonly decision: "block"; readonly reason: string };
+
+/**
+ * Hook output for the Stop guardrail. Claude Code gets the non-error
+ * `additionalContext` channel; every other runtime gets the portable
+ * `decision: "block"` shape. Both continue the turn once and carry the
+ * same one-line text.
+ */
+export function stopGuardrailOutput(runtime: HookRuntime): StopGuardrailOutput {
+ if (runtime === "claudecode") {
+ return {
+ hookSpecificOutput: { hookEventName: "Stop", additionalContext: STOP_GUARDRAIL_TEXT },
+ };
+ }
+ return { decision: "block", reason: STOP_GUARDRAIL_TEXT };
}
/**
diff --git a/hooks/stop-log-guardrail.ts b/hooks/stop-log-guardrail.ts
index 0865be67..bc6b18e3 100755
--- a/hooks/stop-log-guardrail.ts
+++ b/hooks/stop-log-guardrail.ts
@@ -1,34 +1,36 @@
#!/usr/bin/env -S bun
/**
- * Stop hook: blocks the turn at most once when the agent produced a
+ * Stop hook: nudges the agent at most once per turn when it produced a
* durable-looking artifact (Write / Edit / MultiEdit / apply_patch) but
- * never called `event_log_append`. Lets the agent decide whether to log
- * or finish β€” but forces the decision to be conscious.
+ * recorded no brain event (`brain_feedback` / `brain_apply_evidence` /
+ * `brain_note`). The agent decides whether to record or just finish.
*
- * Decision shape (identical for Claude Code and Codex):
+ * Output channel per runtime (v1.58.2):
*
- * - On the first Stop of a turn (`stop_hook_active === false` and the
- * artifact-without-log condition holds): emit
- * {"decision": "block", "reason": "<text>"}
- * so the runtime continues the agent loop with that reason injected
- * as a developer message. The agent can then either call
- * `event_log_append` or just finish; either way the next Stop sees
- * `stop_hook_active === true` and passes through.
+ * - Claude Code: `hookSpecificOutput.additionalContext` on the Stop
+ * event. Claude Code (2.1.163+) continues the turn with it as
+ * non-error feedback, labelled "Stop hook feedback", instead of the
+ * red "Stop hook error" that `decision: "block"` renders with the
+ * whole reason in the user's transcript.
*
- * - On any Stop where the guardrail already fired
- * (`stop_hook_active === true`): exit 0 silently. No deadlocks.
+ * - Codex, Grok Build and unrecognised runtimes:
+ * {"decision": "block", "reason": "<one line>"}
+ * Codex documents only this shape for Stop (the reason becomes the
+ * continuation prompt), and it is the portable fallback.
*
- * - On any Stop where there was no artifact or a log was made: exit 0
- * silently.
+ * Either way the text is one short line (`STOP_GUARDRAIL_TEXT`); the
+ * details live in the `brain-memory` skill.
*
- * The guardrail never blocks twice in a row by design β€” that matches
- * the user's "agent decides what to log" requirement.
+ * Fires at most once per turn: when the runtime reports
+ * `stop_hook_active === true` (this turn was already continued by a
+ * Stop hook) the hook exits 0 silently. No artifact, or a recorded
+ * brain event, also exits 0 silently. Crashes exit 0 - never deadlock.
*/
import { asHookPayload, readHookInput } from "./lib/stdin.ts";
import { readTranscript } from "./lib/transcript.ts";
import { detectHookRuntime, summarizeTurn } from "./lib/detect.ts";
-import { stopGuardrailReason } from "./lib/messages.ts";
+import { stopGuardrailOutput } from "./lib/messages.ts";
async function main(): Promise<void> {
let payload;
@@ -53,12 +55,7 @@ async function main(): Promise<void> {
const summary = summarizeTurn(signal.toolCalls, signal.bashCommands);
if (!summary.hadArtifact || summary.hadBrainEvent) return;
- const runtime = detectHookRuntime(payload);
- const out = {
- decision: "block",
- reason: stopGuardrailReason(runtime),
- };
- process.stdout.write(JSON.stringify(out) + "\n");
+ process.stdout.write(JSON.stringify(stopGuardrailOutput(detectHookRuntime(payload))) + "\n");
}
main().catch(() => {
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 6cf9c5b9..5ff88fe6 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "1.58.1",
+ "version": "1.58.2",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index 65bf0845..ee6696e8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.58.1",
+ "version": "1.58.2",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index 0deccc3b..ff066323 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.58.1"
+version: "1.58.2"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 3073ca05..7212a71c 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.58.1",
+ "version": "1.58.2",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/codex/skills/brain-memory/SKILL.md b/plugins/codex/skills/brain-memory/SKILL.md
index f366b128..255c23c9 100644
--- a/plugins/codex/skills/brain-memory/SKILL.md
+++ b/plugins/codex/skills/brain-memory/SKILL.md
@@ -54,7 +54,7 @@ Parameters:
- `pref_id`: id of the preference you are recording against (`pref-no-internal-abbrev`).
- `artifact`: wikilink identifying what you produced β€” `[[src/cli/main.ts]]`, `[[docs/release-notes/v0.11.0.md]]`, `[[Brain/preferences/pref-no-internal-abbrev]]`. The wikilink resolves in Obsidian; use `#anchor` to point at a specific section when relevant.
-- `result`: `applied` if the rule held in this artifact, `violated` if you (or another agent) broke it. Recording a `violated` event is not a failure β€” it is what trains the system.
+- `result`: `applied` if the rule held in this artifact, `violated` if you (or another agent) broke it, `outdated` if the artifact shows the rule itself is obsolete (one `outdated` event retires the preference on the next dream pass). Recording a `violated` event is not a failure β€” it is what trains the system.
- `agent`: your runtime identity.
Optional:
@@ -73,6 +73,17 @@ Optional:
When a preference *might* apply but you are unsure, do not skip β€” record the event with `note: "speculative; <reason>"` so the dream pass sees the signal. A one-off speculative entry that does not recur is filtered out by dream; the cost of writing is one MCP call, the cost of missing is a silent gap in the evidence trail. The "do not call" list above is exhaustive on purpose: outside those four bullets, record.
+## End-of-turn check
+
+When a turn changed files (Write / Edit / MultiEdit / apply_patch) and none of `brain_feedback`, `brain_apply_evidence` or `brain_note` was called, the Stop hook continues the turn once with a single line: "Open Second Brain: this turn changed files but recorded no brain event. ..." Claude Code shows it as Stop hook feedback; Codex and other runtimes receive it as a continuation prompt. It is a prompt to decide, not an error:
+
+- a rule the user stated this turn β†’ `brain_feedback`;
+- an active preference in `Brain/preferences/` applied, violated or made obsolete by the change β†’ `brain_apply_evidence` with `result: applied | violated | outdated`;
+- a durable milestone that fits neither (release shipped, PR merged, fact discovered) β†’ `brain_note`;
+- nothing worth recording (the four cases under "When NOT to call") β†’ finish the reply without comment.
+
+It fires at most once per turn: the next stop passes whether or not you record anything. Do not mention the check to the user.
+
## Language
The `principle` and `note` fields must match the **natural language the user has been speaking in this session**. Technical identifiers stay English regardless: `topic` slug, `scope`, `pref_id`, `result`, `agent` name, file paths, library names, error messages quoted from logs. This mirrors the policy from the `agent-event-log` skill.
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 0deccc3b..ff066323 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.58.1"
+version: "1.58.2"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index 167a9a78..5224c5e5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "1.58.1"
+version = "1.58.2"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/skills/brain-memory/SKILL.md b/skills/brain-memory/SKILL.md
index f366b128..255c23c9 100644
--- a/skills/brain-memory/SKILL.md
+++ b/skills/brain-memory/SKILL.md
@@ -54,7 +54,7 @@ Parameters:
- `pref_id`: id of the preference you are recording against (`pref-no-internal-abbrev`).
- `artifact`: wikilink identifying what you produced β€” `[[src/cli/main.ts]]`, `[[docs/release-notes/v0.11.0.md]]`, `[[Brain/preferences/pref-no-internal-abbrev]]`. The wikilink resolves in Obsidian; use `#anchor` to point at a specific section when relevant.
-- `result`: `applied` if the rule held in this artifact, `violated` if you (or another agent) broke it. Recording a `violated` event is not a failure β€” it is what trains the system.
+- `result`: `applied` if the rule held in this artifact, `violated` if you (or another agent) broke it, `outdated` if the artifact shows the rule itself is obsolete (one `outdated` event retires the preference on the next dream pass). Recording a `violated` event is not a failure β€” it is what trains the system.
- `agent`: your runtime identity.
Optional:
@@ -73,6 +73,17 @@ Optional:
When a preference *might* apply but you are unsure, do not skip β€” record the event with `note: "speculative; <reason>"` so the dream pass sees the signal. A one-off speculative entry that does not recur is filtered out by dream; the cost of writing is one MCP call, the cost of missing is a silent gap in the evidence trail. The "do not call" list above is exhaustive on purpose: outside those four bullets, record.
+## End-of-turn check
+
+When a turn changed files (Write / Edit / MultiEdit / apply_patch) and none of `brain_feedback`, `brain_apply_evidence` or `brain_note` was called, the Stop hook continues the turn once with a single line: "Open Second Brain: this turn changed files but recorded no brain event. ..." Claude Code shows it as Stop hook feedback; Codex and other runtimes receive it as a continuation prompt. It is a prompt to decide, not an error:
+
+- a rule the user stated this turn β†’ `brain_feedback`;
+- an active preference in `Brain/preferences/` applied, violated or made obsolete by the change β†’ `brain_apply_evidence` with `result: applied | violated | outdated`;
+- a durable milestone that fits neither (release shipped, PR merged, fact discovered) β†’ `brain_note`;
+- nothing worth recording (the four cases under "When NOT to call") β†’ finish the reply without comment.
+
+It fires at most once per turn: the next stop passes whether or not you record anything. Do not mention the check to the user.
+
## Language
The `principle` and `note` fields must match the **natural language the user has been speaking in this session**. Technical identifiers stay English regardless: `topic` slug, `scope`, `pref_id`, `result`, `agent` name, file paths, library names, error messages quoted from logs. This mirrors the policy from the `agent-event-log` skill.
diff --git a/tests/hooks/detect.test.ts b/tests/hooks/detect.test.ts
index 73440593..ab2c834a 100644
--- a/tests/hooks/detect.test.ts
+++ b/tests/hooks/detect.test.ts
@@ -245,6 +245,20 @@ describe("summarizeTurn", () => {
});
describe("detectHookRuntime", () => {
+ test("Claude Code Stop payload outside ~/.claude β†’ claudecode; Codex Stop (turn_id) is not", () => {
+ const stop = {
+ hook_event_name: "Stop",
+ session_id: "s",
+ cwd: "/w",
+ transcript_path: "/custom/config/projects/-w/abc.jsonl",
+ stop_hook_active: false,
+ last_assistant_message: "done",
+ };
+ expect(detectHookRuntime(stop)).toBe("claudecode");
+ expect(detectHookRuntime({ ...stop, turn_id: "t1" })).toBe("unknown");
+ expect(detectHookRuntime({ ...stop, hook_event_name: "SubagentStop" })).toBe("unknown");
+ });
+
test("Claude Code transcript path β†’ claudecode", () => {
expect(
detectHookRuntime({
diff --git a/tests/hooks/stop-log-guardrail.test.ts b/tests/hooks/stop-log-guardrail.test.ts
index 5901c546..be8557a1 100644
--- a/tests/hooks/stop-log-guardrail.test.ts
+++ b/tests/hooks/stop-log-guardrail.test.ts
@@ -4,6 +4,8 @@ import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
+import { STOP_GUARDRAIL_TEXT } from "../../hooks/lib/messages.ts";
+
const HOOK = resolve(
dirname(fileURLToPath(import.meta.url)),
"..",
@@ -79,12 +81,10 @@ describe("stop-log-guardrail hook", () => {
expect(r.exit).toBe(0);
expect(r.stdout.endsWith("\n")).toBe(true);
const out = JSON.parse(r.stdout);
- expect(out.decision).toBe("block");
- expect(out.reason).toContain("brain_feedback");
- expect(out.reason).toContain("brain_apply_evidence");
- expect(out.reason).toContain("brain_note");
- // Β§32 (v0.10.8): event_log_append must not appear in the new
- // guardrail body β€” the tool is retired across every runtime.
+ // An unrecognised runtime gets the portable one-line block.
+ expect(out).toEqual({ decision: "block", reason: STOP_GUARDRAIL_TEXT });
+ // Β§32 (v0.10.8): event_log_append must not appear in the guardrail
+ // body β€” the tool is retired across every runtime.
expect(out.reason).not.toContain("event_log_append");
});
@@ -271,7 +271,7 @@ describe("stop-log-guardrail hook", () => {
expect(out.decision).toBe("block");
});
- test("Claude Code transcript path adds the claudecode cadence line", async () => {
+ test("Claude Code gets non-error additionalContext feedback, not a block", async () => {
// Reuse the per-test `tmp` so afterEach cleans this up too.
const transcript_path = join(tmp, ".claude", "projects", "session.jsonl");
mkdirSync(dirname(transcript_path), { recursive: true });
@@ -287,11 +287,18 @@ describe("stop-log-guardrail hook", () => {
stop_hook_active: false,
});
const out = JSON.parse(r.stdout);
- expect(out.decision).toBe("block");
- expect(out.reason as string).toContain("This guardrail fires");
+ // `decision: "block"` renders as a red "Stop hook error" with the whole
+ // reason in the user's transcript; additionalContext continues the turn
+ // as "Stop hook feedback".
+ expect(out.decision).toBeUndefined();
+ expect(out.reason).toBeUndefined();
+ expect(out.hookSpecificOutput).toEqual({
+ hookEventName: "Stop",
+ additionalContext: STOP_GUARDRAIL_TEXT,
+ });
});
- test("Codex transcript path adds the codex cadence line", async () => {
+ test("Codex transcript path gets the one-line block reason", async () => {
// Reuse the per-test `tmp` so afterEach cleans this up too.
const transcript_path = join(tmp, ".codex", "sessions", "session.jsonl");
mkdirSync(dirname(transcript_path), { recursive: true });
@@ -323,29 +330,34 @@ describe("stop-log-guardrail hook", () => {
stop_hook_active: false,
});
const out = JSON.parse(r.stdout);
- expect(out.decision).toBe("block");
- expect(out.reason as string).toContain("codex exec");
+ // Codex documents only decision/reason for Stop; the reason becomes the
+ // continuation prompt, so it stays one line.
+ expect(out).toEqual({ decision: "block", reason: STOP_GUARDRAIL_TEXT });
});
- test("unknown runtime omits the cadence line (v0.10.4 baseline)", async () => {
+ test("Grok Build payload gets the one-line block reason", async () => {
const transcript_path = writeTranscript([
ccUser("please add a file"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
]);
const r = await runHook({
- hook_event_name: "Stop",
+ hookEventName: "Stop",
+ workspaceRoot: tmp,
transcript_path,
stop_hook_active: false,
});
- const out = JSON.parse(r.stdout);
- expect(out.decision).toBe("block");
- const reason = out.reason as string;
- expect(reason).not.toContain("This guardrail fires");
- expect(reason).not.toContain("codex exec");
- // Β§32 (v0.10.8) β€” the unknown-runtime body still names the
- // current trio of brain-event tools.
- expect(reason).toContain("brain_feedback");
- expect(reason).toContain("brain_apply_evidence");
- expect(reason).toContain("brain_note");
+ expect(JSON.parse(r.stdout)).toEqual({ decision: "block", reason: STOP_GUARDRAIL_TEXT });
+ });
+});
+
+describe("STOP_GUARDRAIL_TEXT", () => {
+ test("is one short line that names the three brain-event tools", () => {
+ expect(STOP_GUARDRAIL_TEXT).not.toContain("\n");
+ expect(STOP_GUARDRAIL_TEXT.length).toBeLessThanOrEqual(200);
+ expect(STOP_GUARDRAIL_TEXT).toStartWith("Open Second Brain:");
+ expect(STOP_GUARDRAIL_TEXT).not.toContain("!");
+ for (const tool of ["brain_feedback", "brain_apply_evidence", "brain_note", "brain-memory"]) {
+ expect(STOP_GUARDRAIL_TEXT).toContain(tool);
+ }
});
});
diff --git a/uv.lock b/uv.lock
index 3c34faee..945be144 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4,5 +4,5 @@ requires-python = ">=3.11"
[[package]]
name = "open-second-brain"
-version = "1.58.1"
+version = "1.58.2"
source = { editable = "." }