Add an extension that scans .claude/rules/ folder for project-specific
rules and lists them in the system prompt. The agent can then load
relevant rules using the read tool when needed.
Breaking changes:
- Settings: 'hooks' and 'customTools' arrays replaced with 'extensions'
- CLI: '--hook' and '--tool' flags replaced with '--extension' / '-e'
- API: HookMessage renamed to CustomMessage, role 'hookMessage' to 'custom'
- API: FileSlashCommand renamed to PromptTemplate
- API: discoverSlashCommands() renamed to discoverPromptTemplates()
- Directories: commands/ renamed to prompts/ for prompt templates
Migration:
- Session version bumped to 3 (auto-migrates v2 sessions)
- Old 'hookMessage' role entries converted to 'custom'
Structural changes:
- src/core/hooks/ and src/core/custom-tools/ merged into src/core/extensions/
- src/core/slash-commands.ts renamed to src/core/prompt-templates.ts
- examples/hooks/ and examples/custom-tools/ merged into examples/extensions/
- docs/hooks.md and docs/custom-tools.md merged into docs/extensions.md
New test coverage:
- test/extensions-runner.test.ts (10 tests)
- test/extensions-discovery.test.ts (26 tests)
- test/prompt-templates.test.ts
When hooks are loaded via jiti, they get a separate module instance from
the main app. This means the global 'theme' variable in the hook's module
is never initialized. Adding an optional theme parameter allows hooks to
pass the theme from ctx.ui.custom() callback.
Usage in hooks:
getSettingsListTheme(theme) // theme from ctx.ui.custom callback
- HookError now includes optional stack field
- Hook error display shows stack trace in dim color below error message
- tools.ts: create SettingsListTheme using the theme passed to ctx.ui.custom()
instead of using getSettingsListTheme() which depends on global theme
- before_agent_start handlers can return systemPromptAppend to dynamically
append text to the system prompt for that turn
- Multiple hooks' systemPromptAppend strings are concatenated
- Multiple hooks' messages are now all injected (not just first)
- Tool registry now contains ALL built-in tools (read, bash, edit, write,
grep, find, ls) regardless of --tools flag
- --tools only sets initially active tools, hooks can enable any via
setActiveTools()
- System prompt automatically rebuilds when tools change, updating tool
descriptions and guidelines
- Add pirate.ts example hook demonstrating systemPromptAppend
- Update hooks.md with systemPromptAppend documentation
- /tools command opens SettingsList-based selector for all loaded tools
- Space/Enter toggles individual tools between enabled/disabled
- Changes apply immediately on toggle (like /settings)
- Tool selection persisted to session via appendEntry()
- State restored from current branch on session_start, session_tree, session_branch
- Uses getBranch() to respect branch-specific tool configuration
- Export getSettingsListTheme and getSelectListTheme for hooks to use
1. Merge setWidget and setWidgetComponent into single overloaded method
- Accepts either string[] or component factory function
- Uses single Map<string, Component> internally
- String arrays wrapped in Container with Text components
2. Use KeyId type for registerShortcut instead of plain string
- Import Key from @mariozechner/pi-tui
- Update plan-mode example to use Key.shift('p')
- Type-safe shortcut registration
3. Fix tool API docs
- Both built-in and custom tools can be enabled/disabled
- Removed incorrect 'custom tools always active' statement
4. Use matchesKey instead of matchShortcut (already done in rebase)
- Non-tool turns (analysis, explanation) now mark step complete at turn_end
- Clean up extracted step text: remove markdown, truncate to 50 chars
- Remove redundant action words (Use, Run, Execute, etc.)
- Track toolsCalledThisTurn flag to distinguish tool vs non-tool turns
- No longer relies on agent outputting [STEP N DONE] tags
- Each successful tool_result marks the next uncompleted step done
- Much more reliable than expecting LLM to follow tag format
- Simplified execution context (no special instructions needed)
- Steps are numbered 1, 2, 3... which is easier for agent to track
- Agent outputs [STEP 1 DONE], [STEP 2 DONE] instead of [DONE:abc123]
- Clearer instructions in execution context
- Was incorrectly typed as Message[] which caused filtered messages to be ignored
- Context event filter in plan-mode hook should now properly remove stale [PLAN MODE ACTIVE] messages
- Filter out old [PLAN MODE ACTIVE] and [EXECUTING PLAN] messages
- Fresh context injected via before_agent_start with current state
- Agent now correctly sees tools are enabled when executing
- Reverted to ID-based tracking with [DONE:id] tags
- Simplified execution message (no need to override old context)
- Add explicit [PLAN MODE DISABLED - EXECUTE NOW] message
- Emphasize FULL access to all tools in execution context
- List remaining steps in execution context
- Prevents agent from thinking it's still restricted
- Remove ugly [DONE:id] tags - users no longer see IDs
- Track progress via keyword matching on tool results
- Extract significant keywords from todo text
- Match tool name + input against todo keywords
- Sequential preference: first uncompleted item gets bonus score
- Much cleaner UX - progress tracked silently in background
- New text_delta hook event fires for each chunk of streaming text
- Enables real-time monitoring of agent output
- Plan-mode hook now updates todo progress as [DONE:id] tags stream in
- Each todo item has unique ID for reliable tracking
- Each todo item gets a unique ID (e.g., abc123)
- Agent marks items complete by outputting [DONE:id]
- IDs shown in chat and in execution context
- Agent instructed to output [DONE:id] after each step
- Removed unreliable tool-counting heuristics
- After agent creates plan: show todo list as a message in chat
- During execution: show widget under Working indicator with checkboxes
- Check off items as they complete with strikethrough
- ctx.ui.setWidget(key, lines) for multi-line displays above editor
- Widgets appear below 'Working...' indicator, above editor
- Supports ANSI styling including strikethrough
- Added theme.strikethrough() method
- Plan-mode hook now shows todo list with checkboxes
- Completed items show checked box and strikethrough text
- Extract numbered steps from agent's plan response
- Track progress during execution with footer indicator (📋 2/5)
- /todos command to view current plan progress
- State persists across sessions including todo progress
- Agent prompted to format plans as numbered lists for tracking
Hook API additions:
- pi.getTools() / pi.setTools(toolNames) - dynamically enable/disable tools
- pi.registerFlag(name, options) / pi.getFlag(name) - register custom CLI flags
- pi.registerShortcut(shortcut, options) - register keyboard shortcuts
Plan mode hook (examples/hooks/plan-mode.ts):
- /plan command or Shift+P shortcut to toggle
- --plan CLI flag to start in plan mode
- Read-only tools: read, bash, grep, find, ls
- Bash restricted to non-destructive commands (blocks rm, mv, git commit, etc.)
- Interactive prompt after each response: execute, stay, or refine
- Shows plan indicator in footer when active
- State persists across sessions
- Add pi.getTools() and pi.setTools(toolNames) to HookAPI
- Hooks can now enable/disable tools dynamically
- Changes take effect on next agent turn
New example hook: plan-mode.ts
- Claude Code-style read-only exploration mode
- /plan command toggles plan mode on/off
- Plan mode tools: read, bash, grep, find, ls
- Edit/write tools disabled in plan mode
- Injects context telling agent about restrictions
- After each response, prompts to execute/stay/refine
- State persists across sessions
- pi.sendMessage(msg, options?) now accepts { triggerTurn?, deliverAs? }
- deliverAs: 'steer' (default) or 'followUp' controls delivery timing
- Update all mode handlers to pass options through
- Update file-trigger example to use new API
- Update CHANGELOG
- /todos command displays all todos on current branch with custom UI
- Update hooks.md to clarify components must not be wrapped in Box/Container
- Cross-reference tool and hook in example READMEs
