libtmux 0.1.0.alpha.1

data/lib/libtmux/operations.rb

@@ -0,0 +1,412 @@
+# frozen_string_literal: true
+
+require_relative "options"
+
+module LibTmux
+  class Server
+    def options(scope: :server)
+      Options.__send__(:new, self, scope: scope)
+    end
+
+    def hooks(scope: :session)
+      raise ArgumentError, "hooks use session or window scope" unless [:session, :window].include?(scope)
+
+      Hooks.__send__(:new, self, scope: scope)
+    end
+
+    # Formats are intentionally executable tmux formats, not literal text.
+    def display(format, target: nil, timeout: 5.0, cancel: nil)
+      return window_link(target).display(format, timeout: timeout, cancel: cancel) if target.is_a?(EntityRef) && target.kind == :window_link
+
+      args = ["display-message", "-p"]
+      if target
+        id = self.target(target, target.kind)
+        args.concat(["-t", id])
+        raise ArgumentError, "format must be a String" unless format.is_a?(String)
+
+        # display-message accepts a missing -t target; bind its returned context
+        # in this same command instead of accepting an empty fallback format.
+        format = id_format(target.kind) + format
+      end
+      result = execute_typed([*args, "--", format], timeout: timeout, cancel: cancel)
+      return result unless target
+
+      prefix = "#{id.bytesize}:#{id}"
+      unless result.stdout.start_with?(prefix)
+        raise TargetNotFoundError.new("display target no longer exists", phase: :command, delivery: :observed)
+      end
+      CommandResult.new(stdout: result.stdout.byteslice(prefix.bytesize..), stderr: result.stderr,
+        status: result.status, elapsed_seconds: result.elapsed_seconds, pid: result.pid, argv: result.argv)
+    end
+
+    def source_file(path, timeout: 5.0, cancel: nil)
+      execute_typed(["source-file", "--", path], timeout: timeout, cancel: cancel)
+    end
+
+    # Retiring the client cannot remove a dispatched waiter from tmux's queue.
+    def wait_for(channel, action: :wait, timeout: 5.0, cancel: nil)
+      flag = {wait: nil, signal: "-S", lock: "-L", unlock: "-U"}.fetch(action) do
+        raise ArgumentError, "action must be :wait, :signal, :lock or :unlock"
+      end
+      execute_typed(["wait-for", *[flag].compact, "--", channel], timeout: timeout, cancel: cancel)
+    end
+
+    def write_buffer(name:, data:, timeout: 5.0, cancel: nil)
+      execute_typed(["load-buffer", "-b", name, "--", "-"], input: data, timeout: timeout, cancel: cancel)
+    end
+
+    def read_buffer(name, timeout: 5.0, cancel: nil)
+      execute_typed(["save-buffer", "-b", name, "--", "-"], timeout: timeout, cancel: cancel)
+    end
+
+    def delete_buffer(name, timeout: 5.0, cancel: nil)
+      execute_typed(["delete-buffer", "-b", name], timeout: timeout, cancel: cancel)
+    end
+
+    def list_buffers(timeout: 5.0, cancel: nil)
+      result = execute_typed(["list-buffers", "-F", metadata_format(%w[buffer_name buffer_size])], timeout: timeout, cancel: cancel)
+      Internal::Metadata.decode(result.stdout, fields: 2, quoted: true).map do |name, size|
+        {name: name, size: decode_integer(size, "buffer size")}.freeze
+      end.freeze
+    end
+
+    def list_window_links(timeout: 5.0, cancel: nil)
+      acquire_links(["-a"], timeout: timeout, cancel: cancel)
+    end
+
+    def window_link(ref)
+      resolve(ref, :window_link)
+    end
+
+    def set_environment(name, value, hidden: false, timeout: 5.0, cancel: nil)
+      mutate_environment(["-g"], name, value, hidden: hidden, timeout: timeout, cancel: cancel)
+    end
+
+    def environment(name, hidden: false, timeout: 5.0, cancel: nil)
+      read_environment(["-g"], name, hidden: hidden, timeout: timeout, cancel: cancel)
+    end
+
+    def unset_environment(name, timeout: 5.0, cancel: nil)
+      execute_typed(["set-environment", "-g", "-u", "--", environment_name(name)], timeout: timeout, cancel: cancel)
+    end
+
+    def list_clients(timeout: 5.0, cancel: nil)
+      fields = %w[client_name client_pid client_created client_tty session_id client_control_mode]
+      result = execute_typed(["list-clients", "-F", metadata_format(fields)], timeout: timeout, cancel: cancel)
+      Internal::Metadata.decode(result.stdout, fields: fields.length, quoted: true).map do |name, pid, created, tty, session_id, control|
+        unless ["0", "1"].include?(control)
+          raise FieldDecodeError.new("client control mode is malformed", phase: :decode, delivery: :observed)
+        end
+        {name: name, pid: decode_integer(pid, "client PID"), created: decode_integer(created, "client creation time"),
+          tty: tty.empty? ? nil : tty, session_id: session_id.empty? ? nil : session_id, control: control == "1"}.freeze
+      end.freeze
+    end
+
+    private
+
+    # The format guard and nonwaiting mutation run within one tmux queue turn.
+    # Resolve configured aliases first; concurrent alias reconfiguration is not
+    # a supported coordination mechanism for these guarded operations.
+    def execute_link(refs, command, arguments, timeout: 5.0, cancel: nil, budget: nil)
+      budget ||= operation_budget(timeout, cancel)
+      refs.each { |ref| target(ref, :window_link) }
+      names = builtin_spellings("if-shell", "display-message", command, budget: budget)
+      marker = "libtmux-missing-#{SecureRandom.hex(16)}"
+      failure = tmux_command([names.fetch("display-message"), "-p", "--", marker])
+      body = tmux_command([names.fetch(command), *arguments])
+      refs.reverse_each do |ref|
+        guard = "\#{&&:\#{==:\#{session_id},#{ref.session_id}},\#{&&:\#{==:\#{window_index},#{ref.index}},\#{==:\#{window_id},#{ref.id}}}}"
+        body = tmux_command([names.fetch("if-shell"), "-F", "-t", "#{ref.session_id}:#{ref.index}", guard, body, failure])
+      end
+      # One command string is parsed by tmux; it never passes through a shell.
+      result = execute_typed([names.fetch("if-shell"), "-F", "1", body], **budget.options)
+      if result.stdout == "#{marker}\n"
+        raise TargetNotFoundError.new("window link was removed or replaced", phase: :command, delivery: :observed)
+      end
+      result
+    end
+
+    def builtin_spellings(*commands, budget:)
+      inventory = options(scope: :server).list(name: "command-alias", **budget.options)
+      unless !inventory.empty? && inventory.all? { |option| option.name == "command-alias" && option.array? }
+        raise UnsupportedFeatureError.new("tmux command alias inventory is unavailable", phase: :admission)
+      end
+      aliases = inventory.filter_map do |option|
+        option.raw.split("=", 2).first if option.present?
+      end
+      result = execute_typed(["list-commands", "-F", metadata_format(%w[command_list_name command_list_alias])], **budget.options)
+      catalog = Internal::Metadata.decode(result.stdout, fields: 2, quoted: true).to_h
+      commands.uniq.to_h do |name|
+        candidates = [name, catalog[name], *(1...name.length).map { |length| name[0, length] }.reverse].compact
+        spelling = candidates.find do |candidate|
+          next false if aliases.include?(candidate)
+
+          exact_alias = catalog.find { |_key, value| value == candidate }&.first
+          matching = exact_alias ? [exact_alias] : catalog.keys.select { |key| key.start_with?(candidate) }
+          matching == [name] || candidate == name
+        end
+        raise UnsupportedFeatureError.new("all builtin spellings of #{name} are aliased", phase: :admission) unless spelling
+
+        [name, spelling]
+      end
+    end
+
+    def kill_session_with_windows(ref, expected, expected_panes, timeout:, cancel:)
+      budget = operation_budget(timeout, cancel)
+      id = target(ref, :session)
+      unless expected.is_a?(Array) && expected.length <= 1024
+        raise ArgumentError, "expected_windows must be an Array of at most 1024 window references"
+      end
+      unless expected_panes.is_a?(Array) && expected_panes.length <= 4096
+        raise ArgumentError, "expected_panes must be an Array of at most 4096 pane references"
+      end
+      ids = expected.map { |window| target(window, :window) }.uniq
+      pane_ids = expected_panes.map { |pane| target(pane, :pane) }.uniq
+      names = builtin_spellings("if-shell", "display-message", "kill-session", budget: budget)
+      allowed = ids.empty? ? "0" : "\#{m/r:^(#{ids.join('|')})$,\#{window_id}}"
+      allowed_panes = pane_ids.empty? ? "0" : "\#{m/r:^(#{pane_ids.join('|')})$,\#{pane_id}}"
+      guard = "\#{&&:\#{==:\#{session_id},#{id}},\#{==:\#{W:\#{?#{allowed},,w}\#{P:\#{?#{allowed_panes},,p}}},}}"
+      marker = "libtmux-membership-#{SecureRandom.hex(16)}"
+      failure = tmux_command([names.fetch("display-message"), "-p", "--", marker])
+      body = tmux_command([names.fetch("kill-session"), "-t", id])
+      result = execute_typed([names.fetch("if-shell"), "-F", "-t", id, guard, body, failure], **budget.options)
+      if result.stdout == "#{marker}\n"
+        raise TargetNotFoundError.new("session contains windows or panes outside the expected ownership sets", phase: :command, delivery: :observed)
+      end
+      result
+    end
+
+    def tmux_command(arguments)
+      validate_argv(arguments)
+      arguments.map { |argument| "'#{argument.gsub("'") { %q('\\'') }}'" }.join(" ")
+    end
+
+    def metadata_format(fields)
+      Internal::Metadata.format(fields)
+    end
+
+    def decode_integer(value, label)
+      unless value.match?(/\A\d+\z/)
+        raise FieldDecodeError.new("#{label} is malformed", phase: :decode, delivery: :observed)
+      end
+      Integer(value, 10)
+    end
+
+    def require_command_flag(command, flag, budget:)
+      result = execute_typed(["list-commands", "-F", metadata_format(%w[command_list_name command_list_usage]), command], **budget.options)
+      commands = Internal::Metadata.decode(result.stdout, fields: 2, quoted: true).to_h
+      usage = commands.fetch(command) do
+        raise UnsupportedFeatureError.new("tmux does not advertise #{command}", phase: :admission)
+      end
+      unless usage.scan(/\[-([A-Za-z]+)(?:\]|\s)/).flatten.any? { |flags| flags.include?(flag) }
+        raise UnsupportedFeatureError.new("tmux does not advertise #{command} -#{flag}", phase: :admission)
+      end
+    end
+
+    def acquire_links(flags, timeout: 5.0, cancel: nil)
+      result = execute_typed(["list-windows", *flags, "-F", metadata_format(%w[session_id window_index window_id])], timeout: timeout, cancel: cancel)
+      Internal::Metadata.decode(result.stdout, fields: 3, quoted: true).map do |session_id, index, id|
+        ref = EntityRef.__send__(:new, binding_key: @pin.key, kind: :window_link, id: id,
+          session_id: session_id, index: decode_integer(index, "window index"))
+        WindowLink.__send__(:new, self, ref)
+      end.sort_by { |link| [link.ref.session_id[1..].to_i, link.index] }.freeze
+    end
+
+    def environment_name(name)
+      unless name.is_a?(String) && name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+        raise ArgumentError, "environment name must be a portable variable name"
+      end
+      name
+    end
+
+    def mutate_environment(flags, name, value, hidden:, timeout: 5.0, cancel: nil)
+      execute_typed(["set-environment", *flags, *(hidden ? ["-h"] : []), "--", environment_name(name), value], timeout: timeout, cancel: cancel)
+    end
+
+    def read_environment(flags, name, hidden:, timeout: 5.0, cancel: nil)
+      name = environment_name(name)
+      result = execute_typed(["show-environment", "-s", *flags, *(hidden ? ["-h"] : []), "--", name], timeout: timeout, cancel: cancel)
+      return nil if result.stdout == "unset #{name};\n"
+      prefix, suffix = "#{name}=\"", "\"; export #{name};\n"
+      unless result.stdout.start_with?(prefix) && result.stdout.end_with?(suffix)
+        raise ProtocolError.new("tmux returned an unexpected environment record", phase: :decode, delivery: :observed)
+      end
+      Internal::Metadata.unquote(result.stdout.byteslice(prefix.bytesize, result.stdout.bytesize - prefix.bytesize - suffix.bytesize)).freeze
+    end
+  end
+
+  class Entity
+    def options
+      Options.__send__(:new, server, ref: ref)
+    end
+
+    def hooks
+      Hooks.__send__(:new, server, ref: ref)
+    end
+
+    def display(format, timeout: 5.0, cancel: nil)
+      server.display(format, target: ref, timeout: timeout, cancel: cancel)
+    end
+  end
+
+  class Session
+    # Both allowlists are required for guarded deletion of a changing topology.
+    def kill(expected_windows: nil, expected_panes: nil, timeout: 5.0, cancel: nil)
+      return super(timeout: timeout, cancel: cancel) if expected_windows.nil? && expected_panes.nil?
+
+      server.__send__(:kill_session_with_windows, ref, expected_windows, expected_panes, timeout: timeout, cancel: cancel)
+    end
+
+    def rename(name, timeout: 5.0, cancel: nil)
+      server.__send__(:execute_typed, ["rename-session", "-t", target, "--", server.__send__(:literal_name, name)], timeout: timeout, cancel: cancel)
+    end
+
+    def list_window_links(timeout: 5.0, cancel: nil)
+      server.__send__(:acquire_links, ["-t", target], timeout: timeout, cancel: cancel)
+    end
+
+    def link_window(window, index:, timeout: 5.0, cancel: nil)
+      raise ArgumentError, "index must be a nonnegative Integer" unless index.is_a?(Integer) && index >= 0
+
+      source = server.__send__(:target, window, :window)
+      server.__send__(:execute_typed, ["link-window", "-d", "-s", source, "-t", "#{target}:#{index}"], timeout: timeout, cancel: cancel)
+    end
+
+    def set_environment(name, value, hidden: false, timeout: 5.0, cancel: nil)
+      server.__send__(:mutate_environment, ["-t", target], name, value, hidden: hidden, timeout: timeout, cancel: cancel)
+    end
+
+    def environment(name, hidden: false, timeout: 5.0, cancel: nil)
+      server.__send__(:read_environment, ["-t", target], name, hidden: hidden, timeout: timeout, cancel: cancel)
+    end
+
+    def unset_environment(name, timeout: 5.0, cancel: nil)
+      server.__send__(:execute_typed, ["set-environment", "-t", target, "-u", "--", server.__send__(:environment_name, name)], timeout: timeout, cancel: cancel)
+    end
+  end
+
+  class Window
+    def rename(name, timeout: 5.0, cancel: nil)
+      server.__send__(:execute_typed, ["rename-window", "-t", target, "--", server.__send__(:literal_name, name)], timeout: timeout, cancel: cancel)
+    end
+
+    def respawn(command:, kill: false, cwd: nil, environment: {}, timeout: 5.0, cancel: nil)
+      budget = server.__send__(:operation_budget, timeout, cancel)
+      args = ["respawn-window", "-t", target, *(kill ? ["-k"] : [])]
+      args.concat(server.__send__(:creation_options, cwd: cwd, environment: environment))
+      server.__send__(:execute_typed, [*args, "--", *server.__send__(:pane_command, command)], **budget.options)
+    end
+
+    def resize(width: nil, height: nil, timeout: 5.0, cancel: nil)
+      dimensions = {"-x" => width, "-y" => height}.flat_map do |flag, value|
+        next [] if value.nil?
+        raise ArgumentError, "dimensions must be positive Integers" unless value.is_a?(Integer) && value.positive?
+
+        [flag, value.to_s]
+      end
+      raise ArgumentError, "provide width or height" if dimensions.empty?
+
+      server.__send__(:execute_typed, ["resize-window", "-t", target, *dimensions], timeout: timeout, cancel: cancel)
+    end
+  end
+
+  class Pane
+    def select(timeout: 5.0, cancel: nil)
+      server.__send__(:execute_typed, ["select-pane", "-t", target], timeout: timeout, cancel: cancel)
+    end
+
+    def resize(width: nil, height: nil, direction: nil, amount: 1, zoom: false, timeout: 5.0, cancel: nil)
+      args = ["resize-pane", "-t", target]
+      {"-x" => width, "-y" => height}.each do |flag, value|
+        next if value.nil?
+        raise ArgumentError, "dimensions must be positive Integers" unless value.is_a?(Integer) && value.positive?
+
+        args.concat([flag, value.to_s])
+      end
+      if direction
+        flag = {left: "-L", right: "-R", up: "-U", down: "-D"}.fetch(direction) { raise ArgumentError, "invalid resize direction" }
+        raise ArgumentError, "amount must be a positive Integer" unless amount.is_a?(Integer) && amount.positive?
+
+        args.concat([flag, amount.to_s])
+      end
+      args << "-Z" if zoom
+      server.__send__(:execute_typed, args, timeout: timeout, cancel: cancel)
+    end
+
+    def swap(other, timeout: 5.0, cancel: nil)
+      server.__send__(:execute_typed, ["swap-pane", "-d", "-s", target, "-t", server.__send__(:target, other, :pane)], timeout: timeout, cancel: cancel)
+    end
+
+    def join(other, direction:, before: false, timeout: 5.0, cancel: nil)
+      reposition("join-pane", other, direction: direction, before: before, timeout: timeout, cancel: cancel)
+    end
+
+    def move(other, direction:, before: false, timeout: 5.0, cancel: nil)
+      reposition("move-pane", other, direction: direction, before: before, timeout: timeout, cancel: cancel)
+    end
+
+    def break_out(session:, name:, timeout: 5.0, cancel: nil)
+      destination = server.__send__(:target, session, :session)
+      server.__send__(:create_entity, :window, ["break-pane", "-d", "-P", "-F", server.__send__(:id_format, :window),
+        "-s", target, "-t", "#{destination}:", "-n", server.__send__(:literal_name, name)], timeout: timeout, cancel: cancel)
+    end
+
+    def respawn(command:, kill: false, cwd: nil, environment: {}, timeout: 5.0, cancel: nil)
+      budget = server.__send__(:operation_budget, timeout, cancel)
+      args = ["respawn-pane", "-t", target, *(kill ? ["-k"] : [])]
+      args.concat(server.__send__(:creation_options, cwd: cwd, environment: environment))
+      server.__send__(:execute_typed, [*args, "--", *server.__send__(:pane_command, command)], **budget.options)
+    end
+
+    def paste(buffer:, delete: false, bracketed: false, separator: nil, timeout: 5.0, cancel: nil)
+      args = ["paste-buffer", "-t", target, "-b", buffer]
+      args << "-d" if delete
+      args << "-p" if bracketed
+      args.concat(["-s", separator]) if separator
+      server.__send__(:execute_typed, args, timeout: timeout, cancel: cancel)
+    end
+
+    # The shell command and its format expansion are explicitly requested here.
+    # only_if_closed follows tmux -o: an existing pipe is closed, not retained.
+    def pipe(shell_command: nil, input: false, output: true, only_if_closed: false, timeout: 5.0, cancel: nil)
+      if shell_command && !input && !output
+        raise ArgumentError, "a pipe command requires input or output"
+      end
+      args = ["pipe-pane", "-t", target]
+      args << "-I" if input
+      args << "-O" if output
+      args << "-o" if only_if_closed
+      args.concat(["--", shell_command]) if shell_command
+      server.__send__(:execute_typed, args, timeout: timeout, cancel: cancel)
+    end
+
+    def copy_mode(scroll_up: false, exit_on_bottom: false, mouse_drag: false, cancel_mode: false, page_down: false, source: nil, timeout: 5.0, cancel: nil)
+      budget = server.__send__(:operation_budget, timeout, cancel)
+      args = ["copy-mode", "-t", target]
+      {"u" => scroll_up, "e" => exit_on_bottom, "M" => mouse_drag, "q" => cancel_mode, "d" => page_down}.each do |flag, enabled|
+        next unless enabled
+
+        server.__send__(:require_command_flag, "copy-mode", flag, budget: budget)
+        args << "-#{flag}"
+      end
+      if source
+        server.__send__(:require_command_flag, "copy-mode", "s", budget: budget)
+        args.concat(["-s", server.__send__(:target, source, :pane)])
+      end
+      server.__send__(:execute_typed, args, **budget.options)
+    end
+
+    def copy_command(command, *arguments, timeout: 5.0, cancel: nil)
+      server.__send__(:execute_typed, ["send-keys", "-X", "-t", target, "--", command, *arguments], timeout: timeout, cancel: cancel)
+    end
+
+    private
+
+    def reposition(command, other, direction:, before:, timeout:, cancel:)
+      flag = {horizontal: "-h", vertical: "-v"}.fetch(direction) { raise ArgumentError, "invalid split direction" }
+      args = [command, "-d", flag, "-s", target, "-t", server.__send__(:target, other, :pane)]
+      args << "-b" if before
+      server.__send__(:execute_typed, args, timeout: timeout, cancel: cancel)
+    end
+  end
+end

