Complete

Complete tool - signals that the autonomous session is finished.

exception gptme.tools.complete.SessionCompleteException

Exception raised to signal that the session should end.

gptme.tools.complete.auto_reply_hook(manager: LogManager, interactive: bool, prompt_queue: Any, no_confirm: bool = False) → Generator[Message | StopPropagation, None, None]

Hook that implements auto-reply mechanism for autonomous operation.

If in non-interactive mode and last assistant message had no tools, inject an auto-reply to ensure the assistant does work.

In interactive + no_confirm mode (gptme -y), inject a quiet nudge once to avoid piling on, then let the loop continue naturally.

This is called via LOOP_CONTINUE hook, which receives interactive, prompt_queue, and no_confirm.

Parameters:

• manager – Conversation manager with log and workspace

• interactive – Whether in interactive mode

• prompt_queue – Queue of pending prompts

• no_confirm – Whether tool confirmations are skipped (–no-confirm / -y mode)

gptme.tools.complete.complete_hook(messages: list[Message], workspace: Path | None = None, **kwargs) → Generator[Message | StopPropagation, None, None]

Hook that detects complete tool call and prevents next generation.

Runs at GENERATION_PRE (before generating response) to stop the session immediately after complete tool is called.

If GPTME_VERIFY_COMPLETION is set (or a .gptme/verify-completion.sh script exists in the workspace), that command is run before the session is allowed to close. On failure the agent receives one more turn to fix the issue; it can retry up to GPTME_VERIFY_COMPLETION_MAX_RETRIES times (default 3) before the hook gives up and closes the session anyway.

Parameters:

• messages – List of conversation messages

• workspace – Path to the workspace directory (passed via kwargs at dispatch)

• **kwargs – Additional arguments (manager etc. — currently unused)

Note: GENERATION_PRE hooks are called with messages as first positional arg, not manager as the Protocol suggests. This is a known type safety issue.

gptme.tools.complete.execute_complete(code: str | None, args: list[str] | None, kwargs: dict[str, str] | None) → Message

Signal that the autonomous session is complete and ready to exit.

gptme.tools.complete.stuck_detect_hook(manager: LogManager, interactive: bool, prompt_queue: Any, no_confirm: bool = False) → Generator[Message | StopPropagation, None, None]

Detect a stuck agent that keeps issuing the same tool call(s).

Unlike auto_reply_hook (which only acts when the last assistant message has no tool uses), this hook fires when the agent does emit tool uses but keeps repeating an identical action without progress — a silent failing loop that would otherwise run until the budget or session timeout is hit.

Registered as a separate LOOP_CONTINUE hook at higher priority than auto_reply_hook so it can observe the yes-tool-but-repeating case the latter early-returns on. Yields a system nudge when stuck; in non-interactive mode, raises SessionCompleteException after repeated escalations.

In interactive mode (e.g. gptme.ai web sessions) the nudge fires normally but the session is never force-exited — the human can break the loop.

See gptme/gptme#2725, gptme/gptme#3459, and the design note in Bob’s workspace.