@raidiant/notifai 0.5.1 → 1.0.1

package/src/install-hooks.test.ts

@@ -23,15 +23,18 @@ import {
   HARNESSES,
   applyPlan,
   detectHarness,
+  detectedHarnesses,
   buildHookConfig,
   codexLayerDir,
   codexProjectRoot,
   findInstallations,
   codexHookIdentityHash,
+  codexRepresentationProblems,
   codexTrustKey,
   codexTrustProblems,
   handlerEvent,
   hookCommand,
+  loadSettings,
   mergeHooks,
   removeHooks,
   settingsFile,
@@ -223,12 +226,86 @@ describe('settings locations', () => {
     )
   })
 
-  it('uses hooks.json for Codex', () => {
-    expect(settingsFile('codex', false, '/repo', {})).toBe('/repo/.codex/hooks.json')
+  it('uses config.toml for Codex, not the legacy hooks.json', () => {
+    expect(settingsFile('codex', false, '/repo', {})).toBe('/repo/.codex/config.toml')
     expect(settingsFile('codex', true, '/repo', {})).toBe(
-      path.join(os.homedir(), '.codex', 'hooks.json'),
+      path.join(os.homedir(), '.codex', 'config.toml'),
     )
   })
+
+  it('migrates a leftover Notifai-only hooks.json onto config.toml', () => {
+    const repo = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-migrate-json-'))
+    mkdirSync(path.join(repo, '.codex'), { recursive: true })
+    applyPlan(path.join(repo, '.codex', 'hooks.json'), { hooks: ours() })
+
+    expect(settingsFile('codex', false, repo, {})).toBe(path.join(repo, '.codex', 'config.toml'))
+  })
+
+  it('stays on hooks.json when that file already holds someone else\'s hooks', () => {
+    const repo = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-foreign-json-'))
+    mkdirSync(path.join(repo, '.codex'), { recursive: true })
+    applyPlan(path.join(repo, '.codex', 'hooks.json'), {
+      hooks: {
+        Stop: [{ hooks: [{ type: 'command', command: 'gdh-stop' }] }],
+      },
+    })
+
+    expect(settingsFile('codex', false, repo, {})).toBe(path.join(repo, '.codex', 'hooks.json'))
+  })
+
+  it('writes Codex hooks into an existing inline [hooks] instead of inventing hooks.json', () => {
+    const repo = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-toml-layer-'))
+    mkdirSync(path.join(repo, '.codex'), { recursive: true })
+    writeFileSync(
+      path.join(repo, '.codex', 'config.toml'),
+      [
+        'model = "gpt-5.6"',
+        '',
+        '[[hooks.PostToolUse]]',
+        'matcher = "Bash"',
+        '',
+        '[[hooks.PostToolUse.hooks]]',
+        'type = "command"',
+        'command = "gdh-guard"',
+        '',
+        '[[hooks.Stop]]',
+        '',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        'command = "gdh-stop"',
+        '',
+      ].join('\n'),
+    )
+
+    expect(settingsFile('codex', false, repo, {})).toBe(path.join(repo, '.codex', 'config.toml'))
+  })
+
+  it('does not treat the Codex trust store as an inline hook representation', () => {
+    const home = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-trust-only-'))
+    writeFileSync(
+      path.join(home, 'config.toml'),
+      `[hooks.state."${home}/hooks.json:stop:0:0"]\ntrusted_hash = "sha256:abc"\n`,
+    )
+
+    expect(settingsFile('codex', true, '/repo', { CODEX_HOME: home })).toBe(
+      path.join(home, 'config.toml'),
+    )
+  })
+
+  it('keeps writing to inline [hooks] when a leftover hooks.json only holds Notifai', () => {
+    const repo = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-both-'))
+    const layer = path.join(repo, '.codex')
+    mkdirSync(layer, { recursive: true })
+    writeFileSync(
+      path.join(layer, 'config.toml'),
+      ['[[hooks.Stop]]', '', '[[hooks.Stop.hooks]]', 'type = "command"', 'command = "gdh-stop"', ''].join(
+        '\n',
+      ),
+    )
+    applyPlan(path.join(layer, 'hooks.json'), { hooks: ours() })
+
+    expect(settingsFile('codex', false, repo, {})).toBe(path.join(layer, 'config.toml'))
+  })
 })
 
 /**
@@ -253,7 +330,7 @@ describe('a Codex install run inside a git worktree', () => {
   it('targets the main repository, which is the file Codex actually reads', () => {
     const { main, worktree } = repoWithWorktree()
 
-    expect(settingsFile('codex', false, worktree, {})).toBe(path.join(main, '.codex', 'hooks.json'))
+    expect(settingsFile('codex', false, worktree, {})).toBe(path.join(main, '.codex', 'config.toml'))
     expect(codexProjectRoot(worktree)).toBe(main)
   })
 
@@ -322,14 +399,14 @@ describe('a Codex install run inside a git worktree', () => {
     // Orca points CODEX_HOME at a per-account home; writing to ~/.codex there
     // produced hooks Codex never loaded, and nothing reported a problem.
     expect(settingsFile('codex', true, '/repo', { CODEX_HOME: '/managed/codex' })).toBe(
-      '/managed/codex/hooks.json',
+      '/managed/codex/config.toml',
     )
     expect(settingsFile('claude-code', true, '/repo', { CLAUDE_CONFIG_DIR: '/managed/claude' })).toBe(
       '/managed/claude/settings.json',
     )
     // An empty value is not a relocation.
     expect(settingsFile('codex', true, '/repo', { CODEX_HOME: '' })).toBe(
-      path.join(os.homedir(), '.codex', 'hooks.json'),
+      path.join(os.homedir(), '.codex', 'config.toml'),
     )
   })
 })
@@ -422,9 +499,96 @@ describe('writing the settings file', () => {
     applyPlan(file, { hooks: {} })
     expect(statSync(file).mode & 0o777).toBe(0o600)
   })
+
+  it('merges into Codex config.toml without dropping trust state or foreign hooks', () => {
+    const dir = scratch()
+    const file = path.join(dir, 'config.toml')
+    writeFileSync(
+      file,
+      [
+        'model = "gpt-5.6"',
+        '',
+        '[features]',
+        'hooks = true',
+        '',
+        `[hooks.state."${file}:stop:0:0"]`,
+        'trusted_hash = "sha256:abc"',
+        '',
+        '[[hooks.Stop]]',
+        '',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        'command = "gdh-stop"',
+        '',
+      ].join('\n'),
+    )
+
+    const merged = mergeHooks(loadSettings(file), ours(), SCRIPT)
+    applyPlan(file, merged.document)
+
+    const text = readFileSync(file, 'utf8')
+    expect(text).toContain('model = "gpt-5.6"')
+    expect(text).toContain('trusted_hash = "sha256:abc"')
+    expect(text).toContain('gdh-stop')
+    expect(text).toContain('hook stop')
+    expect(text).toContain('[[hooks.UserPromptSubmit]]')
+    expect(text).toContain('[[hooks.SessionEnd]]')
+    expect(merged.document.hooks?.['Stop']?.flatMap((group) => group.hooks)).toHaveLength(2)
+  })
 })
 
 describe('finding what is installed', () => {
+  it('reports Notifai handlers written as inline Codex [hooks]', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-find-toml-'))
+    const file = path.join(cwd, '.codex', 'config.toml')
+    mkdirSync(path.dirname(file), { recursive: true })
+    writeFileSync(
+      file,
+      [
+        '[[hooks.Stop]]',
+        '',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        'command = "gdh-stop"',
+        '',
+        '[[hooks.Stop]]',
+        '',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        `command = "${hookCommand(ADAPTER, 'stop', 'codex')}"`,
+        '',
+      ].join('\n'),
+    )
+
+    const found = findInstallations(cwd, { CODEX_HOME: path.join(cwd, 'no-codex-here') })
+    const codex = found.find((installation) => installation.harness === 'codex' && !installation.global)
+    expect(codex?.file).toBe(file)
+    expect(codex?.handlers.map((handler) => handler.event)).toEqual(['Stop'])
+    expect(codex?.handlers[0]?.handlerIndex).toBe(0)
+    expect(codex?.handlers[0]?.groupIndex).toBe(1)
+  })
+
+  it('names a Codex layer that loads both representations', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-dual-rep-'))
+    const layer = path.join(cwd, '.codex')
+    mkdirSync(layer, { recursive: true })
+    applyPlan(path.join(layer, 'hooks.json'), { hooks: ours() })
+    writeFileSync(
+      path.join(layer, 'config.toml'),
+      ['[[hooks.Stop]]', '', '[[hooks.Stop.hooks]]', 'type = "command"', 'command = "gdh-stop"', ''].join(
+        '\n',
+      ),
+    )
+
+    const problems = codexRepresentationProblems(cwd, { CODEX_HOME: path.join(cwd, 'no-codex-here') })
+    expect(problems).toHaveLength(1)
+    expect(problems[0]).toContain('loading hooks from both')
+    expect(problems[0]).toContain(path.join(layer, 'hooks.json'))
+    expect(problems[0]).toContain(path.join(layer, 'config.toml'))
+    expect(problems[0]).toMatch(/prefer a single representation for this layer/)
+    expect(problems[0]).toMatch(/Stop/)
+  })
+
   it('reports handlers from either harness with their positions', () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-find-'))
     mkdirSync(path.join(cwd, '.claude'), { recursive: true })
@@ -666,11 +830,19 @@ describe('detectHarness', () => {
   })
 
   it('returns null when the project itself names two harnesses', () => {
-    // Genuine ambiguity, and the caller must ask rather than pick. Not the
-    // same as having no evidence.
+    // Genuine ambiguity for a single-harness caller. detectedHarnesses lists
+    // both so install can wire them together.
     expect(detectHarness(project('.claude', '.codex'))).toBeNull()
   })
 
+  it('lists every project-named harness in declared order', () => {
+    const isolated = { HOME: mkdtempSync(path.join(os.tmpdir(), 'notifai-detect-home-')) }
+    expect(detectedHarnesses(project('.codex', '.claude'), isolated)).toEqual([
+      'claude-code',
+      'codex',
+    ])
+  })
+
   it('prefers project evidence over anything installed on the machine', () => {
     // The regression. Machine-global markers used to be OR-ed in per harness,
     // so a developer with several agent tools installed got a candidate for

package/src/install-hooks.ts

@@ -3,12 +3,13 @@ import {
   lstatSync,
   readFileSync,
   realpathSync,
+  rmSync,
   statSync,
 } from 'node:fs'
 import { createHash } from 'node:crypto'
 import os from 'node:os'
 import path from 'node:path'
-import { parse as parseToml } from 'smol-toml'
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
 import { atomicWriteFileSync } from './atomic-file.js'
 import { hookAdapterPath } from './hook-adapter.js'
 import { opencodePluginPath, opencodePluginTarget } from './opencode-plugin.js'
@@ -30,10 +31,13 @@ const OPENCODE_EVENTS = [
 /**
  * Harness hook installation.
  *
- * Claude Code's `settings.json` and Codex's `hooks.json` use the same shape —
+ * Claude Code's `settings.json` and Codex's hook files use the same shape —
  * `hooks` maps an event name to matcher groups, each holding command handlers
  * with an optional timeout — so one generator serves both. Only the file
- * location and the event set differ.
+ * location and the event set differ. Codex still loads a leftover
+ * `hooks.json`, but that file is the legacy representation. We write inline
+ * `[hooks]` tables in the same layer's `config.toml`. One representation per
+ * layer, never both.
  *
  * Cursor's native format is flat and lower-camel-cased, while OpenCode's
  * extension point is a JavaScript plugin module. Each therefore has a bounded
@@ -260,9 +264,7 @@ export function settingsFile(
         ? path.join(configHome(env, 'CLAUDE_CONFIG_DIR', '.claude'), 'settings.json')
         : path.join(cwd, '.claude', 'settings.local.json')
     case 'codex':
-      return global
-        ? path.join(configHome(env, 'CODEX_HOME', '.codex'), 'hooks.json')
-        : path.join(codexProjectRoot(cwd), '.codex', 'hooks.json')
+      return inspectCodexLayer(codexLayerPaths(global, cwd, env)).writeTarget
     default:
       return assertNeverHarness(harness)
   }
@@ -276,8 +278,8 @@ function assertNeverHarness(harness: never): never {
  * Where Codex looks for a project's hooks — the **main** repository, not the
  * working directory.
  *
- * Run from a linked git worktree, Codex reads `<main repo>/.codex/hooks.json`
- * and never looks at the worktree's own. Proven 2026-08-03 in an isolated
+ * Run from a linked git worktree, Codex reads `<main repo>/.codex/config.toml`
+ * (or a leftover `hooks.json`) and never looks at the worktree's own. Proven 2026-08-03 in an isolated
  * `CODEX_HOME`: with cwd set to a worktree, a handler at the main repo root
  * fired and an identical one at the worktree root did not; removing the main
  * one left nothing firing at all. Writing to cwd therefore produces a silent
@@ -307,7 +309,7 @@ export function codexProjectRoot(cwd: string): string {
  *
  * Codex splits the two halves of "which project am I in": it discovers the
  * project layer by walking up from cwd for a `.codex` directory, but resolves
- * `hooks.json` inside that layer against the main repository. In an ordinary
+ * the hook file inside that layer against the main repository. In an ordinary
  * checkout both land on the same directory and the split is invisible. In a
  * worktree they diverge, and writing only the main repository's file leaves it
  * unread — Codex never looks, because nothing at or above cwd told it there was
@@ -363,6 +365,151 @@ export function configHome(env: NodeJS.ProcessEnv, variable: string, fallback: s
   return override !== undefined && override !== '' ? override : path.join(os.homedir(), fallback)
 }
 
+export interface CodexLayerPaths {
+  dir: string
+  hooksJson: string
+  configToml: string
+}
+
+/** The two files Codex will look at for one config layer. */
+export function codexLayerPaths(
+  global: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): CodexLayerPaths {
+  const dir = global
+    ? configHome(env, 'CODEX_HOME', '.codex')
+    : path.join(codexProjectRoot(cwd), '.codex')
+  return {
+    dir,
+    hooksJson: path.join(dir, 'hooks.json'),
+    configToml: path.join(dir, 'config.toml'),
+  }
+}
+
+export interface CodexLayerInspection {
+  paths: CodexLayerPaths
+  jsonEvents: string[]
+  tomlEvents: string[]
+  writeTarget: string
+  dual: boolean
+  overlappingEvents: string[]
+  canCollapse: boolean
+}
+
+/**
+ * Which representation this Codex layer already uses.
+ *
+ * `hooks.json` is the legacy file. We write inline `[hooks]` in
+ * `config.toml` unless this layer already has someone else's hooks only in
+ * `hooks.json` — writing a second file would make Codex load both and run
+ * every matching handler. `[hooks.state]` is the trust store, not a hook
+ * definition, so it does not count as a representation.
+ */
+export function inspectCodexLayer(paths: CodexLayerPaths): CodexLayerInspection {
+  const jsonDocument = tryLoadSettings(paths.hooksJson)
+  const tomlDocument = tryLoadSettings(paths.configToml)
+  const jsonEvents = hookEventNames(jsonDocument?.hooks)
+  const tomlEvents = hookEventNames(tomlDocument?.hooks)
+  const jsonForeign = documentHasForeignHandlers(jsonDocument)
+  const tomlForeign = documentHasForeignHandlers(tomlDocument)
+  const dual = jsonEvents.length > 0 && tomlEvents.length > 0
+  // Current representation. Stay on the legacy file only when that is
+  // already where someone else's hooks live and toml has none.
+  let writeTarget = paths.configToml
+  if (jsonEvents.length > 0 && tomlEvents.length === 0 && jsonForeign) {
+    writeTarget = paths.hooksJson
+  } else if (dual && jsonForeign && !tomlForeign) {
+    writeTarget = paths.hooksJson
+  }
+  return {
+    paths,
+    jsonEvents,
+    tomlEvents,
+    writeTarget,
+    dual,
+    overlappingEvents: jsonEvents.filter((event) => tomlEvents.includes(event)),
+    canCollapse: dual && !(jsonForeign && tomlForeign),
+  }
+}
+
+/** Every file in this layer Codex might already be reading hooks from. */
+export function hookDefinitionFiles(
+  harness: Harness,
+  global: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  if (harness !== 'codex') return [settingsFile(harness, global, cwd, env)]
+  const paths = codexLayerPaths(global, cwd, env)
+  return [paths.hooksJson, paths.configToml]
+}
+
+/**
+ * Drop the unused representation after writing the one this layer already had.
+ *
+ * Only safe when the discarded file has no one else's handlers. `hooks.json`
+ * is deleted once it has no events left so Codex stops warning; `config.toml`
+ * is never deleted.
+ */
+export function collapseUnusedCodexRepresentation(
+  keepFile: string,
+  scriptPath: string,
+  paths: CodexLayerPaths,
+): string | null {
+  const other = keepFile === paths.hooksJson ? paths.configToml : paths.hooksJson
+  if (!existsSync(other)) return null
+  const document = tryLoadSettings(other)
+  if (document === null || documentHasForeignHandlers(document)) return null
+  const stripped = removeHooks(document, scriptPath)
+  if (other === paths.hooksJson && hookEventNames(stripped.document.hooks).length === 0) {
+    rmSync(other)
+    return other
+  }
+  applyPlan(other, stripped.document)
+  return other
+}
+
+export function codexRepresentationProblems(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  return [false, true].flatMap((global) => {
+    const layer = inspectCodexLayer(codexLayerPaths(global, cwd, env))
+    if (!layer.dual) return []
+    const overlap =
+      layer.overlappingEvents.length > 0
+        ? ` Matching handlers from both files all run — this layer's ${layer.overlappingEvents.join(', ')} handlers will both fire.`
+        : ' Matching handlers from both files all run.'
+    const collapse = layer.canCollapse
+      ? ` Run \`notifai hooks install --harness codex${global ? ' --global' : ''}\` to collapse onto ${path.basename(layer.writeTarget)}.`
+      : ' Both files have other hooks, so Notifai cannot collapse them.'
+    return [
+      `loading hooks from both ${layer.paths.hooksJson} and ${layer.paths.configToml}; prefer a single representation for this layer.${overlap}${collapse}`,
+    ]
+  })
+}
+
+function tryLoadSettings(file: string): SettingsDocument | null {
+  if (!existsSync(file)) return null
+  try {
+    return loadSettings(file)
+  } catch {
+    return null
+  }
+}
+
+function hookEventNames(hooks: SettingsDocument['hooks']): string[] {
+  return Object.entries(hooks ?? {})
+    .filter(([, value]) => Array.isArray(value))
+    .map(([event]) => event)
+}
+
+function documentHasForeignHandlers(document: SettingsDocument | null): boolean {
+  if (document === null) return false
+  return locateAllHandlers(document).some((handler) => !isNotifaiCommand(handler.command))
+}
+
 /** Best-effort detection so `hooks install` usually needs no flags. */
 /**
  * Harnesses this *project* shows evidence of, in the working directory only.
@@ -389,8 +536,8 @@ function localHarnessEvidence(cwd: string): Harness[] {
 }
 
 /** Harnesses installed anywhere on this machine — a much weaker signal. */
