Ergonomic DX layer for agent handler code running inside session/prompt turn tasks (the functions a turn_runner closure or one of its subagent tasks actually calls). This module introduces no new runtime semantics: every function here is a thin, documented wrapper over Raxol.AgentClientProtocol.Connection.request/4 (the agent->client filesystem/terminal/permission requests) or Raxol.AgentClientProtocol.Session.post_update/2 / Session.request_permission/2 (the Session-owned turn primitives).

Why this isn't built on Connection.Ctx

Raxol.AgentClientProtocol.Connection.Ctx is the per-DISPATCH struct handed to the request/notification handler callback that answers session/prompt itself (it carries conn, reply_ref, rx_seq, etc.). It does not reach the turn task the handler spawns — turn_runner is injected at Session start with a fixed (session_pid, req) -> ... arity-2 shape (session.ex moduledoc, "Turn runner seam"), and a subagent's task closure only ever receives what its parent closed over. There is deliberately one ctx concept in this package (Connection.Ctx); this module does not introduce a second, competing one. Instead every function below takes the plain pid a turn task actually has in hand — the Connection pid (closed over from the original dispatch's ctx.conn when the app builds its turn_runner fun) for the outbound protocol requests, or the Session pid (the task's own session argument) for the two Session-owned primitives.

What's here

• read_text_file/3,4, write_text_file/4,5 — fs/read_text_file / fs/write_text_file, sent via Connection.request/4. request/4 blocks its caller, so it is for plain handler-task code; a process that must stay responsive uses async_request/6 instead. A turn task is plain handler-task code, not the Session itself.
• create_terminal/3,4, terminal_output/3,4, wait_for_terminal_exit/3,4, kill_terminal/3,4, release_terminal/3,4 — the five terminal/* methods, same Connection.request/4 wrapper.
• request_permission/3,4 — builds a RequestPermissionRequest and delegates to Session.request_permission/2. Fail-closed, always: the ONLY way to get an allow back is a literal {:selected, %SelectedPermissionOutcome{}} decoded from the client's reply; every other terminal (timeout, client error, decode failure, disconnect, a session/cancel racing the ask) resolves {:ok, :cancelled} — deny is the zero value everywhere. This wrapper adds no new fail-closed logic; it is documentation + ergonomics over the Session's existing guarantee.
• post_update/2 — delegates to Session.post_update/2 verbatim (same arity, same contract): forwards a session/update for the live turn, surfacing {:error, :turn_over} for a straggler post after drain and {:error, :empty_chunk} for an empty-text agent_message_chunk/agent_thought_chunk (never sent to the wire — see session.ex's empty_chunk?/1).

Timeouts

Connection.request/4's timeout_ms is pos_integer() — not :infinity (only async_request/6 accepts that). Every function below takes a :timeout option (default 30_000ms, except wait_for_terminal_exit/3,4 which defaults to 30 minutes since waiting for a command to exit is expected to take a while); pass a larger :timeout explicitly for a longer-running command rather than relying on a library-invented unbounded wait.