Design: Hook-Based Tool Confirmations

Design: Hook-Based Tool Confirmations

Issue: #1104 Author: Bob Date: 2026-01-10 Status: In Progress

Implementation Status

Current state: Phases 1-4, 6, 7, 8 complete. Phase 5 was reverted.

Implemented:

• confirm_func in chat.py always uses hooks (no ask_execute fallback)
• confirm_func in api.py (v1) uses hooks when available, falling back to auto-confirm
• Server's HTTP endpoint resolves hook-based confirmations via _resolve_hook_confirmation
• Server hook now emits SSE events and blocks until client responds via HTTP endpoint
• Context vars (current_conversation_id, current_session_id) provide session context to hooks

Phase 5 Reversion Notes: The Phase 5 "tool migration" was reverted because:

1. It added ~88 lines without removing any (violated simplification goal)
2. Tools were creating ToolUse objects just to pass to confirmation - this is redundant since ToolUse already exists at the ToolUse.execute() level
3. The _execute_with_hook_confirmation() helper duplicated logic from execute_with_confirmation()

The hook system works correctly through the confirm_func bridge without requiring tools to create ToolUse objects.

Architecture notes:

• V1 API: Uses hook-aware confirm_func, auto-confirms when no context vars set (legacy behavior)
• V2 API: Uses separate pending_tools mechanism + hook resolution for HTTP confirmations
• CLI: Uses hook-aware confirm_func, routes through cli_confirm_hook when registered
• Hooks receive confirmation requests via make_confirm_func_from_hooks() bridge

Phase 6.1 Notes (Completed): Consolidated duplicate _print_preview in cli_confirm.py by importing shared print_preview from ask_execute.py. This reduced cli_confirm.py by 10 lines (245 → 235) and eliminates duplicate preview logic.

Phase 6.4 Notes (Completed): Extracted shared print_confirmation_help() function in ask_execute.py. Both ask_execute and cli_confirm_hook now use this shared function instead of maintaining duplicate help text. Reduced cli_confirm.py by 19 lines.

Phase 6.2-6.3 Notes (Completed): Centralized auto-confirm state in confirm.py with unified functions:

• set_auto_confirm(count) - Set auto-confirm (count or infinite)
• reset_auto_confirm() - Reset to defaults
• check_auto_confirm() - Check and decrement (returns tuple)
• is_auto_confirm_active() - Check without decrementing

Both cli_confirm.py and ask_execute.py now use this centralized state instead of maintaining their own duplicate globals. Server auto-confirm is also unified - server_confirm_hook now checks centralized state first before checking session context.

Phase 7 Notes (Completed): Removed ask_execute fallback from chat.py per Erik's suggestion:

• confirm_func now always uses hooks via make_confirm_func_from_hooks()
• CLI hook registration moved into init_hooks() via hook_allowlist parameter
• Auto-confirm state converted to ContextVars for thread safety in server mode
• When no_confirm=True, no CLI hook is registered, so get_confirmation() auto-confirms

Phase 8 Notes (Completed): Tools register their own auto-approve hooks via ToolSpec.hooks per Erik's suggestion:

• Modified get_confirmation() to support fall-through: hooks returning None pass to next hook
• Hooks are tried in priority order (highest first), first non-None result wins
• Updated ToolConfirmHook protocol: now returns ConfirmationResult | None
• Shell tool registers shell_allowlist_hook with priority 10 (higher than CLI hook at 0)
• Shell allowlist hook auto-confirms allowlisted commands, returns None for others
• This keeps ToolSpec clean (no new fields) while enabling tool-specific auto-approve
• Tests added: 3 fall-through tests + 5 shell allowlist tests (27 total passing)

Example usage for other tools:

def my_tool_auto_approve(tool_use, preview=None, workspace=None):
    """Auto-approve safe operations, fall through for others."""
    if is_safe(tool_use):
        return ConfirmationResult.confirm()
    return None  # Fall through to CLI/server hook

tool = ToolSpec(
    name="my_tool",
    hooks={
        "auto_approve": ("tool_confirm", my_tool_auto_approve, 10),
    },
    ...
)

Next steps:

