maf 0.2.0 → 0.3.0

data/install.md

@@ -198,7 +198,12 @@ list with the existing entries plus the new entry.
 The second command approves the hook one time. Hermes stores the consent for this
 version of the script. A new script version needs a new approval.
 
-Confirm that every check from `hermes hooks doctor` passes. Then continue.
+Confirm that every check from `hermes hooks doctor` passes.
+
+Hermes gives the commands of an agent only the variables in
+`terminal.client_env_passthrough`. If `maf add` prints a `hermes config set
+terminal.client_env_passthrough` command, run it. It keeps the names that the
+list has now. Then continue.
 
 ## Step 5c - Set the Gemini key for the doc-graph refresh
 

data/lib/maf/bootstrap/claude_settings.rb

@@ -2,9 +2,10 @@
 
 module Maf
   module Bootstrap
-    # ClaudeSettings plans and applies the Claude Code hooks in the settings
-    # file of the flow, .maf/claude/settings.json. `maf start` passes the file
-    # with --settings. Claude Code runs these hooks next to the project's own.
+    # ClaudeSettings plans and applies the Claude Code hooks and environment in
+    # the settings file of the flow, .maf/claude/settings.json. `maf start`
+    # passes the file with --settings. Claude Code runs these hooks next to the
+    # project's own. The --settings env wins over the env of the user settings.
     class ClaudeSettings
       def initialize(project)
         @project = project
@@ -12,23 +13,30 @@ module Maf
 
       def plan
         file = @project.path(CLAUDE_SETTINGS)
-        [@project.action(status(file), file, "#{file} (next-task + board-watch hooks)", :claude_stop_hook)]
+        [@project.action(status(file), file, "#{file} (next-task + board-watch hooks, env)", :claude_stop_hook)]
       end
 
       def configure(file)
         settings = read(file)
-        missing = missing_hooks(settings)
-        missing.each { |event, hook| add_hook(settings, event, hook) }
-        write(file, settings) unless missing.empty?
-        !missing.empty?
+        return false if current?(settings)
+
+        write(file, update(settings))
+        true
       end
 
       private
 
       def status(file)
-        File.exist?(file) && missing_hooks(read(file)).empty? ? :skip : :configure_claude_hook
+        File.exist?(file) && current?(read(file)) ? :skip : :configure_claude_hook
+      end
+
+      def update(settings)
+        missing_hooks(settings).each { |event, hook| add_hook(settings, event, hook) }
+        settings.merge("env" => (settings["env"] || {}).merge(CLAUDE_ENV))
       end
 
+      def current?(settings) = missing_hooks(settings).empty? && (settings["env"] || {}) >= CLAUDE_ENV
+
       def read(file)
         File.exist?(file) ? (JSON.parse(File.read(file)) rescue {}) : {}
       end

data/lib/maf/bootstrap.rb

@@ -64,6 +64,10 @@ module Maf
       end
     ].freeze
 
