Long-lived claude session over the CLI's stream-json duplex protocol.

Holds a single claude subprocess open across many turns, communicating via NDJSON on stdin/stdout. Complementary to ClaudeWrapper.Query and ClaudeWrapper.Session -- those spawn one subprocess per turn and are the right fit for short-lived hosts (escripts, mix tasks, batch jobs). DuplexSession is for long-running hosts (Phoenix servers, agent runtimes, OTP applications) where holding a claude open across turns is cheap.

This is the mode @anthropic-ai/claude-agent-sdk uses internally and that the @agentclientprotocol/claude-agent-acp bridge relies on for IDE integrations like Zed's agent panel.

See https://github.com/genagent/claude_wrapper_ex/issues/55 for the full design discussion and phased rollout.

Usage

config = ClaudeWrapper.Config.new()

# Provide a permission callback to decide on tool use mid-turn.
# The default is to deny everything.
on_permission = fn tool_name, _input ->
  if tool_name in ["Bash", "Edit"], do: {:deny, "not allowed"}, else: :allow
end

{:ok, pid} =
  ClaudeWrapper.DuplexSession.start_link(
    config: config,
    on_permission: on_permission
  )

# Subscribe the calling process to streaming events.
:ok = ClaudeWrapper.DuplexSession.subscribe(pid)

{:ok, result} = ClaudeWrapper.DuplexSession.send(pid, "Say hi.")

ClaudeWrapper.DuplexSession.stop(pid)

Permission callback

The optional :on_permission callback runs synchronously inside the GenServer when the CLI emits a can_use_tool control request. Two arities are supported and detected at call time:

• (tool_name, input) -> decision -- when the decision can be made from the tool name and input alone (allow/deny lists, role-based policy, etc.).

• (tool_name, input, request_id) -> decision -- when the handler may return :defer and a separate process needs to call respond_to_permission/3 later. The request_id lets the handler correlate the deferred response with the original request (e.g. broadcast {:permission_request, request_id, ...} to a UI; the UI eventually answers via respond_to_permission/3).

The decision is one of:

• :allow -- allow the tool with the original input
• {:allow, updated_input} -- allow the tool with a modified input map (sandbox a path, redact a secret, etc.)
• {:deny, reason} -- deny the tool with a reason string the model will see
• :defer -- do not respond synchronously; the caller is expected to invoke respond_to_permission/3 later

The callback runs in the GenServer process, so synchronous decisions must be fast. For slow decisions, return :defer and answer later.

The default callback is &deny_all/2, which denies every tool call. Without an explicit callback or one of the CLI's other permission modes (plan, bypass_permissions, etc.) tool use will not work.

Subscriber events

Subscribers receive plain messages of the form {:claude, event}:

• {:system_init, session_id} -- the CLI's init event
• {:assistant, msg} -- a full assistant turn (SDKAssistantMessage)
• {:stream_event, msg} -- a partial assistant token (SDKPartialAssistantMessage)
• {:user, msg} -- a user message (e.g. tool results, replays)
• {:result, %ClaudeWrapper.Result{}} -- the parsed turn boundary

Subscribers are monitored; if a subscriber crashes or exits, it is automatically removed.