• ✅ Phase 6.1-6.4: Consolidation complete
• ✅ Phase 7: Remove ask_execute fallback
• ✅ Phase 8: Tool auto-approve via ToolSpec hooks
• Phase 6.5: Document hook API for custom confirmation backends
• Phase 6.6: Add examples for new backends (GUI, Discord bot)
• Future: Consider moving confirmation to ToolUse.execute()

Problem Statement

gptme currently has two separate implementations for tool confirmation:

1. CLI (ask_execute.py): Interactive terminal-based confirmation with rich features
2. Server V2 (api_v2_sessions.py): SSE event-based confirmation with pending tool queue

These implementations are not harmonized:

• CLI uses ask_execute() called directly from tools via ConfirmFunc
• Server V2 uses pending_tools dict with ToolExecution state machine
• Server V1 has no real confirmation support (always auto-confirms)
• No shared abstraction for confirmation logic

Goals

1. Harmonize CLI and Server confirmation implementations
2. Leverage hooks for extensibility and clean separation
3. Maintain existing functionality (edit, copy, auto-confirm)
4. Simplify tool implementations by removing confirmation boilerplate
5. Enable new confirmation backends (e.g., GUI, Discord bot)

Current Architecture

CLI Flow

User/Tool → execute_with_confirmation() → ask_execute() → User Input → Execute
                                              ↓
                                        print_preview()
                                              ↓
                                    editable/copiable state

Server V2 Flow

Tool Execute → Store in pending_tools → SSE Event (tool_pending) → Client Decides
                                                                         ↓
                                                              /api/v2/.../tool/confirm
                                                                         ↓
                                                              Execute or Skip

Key Differences

Proposed Design

Core Concept: tool.confirm Hook

Introduce a new hook type tool.confirm that handles the confirmation decision:

class HookType(str, Enum):
    # Existing hooks
    TOOL_EXECUTE_PRE = "tool.execute.pre"
    TOOL_EXECUTE_POST = "tool.execute.post"

    # New confirmation hook
    TOOL_CONFIRM = "tool.confirm"

Confirmation Protocol

The tool.confirm hook follows a request-response protocol:

1. Request Phase: System triggers tool.confirm with tool details
2. Decision Phase: Hook implementation gathers user/client decision
3. Response Phase: Hook yields a ConfirmationResult

from dataclasses import dataclass
from typing import Literal

@dataclass
class ConfirmationResult:
    """Result of a tool confirmation request."""

    action: Literal["confirm", "skip", "edit"]
    edited_content: str | None = None
    auto_confirm_remaining: int = 0

Hook Protocol

from typing import Protocol, Generator
from pathlib import Path

class ToolConfirmHook(Protocol):
    """Hook for tool confirmation decisions."""

    def __call__(
        self,
        tooluse: "ToolUse",
        preview: str | None,
        workspace: Path | None,
    ) -> Generator[ConfirmationResult, None, None]:
        """Request confirmation for tool execution.

        Args:
            tooluse: The tool about to be executed
            preview: Optional preview content for display
            workspace: Workspace directory path

        Yields:
            ConfirmationResult with the user's decision
        """
        pass

Implementation Architecture

                     ┌─────────────────────────────────────┐
                     │         ToolUse.execute()           │
                     └─────────────────┬───────────────────┘
                                       │
                                       ▼
                     ┌─────────────────────────────────────┐
                     │    trigger_hook(TOOL_CONFIRM)       │
                     └─────────────────┬───────────────────┘
                                       │
              ┌────────────────────────┼────────────────────────┐
              │                        │                        │
              ▼                        ▼                        ▼
    ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
    │ CLI Confirm Hook│      │Server Confirm   │      │ Auto Confirm    │
    │ (terminal input)│      │Hook (SSE/HTTP)  │      │ Hook (always)   │
    └────────┬────────┘      └────────┬────────┘      └────────┬────────┘
             │                        │                        │
             ▼                        ▼                        ▼
    ┌─────────────────────────────────────────────────────────────────────┐
    │                      ConfirmationResult                              │
    └─────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
                     ┌─────────────────────────────────────┐
                     │      Execute or Skip Tool           │
                     └─────────────────────────────────────┘

