feat(hooks): event-driven hook system with skill disable support (#1932)

[lailoo]

Summary

• Feature: Event-driven hook system + skill disable/enable support
• Architecture: hooks/ package with HookStorage (JSON state), skills.py unaware of hooks
• User Extensibility: JSON-based user hooks (no code changes required)

Fixes #1932

Problem

Users reported that skills cannot be disabled, only deleted. The initial implementation modified SKILL.md frontmatter directly, which was invasive and required complex file manipulation (especially for builtin skills).

Solution: Event-Driven Hook System

Instead of modifying skill files, we introduced a hook system that filters skills at context-build time via a separate JSON state file.

Architecture

nanobot/agent/hooks/
├── __init__.py          # Package exports
├── base.py              # HookEvent enum, HookResult dataclass, Hook ABC
├── registry.py          # HookRegistry with emit() event dispatch
├── storage.py           # HookStorage (JSON persistence)
├── filters.py           # SkillsEnabledFilter (built-in hook)
└── json_loader.py       # User-defined hooks via JSON config

Core Concepts (aligned with Claude Code)

Concept	Implementation
Lifecycle events	HookEvent enum: SessionStart, PreToolUse, PostToolUse, PreBuildContext, Stop
Matcher filtering	Hook.matcher regex — only run hook when tool name matches
Block/pass semantics	HookResult.proceed — False short-circuits remaining hooks
Priority execution	Hook.priority — lower value runs first
Data modification	HookResult.modified_data — chained between hooks

Key Design Decisions

• JSON state vs frontmatter: Skill files are never modified. State stored in hooks/state.json
• User extensibility: Users can define hooks via .nanobot/hooks.json without code changes
• Separation of concerns: skills.py unaware of hooks — all filtering happens in context.py
• Lightweight subagent filtering: Subagents use HookStorage + SkillsLoader directly (no heavy ContextBuilder rebuild)
• Exception safety: Hook exceptions are caught and logged, never break the chain

Changes

New: nanobot/agent/hooks/ package

• base.py — HookEvent enum, HookResult dataclass, Hook ABC with on_event(), matcher, priority
• registry.py — HookRegistry.emit() dispatches events by priority, matcher filtering for tool events, short-circuit on proceed=False
• filters.py — SkillsEnabledFilter listens to PRE_BUILD_CONTEXT to filter disabled skills from prompt
• storage.py — HookStorage persists disabled skills in JSON
• json_loader.py — JsonConfigHook loads user-defined hooks from .nanobot/hooks.json, executes shell commands with exit code semantics (0=pass, 2=block)

Modified files

• nanobot/agent/context.py — Initialize HookRegistry with built-in + JSON hooks; _build_filtered_skills_summary() and _get_filtered_always_skills() emit PRE_BUILD_CONTEXT; _apply_skills_hooks() as unified entry point
• nanobot/agent/skills.py — Added build_skills_summary_from() to accept pre-filtered skills list; no hook dependency
• nanobot/agent/loop.py — Inject hook events: SessionStart, PreToolUse (can block), PostToolUse, Stop
• nanobot/agent/subagent.py — Lightweight filtering via HookStorage + SkillsLoader (respects disabled skills)
• nanobot/cli/commands.py — skills list/enable/disable commands using HookStorage directly

New documentation

• docs/USER_HOOKS.md — Comprehensive guide for user-defined hooks with examples

Tests

• tests/test_hook_system.py — 12 tests: emit, priority, blocking, matcher, data chaining, exception safety
• tests/test_skill_disable.py — 11 tests: storage, filter, context builder, persistence
• tests/test_json_hooks.py — 5 tests: JSON loading, blocking, passing, env vars

User Workflow

Built-in: Skill Disable/Enable

# List all skills with status
nanobot skills list

# Disable a skill (state stored in hooks/state.json, skill files untouched)
nanobot skills disable weather

# Re-enable
nanobot skills enable weather

User-Defined Hooks

Create .nanobot/hooks.json:

{
  "hooks": [
    {
      "name": "block-dangerous-commands",
      "event": "PreToolUse",
      "matcher": "^exec$",
      "command": "~/.nanobot/hooks/security-check.sh",
      "priority": 10
    }
  ]
}

See docs/USER_HOOKS.md for more examples.

Test Plan

• 28 unit tests pass (12 hook system + 11 skill disable + 5 JSON hooks)
• 12 E2E tests pass (CLI commands + prompt filtering + state persistence)
• Integration verification: disable → prompt excludes skill → enable → prompt includes skill
• Event emission verified: SessionStart, PreToolUse, PostToolUse, PreBuildContext, Stop
• Blocking semantics verified: PreToolUse hook can prevent tool execution
• Matcher filtering verified: regex-based tool name matching
• Exception safety verified: broken hooks don't break the chain
• Subagent filtering verified: subagents respect disabled skills
• JSON user hooks verified: shell command execution with exit code semantics
• Backward compatible: no hook = no filtering, zero impact on existing behavior

Future Extensibility

The hook system enables:

• Security hooks: Block dangerous tool calls via PreToolUse
• Audit logging: Record tool usage via PostToolUse
• Custom filters: Register additional hooks without modifying existing code
• User-defined workflows: JSON config allows users to customize behavior without code changes

[chengyongru]

Hi @lailoo ,

In my perspective , supporting multiple disabled formats is unnecessary. And thanks for your work!

[Re-bin]

Hi, very nice feature! Is it ready for reviewing?

[lailoo]

Hi @lailoo ,

In my perspective , supporting multiple disabled formats is unnecessary. And thanks for your work!

Hi @chengyongru,thanks for the valuable feedback! I'll optimize it to simplify the disabled format support.

[lailoo]

Hi, very nice feature! Is it ready for reviewing?

Hi @Re-bin thanks for your interest! It will be ready very soon - just need to run a full round of testing and verification first.

[lailoo]

@Re-bin @chengyongru I've made some updates — would appreciate another look.

I created a test-verify skill to verify the enable/disable functionality across different scenarios.

Test Scenarios

• Enable → Disable → Enable workflow
• Verify skill visibility in new sessions after each state change
• Verify CLI list shows correct status (✓/✗)

Test Steps

1. Create test skill and verify it's visible in new session
2. Disable the skill and verify it disappears from new session
3. Enable the skill and verify it reappears in new session

Test Results

[lailoo]

However during testing, I discovered that after disabling a skill, the agent may still "see" the disabled skill within the same conversation session.

Root Causes

1. Conversation History Interference: If the agent mentioned the skill in previous responses, LLMs tend to maintain consistency with conversation history,
   even after the system prompt has been updated.

2. File System Visibility: Disabling a skill only sets enabled: false in the frontmatter—the file still exists in the skills/ directory. The agent can
   use list_dir to inspect the filesystem and may conclude the skill is still available upon finding the file. By contrast, uninstalling directly deletes the
   file, so the agent can confirm its absence after checking the directory.

Current Solution

• Disabled skills are completely removed from the system prompt (same effect as uninstalling)
• Works correctly in new sessions
• CLI displays a hint: "Start a new session or use a different session ID (-s flag) to see the change"

Complete Solution (Future Consideration)

Move disabled skills to a hidden directory (e.g., skills/.disabled/) so they physically disappear from the skills/ directory. This would prevent the agent
from discovering them through either the system prompt or filesystem inspection. Skills would be moved back when re-enabled.

This approach has higher implementation complexity and is more invasive, so it's not adopted at this time.

---

I'd love to hear your thoughts on this approach. If you have any concerns or suggestions for improvement, please let me know!

[Re-bin]

However during testing, I discovered that after disabling a skill, the agent may still "see" the disabled skill within the same conversation session.

Root Causes

1. Conversation History Interference: If the agent mentioned the skill in previous responses, LLMs tend to maintain consistency with conversation history,
   even after the system prompt has been updated.
2. File System Visibility: Disabling a skill only sets enabled: false in the frontmatter—the file still exists in the skills/ directory. The agent can
   use list_dir to inspect the filesystem and may conclude the skill is still available upon finding the file. By contrast, uninstalling directly deletes the
   file, so the agent can confirm its absence after checking the directory.

Current Solution

• Disabled skills are completely removed from the system prompt (same effect as uninstalling)
• Works correctly in new sessions
• CLI displays a hint: "Start a new session or use a different session ID (-s flag) to see the change"

Complete Solution (Future Consideration)

Move disabled skills to a hidden directory (e.g., skills/.disabled/) so they physically disappear from the skills/ directory. This would prevent the agent from discovering them through either the system prompt or filesystem inspection. Skills would be moved back when re-enabled.

This approach has higher implementation complexity and is more invasive, so it's not adopted at this time.

I'd love to hear your thoughts on this approach. If you have any concerns or suggestions for improvement, please let me know!

Nice idea. Please give me some time to think about this issue carefully :)

[chengyongru]

#1721

Suddenly remembered I had a similar PR before.