+    # Claude Code environment of a flow session. Agent teams stay off: with
+    # them on, a subagent that Claude names starts as a teammate.
+    CLAUDE_ENV = { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" => "0" }.freeze
+
     # The knowledge graph and the Obsidian vault, at the project root where graphify looks by default.
     GRAPH_DIR = "graphify-out"
 

data/lib/maf/cli.rb

@@ -12,6 +12,7 @@ require_relative "menu"
 require_relative "team"
 require_relative "team_command"
 require_relative "worker_control"
+require_relative "worker_list"
 require_relative "untrack"
 require_relative "vm"
 require_relative "version"
@@ -21,6 +22,7 @@ module Maf
 
   def self.flow(*args) = Flow::Generator.new(["--project", Dir.pwd, *args]).run
   def self.role_names = Flow::RoleCatalog.new(Dir.pwd).roles.keys
+  def self.role_effort(role) = Flow::RoleCatalog.new(Dir.pwd).roles.dig(role, "effort")
 
   def self.agents = File.exist?(MANIFEST) ? JSON.parse(File.read(MANIFEST)).fetch("agents") : []
   def self.agent_specs = agents.map { |a| "#{a["harness"]}:#{a["role"]}" }
@@ -38,19 +40,21 @@ module Maf
 
   class CLI
     COMMANDS = {
-      "add" => "[HARNESS:ROLE[:MODEL] ...] [--model ROLE=MODEL]  add agents and install the flow; " \
-               "without arguments it asks",
+      "add" => "[HARNESS:ROLE[:MODEL] ...] [--model ROLE=MODEL] [--effort ROLE=LEVEL]  add agents and install " \
+               "the flow; without arguments it asks",
       "remove" => "HARNESS:ROLE ...                        remove agents",
       "update" => "                                        regenerate the files of the current agents",
       "agents" => "                                        list the current agents",
       "roles" => "                                        list the built-in roles and the project roles",
       "role" => "add NAME                                add a stub role to .maf/roles.yml",
-      "start" => "[HARNESS ROLE[_WORKER]] [--dispatch [--detach]]  start one agent in its worktree",
-      "prepare" => "HARNESS ROLE[_WORKER] [--dispatch|--interactive] [--replace W]  prepare a worker; " \
+      "start" => "[HARNESS ROLE[_WORKER]] [--effort LEVEL] [--dispatch [--detach]]  start one agent in its worktree",
+      "prepare" => "HARNESS ROLE[_WORKER] [--effort LEVEL] [--dispatch|--interactive] [--replace W]  " \
+                   "prepare a worker; " \
                    "--dispatch starts it (default for the architect)",
       "retire" => "ROLE[_WORKER]                           remove a worker; its tasks return to the pool",
-      "worker" => "status|stop|start|restart ROLE[_WORKER] [--force] [--max-context N] [--max-session-runs N] " \
-                  "[--cache-window S]  control one worker; start and restart save the session limits of the role",
+      "worker" => "list | status|stop|start|restart ROLE[_WORKER] [--force] [--max-context N] " \
+                  "[--max-session-runs N] [--cache-window S]  list the running workers, or control one worker; " \
+                  "start and restart save the session limits of the role",
       "team" => "[set --max N --allow HARNESS[:MODEL]]   show the team, or set its budget",
       "uninstall" => "[--check] [--yes] [--force]             remove the flow from the project",
       "migrate" => "[--check] [--yes]                       move an old-layout install into .maf/",
@@ -95,7 +99,10 @@ module Maf
     # Without arguments on a terminal, maf add asks for the harness, the roles, and the models.
     def run_add = @args.empty? && $stdin.tty? ? Menu.new.add : Maf.flow(*AgentArgs.convert(@args, "--agent"))
     def run_remove = Maf.flow(*AgentArgs.convert(@args, "--remove"))
-    def run_update = Maf.flow(*@args)
+    def run_update
+      Maf.flow(*@args)
+      Untrack.warn_tracked(SetupAgent::Project.root)
+    end
     def run_roles = Maf.flow("--list-roles")
 
     def run_role
@@ -108,13 +115,15 @@ module Maf
     def run_prepare = Prepare.new(@args).run
     def run_team = TeamCommand.new(@args, SetupAgent::Project.root).run
     def run_worker
+      return WorkerList.new(SetupAgent::Project.root).run if @args.first == "list"
+
       spec = @args[1] || abort(worker_usage)
       limits = RoleLimits.parse(@args)
       WorkerControl.new(SetupAgent::Project.root, spec, force: @args.include?("--force"), limits: limits)
         .run(@args[0].to_s)
     end
 
-    def worker_usage = "usage: maf worker #{WorkerControl::ACTIONS.join("|")} ROLE[_WORKER] [--force] " \
+    def worker_usage = "usage: maf worker list | #{WorkerControl::ACTIONS.join("|")} ROLE[_WORKER] [--force] " \
                        "[--max-context N] [--max-session-runs N] [--cache-window S]"
     def run_retire = Retire.new(SetupAgent::Project.root, @args.first || abort("usage: maf retire ROLE[_WORKER]")).run
     def run_uninstall = Uninstall::Runner.new(["--project", Dir.pwd, *@args]).run
@@ -132,7 +141,8 @@ module Maf
     end
 
     def agent_line(agent)
-      "#{agent["harness"]}:#{agent["role"]}".ljust(32) + agent["model"].to_s
+      effort = agent["effort"] && "effort=#{agent["effort"]}"
+      "#{agent["harness"]}:#{agent["role"]}".ljust(32) + [agent["model"], effort].compact.join(" ")
     end
   end
 end

data/lib/maf/flow/effort_report.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # EffortReport warns about an effort level that the harness does not list.
+    module EffortReport
+      def self.print(results)
+        list = results.select { |r| r[:effort] && !harness(r).known_effort?(r[:effort], r[:model]) }
+        return if list.empty?
+
+        puts "", "WARNING: the harness does not list these effort levels. Check the level for a typo:",
+             list.map { |r| "  #{name(r)} -> #{r[:effort]}" },
+             "  Fix one with: maf add HARNESS:ROLE --effort ROLE=LEVEL"
+      end
+
+      def self.harness(result) = Harness.fetch(result[:agent][:harness])
+      def self.name(result) = "#{result[:agent][:harness]}:#{result[:agent][:role]}"
+    end
+  end
+end

data/lib/maf/flow/generator.rb

@@ -26,6 +26,7 @@ module Maf
         Validator.project!(@options)
         @catalog = RoleCatalog.new(@options.project)
         @roles = @catalog.roles
+        @options.role_efforts = @roles.transform_values { |data| data["effort"] }
       end
 
       def generate_all
@@ -51,7 +52,7 @@ module Maf
 
       def print_role(key, data)
         puts "", "  #{key} (#{@catalog.source(key)})", "    #{data.fetch("description")}",
-             "    model hint: #{data.fetch("model_hint")}"
+             "    model hint: #{data.fetch("model_hint")}", *("    effort: #{data["effort"]}" if data["effort"])
       end
 
       def finish_without_agents

data/lib/maf/flow/hermes_env_setup.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # HermesEnvSetup prints the step that lets Hermes give the flow variables to
+    # the commands of an agent. The flow never edits the Hermes config.
+    class HermesEnvSetup
+      KEY = "terminal.client_env_passthrough"
+      NAMES = %w[COORD_DIR COORD_ROLE COORD_WORKER COORD_DISPATCHED COORD_SLOT COORD_SESSION_PID TASKRC
+                 MAF_BIN].freeze
+
+      def initialize(config_yaml = File.join(Dir.home, ".hermes", "config.yaml"))
+        @config_yaml = config_yaml
+      end
+
+      # Returns true when the user has a step left.
+      def install
+        names = listed
+        return puts("  hermes env ready: #{KEY}") || false if (NAMES - names).empty?
+
+        print_step(names) || true
+      end
+
+      def command(names) = "hermes config set #{KEY} '#{JSON.generate((names + NAMES).uniq)}'"
+
+      def listed
+        list = config.dig("terminal", "client_env_passthrough")
+        list.is_a?(Array) ? list.map(&:to_s) : []
+      end
+
+      private
+
+      def print_step(names)
+        puts "", "  Hermes env: the commands of a Hermes agent get no COORD_* variables yet.",
+             "  Do this step one time. It keeps the names that the list has now.", "", "    #{command(names)}", ""
+      end
+
+      def config
+        data = YAML.safe_load_file(@config_yaml)
+        data.is_a?(Hash) ? data : {}
+      rescue SystemCallError, Psych::Exception
+        {}
+      end
+    end
+  end
+end

data/lib/maf/flow/manifest.rb

@@ -34,7 +34,7 @@ module Maf
       # a role without the role definitions.
       def entry(agent)
         { harness: agent[:harness], role: agent[:role], model: @options.model_for(agent),
-          can_edit: @roles.fetch(agent[:role]).fetch("can_edit") }
+          can_edit: @roles.fetch(agent[:role]).fetch("can_edit") }.merge({ effort: @options.effort_for(agent) }.compact)
       end
 
       # Other tools own other keys (maf team: "team"; users: "base_branch").

data/lib/maf/flow/models.rb

@@ -21,6 +21,17 @@ module Maf
 
       def self.known?(harness, model) = Harness[harness]&.known_model?(model, self.for(harness)) != false
       def self.default(harness) = Harness[harness]&.default_model
+      # Without a model, the levels of the default model of the harness.
+      def self.efforts(harness, model) = Harness[harness]&.efforts(model || default(harness))
+
+      # The level of the role if the harness lists it. A model that runs only
+      # with a level gets the lowest level instead.
+      def self.default_effort(harness, level, model)
+        levels = efforts(harness, model).to_a
+        return level if levels.include?(level)
+
+        levels.first if Harness[harness]&.effort_required?(model)
+      end
     end
   end
 end

data/lib/maf/flow/options.rb

@@ -4,8 +4,8 @@ module Maf
   module Flow
     # Options parses the command line and holds the settings of one run.
     class Options
-      attr_accessor :project, :agents
-      attr_reader :removed, :models, :hermes_dir, :list_roles
+      attr_accessor :project, :agents, :role_efforts
+      attr_reader :removed, :models, :efforts, :hermes_dir, :list_roles
 
       # Each flag: the OptionParser arguments, and a block that runs in the
       # Options instance with the flag value.
@@ -14,6 +14,7 @@ module Maf
         [["--agent SPEC", "HARNESS:ROLE[:MODEL]"], ->(v) { @agents << parse_agent(v) }],
         [["--remove SPEC", "HARNESS:ROLE"], ->(v) { @removed << parse_agent(v) }],
         [["--model PAIR", "ROLE=MODEL"], ->(v) { @models.store(*v.split("=", 2)) }],
+        [["--effort PAIR", "ROLE=LEVEL"], ->(v) { @efforts.store(*v.split("=", 2)) }],
         [["--hermes-dir DIR"], ->(v) { @hermes_dir = File.expand_path(v) }],
         [["--check"], ->(_) { @check = true }],
         [["--force"], ->(_) { @force = true }],
@@ -22,7 +23,8 @@ module Maf
       ].freeze
 
       def initialize(argv)