Hook Implementations

1. CLI Confirmation Hook

def cli_confirm_hook(
    tooluse: ToolUse,
    preview: str | None,
    workspace: Path | None,
) -> Generator[ConfirmationResult, None, None]:
    """CLI-based confirmation using terminal input."""

    # Show preview if available
    if preview:
        print_preview(preview, tooluse.tool, copy=True)

    # Make content editable
    if tooluse.content:
        set_editable_text(tooluse.content, get_extension(tooluse))

    # Get user decision via terminal prompt
    confirmed = ask_execute(f"Execute {tooluse.tool}?")

    if confirmed:
        edited = get_editable_text() if editable else None
        was_edited = edited != tooluse.content if edited else False
        yield ConfirmationResult(
            action="edit" if was_edited else "confirm",
            edited_content=edited if was_edited else None,
        )
    else:
        yield ConfirmationResult(action="skip")

2. Server Confirmation Hook

def server_confirm_hook(
    tooluse: ToolUse,
    preview: str | None,
    workspace: Path | None,
) -> Generator[ConfirmationResult, None, None]:
    """Server-based confirmation using SSE events."""

    session = get_current_session()

    # Check auto-confirm
    if session.auto_confirm_count > 0:
        session.auto_confirm_count -= 1
        yield ConfirmationResult(action="confirm")
        return

    # Create pending tool entry
    tool_id = str(uuid.uuid4())
    session.pending_tools[tool_id] = ToolExecution(
        tooluse=tooluse,
        status=ToolStatus.PENDING,
    )

    # Emit SSE event
    emit_event("tool_pending", {
        "tool_id": tool_id,
        "tool": tooluse.tool,
        "content": tooluse.content,
        "preview": preview,
    })

    # Wait for client decision (via HTTP endpoint)
    result = wait_for_confirmation(tool_id)
    yield result

3. Auto-Confirm Hook (Non-Interactive Mode)

def auto_confirm_hook(
    tooluse: ToolUse,
    preview: str | None,
    workspace: Path | None,
) -> Generator[ConfirmationResult, None, None]:
    """Always confirms - for non-interactive/autonomous mode."""
    yield ConfirmationResult(action="confirm")

Integration Points

Tool Execution Flow

# In tools/base.py - ToolUse.execute()

def execute(self, confirm: ConfirmFunc) -> Generator[Message, None, None]:
    # Trigger confirmation hook
    confirm_results = list(trigger_hook(
        HookType.TOOL_CONFIRM,
        tooluse=self,
        preview=self.get_preview(),
        workspace=get_workspace(),
    ))

    if not confirm_results:
        # No confirmation hook registered - fall back to confirm function
        if not confirm(f"Execute {self.tool}?"):
            yield Message("system", "Aborted")
            return
        result = ConfirmationResult(action="confirm")
    else:
        result = confirm_results[0]

    # Handle result
    if result.action == "skip":
        yield Message("system", "Operation skipped by user")
        return

    if result.action == "edit" and result.edited_content:
        self.content = result.edited_content

    # Proceed with execution
    yield from self._do_execute()

Hook Registration

# In gptme/main.py or gptme/chat.py

def init_confirmation_hooks(interactive: bool, server_mode: bool):
    """Register appropriate confirmation hook based on mode."""

    if server_mode:
        register_hook(
            name="server_confirm",
            hook_type=HookType.TOOL_CONFIRM,
            func=server_confirm_hook,
            priority=100,
        )
    elif interactive:
        register_hook(
            name="cli_confirm",
            hook_type=HookType.TOOL_CONFIRM,
            func=cli_confirm_hook,
            priority=100,
        )
    else:
        register_hook(
            name="auto_confirm",
            hook_type=HookType.TOOL_CONFIRM,
            func=auto_confirm_hook,
            priority=100,
        )

Evaluation Dimensions

Dimension 1: Code Simplification

Criteria: Does this reduce complexity in tool implementations?

Current Assessment: 4/5

Rationale:

• Tools no longer need to handle confirmation logic directly
• execute_with_confirmation() helper can be simplified or deprecated
• Single point of confirmation logic vs scattered across tools
• Minor complexity added in hook registration

