Agent Skills: Notification Triggers

Notification Triggers

Step 1: Gather Context

Read relevant files and understand requirements

Step 2: Execute

Perform the skill's main function using available tools

Step 3: Output

Return results and save artifacts if applicable

</execution_process>

<best_practices>

1. Follow existing project patterns: Follow this practice for best results
2. Document all outputs clearly: Follow this practice for best results
3. Handle errors gracefully: Follow this practice for best results

</best_practices> </instructions>

# Invoke this skill
/notification-triggers [arguments]

# Or run the script directly
node .claude/skills/notification-triggers/scripts/main.cjs --help

</usage_example> </examples>

Trigger Configuration Schema

Notification triggers are defined in .claude/context/runtime/notification-triggers.json:

{
  "version": "1.0",
  "triggers": [
    {
      "id": "unique-trigger-id",
      "name": "Human-readable trigger name",
      "description": "What this trigger detects",
      "type": "error|regex|token_threshold|pattern",
      "enabled": true,
      "condition": {
        "pattern": "regex pattern to match",
        "minTokens": 120000,
        "minOccurrences": 3,
        "scope": "session|task|global"
      },
      "actions": [
        {
          "type": "log|alert|spawn_agent|interrupt",
          "target": "agent-name|file-path",
          "message": "Action message template"
        }
      ]
    }
  ]
}

Condition Fields:

• pattern — JavaScript RegExp (error/regex triggers)
• minTokens — Token threshold for alert (token_threshold trigger)
• minOccurrences — Pattern match count before triggering (pattern trigger)
• scope — Where to evaluate: current session, task, or cumulative

Action Types:

• log — Write to .claude/context/runtime/notifications.jsonl
• alert — Display alert in session output
• spawn_agent — Create Task() to handle the notification
• interrupt — Pause execution for user input

Trigger Evaluation Workflow

Step 1: Load Configuration

1. Read .claude/context/runtime/notification-triggers.json
2. Validate schema against notification-triggers.schema.json
3. Filter to enabled triggers only

Step 2: Evaluate Conditions For each enabled trigger:

• Error triggers: Check tool output for exception patterns
• Regex triggers: Match pattern against tool stdout/stderr
• Token threshold: Sum session tokens, compare to minTokens
• Pattern triggers: Count regex occurrences in recent output, compare to minOccurrences

Step 3: Execute Matched Actions If condition is true:

1. Process action in order (log → alert → spawn → interrupt)
2. Render message templates with context variables
3. Record trigger fire in .claude/context/runtime/notification-log.jsonl

Step 4: Record Event

{
  "timestamp": "ISO-8601",
  "triggerId": "id",
  "triggerName": "name",
  "matched": true,
  "context": {
    "sessionId": "current session",
    "taskId": "current task",
    "tokenCount": number
  }
}

Action Execution Logic

Log Action

// Append to notifications.jsonl
fs.appendFileSync(
  notificationsPath,
  JSON.stringify({
    timestamp: new Date().toISOString(),
    triggerId: trigger.id,
    message: renderTemplate(action.message, context),
    severity: 'info|warn|error',
  }) + '\n'
);

Alert Action

// Write to stdout with standard format
console.log(`\n🔔 NOTIFICATION [${trigger.name}]\n${renderedMessage}\n`);

Spawn Agent Action

// Create async task to handle notification
Task({
  task_id: `notify-${trigger.id}-${Date.now()}`,
  subagent_type: action.target,
  prompt: `Handle notification: ${trigger.description}\nContext: ${JSON.stringify(context)}`,
});

Interrupt Action

// Pause and ask user
const response = await AskUserQuestion({
  question: `${trigger.name}: ${action.message}\n\nContinue? [y/n]`,
});
if (response.toLowerCase() !== 'y') {
  process.exit(0);
}

Example Configurations

Example 1: High Token Usage Alert

{
  "id": "token-threshold-warning",
  "name": "High Token Usage Warning",
  "description": "Alert when session exceeds 120K tokens",
  "type": "token_threshold",
  "enabled": true,
  "condition": {
    "minTokens": 120000,
    "scope": "session"
  },
  "actions": [
    {
      "type": "log",
      "message": "Session token count: ${tokenCount}"
    },
    {
      "type": "alert",
      "message": "⚠️ Token budget at 60% — consider compression"
    },
    {
      "type": "spawn_agent",
      "target": "context-compressor",
      "message": "Proactive context compression triggered"
    }
  ]
}

Example 2: Error Pattern Detection

{
  "id": "hook-error-pattern",
  "name": "Hook Execution Errors",
  "description": "Detect repeated hook failures in session",
  "type": "pattern",
  "enabled": true,
  "condition": {
    "pattern": "hook.*error|hook.*failed|HOOK_ERROR",
    "minOccurrences": 3,
    "scope": "session"
  },
  "actions": [
    {
      "type": "log",
      "message": "Hook error pattern detected: ${patternMatches} occurrences"
    },
    {
      "type": "alert",
      "message": "🚨 Hook system unstable — check logs"
    }
  ]
}

Example 3: Security Pattern Alert

{
  "id": "security-violation-detect",
  "name": "Security Policy Violation",
  "description": "Alert on potential security violations",
  "type": "regex",
  "enabled": true,
  "condition": {
    "pattern": "shell:\\s*true|JSON\\.parse\\(|eval\\(|exec\\(",
    "scope": "task"
  },
  "actions": [
    {
      "type": "alert",
      "message": "⚠️ Potential security issue detected — review code"
    },
    {
      "type": "spawn_agent",
      "target": "security-architect",
      "message": "Review potential security issue in task output"
    },
    {
      "type": "interrupt",
      "message": "Continue despite security concern?"
    }
  ]
}

Search Protocol

For code discovery, follow this priority order:

1. pnpm search:code "<query>" (Primary intent-based search)
2. ripgrep (for exact keyword/regex matches)
3. semantic/structural search via code tools if available

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md
cat .claude/context/memory/decisions.md

After completing:

• New pattern → .claude/context/memory/learnings.md
• Issue found → .claude/context/memory/issues.md
• Decision made → .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.