-        @argv, @agents, @removed, @models = argv, [], [], {}
+        @argv, @agents, @removed, @models, @efforts = argv, [], [], {}, {}
+        @role_efforts = {}
         @check = @force = @list_roles = false
         @bootstrap = true
       end
@@ -48,8 +50,32 @@ module Maf
         agent[:model] || @models[agent[:role]] || agent[:saved_model] || Harness[agent[:harness]]&.default_model
       end
 
+      # An empty --effort ROLE= clears the level: the harness default applies.
+      # A saved level belongs to the saved model, so a new model gets the role default.
+      def effort_for(agent)
+        flag = effort_flag(agent)
+        return (flag unless flag.empty?) if flag
+
+        (agent[:saved_effort] unless model_changed?(agent)) ||
+          Models.default_effort(agent[:harness], @role_efforts[agent[:role]], model_for(agent))
+      end
+
       private
 
+      # --effort ROLE=LEVEL applies to the agents of this run. Without one of
+      # the role, it applies to the saved agents of the role.
+      def effort_flag(agent)
+        role = agent[:role]
+        @efforts[role] if run_agent?(agent) || @agents.none? { |a| a[:role] == role && run_agent?(a) }
+      end
+
+      def run_agent?(agent) = agent.key?(:model)
+
+      def model_changed?(agent)
+        chosen = agent[:model] || @models[agent[:role]]
+        chosen && chosen != agent[:saved_model]
+      end
+
       def parser
         OptionParser.new do |o|
           o.banner = "Usage: maf add|remove|update [HARNESS:ROLE ...] [options]"

