Skip to main content

Error Report: SessionStart Hook & MCP Server Issues

Generated: 2026-01-22 Investigator: Claude Code Severity: High - Prevents CODITECT governance from loading

Executive Summary​

Investigation Status: ✅ COMPLETE - No further investigation required

Four critical configuration issues prevent proper CODITECT initialization:

  1. SessionStart hook not registered in settings.json
  2. MCP servers not configured - codanna binary not installed
  3. Hardcoded path to wrong user in existing hook configuration
  4. Missing hook file - task-id-validator.py does not exist

Root Cause​

The settings.json was copied from another machine (halcasteel's) without updating paths. This causes an error on every Bash command execution.

Finding 1: SessionStart Hook Not Registered​

Evidence​

File: /Users/matiasmeirelles/PROJECTS/.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/halcasteel/PROJECTS/coditect-rollout-master/submodules/core/coditect-core/hooks/session-retrospective.py --event session.end",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Issues Identified​

IssueImpact
No SessionStart hook sectionGovernance skill never injected at session start
Path references /Users/halcasteel/Hook fails for user matiasmeirelles
Missing PreToolUse hooksTask ID validation not enforced

Expected Configuration (per ADR-074)​

{
  "hooks": {
    "SessionStart": [
      {
        "command": "python3 ~/.coditect/hooks/session_start_governance.py",
        "description": "Load CODITECT governance skill"
      }
    ],
    "PreToolUse": [
      {
        "matcher": {"tool_name": "Bash"},
        "command": "python3 ~/.coditect/hooks/task-id-validator.py"
      },
      {
        "matcher": {"tool_name": "Edit"},
        "command": "python3 ~/.coditect/hooks/task-id-validator.py"
      },
      {
        "matcher": {"tool_name": "Write"},
        "command": "python3 ~/.coditect/hooks/task-id-validator.py"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.coditect/hooks/session-retrospective.py --event session.end",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Hook File Status (Verified)​

FilePathExistsNotes
session_start_governance.py.coditect/hooks/session_start_governance.py✅ YesNot registered in settings.json
task-id-validator.py.coditect/hooks/task-id-validator.py❌ MissingADR-074 specifies it, never created
session-retrospective.py.coditect/hooks/session-retrospective.py✅ YesWrong path in settings.json
session-retrospective-v2.py.coditect/hooks/session-retrospective-v2.py✅ YesAlternative version available

Finding 2: MCP Servers Not Configured​

Evidence​

  • No MCP config files found in /Users/matiasmeirelles/PROJECTS/
  • Template exists at: .coditect/config/templates/mcp-codanna.json
  • Template NOT deployed to active configuration

Template Contents​

{
  "mcpServers": {
    "codanna-direct": {
      "command": "codanna",
      "args": ["serve", "--watch"]
    },
    "codanna": {
      "command": "python3",
      "args": ["${CODITECT_HOME}/scripts/codanna-mcp-wrapper.py", ...]
    }
  }
}

Prerequisites (Verified)​

DependencyStatusNotes
codanna binary installed❌ Not installedwhich codanna returns nothing
codanna-mcp-wrapper.py exists❓ UnknownCannot test without codanna
Environment variables set❓ UnknownNot applicable without codanna

Conclusion: MCP server errors are expected because codanna is not installed on this machine.

Finding 3: Path Compatibility Issue​

Current Path (Broken)​

/Users/halcasteel/PROJECTS/coditect-rollout-master/submodules/core/coditect-core/hooks/

Required Path (Current User)​

/Users/matiasmeirelles/PROJECTS/.coditect/hooks/

Or use portable path:

~/.coditect/hooks/

Finding 4: Missing Hook File​

Evidence​

$ ls ~/.coditect/hooks/ | grep task-id
# (no output - file does not exist)

Impact​

  • ADR-074 specifies task-id-validator.py for PreToolUse validation
  • Without this file, task ID enforcement cannot be enabled
  • Even if settings.json is fixed, PreToolUse hooks will fail

Resolution Required​

The task-id-validator.py hook must be created per ADR-074 specification, or PreToolUse hooks must be removed from the expected configuration.

Investigation Complete: Final Status​

ComponentStatusIssue
CODITECT symlink✅ OKPoints to ~/Library/Application Support/CODITECT/core
Machine ID✅ OK~/.coditect/machine-id.json exists
session_start_governance.py✅ ExistsNot registered in settings.json
session-retrospective.py✅ ExistsWrong path in settings.json
task-id-validator.py❌ MissingADR-074 specifies it, never created
codanna (MCP)❌ Not installedExplains MCP server errors
settings.json❌ BrokenPoints to /Users/halcasteel/

Available Hook Files​

The following session-related hooks exist in ~/.coditect/hooks/:

session_start_governance.py
session-auto-recall.py
session-handoff.py
session-retrospective.py
session-retrospective-v2.py
session-start-context.py
post-session.py
post-session-context-health.md
post-session-log-update.py
pre-session-memory.md
worktree-session-scope.sh

Remediation Steps​

Step 1: Fix settings.json​

# Backup current settings
cp ~/.claude/settings.json ~/.claude/settings.json.backup

# Apply correct configuration (see Expected Configuration above)

Step 2: Verify Hook Files Exist​

ls -la ~/.coditect/hooks/session_start_governance.py
ls -la ~/.coditect/hooks/task-id-validator.py
ls -la ~/.coditect/hooks/session-retrospective.py

Step 3: Test SessionStart Hook​

# Test hook directly
python3 ~/.coditect/hooks/session_start_governance.py
# Should output JSON with hookSpecificOutput

Step 4: Configure MCP Servers (Optional)​

# Check if codanna is installed
which codanna

# If installed, copy MCP config
cp ~/.coditect/config/templates/mcp-codanna.json ~/.mcp.json

# Set required environment variables
export CODITECT_HOME="$HOME/.coditect"
export CODITECT_TENANT_ID="default"
export CODITECT_USER_ID="$USER"
python3 ~/.coditect/scripts/CODITECT-CORE-INITIAL-SETUP.py

This will:

  • Regenerate settings.json with correct paths
  • Configure hooks properly
  • Set up MCP servers if available
DocumentPurpose
ADR-074SessionStart governance architecture
ADR-057Initial setup script
CLAUDE.mdSection 3 - Governance Hooks

Verification Commands​

After remediation, verify with:

# Check CODITECT installation
[ -L ~/.coditect ] && echo "✓ Symlink OK" || echo "✗ Symlink missing"

# Check hooks registered
grep -A5 "SessionStart" ~/.claude/settings.json

# Test governance hook
python3 ~/.coditect/hooks/session_start_governance.py | python3 -m json.tool

# Verify MCP (if configured)
claude mcp list 2>/dev/null || echo "MCP not configured"

Report Status​

FieldValue
Status✅ Investigation Complete
Findings4 issues identified
SeverityHigh - Errors on every Bash command
Blocking Errorsettings.json path to wrong user

Immediate Fix Required​

Update settings.json to use correct local paths. This will stop the repeated error messages on every command.

Run the initial setup script to regenerate all configuration:

python3 ~/.coditect/scripts/CODITECT-CORE-INITIAL-SETUP.py

Optional: Install MCP Support​

# Install codanna (if available)
cargo install codanna

# Or build from source
cd ~/.coditect/tools/codanna && cargo build --release

Report Generated: 2026-01-22 Last Updated: 2026-01-22 Investigator: Claude Code (Opus 4.5)