Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

fix: match every SessionStart source under Codex and Gemini (#358)

Brenno Ferrari768bad39835c
diff --git a/.claude/scripts/tests/hook-config.test.ts b/.claude/scripts/tests/hook-config.test.ts
index 1cfb04d..9f4d482 100644
--- a/.claude/scripts/tests/hook-config.test.ts
+++ b/.claude/scripts/tests/hook-config.test.ts
@@ -34,6 +34,7 @@ type HookConfig = {
readonly hooks?: Record<
string,
ReadonlyArray<{
+ readonly matcher?: string;
readonly hooks?: ReadonlyArray<{
readonly type?: string;
readonly command?: string;
@@ -420,3 +421,57 @@ describe("hook config — Codex and Gemini commands run under their agents' shel
});
}
});
+
+describe("hook config — SessionStart fires for every source the agent documents (#352)", () => {
+ // Each agent matches SessionStart's matcher against the session's source
+ // its own way, and a matcher written for one rule silently matches nothing
+ // under another: Gemini's "startup|resume" equalled no source, so
+ // session-start never ran there.
+ const regex = (matcher: string, source: string) => new RegExp(`^(?:${matcher})$`).test(source);
+ // Gemini: a lifecycle matcher is an exact string, "" or "*" matching all
+ // (packages/core/src/hooks/hookPlanner.ts: matchesTrigger is
+ // matcher === trigger; gemini-cli main as of 2026-10-13).
+ const exact = (matcher: string, source: string) => ["", "*", source].includes(matcher.trim());
+ const FOUR_SOURCES = ["startup", "resume", "clear", "compact"];
+ const agents: ReadonlyArray<{
+ readonly label: string;
+ readonly path: string;
+ readonly sources: readonly string[];
+ readonly matches: (matcher: string, source: string) => boolean;
+ }> = [
+ // Claude Code: a regex over startup|resume|clear|compact (hooks reference).
+ { label: "Claude Code", path: ".claude/settings.json", sources: FOUR_SOURCES, matches: regex },
+ // Codex: "matcher is applied to source for this event. Values are startup,
+ // resume, clear, and compact", and "The matcher field is a regex string"
+ // (developers.openai.com/codex/hooks, as of 2026-10-13).
+ { label: "Codex CLI", path: ".codex/hooks.json", sources: FOUR_SOURCES, matches: regex },
+ // Gemini: sources startup|resume|clear (docs/hooks/reference.md).
+ { label: "Gemini CLI", path: ".gemini/settings.json", sources: ["startup", "resume", "clear"], matches: exact },
+ ];
+
+ for (const agent of agents) {
+ test(`${agent.label}: session-start runs on every documented source`, () => {
+ const entries = (loadConfig(agent.path).hooks?.["SessionStart"] ?? []).filter((e) =>
+ (e.hooks ?? []).some((h) => h.command?.includes("session-start.ts")),
+ );
+ assert.ok(entries.length > 0, "a SessionStart entry runs session-start.ts");
+ for (const source of agent.sources) {
+ const fires = entries.some((e) => e.matcher === undefined || agent.matches(e.matcher, source));
+ assert.ok(fires, `no SessionStart matcher fires on source "${source}"`);
+ }
+ });
+ }
+
+ // Gemini's tool events (BeforeTool, AfterTool) take a regex; every other
+ // event compares its matcher exactly, so a regex there matches nothing.
+ test("Gemini CLI: no lifecycle matcher is written as a regex", () => {
+ const TOOL_EVENTS = new Set(["BeforeTool", "AfterTool"]);
+ for (const [event, entries] of Object.entries(loadConfig(".gemini/settings.json").hooks ?? {})) {
+ if (TOOL_EVENTS.has(event)) continue;
+ for (const { matcher } of entries) {
+ if (matcher === undefined) continue;
+ assert.match(matcher.trim(), /^(\*|[\w-]*)$/, `${event}'s matcher ${JSON.stringify(matcher)} is compared exactly`);
+ }
+ }
+ });
+});
diff --git a/.codex/hooks.json b/.codex/hooks.json
index 81fe1cf..3428b25 100644
--- a/.codex/hooks.json
+++ b/.codex/hooks.json
@@ -2,7 +2,7 @@
"hooks": {
"SessionStart": [
{
- "matcher": "startup|resume",
+ "matcher": "startup|resume|clear|compact",
"hooks": [
{
"type": "command",
diff --git a/.gemini/settings.json b/.gemini/settings.json
index 9b22ee4..2ed2ae7 100644
--- a/.gemini/settings.json
+++ b/.gemini/settings.json
@@ -7,7 +7,7 @@
"hooks": {
"SessionStart": [
{
- "matcher": "startup|resume",
+ "matcher": "*",
"hooks": [
{
"type": "command",
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 1847764..111e128 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -887,7 +887,7 @@ Step 2 is not documentation garnish. Measured: with the server wired and no repo
## Multi-Agent Portability
-The same scripts serve three agents. Each agent has its own config file mapping equivalent lifecycle events to the shared scripts. The checklist runs on `Stop` for Claude Code and Codex (per response, deduped) and on `SessionEnd` for Gemini (at shutdown). The script branches on the documented event name and on what a payload field means, never on which agent sent it. Where agents spell one field differently, every spelling is read, so the field can never tell the agents apart: Grok's Stop sends the re-entry flag as `stopHookActive`, and the checklist reads it beside `stop_hook_active` (#323).
+The same scripts serve three agents. Each agent has its own config file mapping equivalent lifecycle events to the shared scripts. The checklist runs on `Stop` for Claude Code and Codex (per response, deduped) and on `SessionEnd` for Gemini (at shutdown). The script branches on the documented event name and on what a payload field means, never on which agent sent it. Where agents spell one field differently, every spelling is read, so the field can never tell the agents apart: Grok's Stop sends the re-entry flag as `stopHookActive`, and the checklist reads it beside `stop_hook_active` (#323). Matchers differ the same way. Claude Code and Codex read a SessionStart matcher as a regex over the source (`startup|resume|clear|compact`). Gemini compares a lifecycle matcher to the source as an exact string, with `""` or `"*"` matching all (gemini-cli `hookPlanner.ts`, as of 2026-10-13). A `startup|resume` matcher once matched nothing there, so session-start never ran under Gemini (#352). `tests/hook-config.test.ts` checks every agent's SessionStart matcher under that agent's own rule.
Session-boundary output is JSON-or-nothing on all three agents. On the hook path `session-start.ts` prints one `hookSpecificOutput` envelope too, for every agent (#340). `stop-checklist.ts` emits `{}` when a Stop has nothing new to say. What the user sees is `systemMessage`, the one user-facing field all three agents share: on a Stop whose findings changed, a one-line-per-section summary, with the full report saved for the next prompt's `UserPromptSubmit` to hand to the agent unseen. Only when the report cannot be saved does it go out as Stop feedback, which Claude Code prints in full; whether Codex honours Stop feedback is unverified. SessionEnd (Gemini) has no next prompt, so there the full report is `systemMessage` only. `om-wrap-up` still owns the deliberate acting pass at the end of a session.