data/lib/maf/flow/prompt_text.rb

@@ -99,9 +99,12 @@ module Maf
       - Before you continue a claimed task after a pause, run `coord show <id>`. If the status is not pending,
         or the worker is not you, stop work on that task. `coord reap` releases the claims of stalled workers.
       - Finish the whole task. Report done only when each acceptance criterion passes.
-      - If you cannot finish, do the parts you can. Keep the claim, so another worker
-        does not hit the same blocker. Annotate the blocker and the missing parts.
-        Message the architect. Stop. Do not retry a failing approach.
+      - If you cannot finish, do the parts you can and commit them on the task branch.
+        Then block the task: `coord block <id> --kind <kind> "<blocker and missing parts>"`.
+        Kinds: needs_input (a decision of the user), dependency (other work must land first),
+        capability (a missing tool, access, or model). coord tells the role that can remove the blocker.
+        A blocked task leaves `coord next`, so no other worker hits the blocker.
+        Stop. Do not retry a failing approach.
       %{no_task_instruction}
       - Record durable knowledge in the shared vault or #{DECISIONS}.
       - Never write ad-hoc verification scripts. The test suite is the verification.

data/lib/maf/flow/report.rb

@@ -12,20 +12,21 @@ module Maf
 
       def print(results)
         puts "", "Generated role files:", results.map { |result| generated_line(result) }
