[Bug][P1] Invalid hook type 'StopFailure' causes Claude Code settings error on session creation

[lorenzostorchi]

Description

When creating a session, Aegis generates a hooks file with StopFailure as a hook type, which Claude Code does not recognize. This causes Claude Code to fail with a settings error and prevents the session from starting properly.

Error

Settings Error
/tmp/aegis-hooks/hooks-493c7850-b383-4a4e-9a57-69b7fcc70825.json
 └ hooks
   └ StopFailure: Invalid key in record

Environment

• Aegis version: 2.2.2 (via npx aegis-bridge)
• Claude Code version: 2.1.63
• OS: Raspberry Pi OS (Debian 12) on arm64
• Node: v22.19.0

Steps to Reproduce

1. Run npx aegis-bridge
2. Create a session:

curl -X POST http://127.0.0.1:9100/v1/sessions   -H "Content-Type: application/json"   -d '{"name": "test-session", "workDir": "/home/openclaw/.openclaw/workspace", "prompt": "Create a hello.txt file"}'

3. Check the pane output - Claude Code shows the settings error

Generated Hooks File

{
  "hooks": {
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://127.0.0.1:9100/v1/hooks/StopFailure?sessionId=..."
          }
        ]
      }
    ],
    ...
  }
}

Suggested Fix

Remove or rename StopFailure to a valid Claude Code hook type. Check the Claude Code documentation for the list of supported hook types.

Additional Notes

Other hook types in the generated file may also be invalid - worth validating the full list against Claude Code's supported hooks.

[OneStepAt4time]

Thanks for the detailed report! 🙌

This is a real bug — Aegis generates StopFailure as a hook type in the settings file, but Claude Code doesn't recognize it as a valid hook event. This prevents sessions from starting on CC versions that strictly validate hook types.

Root cause: Aegis hooks system (src/hooks.ts, src/hook-settings.ts) registers StopFailure as a Claude Code hook, but CC only supports: PreToolUse, PostToolUse, Stop, Notification, SessionStart.

Fix plan: Remove StopFailure from the hook settings file sent to CC. Keep internal handling in Aegis (signal files, error tracking) but don't register it as a CC hook. The Stop hook already fires on failures too.

Tracking: Will be fixed in v2.2.3.

[OneStepAt4time]

⚠️ Update after investigation:

After checking the official Claude Code docs at https://code.claude.com/docs/en/hooks, StopFailure IS a valid hook event type in current CC versions:

StopFailure — When the turn ends due to an API error. Output and exit code are ignored

This means the issue is likely a Claude Code version mismatch. You're running CC 2.1.63 while the current latest is 2.1.87. StopFailure may have been added in a newer version.

Recommended fix: Update Claude Code to the latest version:

npm install -g @anthropic-ai/claude-code@latest

That said, Aegis should validate the minimum CC version requirement and warn users if their version is too old. I'll add a version check to prevent this kind of confusion. Downgrading the priority from P1 to P2.

[OneStepAt4time]

Closing as works as designed.

After investigation: StopFailure is a valid Claude Code hook event (confirmed in official docs: https://code.claude.com/docs/en/hooks). The error was caused by running an outdated Claude Code version (2.1.63 vs current 2.1.87).

Fix: npm install -g @anthropic-ai/claude-code@latest

Future improvement: Aegis should validate minimum CC version on session create and warn users. Created a follow-up issue for this.