cc-sessions-hooks

Type: WRITE-CAPABLE DAIC Modes: IMPLEMENT only Priority: High

Trigger Reference

This skill activates on:

• •Keywords: "hook", "sessions_enforce", "post_tool_use", "user_messages", "subagent_hooks", "shared_state"
• •Intent patterns: "(create|modify|fix).?hook", "hook.?(enforcement|validation)"
• •File patterns: sessions/hooks/**/*.js

From: skill-rules.json - cc-sessions-hooks configuration

Purpose

Specialized guidance for creating, modifying, and debugging cc-sessions hooks. Hooks are the enforcement layer that ensures DAIC discipline, write-gating, and framework integrity.

Core Behavior

When activated in IMPLEMENT mode with an active cc-sessions task:

1. •

   Hook Types & Purposes

   UserPromptSubmit Hook:

   • •Fires when user submits a prompt
   • •Use for: Mode transition triggers, startup protocols, context warnings
   • •Access: User message content, current session state

   PreToolUse Hook:

   • •Fires BEFORE any tool executes
   • •Use for: Write-gating enforcement, permission checks, guardrails
   • •Access: Tool name, parameters, current mode, task state
   • •Can: Block tool execution, modify parameters, inject warnings

   PostToolUse Hook:

   • •Fires AFTER tool completes
   • •Use for: State updates, logging, cleanup, validation
   • •Access: Tool name, parameters, result, errors

   SessionStart Hook:

   • •Fires when Claude Code session begins
   • •Use for: Initialization, state loading, environment checks
   • •Access: Session configuration, environment variables
2. •

   Hook Development Patterns

   Basic Hook Structure:

   javascript

   // sessions/hooks/example_hook.js
   module.exports = {
     name: 'example_hook',
     description: 'Brief description of what this hook does',
   
     async execute(context) {
       // Hook logic here
       // Return { success: true } or { success: false, error: 'message' }
     }
   };
   

   Enforcement Hook Pattern:

   javascript

   async execute(context) {
     const { toolName, toolParams, sessionState } = context;
   
     // Check conditions
     if (shouldBlock(toolName, sessionState)) {
       return {
         success: false,
         error: 'Tool blocked: [reason]',
         additionalContext: '[guidance for user]'
       };
     }
   
     return { success: true };
   }
   

3. •

   Write-Gating Enforcement

   The sessions_enforce.js hook is CRITICAL for framework integrity:

   What it enforces:

   • •Write tools (Edit, Write, MultiEdit) only in IMPLEMENT mode
   • •Only cc-sessions may modify CC_SESSION_MODE / CC_SESSION_TASK_ID
   • •Todo list changes require user approval
   • •No writes when no active task exists

   How to extend:

   • •Add new tool checks to WRITE_TOOLS array
   • •Add new state validations to checkWriteGating()
   • •Log enforcement decisions for debugging
   • •Never weaken existing checks
4. •

   Shared State Access

   Hooks can read/modify shared state:

   javascript

   const state = require('../sessions-state.json');
   const fs = require('fs');
   
   // Read state
   const currentMode = state.mode;
   const activeTask = state.task;
   
   // Modify state (carefully!)
   state.flags.contextWarning85 = true;
   fs.writeFileSync(
     path.join(__dirname, '../sessions-state.json'),
     JSON.stringify(state, null, 2)
   );
   

5. •

   Hook Execution Order

   Understand execution flow:

   1. •UserPromptSubmit (user input processed)
   2. •PreToolUse (before each tool call)
   3. •Tool executes
   4. •PostToolUse (after each tool call)

   Hooks execute synchronously within their phase.

Safety Guardrails

CRITICAL WRITE-GATING RULES:

• •✓ Only execute write operations when in IMPLEMENT mode
• •✓ Verify active cc-sessions task exists before writing hooks
• •✓ Follow approved manifest/todos from task file
• •✓ NEVER weaken write-gating logic
• •✓ NEVER allow hooks to bypass DAIC discipline

Hook-Specific Safety:

• •Test hooks thoroughly before deployment (they can break the entire framework)
• •Always return { success: true/false } from execute()
• •Include clear error messages when blocking actions
• •Log hook decisions for debugging
• •Never create infinite loops (hook triggering hook)
• •Handle async operations properly (await all promises)
• •Validate all inputs (context might be malformed)

State Mutation Safety:

• •Only modify state when necessary
• •Always validate state structure before writing
• •Use atomic writes (read-modify-write pattern)
• •Log state changes for auditability
• •Never corrupt state (keep backups during development)

Examples

When to Activate

✓ "Add a hook to validate task manifest format" ✓ "Fix the sessions_enforce.js write-gating for MultiEdit tool" ✓ "Create a PostToolUse hook to log all file modifications" ✓ "Modify UserPromptSubmit to detect '/squish' command" ✓ "Debug why the IMPLEMENT mode transition isn't triggering"

When NOT to Activate

✗ In DISCUSS/ALIGN/CHECK mode (hook development requires IMPLEMENT) ✗ No active cc-sessions task (violates write-gating) ✗ User wants to create non-hook cc-sessions code (use cc-sessions-core) ✗ Changes would weaken enforcement mechanisms

Hook Testing Checklist

Before deploying a new or modified hook:

• • Hook returns proper { success, error? } structure
• • Error messages are clear and actionable
• • Hook doesn't block legitimate operations
• • Hook doesn't create infinite loops
• • Async operations are properly awaited
• • State modifications are atomic and validated
• • Hook behavior logged for debugging
• • Tested in all DAIC modes
• • Doesn't introduce performance issues
• • Documented in hook file comments

Common Hook Patterns

1. Blocking Pattern

if (invalidCondition) {
  return {
    success: false,
    error: '[CATEGORY: Clear Error Message]',
    additionalContext: 'What user should do instead'
  };
}

2. Warning Pattern

if (warningCondition) {
  console.warn('[Hook Warning]', message);
  // Continue execution
}
return { success: true };

3. State Update Pattern

const state = loadState();
state.flags.someFlag = true;
saveState(state);
return { success: true };

4. Conditional Execution

if (context.toolName === 'Write' && context.sessionState.mode !== 'IMPLEMENT') {
  return { success: false, error: 'Write only in IMPLEMENT mode' };
}

Decision Logging

When creating or modifying hooks, log in context/decisions.md:

### Hook Change: [Date]
- **Hook:** sessions/hooks/sessions_enforce.js
- **Change:** Added MultiEdit to WRITE_TOOLS array
- **Rationale:** MultiEdit can write to multiple files, needs same gating as Write/Edit
- **Testing:** Verified blocks in DISCUSS, allows in IMPLEMENT
- **Risk:** Low (additive change, follows existing pattern)

Related Skills

• •cc-sessions-core - For broader framework development beyond hooks
• •framework_health_check - To validate hook behavior after changes
• •framework_repair_suggester - If hooks malfunction or cause framework issues
• •daic_mode_guidance - For understanding mode transitions that hooks enforce

Last Updated: 2025-11-15 Framework Version: 2.0