-        %i[print_missing_models print_unknown_models print_unembeddable print_sessions]
-          .each { |name| send(name, results) }
+        %i[print_missing_models print_unknown_models print_unembeddable].each { |name| send(name, results) }
+        EffortReport.print(results)
+        print_sessions(results)
         print_hermes_reminder
       end
 
       private
 
-      # The hook steps print at install time, far above the last lines the user
+      # The Hermes steps print at install time, far above the last lines the user
       # reads. Repeat the state here so the flow is not started with a dead hook.
       def print_hermes_reminder
         return unless @hermes_pending
 
-        puts "The Hermes hook is not active yet. Finish the steps above.",
-             "Then run `maf update` to confirm the hook is ready."
+        puts "The Hermes setup is not done yet. Finish the steps above.",
+             "Then run `maf update` to confirm that Hermes is ready."
       end
 
       def generated_line(result)

data/lib/maf/flow/role_catalog.rb

@@ -6,7 +6,7 @@ module Maf
     # role in .maf/roles.yml adds a role or replaces a built-in role.
     class RoleCatalog
       FILE = ".maf/roles.yml"
-      DEFAULTS = { "model_hint" => "", "can_edit" => true }.freeze
+      DEFAULTS = { "model_hint" => "", "can_edit" => true, "effort" => nil }.freeze
 
       def initialize(project)
         @project = project

data/lib/maf/flow/role_files.rb

@@ -20,14 +20,14 @@ module Maf
 
       def generate_agent(agent)
         harness = Harness.fetch(agent[:harness])
-        model = @options.model_for(agent)
+        choice = { model: @options.model_for(agent), effort: @options.effort_for(agent) }
         dest = harness.role_destination(@options.project, agent[:role], @options.settings)
-        content = render(harness, agent[:role], @roles.fetch(agent[:role]), model)
-        { agent: agent, dest: dest, status: write(dest, content), model: model }
+        content = render(harness, agent[:role], @roles.fetch(agent[:role]), choice)
+        { agent: agent, dest: dest, status: write(dest, content), **choice }
       end
 
-      def render(harness, role, data, model)
-        harness.render_role(**template_values(role, data), prompt: @prompts.build(harness, role, data), model: model)
+      def render(harness, role, data, choice)
+        harness.render_role(**template_values(role, data), prompt: @prompts.build(harness, role, data), **choice)
       end
 
       def template_values(role, data)

data/lib/maf/flow/roster.rb

@@ -3,7 +3,8 @@
 module Maf
   module Flow
     # Roster merges the agents saved in .maf/config.json with the --agent and
-    # --remove specs of this run. A saved model ranks below --model.
+    # --remove specs of this run. A saved model ranks below --model, a saved
+    # effort below --effort.
     class Roster
       def initialize(project)
         path = File.join(project, ".maf/config.json")
@@ -11,7 +12,7 @@ module Maf
       end
 
       def merge(added, removed)
-        kept = saved.map { |a| added.find { |b| same?(a, b) }&.merge(saved_model: a[:saved_model]) || a }
+        kept = saved.map { |a| added.find { |b| same?(a, b) }&.merge(a.slice(:saved_model, :saved_effort)) || a }
         agents = kept + added.reject { |b| kept.any? { |a| same?(a, b) } }
         agents.reject { |a| removed.any? { |b| same?(a, b) } }
       end
@@ -19,7 +20,9 @@ module Maf
       private
 
       def saved
-        @saved.map { |a| { harness: a["harness"], role: a["role"], saved_model: a["model"] } }
+        @saved.map do |a|
+          { harness: a["harness"], role: a["role"], saved_model: a["model"], saved_effort: a["effort"] }
+        end
       end
 
       def same?(one, other) = one[:harness] == other[:harness] && one[:role] == other[:role]

data/lib/maf/flow.rb

@@ -4,7 +4,7 @@
 #
 # maf add, maf remove, maf update, and maf roles run Flow::Generator.
 # Options: --project DIR [--agent HARNESS:ROLE ...] [--remove HARNESS:ROLE ...]
-#          [--model ROLE=MODEL] [--hermes-dir DIR] [--check] [--force] [--no-bootstrap]
+#          [--model ROLE=MODEL] [--effort ROLE=LEVEL] [--hermes-dir DIR] [--check] [--force] [--no-bootstrap]
 #          [--list-roles]
 #
 # HARNESS is a harness of the registry: one file in lib/maf/shared/harnesses/.