Dimension 2: Extensibility

Criteria: How easy is it to add new confirmation backends?

Current Assessment: 5/5

Rationale:

• New backends just register a hook function
• No core code changes needed
• Examples: Discord bot, GUI, mobile app, voice confirmation
• Clear protocol makes implementation straightforward

Dimension 3: Backward Compatibility

Criteria: Does this maintain existing behavior and APIs?

Current Assessment: 4/5

Rationale:

• ConfirmFunc type can still work (fallback when no hook)
• ask_execute() still functions (wrapped by CLI hook)
• Server V2 API unchanged externally
• Internal refactoring required for execute_with_confirmation()

Dimension 4: Testability

Criteria: How testable is the new design?

Current Assessment: 5/5

Rationale:

• Hooks are pure functions that can be mocked
• ConfirmationResult is a simple dataclass
• Can test each hook implementation independently
• Can test tool execution with different hook configurations

Dimension 5: Server Harmonization

Criteria: Does this improve CLI/Server code sharing?

Current Assessment: 4/5

Rationale:

• Same protocol for both CLI and Server
• Same ConfirmationResult type
• Tool code doesn't need to know which environment
• Server still needs SSE/HTTP infrastructure (inherent)

Dimension 6: Performance Impact

Criteria: Does this affect performance?

Current Assessment: 5/5

Rationale:

• Hook dispatch is O(1) lookup
• No additional I/O or computation
• Existing confirmation logic just moves to hook
• Could potentially improve by reducing redundant preview generation

Overall Evaluation

Implementation Plan

Phase 1: Foundation (1-2 days)

1. Add HookType.TOOL_CONFIRM enum value
2. Add ToolConfirmHook protocol
3. Add ConfirmationResult dataclass
4. Update hook type overloads

Phase 2: CLI Implementation (2-3 days)

1. Create gptme/hooks/cli_confirm.py
2. Refactor ask_execute.py to be callable by hook
3. Register CLI hook in interactive mode
4. Test with existing CLI flows

Phase 3: Server Implementation (2-3 days)

1. Create gptme/hooks/server_confirm.py
2. Integrate with api_v2_sessions.py pending_tools
3. Register Server hook in server mode
4. Test with existing Server V2 flows

Phase 4: Tool Migration (3-5 days)

1. Update ToolUse.execute() to use confirmation hook
2. Simplify execute_with_confirmation() usage
3. Migrate tools one by one
4. Add deprecation warnings for direct ask_execute usage

Phase 5: Documentation & Cleanup (1-2 days)

1. Document hook API
2. Add examples for custom confirmation backends
3. Remove deprecated code paths
4. Update tests

Risks and Mitigations

Risk 1: Async/Sync Mismatch

Risk: Server needs async, CLI is sync Mitigation: Hook protocol uses generators which work for both; Server hook uses threading.Event for blocking

Risk 2: State Management

Risk: Auto-confirm count, editable state are currently global Mitigation: Move state into hook context or use ContextVars

Risk 3: Migration Complexity

Risk: Many tools use execute_with_confirmation Mitigation: Phased migration with backward compatibility layer

Open Questions

1. Priority System: Should multiple confirmation hooks be allowed? (e.g., logging + confirmation)
2. Timeout: Should there be a configurable timeout for confirmation?
3. Preview Protocol: Should preview generation be standardized across tools?
4. State Location: Where should auto-confirm count live in server mode?

Alternatives Considered

Alternative 1: Use Existing TOOL_EXECUTE_PRE

Rejected: PRE hook doesn't have a response mechanism; would need to modify hook system fundamentally.

Alternative 2: Middleware Pattern

Rejected: More complex than hooks; would require new abstraction layer.

Alternative 3: Event System

Rejected: Overkill for this use case; hooks are simpler and already exist.

Conclusion

The hook-based confirmation design provides a clean, extensible solution that:

• Harmonizes CLI and Server implementations
• Maintains backward compatibility
• Enables new confirmation backends
• Simplifies tool implementations

Recommendation: Proceed with implementation starting from Phase 1.