core/tools: add wait tool (Enter to disturb)

src/plyngent/agent/directive_checkpoint.py

@@ -23,6 +23,7 @@ use `run_argv_batch` for ordered pipelines.
 `read_file(with_lineno=true)`, and line numbers reset after any file write.
 - Prefer `fetch` for HTTP(S); private/LAN hosts need human policy allow (not YOLO).
 - PTY secrets only via `ask_into_pty`; denylists and confirms still apply.
+- `wait` pauses; pressing Enter disturbs early (optional reason).
 - Todo stack: open items mean unfinished work.
 """
 

src/plyngent/config/models.py

@@ -49,6 +49,7 @@ otherwise a small default is used. Never rely on shell to spoof identity.
 
 ### Humans & safety
 - Prefer `ask_user_line` / `ask_user_choice` / `ask_user_form` over waiting for the next free-form turn.
+- Use `wait` to pause; pressing Enter during the wait disturbs it (reason optional; turn continues immediately).
 - Overwrites, deletes, shells, and risky ops may require human confirm; hard denylists are not skipped by YOLO.
 - Temporary scratch: `new_temporary_workspace`.
 

src/plyngent/tools/__init__.py

@@ -8,6 +8,7 @@ from .chat import CHAT_TOOLS as CHAT_TOOLS
 from .chat import ask_user as ask_user
 from .chat import choose_user as choose_user
 from .chat import form_user as form_user
+from .chat import wait as wait
 from .context import InstanceState as InstanceState
 from .context import SessionState as SessionState
 from .context import bind_instance as bind_instance

src/plyngent/tools/chat/__init__.py

@@ -1,5 +1,6 @@
 from .ask import ask_user as ask_user
 from .choose import choose_user as choose_user
 from .form import form_user as form_user
+from .wait import wait as wait
 
-CHAT_TOOLS = [ask_user, choose_user, form_user]
+CHAT_TOOLS = [ask_user, choose_user, form_user, wait]

src/plyngent/tools/chat/wait.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import asyncio
+
+from plyngent.agent import ToolTag, tool
+from plyngent.prompting import get_prompt_backend, read_line_with_timeout, run_prompt_async
+
+WAIT_PROMPT = "Waiting for {duration}s. Press Enter to disturb. Feel free to ship any reason before pressing Enter. "
+
+
+@tool(name="wait", tags=ToolTag.LOCAL)
+async def wait(duration: int, *, reason: str | None = None) -> str:
+    """Wait ``duration`` seconds before continuing.
+
+    Interactive sessions show a line prompt: pressing Enter (optionally after
+    typing a reason) "disturbs" the wait so the turn continues immediately.
+    Non-interactive runs simply sleep the full duration.
+    """
+    if duration < 0:
+        return "error: duration must not be negative"
+    if duration == 0:
+        return "waited 0s"
+    backend = get_prompt_backend()
+    if not backend.is_interactive():
+        await asyncio.sleep(duration)
+        return f"waited {duration}s"
+    prompt = WAIT_PROMPT.format(duration=duration)
+    if reason:
+        prompt = (
+            f"Waiting for {duration}s (reason: {reason}). Press Enter to disturb. "
+            "Feel free to ship any reason before pressing Enter. "
+        )
+    line = await run_prompt_async(read_line_with_timeout, prompt, float(duration))
+    if line is None:
+        return f"waited {duration}s"
+    text = line.strip()
+    if text:
+        return f"disturbed by user: {text}"
+    return "disturbed by user (no reason)"