@@ -52,6 +52,7 @@ require_relative "flow/options"
 require_relative "flow/prompt_builder"
 require_relative "flow/hook_files"
 require_relative "flow/hermes_hook_setup"
+require_relative "flow/hermes_env_setup"
 require_relative "flow/codex_hooks"
 require_relative "flow/legacy_codex_hook"
 require_relative "flow/hook_installer"
@@ -61,6 +62,7 @@ require_relative "flow/mcp_installer"
 require_relative "flow/role_files"
 require_relative "flow/manifest"
 require_relative "flow/models"
+require_relative "flow/effort_report"
 require_relative "flow/report"
 require_relative "flow/validator"
 require_relative "flow/harness_linker"

data/lib/maf/menu.rb

@@ -21,14 +21,14 @@ module Maf
       end
     end
 
-    # Only the installed harnesses are choices. Each role gets its own model.
+    # Only the installed harnesses are choices. Each role gets its own model and effort.
     def add
       harness = @prompt.choose("Harness", Flow::Models.installed) or return
       roles = @prompt.choose_many("Roles", Maf.role_names)
       return if roles.empty?
 
       models = show_models(harness)
-      Maf.flow(*roles.flat_map { |role| ["--agent", agent_spec(harness, role, models)] })
+      Maf.flow(*roles.flat_map { |role| agent_args(harness, role, models) })
     end
 
     private
@@ -56,21 +56,18 @@ module Maf
       @prompt.say("error: #{e.message}")
     end
 
-    def agent_spec(harness, role, models)
+    def agent_args(harness, role, models)
       model = ask_model(harness, role, models).to_s
-      [harness, role, model].reject(&:empty?).join(":")
+      effort = ask_effort(harness, role, model.empty? ? nil : model).to_s
+      flags = effort.empty? ? [] : ["--effort", "#{role}=#{effort}"]
+      ["--agent", [harness, role, model].reject(&:empty?).join(":"), *flags]
     end
 
-    # The answer is a number of the list, a model name, or Enter for the default.
-    # A name that the harness does not list needs a confirmation: a typo makes
-    # every dispatched run fail.
+    # A model name that the harness does not list needs a confirmation: a typo
+    # makes every dispatched run fail.
     def ask_model(harness, role, models)
-      answer = @prompt.ask("Model for #{role} (number or name, Enter = #{default_label(harness)}):").to_s
-      number = Integer(answer, exception: false)
-      return models[number - 1] if number&.between?(1, models.size)
-      return answer if answer.empty? || Flow::Models.known?(harness, answer)
-
-      @prompt.confirm?("#{harness} does not list #{answer}. Use it anyway?") ? answer : ask_model(harness, role, models)
+      question = "Model for #{role} (number or name, Enter = #{default_label(harness)}):"
+      ask_listed(harness, question, models) { |name| Flow::Models.known?(harness, name) }
     end
 
     def default_label(harness) = Flow::Models.default(harness) || "the harness default"
@@ -78,10 +75,47 @@ module Maf
     def show_models(harness)
       models = Flow::Models.for(harness).to_a
       @prompt.say(models.empty? ? "#{harness} lists no models. Type a name." : "Models of #{harness}:")
-      models.each_with_index { |model, i| @prompt.say("  #{i + 1}) #{model}") }
+      models.each_with_index { |model, i| @prompt.say("  #{i + 1}) #{model}#{levels_label(harness, model)}") }
       models
     end
 
