gastownhall/beads · error

unsupported Codex hook event %q

Error message

unsupported Codex hook event %q

What it means

The Codex hook dispatcher received a hook event name it doesn't recognize. Only a fixed set of events (session-start, pre-compact, post-compact, user-prompt-submit) is supported; anything else is rejected.

Source

Thrown at cmd/bd/codex_hook.go:87

	}
	if input.HookEventName != "" {
		event = input.HookEventName
	}

	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
	defer cancel()

	switch event {
	case codexHookSessionStart:
		return codexHookInjectPrime(ctx, stdout, codexHookSessionStart)
	case codexHookPreCompact:
		return codexHookPreCompactCheck(ctx, stdout)
	case codexHookPostCompact:
		return codexHookMarkNeedsRefresh(input)
	case codexHookUserPromptSubmit:
		return codexHookMaybeRefresh(ctx, input, stdout)
	default:
		return fmt.Errorf("unsupported Codex hook event %q", event)
	}
}

func codexHookInjectPrime(ctx context.Context, stdout io.Writer, event string) error {
	out, err := codexHookExecPrime(ctx, false)
	if err != nil || strings.TrimSpace(out) == "" {
		return nil
	}
	return writeCodexHookAdditionalContext(stdout, event, out)
}

func codexHookPreCompactCheck(ctx context.Context, stdout io.Writer) error {
	if _, err := codexHookExecPrime(ctx, true); err != nil {
		return writeCodexHookSystemMessage(stdout, fmt.Sprintf("Beads context check failed before compaction: %v", err))
	}
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Upgrade bd to the latest version so new Codex hook events are recognized
2. Check the Codex hooks configuration and correct the event name spelling
3. If the event is genuinely unsupported, remove or ignore that hook entry
4. Verify the hook wiring passes the event as the expected argument/format

Example fix

// before
event = "session_start"   // wrong format
// after
event = "session-start"   // supported: session-start, pre-compact, post-compact, user-prompt-submit

// allowlist supported events before invoking
SUPPORTED="session-start pre-compact post-compact user-prompt-submit"
case "$EVENT" in session-start|pre-compact|post-compact|user-prompt-submit) ;; *) exit 0;; esac

When it happens

Trigger: Codex invokes the hook binary with an event name outside the supported set — a newer Codex version added an event the installed bd doesn't know, a misconfigured hook entry passes the wrong event string, or hooks are wired with a typo.

Common situations: Upgraded Codex CLI emitting new hook events while bd is older; hand-edited Codex config with a misspelled event name; copying hook config from docs for a different version.

Related errors

• bd %s: %w: %s
• httpapi: a configured role fires this workspace's hooks; thi
• httpapi: the configured provider fires this workspace's hook
• ErrAmbiguousID
• 'bd admin %s' is not yet supported in embedded mode

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/c46f78846d2a502a. Report an issue: GitHub.