bug: install registers precompact-session-digest hook in UserPromptSubmit with missing runner

[olucasalles]

Description

Running npx aios-core@latest install registers precompact-session-digest.cjs as a UserPromptSubmit hook in .claude/settings.local.json, but the runner file it depends on does not exist in the installed version.

Screenshot

The error appears on every single user input in Claude Code:

/AIOS:agents:devops → UserPromptSubmit hook error

Steps to Reproduce

1. Run npx aios-core@latest install on a project
2. Open Claude Code in the project
3. Type any prompt (e.g., /AIOS:agents:devops)

Expected Behavior

No hook error should appear on every user input.

Actual Behavior

Every prompt shows:

⎿ UserPromptSubmit hook error

This happens on every single input, not just once, severely impacting UX.

Root Cause

The hook at .claude/hooks/precompact-session-digest.cjs requires:

.aios-core/hooks/unified/runners/precompact-runner.js

This file does not exist in the installed package. The hook logs the error to stderr:

[PreCompact Hook] Failed to load hook runner: Cannot find module '/path/to/.aios-core/hooks/unified/runners/precompact-runner.js'

Additionally, this hook appears to be intended for the PreCompact event, not UserPromptSubmit — it runs unnecessarily on every user input.

Generated settings.local.json (relevant section)

"UserPromptSubmit": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "node \".claude/hooks/synapse-engine.cjs\""
      }
    ]
  },
  {
    "hooks": [
      {
        "type": "command",
        "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/precompact-session-digest.cjs\"",
        "timeout": 10
      }
    ]
  }
]

Workaround

Remove the second hook entry from UserPromptSubmit in .claude/settings.local.json.

Suggestion

Either:

• Don't register the precompact-session-digest hook during install until the runner is shipped
• Or ship the precompact-runner.js file with the install
• Or add a file-existence check in the hook before attempting require()

Environment

• AIOS Core version: 4.31.1 (installed via npx aios-core@latest)
• Platform: macOS (Darwin 24.6.0)
• Node.js: 18+
• Claude Code: latest

[olucasalles]

Additional Context & Screenshot

Screenshot of the error

The error appears on every single user input in Claude Code, directly below the prompt:

Context

This was discovered when running /AIOS:agents:devops (or any agent activation). The error line UserPromptSubmit hook error shows up persistently under every input, making it look like Claude Code itself is broken.

The user experience impact is significant — it appears on every prompt, not just once, creating confusion about whether Claude Code or the project is misconfigured.

How the bug was introduced

1. User ran npx aios-core@latest install from an external terminal
2. The installer wrote .claude/settings.local.json with precompact-session-digest.cjs registered under UserPromptSubmit
3. The hook's dependency (precompact-runner.js) was never shipped in the install
4. Result: every Claude Code input triggers the broken hook → stderr error → visible error message

Suggestion

Either:

• Don't register the precompact-session-digest hook during install until the runner is shipped
• Or ship the precompact-runner.js file with the install
• Or add a file-existence check in the hook before attempting require()

[AdmarBarreto]

Eu resolvi dessa forma:

Hooks & Claude Code — Gotchas e Soluções

UserPromptSubmit Hook Error (resolvido 2026-02-25)

Sintoma

UserPromptSubmit hook error ao ativar agentes AIOS (/AIOS:agents:*)

Root Cause

O buildHookOutput() em .aios-core/core/synapse/runtime/hook-runtime.js não incluía hookEventName no JSON de saída. Desde ~fev 2026, o Claude Code exige esse campo — sem ele, qualquer stdout de hooks UserPromptSubmit é tratado como erro.

Fix Aplicado

// hook-runtime.js → buildHookOutput()
// ANTES (quebrado):
return { hookSpecificOutput: { additionalContext: xml } };

// DEPOIS (funcionando):
return { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: xml } };

Referências

• Issue #12151 — Plugin hook output not captured
• Issue #13912 — stdout causes error (fechado como duplicata do #12151)
• Último comentário do #12151 confirma que hookEventName é obrigatório

Regras para hooks UserPromptSubmit

1. stdout DEVE ser JSON com hookSpecificOutput.hookEventName — texto puro causa erro
2. stderr também causa erro mesmo com exit 0 — redirecionar para arquivo se necessário
3. Exit 0 = sucesso, Exit 2 = bloqueia prompt, qualquer outro = erro
4. O campo additionalContext aparece como <system-reminder>UserPromptSubmit hook additional context: ...</system-reminder>

Hooks removidos (dead code)

• precompact-session-digest.cjs — dependia de .aios-core/hooks/unified/runners/precompact-runner.js que foi deletado na limpeza do framework. Não restaurar até que o módulo exista novamente.

Cuidado com aios-core install

npx aios-core install pode sobrescrever settings.local.json e restaurar hooks antigos (sem o fix). Se o erro voltar após update do AIOS, verificar:

1. Se hookEventName ainda está no buildHookOutput() em hook-runtime.js
2. Se precompact-session-digest.cjs foi readicionado ao UserPromptSubmit em settings.local.json

settings.json — Deny Rules Resetadas pelo Install (v4.4.6)

Sintoma

aios doctor mostra WARN: "Deny rules below threshold (0 rules, expected >= 40)"

Root Cause

npx aios-core install --force (e o instalador interativo) reseta .claude/settings.json, removendo todas as deny/allow rules que protegem camadas L1/L2 do framework.

Fix

Rodar o script de geração diretamente (sem o instalador interativo):

node .aios-core/infrastructure/scripts/generate-settings-json.js

Resultado: 80 deny rules + 9 allow rules regeneradas.

Nota

aios doctor --fix apenas sugere npx aios-core install --force, que é interativo e não funciona em batch. O script direto é o caminho correto.

[olucasalles]

Thanks @AdmarBarreto! Your fix worked perfectly.

Applied the hookEventName addition to buildHookOutput() in hook-runtime.js and the UserPromptSubmit hook error is gone — now returns Success on every prompt.

Commit: 84e7dda — 1 line fix, confirmed working on Claude Code v2.1.63 / Opus 4.6.

// fix applied:
hookSpecificOutput: {
  hookEventName: 'UserPromptSubmit',  // ← this was missing
  additionalContext: xml || '',
},

For anyone hitting this: the fix is literally 1 line. The precompact-session-digest.cjs removal from UserPromptSubmit is also recommended if you still have it registered.