+    def levels_label(harness, model)
+      levels = Flow::Models.efforts(harness, model).to_a
+      levels.empty? ? "" : "  (effort: #{levels.join(", ")})"
+    end
+
+    # An empty list: the model takes no level, so maf does not ask.
+    # nil: the harness lists no levels, so every level counts as known.
+    def ask_effort(harness, role, model)
+      levels = Flow::Models.efforts(harness, model)
+      return if levels == []
+
+      levels.to_a.each_with_index { |level, i| @prompt.say("  #{i + 1}) #{level}") }
+      question = "Effort for #{role} (number or name, Enter = #{effort_label(harness, role, model)}):"
+      ask_listed(harness, question, levels.to_a) { |name| levels.nil? || levels.include?(name) }
+    end
+
+    def effort_label(harness, role, model)
+      Flow::Models.default_effort(harness, Maf.role_effort(role), model) || "the harness default"
+    end
+
+    # The answer is a number of the list, a name, or Enter for the default.
+    def ask_listed(harness, question, list, &known)
+      answer = @prompt.ask(question).to_s
+      picked = pick(answer, list, &known)
+      return picked if picked
+      return answer if @prompt.confirm?("#{harness} does not list #{answer}. Use it anyway?")
+
+      ask_listed(harness, question, list, &known)
+    end
+
+    def pick(answer, list)
+      number = Integer(answer, exception: false)
+      return list[number - 1] if number&.between?(1, list.size)
+
+      answer if answer.empty? || yield(answer)
+    end
+
     def remove
       spec = @prompt.choose("Agent", Maf.agent_specs) or return
       Maf.flow("--remove", spec) if @prompt.confirm?("Remove #{spec}?")

data/lib/maf/setup_agent/args.rb

@@ -3,18 +3,23 @@
 module Maf
   module SetupAgent
     # Args reads the positional arguments (HARNESS ROLE[_WORKER] [model:M]),
-    # then the flags. --dispatch and --model M are setup_agent's own flags; all
-    # other flags go to the dispatcher and need --dispatch.
+    # then the flags. --dispatch, --model M, and --effort L are setup_agent's own
+    # flags; all other flags go to the dispatcher and need --dispatch.
     class Args
-      Parsed = Struct.new(:harness, :role, :worker_id, :worker, :model, :dispatch, :detach, :dispatcher_args,
-                          keyword_init: true)
+      Parsed = Struct.new(:harness, :role, :worker_id, :worker, :model, :effort, :dispatch, :detach,
+                          :dispatcher_args, keyword_init: true)
 
       def self.parse(argv)
         dispatch, detach, positional, flags = split(argv)
-        model = take_model(flags)
+        model, effort = %w[--model --effort].map { |flag| take_value(flags, flag) }
+        check_flags(flags, dispatch, detach)
+        Parsed.new(**identity(positional, model, dispatch), effort: effort, dispatch: dispatch, detach: detach,
+                                                            dispatcher_args: flags)
+      end
+
+      def self.check_flags(flags, dispatch, detach)
         reject_stray(flags, dispatch)
         abort "setup_agent: --detach works only with --dispatch" if detach && !dispatch
-        Parsed.new(**identity(positional, model, dispatch), dispatch: dispatch, detach: detach, dispatcher_args: flags)
       end
 
       def self.split(argv)
@@ -31,10 +36,10 @@ module Maf
           model: model || model_arg&.sub(/\Amodel:/, "") }
       end
 
-      def self.take_model(flags)
-        index = flags.index("--model")
+      def self.take_value(flags, flag)
+        index = flags.index(flag)
         value = index && flags.slice!(index, 2)[1]
-        abort "setup_agent: --model needs a value" if index && (value.nil? || value.start_with?("--"))
+        abort "setup_agent: #{flag} needs a value" if index && (value.nil? || value.start_with?("--"))
         value
       end
 
@@ -50,7 +55,8 @@ module Maf
       end
 
       def self.abort_usage
-        abort "usage: maf start HARNESS ROLE[_WORKER] [model:MODEL] [--model MODEL] [--dispatch [FLAGS...]]"
+        abort "usage: maf start HARNESS ROLE[_WORKER] [model:MODEL] [--model MODEL] [--effort LEVEL] " \
+              "[--dispatch [FLAGS...]]"
       end
     end
   end

data/lib/maf/setup_agent/dispatch.rb

@@ -9,11 +9,11 @@ module Maf
     module Dispatch
       DISPATCHER = ".maf/bin/dispatcher"
 
-      def self.launch(args, model)
+      def self.launch(args)
         dispatcher = File.join(Project.root, DISPATCHER)
         require_dispatcher!(dispatcher)
         cmd = [RbConfig.ruby, dispatcher, args.role, "--harness", args.harness]
-        cmd += ["--model", model] if model
+        cmd += { "--model" => args.model, "--effort" => args.effort }.compact.flatten
         cmd += args.dispatcher_args
         args.detach ? detach(cmd, args.worker) : Launcher.exec_or_die(cmd)
       end