data/lib/libtmux/options.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module LibTmux
+  # Raw bytes remain available even when a caller requests a typed conversion.
+  class OptionValue
+    attr_reader :name, :index, :raw
+
+    def initialize(name:, index:, raw:, inherited:, array:, present:)
+      @name, @raw = name.dup.freeze, raw.dup.freeze
+      @index, @inherited, @array, @present = index, inherited, array, present
+      freeze
+    end
+    private_class_method :new
+
+    def inherited?
+      @inherited
+    end
+
+    def array?
+      @array
+    end
+
+    def present?
+      @present
+    end
+
+    def as(type)
+      case type
+      when :bytes then raw
+      when :string
+        text = raw.dup.force_encoding(Encoding::UTF_8)
+        raise FieldDecodeError.new("option is not valid UTF-8", phase: :decode, delivery: :observed) unless text.valid_encoding?
+
+        text.freeze
+      when :integer
+        raise FieldDecodeError.new("option is not an integer", phase: :decode, delivery: :observed) unless raw.match?(/\A-?\d+\z/)
+
+        Integer(raw, 10)
+      when :boolean
+        return true if ["on", "1"].include?(raw)
+        return false if ["off", "0"].include?(raw)
+
+        raise FieldDecodeError.new("option is not a boolean", phase: :decode, delivery: :observed)
+      else raise ArgumentError, "type must be :bytes, :string, :integer or :boolean"
+      end
+    end
+  end
+
+  # Explicit acquisition and mutation at one option scope.
+  class Options
+    def initialize(server, ref: nil, scope: nil)
+      @server, @ref, @scope = server, ref, scope
+      freeze
+    end
+    private_class_method :new
+
+    def list(name: nil, inherited: false, timeout: 5.0, cancel: nil)
+      if inherited && is_a?(Hooks)
+        raise UnsupportedFeatureError.new("inherited hook acquisition is not implemented", phase: :admission)
+      end
+      command = is_a?(Hooks) ? "show-hooks" : "show-options"
+      args = [command, *scope_flags]
+      args << "-A" if inherited && !is_a?(Hooks)
+      args.concat(["--", option_name(name)]) if name
+      result = @server.__send__(:execute_typed, args, timeout: timeout, cancel: cancel)
+      result.stdout.lines.map do |line|
+        match = /\A([^\s\[\]*]+)(?:\[(\d+)\])?(\*)?(?: (.*))?\n\z/n.match(line)
+        raise ProtocolError.new("malformed escaped option record", phase: :decode, delivery: :observed) unless match
+
+        value = match[4]
+        raw = is_a?(Hooks) ? (value || "".b) : decode_escaped(value || "".b)
+        OptionValue.__send__(:new, name: match[1], index: match[2] && Integer(match[2], 10), raw: raw,
+          inherited: !match[3].nil?, array: !match[2].nil? || value.nil?, present: !value.nil?)
+      end.freeze
+    end
+
+    def get(name, index: nil, inherited: true, timeout: 5.0, cancel: nil)
+      unless index.nil? || (index.is_a?(Integer) && index >= 0)
+        raise ArgumentError, "index must be a nonnegative Integer"
+      end
+      # tmux prints a nonexistent requested index as an empty string. Acquire
+      # the array once so absent indexes remain distinct from present empties.
+      values = list(name: name, inherited: inherited, timeout: timeout, cancel: cancel)
+      values = values.select { |value| value.index == index } unless index.nil?
+      if values.empty?
+        raise NoMatchError.new("option is absent at the requested scope", phase: :decode, delivery: :observed)
+      end
+      unless values.length == 1
+        raise MultipleMatchesError.new("option has multiple array entries; provide an index", phase: :decode, delivery: :observed)
+      end
+
+      values.first
+    end
+
+    def set(name, value, index: nil, append: false, timeout: 5.0, cancel: nil)
+      value = case value
+      when true then "on"
+      when false then "off"
+      when Integer then value.to_s
+      when String then value
+      else raise ArgumentError, "option value must be String, Integer or boolean"
+      end
+      mutate("set-option", name, value, index: index, append: append, timeout: timeout, cancel: cancel)
+    end
+
+    def unset(name, index: nil, timeout: 5.0, cancel: nil)
+      command = is_a?(Hooks) ? "set-hook" : "set-option"
+      @server.__send__(:execute_typed, [command, *scope_flags, "-u", "--", option_name(indexed_name(name, index))], timeout: timeout, cancel: cancel)
+    end
+
+    private
+
+    def scope_flags
+      if @ref
+        flags = {session: [], window: ["-w"], pane: ["-p"]}.fetch(@ref.kind)
+        [*flags, "-t", @server.__send__(:target, @ref, @ref.kind)]
+      else
+        {server: ["-s"], session: ["-g"], window: ["-g", "-w"]}.fetch(@scope) do
+          raise ArgumentError, "scope must be :server, :session or :window"
+        end
+      end
+    end
+
+    def option_name(name)
+      unless name.is_a?(String) && name.match?(/\A[^\s\0]+\z/)
+        raise ArgumentError, "option names cannot contain whitespace or NUL"
+      end
+      @server.__send__(:literal_name, name)
+    end
+
+    def indexed_name(name, index)
+      return name if index.nil?
+      raise ArgumentError, "index must be a nonnegative Integer" unless index.is_a?(Integer) && index >= 0
+
+      "#{name}[#{index}]"
+    end
+
+    def mutate(command, name, value, index:, append:, timeout:, cancel:)
+      args = [command, *scope_flags]
+      args << "-a" if append
+      @server.__send__(:execute_typed, [*args, "--", option_name(indexed_name(name, index)), value], timeout: timeout, cancel: cancel)
+    end
+
+    # show-options uses args_escape (VIS_OCTAL|VIS_CSTYLE), not shell escaping.
+    def decode_escaped(value)
+      if value.start_with?("'", '"')
+        unless value.end_with?(value.byteslice(0, 1)) && value.bytesize >= 2
+          raise ProtocolError.new("unterminated escaped option value", phase: :decode, delivery: :observed)
+        end
+        value = value.byteslice(1, value.bytesize - 2)
+      end
+      escapes = {"a" => "\a", "b" => "\b", "t" => "\t", "n" => "\n", "v" => "\v", "f" => "\f", "r" => "\r", "s" => " ", "E" => "\e"}
+      value.gsub(/\\([0-7]{3}|.)/n) do
+        escaped = Regexp.last_match(1)
+        if escaped.match?(/\A[0-7]{3}\z/)
+          escaped.to_i(8).chr(Encoding::BINARY)
+        else
+          escapes.fetch(escaped, escaped)
+        end
+      end
+    end
+  end
+
+  # Hook values are executable tmux command strings, never literal data.
+  class Hooks < Options
+    def get(name, index: nil, inherited: false, timeout: 5.0, cancel: nil)
+      super
+    end
+
+    def set(name, command:, index: nil, append: false, timeout: 5.0, cancel: nil)
+      raise ArgumentError, "command must be a String" unless command.is_a?(String)
+
+      mutate("set-hook", name, command, index: index, append: append, timeout: timeout, cancel: cancel)
+    end
+
+    def run(name, timeout: 5.0, cancel: nil)
+      @server.__send__(:execute_typed, ["set-hook", *scope_flags, "-R", "--", option_name(name)], timeout: timeout, cancel: cancel)
+    end
+  end
+end