-function globalHarnessEvidence(): Harness[] {
-  const home = os.homedir()
+function globalHarnessEvidence(env: NodeJS.ProcessEnv = process.env): Harness[] {
+  const home = env['HOME'] !== undefined && env['HOME'] !== '' ? env['HOME'] : os.homedir()
   const found: Harness[] = []
   if (existsSync(path.join(home, '.claude'))) found.push('claude-code')
   if (existsSync(path.join(home, '.codex'))) found.push('codex')
@@ -400,30 +547,34 @@ function globalHarnessEvidence(): Harness[] {
 }
 
 /**
- * Which harness to wire in this directory, or null when it is genuinely
- * unclear.
+ * Every supported harness this project or machine shows evidence of, in
+ * declared order. Project markers come first, then machine installs that the
+ * project did not already name.
  *
- * Project evidence decides, and machine evidence is consulted only when the
- * project offers none. The two were previously OR-ed together per harness,
- * which meant a developer with several agent tools installed could never get
- * a detection at all: every `~/.<tool>` directory contributed a candidate, the
- * "exactly one" test never passed, and the answer was null in every repository
- * on the machine. Verified on a machine carrying all four — `notifai init
- * --hooks` failed in five separate projects, each of which plainly used Claude
- * Code.
+ * `AGENTS.md` still counts for nothing — see `localHarnessEvidence`.
+ */
+export function detectedHarnesses(cwd: string, env: NodeJS.ProcessEnv = process.env): Harness[] {
+  const seen = new Set<Harness>([...localHarnessEvidence(cwd), ...globalHarnessEvidence(env)])
+  return HARNESSES.filter((harness) => seen.has(harness))
+}
+
+/**
+ * Which *single* harness to wire when a caller still needs exactly one, or
+ * null when it is genuinely unclear.
  *
- * Having a tool installed says nothing about which one *this* project is
- * worked in. Ambiguity within the project is still ambiguity, and returns
- * null so the caller can ask rather than guess.
+ * Project evidence decides, and machine evidence is consulted only when the
+ * project offers none. Several markers are not a failure of detection — they
+ * are several harnesses. `detectedHarnesses` is the default for install;
+ * this helper stays for uninstall and any caller that cannot take a list.
  */
-export function detectHarness(cwd: string): Harness | null {
+export function detectHarness(cwd: string, env: NodeJS.ProcessEnv = process.env): Harness | null {
   const local = localHarnessEvidence(cwd)
   if (local.length > 0) return local.length === 1 ? local[0]! : null
-  const global = globalHarnessEvidence()
+  const global = globalHarnessEvidence(env)
   return global.length === 1 ? global[0]! : null
 }
 
-interface SettingsDocument {
+export interface SettingsDocument {
   hooks?: HookConfig
   [key: string]: unknown
 }
@@ -571,6 +722,11 @@ export function mergeHooks(
   const removed: string[] = []
 
   for (const [event, groups] of Object.entries(existing.hooks ?? {})) {
+    if (!Array.isArray(groups)) {
+      // Codex keeps `[hooks.state]` beside event tables. It is not a matcher list.
+      ;(hooks as Record<string, unknown>)[event] = groups
+      continue
+    }
     const { groups: foreign, removed: hadOurs } = withoutOurs(groups, scriptPath)
     if (hadOurs) {
       if (event in incoming) replaced.push(event)
@@ -591,6 +747,10 @@ export function removeHooks(existing: SettingsDocument, scriptPath: string): Mer
   const hooks: HookConfig = {}
   const replaced: string[] = []
   for (const [event, groups] of Object.entries(existing.hooks ?? {})) {
+    if (!Array.isArray(groups)) {
+      ;(hooks as Record<string, unknown>)[event] = groups
+      continue
+    }
     const { groups: foreign, removed } = withoutOurs(groups, scriptPath)
     if (removed) replaced.push(event)
     if (foreign.length > 0) hooks[event] = foreign
@@ -609,13 +769,31 @@ export function removeHooks(existing: SettingsDocument, scriptPath: string): Mer
  * support.
  */
 export function applyPlan(file: string, document: SettingsDocument | CursorSettingsDocument): void {
-  atomicWriteFileSync(file, `${JSON.stringify(document, null, 2)}\n`, {
+  const body = isTomlSettingsPath(file)
+    ? `${stringifyToml(document)}\n`
+    : `${JSON.stringify(document, null, 2)}\n`
+  atomicWriteFileSync(file, body, {
     requireCurrentUserOwner: true,
   })
 }
 
 export function loadSettings(file: string): SettingsDocument {
-  return readSettings(file)
+  return isTomlSettingsPath(file) ? readTomlSettings(file) : readSettings(file)
+}
+
+function isTomlSettingsPath(file: string): boolean {
+  return file.endsWith('.toml')
+}
+
+function readTomlSettings(file: string): SettingsDocument {
+  if (!existsSync(file)) return {}
+  const source = readOwnedRegularFile(file)
+  try {
+    const parsed: unknown = parseToml(source)
+    return typeof parsed === 'object' && parsed !== null ? (parsed as SettingsDocument) : {}
+  } catch {
+    throw new Error(`Could not parse ${file}; fix or move it before installing hooks.`)
+  }
 }
 
 export function loadCursorSettings(file: string): CursorSettingsDocument {
@@ -766,10 +944,6 @@ function isNotifaiCommand(command: string): boolean {
   return / hook (user-prompt-submit|stop|session-end)\b/.test(command)
 }
 
-function isNotifaiHandler(handler: HookHandler): boolean {
-  return isNotifaiCommand(handler.command)
-}
-
 /** Every place either harness would read a Notifai handler from. */
 export function findInstallations(
   cwd: string,
@@ -779,7 +953,8 @@ export function findInstallations(
   const found: Installation[] = []
   for (const harness of HARNESSES) {
     for (const global of [false, true]) {
-      const file = settingsFile(harness, global, cwd, env)
+      const files = hookDefinitionFiles(harness, global, cwd, env)
+      for (const file of files) {
       if (!existsSync(file)) continue
       // OpenCode's adapter is a plugin module, not a settings document, so it
       // is reported as one installation covering all three events rather than
@@ -837,7 +1012,7 @@ export function findInstallations(
       }
       let document: SettingsDocument
       try {
-        document = readSettings(file)
+        document = loadSettings(file)
       } catch {
         continue
       }
@@ -846,6 +1021,7 @@ export function findInstallations(
         const problems = harnessMarkerProblems(harness, handlers, adapterHome)
         found.push({ harness, file, global, handlers, ...(problems.length > 0 ? { problems } : {}) })
       }
+      }
     }
   }
   return found
@@ -889,28 +1065,32 @@ function locateCursorHandlers(document: CursorSettingsDocument): InstalledHandle
   return handlers
 }
 
-function locateHandlers(document: SettingsDocument): InstalledHandler[] {
+function locateAllHandlers(document: SettingsDocument): InstalledHandler[] {
   const handlers: InstalledHandler[] = []
   for (const [event, groups] of Object.entries(document.hooks ?? {})) {
+    if (!Array.isArray(groups)) continue
     groups.forEach((group, groupIndex) => {
       group.hooks?.forEach((handler, handlerIndex) => {
-        if (isNotifaiHandler(handler)) {
-          handlers.push({
-            event,
-            groupIndex,
-            handlerIndex,
-            command: handler.command,
-            ...(handler.timeout === undefined ? {} : { timeout: handler.timeout }),
-            ...(handler.async === undefined ? {} : { async: handler.async }),
-            ...(handler.statusMessage === undefined ? {} : { statusMessage: handler.statusMessage }),
-          })
-        }
+        if (typeof handler?.command !== 'string') return
+        handlers.push({
+          event,
+          groupIndex,
+          handlerIndex,
+          command: handler.command,
+          ...(handler.timeout === undefined ? {} : { timeout: handler.timeout }),
+          ...(handler.async === undefined ? {} : { async: handler.async }),
+          ...(handler.statusMessage === undefined ? {} : { statusMessage: handler.statusMessage }),
+        })
       })
     })
   }
   return handlers
 }
 
+function locateHandlers(document: SettingsDocument): InstalledHandler[] {
+  return locateAllHandlers(document).filter((handler) => isNotifaiCommand(handler.command))
+}
+
 /** The hook event a handler's command actually invokes, e.g. `stop`. */
 export function handlerEvent(command: string): string | null {
   return / hook ([a-z-]+)/.exec(command)?.[1] ?? null