Canonical error type for ClaudeWrapper.

Every operational failure in this library is returned as {:error, %ClaudeWrapper.Error{}} and can also be raised (it is a proper exception). Branch on the :kind atom for the failure category; the :reason field plus the dedicated :exit_code / :stdout / :stderr fields carry the details.

case ClaudeWrapper.query("hi") do
  {:ok, result} -> result
  {:error, %ClaudeWrapper.Error{kind: :max_turns_exceeded}} -> :hit_limit
  {:error, %ClaudeWrapper.Error{kind: :command_failed, exit_code: code}} -> code
end

The variant set mirrors the Rust claude-wrapper Error enum.

Kinds

• :binary_not_found -- the claude binary could not be launched
• :command_failed -- the CLI exited non-zero (:exit_code, :stdout, :stderr)
• :io -- an OS/IO error launching or talking to the CLI (:reason)
• :timeout -- the call exceeded its timeout (:reason is the timeout in ms)
• :json -- the CLI output could not be decoded as JSON (:reason, optional :stdout)
• :max_turns_exceeded -- the CLI stopped at its --max-turns limit
• :version_mismatch -- the CLI is older than a required minimum (:reason is %{found:, minimum:})
• :invalid_version -- a version string could not be parsed (:reason is the original string)
• :budget_exceeded -- a client-side budget ceiling was hit (:reason is %{total_usd:, max_usd:})
• :dangerous_not_allowed -- a bypass query was attempted without the opt-in env var (:reason is the env var name)
• :duplex_closed -- the duplex session port was already closed
• :turn_in_flight -- a turn is already running on the session
• :duplex_control_failed -- an interrupt/permission control message failed (:reason)
• :terminated -- the session terminated while a turn was pending
• :cannot_defer_again -- a permission decision was deferred twice
• :no_session -- a REPL helper was used with no active session
• :not_found -- a requested resource does not exist (:reason identifies it)
• :already_exists -- a create-new target already exists (:reason)
• :invalid_stem -- an invalid file stem / identifier (:reason)
• :no_home -- the user home directory could not be determined
• :invalid_settings_json -- a settings file is not valid JSON (:reason is %{path:, error:})
• :settings_read_error -- a settings file could not be read (:reason is %{path:, error:})
• :not_a_git_repo -- a path is not inside a git repo (:reason is the path)
• :git_failed -- a git invocation failed (:reason)
• :git_unavailable -- the git binary is not available (:reason)
• :invalid_tool_pattern -- a tool pattern failed validation (:reason is the specific problem)
• :auth -- an authentication failure, classified into :reason (see ClaudeWrapper.Auth.auth_error_kind/0)