v0.3.0: Hook System & Session Management

Clanker v0.3.0: Hook System & Session Management

This major release introduces a comprehensive event-driven hook system and full session management, enabling powerful new patterns for tool development and persistent conversation tracking.

🎉 Major Features

🪝 Hook System

A comprehensive event-driven architecture for extending Clanker functionality:

• Multiple Hook Types: Support for command, function, and tool hooks
• Lifecycle Events: Pre/Post tool execution, message processing, and session events
• Dynamic Registration: Tools can register hooks at runtime
• AI-Interpretable Output: Structured data that AI can understand and act upon
• Configuration Files: Define hooks in settings.json files at global, project, or local level

💾 Session Management

Full session persistence and lifecycle management:

• Automatic Saving: Sessions auto-save every 30 seconds (configurable)
• Message History: Complete conversation and tool execution tracking
• Context Preservation: Session-specific data persists across restarts
• JSONL Export: Export sessions as transcripts for analysis
• Session Events: Hook into session lifecycle events

📦 Local Tool Development

New --local flag for installing tools from local directories:

clanker install --local /path/to/your/tool

🔗 Tool Dependencies

Tools can now declare dependencies that are automatically installed:

{
  "clanker": {
    "dependencies": {
      "ziggle-dev/input": ">=1.0.0"
    }
  }
}

🔧 Enhanced Tool Context

Tools receive an enhanced context with new capabilities:

• context.hooks: Access to hook manager for dynamic registration
• context.tools: Execute other tools programmatically
• context.session: Session management access
• Settings management for secure credential storage

📚 Documentation

• Hook System Guide: Comprehensive guide to using hooks
• Session Management Guide: Learn about session persistence
• Migration Guide: Upgrade your tools to v0.3.0

🔄 Changes

• Tools can now execute other tools programmatically via context.tools.execute()
• Agent requires initialization with agent.initialize() for async operations
• Settings are now stored under tools section in settings.json
• Improved TypeScript types throughout the codebase
• Enhanced error handling and debugging output

🐛 Fixes

• Session message type compatibility with GrokMessage interface
• Async initialization race conditions in agent startup
• Tool dependency installation handling
• Various TypeScript type improvements

💡 Examples

Registering a Hook

context.hooks.register({
  id: 'my-hook',
  name: 'My Custom Hook',
  event: HookEvent.PostMessage,
  handler: async (input, context) => {
    console.log('Message posted:', input.content);
    return { continue: true };
  }
});

Using Session Data

// Store data in session
context.session.updateContext('myData', { count: 1 });

// Retrieve data
const data = context.session.getContext('myData');

Hook Configuration

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "bash",
      "hooks": [{
        "type": "command",
        "command": "echo 'Executing bash command'"
      }]
    }]
  }
}

🚀 Upgrading

This release maintains full backward compatibility. To use new features:

1. Update to v0.3.0: npm update -g @ziggler/clanker
2. Read the Migration Guide for best practices
3. Explore the new hook and session capabilities

🙏 Acknowledgments

Thanks to all contributors and the Clanker community for feedback and testing!

---

Full Changelog: v0.2.81...v0.3.0