agentf 0.4.7 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cf35c1c3dd0c0b331de754c2805b3bbd27e9175a339ecb264509ab3ff5e843b
-  data.tar.gz: 1c552174bd8cfdfb0770f8a4c7ae19dd732c7c8e2d440f9197a5c210a0e55b1c
+  metadata.gz: ace5a58ed6bfb8389d1e7a68349d7cc9f8d80b4093131a8cf2013388b001a08d
+  data.tar.gz: ba9a86b1c4b9e7e7edf62bed089d5cb3a1dddb9c5b4282c16e9be27438fec088
 SHA512:
-  metadata.gz: e60ee2faa826fe20c6845ab4250153838519456109893adcbba592e3a389a85520c00e3302a4bfb279e3b53b2c79c74afbe32a621a044837e904ca73dee37c54
-  data.tar.gz: d246b77664af5a645dc00afd17d0ea2799cf786d8c51f910212c7d24516e0f53a00bbeab81ec84b23a466d3a2185058bdbc89318aca932f20b7ef7c16be7e668
+  metadata.gz: 35767581d0b7561c1800464909dbf00524724527148b20f4f1ab911d846301d1a60333e8703d7b3db04e7d3d34e1a977d522fef236f8899692ae8a8c2bac65ad
+  data.tar.gz: 8d61e62517723d4bc4d39905dfb87b792d27ba1bfbe2b1eb6c445409b138091d072413ad21bffbe2cd584887d9a75f798df64f79601594ccb1029e9db54439f1

data/lib/agentf/agents/architect.rb

@@ -9,7 +9,7 @@ module Agentf
       DESCRIPTION = "Strategy, task decomposition, and memory retrieval."
       COMMANDS = %w[glob read_file memory].freeze
       MEMORY_CONCEPTS = {
-        "reads" => ["get_recent_memories", "get_pitfalls"],
+        "reads" => ["get_recent_memories", "get_episodes"],
         "writes" => [],
         "policy" => "Retrieve relevant memories before planning; do not duplicate runtime memory into static markdown."
       }.freeze
@@ -44,7 +44,7 @@ module Agentf
 
       def self.policy_boundaries
         {
-          "always" => ["Capture constraints before decomposition", "Use recent memories and pitfalls in planning"],
+          "always" => ["Capture constraints before decomposition", "Use recent memories and negative episodes in planning"],
           "ask_first" => ["Changing architectural style from project defaults"],
           "never" => ["Skip task decomposition for non-trivial workflows"],
           "required_inputs" => [],
@@ -57,7 +57,7 @@ module Agentf
 
         # Retrieve relevant memories before planning
         recent = memory.get_recent_memories(limit: 5)
-        pitfalls = memory.get_pitfalls(limit: 3)
+        pitfalls = memory.get_episodes(limit: 3, outcome: "negative")
 
         context = {
           "task" => task,
@@ -78,6 +78,10 @@ module Agentf
 
         { "subtasks" => subtasks, "context" => context }
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        plan_task(task)
+      end
     end
   end
 end

data/lib/agentf/agents/base.rb

@@ -32,8 +32,8 @@ module Agentf
 
       def self.memory_concepts
         {
-          "reads" => ["RedisMemory#get_recent_memories", "RedisMemory#get_pitfalls"],
-          "writes" => ["RedisMemory#store_lesson", "RedisMemory#store_success", "RedisMemory#store_pitfall"],
+          "reads" => ["RedisMemory#get_recent_memories", "RedisMemory#get_episodes"],
+          "writes" => ["RedisMemory#store_lesson", "RedisMemory#store_episode", "RedisMemory#store_playbook"],
           "policy" => "Memory is runtime state in Redis and should not be embedded as raw data in manifest markdown."
         }
       end
@@ -61,7 +61,15 @@ module Agentf
         )
       end
 
+      # Unified execution entrypoint for all agents. Concrete agents must
+      # implement `execute(task:, context:, agents:, commands:, logger:)`.
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
       def log(message)
+        return if ENV["AGENTF_SUPPRESS_AGENT_LOGS"] == "true"
+
         puts "\n[#{@name}] #{message}"
       end
 
@@ -83,8 +91,28 @@ module Agentf
           result: result
         )
 
-        result
+      result
+    end
+
+    # Helper to centralize memory write confirmation handling.
+    # Yields a block that performs the memory write. If the memory layer
+    # requires confirmation (ask_first policy) a structured hash is
+    # returned with confirmation details so agents can merge that into
+    # their own return payloads or let the orchestrator handle prompting.
+    def safe_memory_write(attempted: {})
+      begin
+        yield
+      rescue Agentf::Memory::RedisMemory::ConfirmationRequired => e
+        log "[MEMORY] Confirmation required: #{e.message} -- details=#{e.details.inspect}"
+        {
+          "confirmation_required" => true,
+          "confirmation_details" => e.details,
+          "attempted" => attempted,
+          "confirmed_write_token" => "confirmed",
+          "confirmation_prompt" => "Ask the user whether to save this memory. If they approve, rerun the same tool with confirmedWrite=confirmed. If they decline, do not retry."
+        }
       end
     end
+    end
   end
 end

data/lib/agentf/agents/debugger.rb

@@ -66,14 +66,31 @@ module Agentf
 
           analysis = @commands.parse_error(error)
 
-          memory.store_episode(
-            type: "lesson",
-            title: "Debugged: #{error[0..50]}...",
-            description: "Root cause: #{analysis.possible_causes.first}. Fix: #{analysis.suggested_fix}",
-            context: context.to_s,
-            tags: ["debugging", "error", "fix"],
-            agent: name
-          )
+          res = safe_memory_write(attempted: { action: "store_lesson", title: "Debugged: #{error[0..50]}...", agent: name }) do
+            memory.store_episode(
+              type: "lesson",
+              title: "Debugged: #{error[0..50]}...",
+              description: "Root cause: #{analysis.possible_causes.first}. Fix: #{analysis.suggested_fix}",
+              context: context.to_s,
+              agent: name
+            )
+          end
+
+          if res.is_a?(Hash) && res["confirmation_required"]
+            log "Root cause: #{analysis.possible_causes.first}"
+            log "Suggested fix: #{analysis.suggested_fix}"
+            return {
+              "success" => false,
+              "confirmation_required" => true,
+              "confirmation_details" => res["confirmation_details"],
+              "analysis" => {
+                "error_type" => analysis.error_type,
+                "possible_causes" => analysis.possible_causes,
+                "suggested_fix" => analysis.suggested_fix,
+                "stack_trace" => analysis.stack_trace
+              }
+            }
+          end
 
           log "Root cause: #{analysis.possible_causes.first}"
           log "Suggested fix: #{analysis.suggested_fix}"
@@ -90,6 +107,11 @@ module Agentf
           }
         end
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        error_text = task.is_a?(String) ? task : context["error"]
+        diagnose(error_text, context: context)
+      end
     end
   end
 end

data/lib/agentf/agents/designer.rb

@@ -11,7 +11,7 @@ module Agentf
       COMMANDS = %w[generate_component validate_design_system].freeze
       MEMORY_CONCEPTS = {
         "reads" => [],
-        "writes" => ["store_success"],
+        "writes" => ["store_episode"],
         "policy" => "Capture successful design implementation patterns."
       }.freeze
 
@@ -64,13 +64,20 @@ module Agentf
 
           spec = @commands.generate_component("GeneratedComponent", design_spec)
 
-          memory.store_success(
-            title: "Implemented design: #{design_spec}",
-            description: "Created #{spec.name} in #{spec.framework}",
-            context: "Framework: #{framework}",
-            tags: ["design", "ui", framework],
-            agent: name
-          )
+          res = safe_memory_write(attempted: { action: "store_episode", title: "Implemented design: #{design_spec}", outcome: "positive", agent: name }) do
+            memory.store_episode(
+              type: "episode",
+              title: "Implemented design: #{design_spec}",
+              description: "Created #{spec.name} in #{spec.framework}",
+              context: "Framework: #{framework}",
+              agent: name,
+              outcome: "positive"
+            )
+          end
+
+          if res.is_a?(Hash) && res["confirmation_required"]
+            return { "design_spec" => design_spec, "component" => spec.name, "framework" => framework, "generated_code" => spec.code, "success" => true }.merge(res)
+          end
 
           log "Created component: #{spec.name}"
 
@@ -83,6 +90,11 @@ module Agentf
           }
         end
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        spec = task.is_a?(String) ? task : context["design_spec"]
+        implement_design(spec, framework: context["framework"] || "react")
+      end
     end
   end
 end

data/lib/agentf/agents/documenter.rb

@@ -57,8 +57,8 @@ module Agentf
 
         memories = memory.get_recent_memories(limit: 20)
 
-        successes = memories.select { |m| m["type"] == "success" }
-        pitfalls = memories.select { |m| m["type"] == "pitfall" }
+        successes = memories.select { |m| m["type"] == "episode" && m["outcome"] == "positive" }
+        pitfalls = memories.select { |m| m["type"] == "episode" && m["outcome"] == "negative" }
 
         log "Found #{successes.size} successes"
         log "Found #{pitfalls.size} pitfalls"
@@ -69,6 +69,12 @@ module Agentf
           "total_memories" => memories.size
         }
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        project = task.is_a?(String) ? task : (context["project_name"] || "project")
+        sync_docs(project)
+      end
+
     end
   end
 end

data/lib/agentf/agents/explorer.rb

@@ -11,8 +11,8 @@ module Agentf
       COMMANDS = %w[glob grep read_file].freeze
       MEMORY_CONCEPTS = {
         "reads" => [],
-        "writes" => ["store_episode"],
-        "policy" => "Store exploration breadcrumbs as episodic memories."
+        "writes" => ["store_lesson"],
+        "policy" => "Store research findings as lessons after user confirmation."
       }.freeze
 
       def self.description
@@ -46,7 +46,7 @@ module Agentf
       def self.policy_boundaries
         {
           "always" => ["Return concrete file evidence"],
-          "ask_first" => ["Scanning outside configured base path", "Persisting exploration breadcrumbs to memory"],
+          "ask_first" => ["Scanning outside configured base path", "Persisting research lessons to memory"],
           "never" => ["Mutate project files during exploration"],
           "required_inputs" => [],
           "required_outputs" => ["files", "context_gathered"]
@@ -63,19 +63,37 @@ module Agentf
 
         files = @commands.glob(query, file_types: nil)
 
-        memory.store_episode(
-          type: "exploration",
-          title: "Explored: #{query}",
-          description: "Found #{files.size} relevant files",
-          context: "Search pattern: #{file_pattern || 'all files'}",
-          tags: ["exploration", "context"],
-          agent: name
-        )
+        res = safe_memory_write(attempted: { action: "store_lesson", title: "Research finding: #{query}", agent: name }) do
+          memory.store_lesson(
+            title: "Research finding: #{query}",
+            description: "Found #{files.size} relevant files during exploration",
+            context: "Search pattern: #{file_pattern || 'all files'}",
+            agent: name
+          )
+        end
+
+        if res.is_a?(Hash) && res["confirmation_required"]
+          log "Memory confirmation required during exploration: #{res['confirmation_details'].inspect}"
+          return {
+            "files" => files,
+            "context_gathered" => true,
+            "confirmation_required" => true,
+            "confirmation_details" => res["confirmation_details"],
+            "attempted" => res["attempted"],
+            "confirmed_write_token" => res["confirmed_write_token"],
+            "confirmation_prompt" => res["confirmation_prompt"]
+          }
+        end
 
         log "Found #{files.size} files"
 
         { "query" => query, "files" => files, "context_gathered" => true }
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        query = context["explore_query"] || task || "*.rb"
+        explore(query, file_pattern: context["file_pattern"])
+      end
     end
   end
 end

data/lib/agentf/agents/reviewer.rb

@@ -9,9 +9,9 @@ module Agentf
       DESCRIPTION = "Quality assurance and regression checking against memory."
       COMMANDS = %w[read_file memory].freeze
       MEMORY_CONCEPTS = {
-        "reads" => ["get_pitfalls", "get_recent_memories"],
+        "reads" => ["get_episodes", "get_recent_memories"],
         "writes" => [],
-        "policy" => "Validate outputs against known pitfalls before approval."
+        "policy" => "Validate outputs against known negative episodes before approval."
       }.freeze
 
       def self.description
@@ -56,14 +56,14 @@ module Agentf
         execute_with_contract(context: { "execution" => subtask_result }) do
           log "Reviewing subtask #{subtask_result['subtask_id']}"
 
-          pitfalls = memory.get_pitfalls(limit: 5)
-          memories = memory.get_recent_memories(limit: 5)
+            pitfalls = memory.get_episodes(limit: 5, outcome: "negative")
+            memories = memory.get_recent_memories(limit: 5)
 
           issues = []
 
-          pitfalls.each do |pitfall|
-            issues << "Warning: Known pitfall - #{pitfall['title']}" if pitfall["type"] == "pitfall"
-          end
+            pitfalls.each do |pitfall|
+              issues << "Warning: Known negative episode - #{pitfall['title']}" if pitfall["type"] == "episode"
+            end
 
           approved = issues.empty?
 
@@ -77,6 +77,11 @@ module Agentf
           { "approved" => approved, "issues" => issues }
         end
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        subtask = task.is_a?(Hash) ? task : context["execution"] || {}
+        review(subtask)
+      end
     end
   end
 end

data/lib/agentf/agents/security.rb

@@ -11,7 +11,7 @@ module Agentf
       COMMANDS = %w[scan best_practices].freeze
       MEMORY_CONCEPTS = {
         "reads" => [],
-        "writes" => ["store_success", "store_pitfall"],
+        "writes" => ["store_episode"],
         "policy" => "Record findings while redacting sensitive values."
       }.freeze
 
@@ -66,27 +66,39 @@ module Agentf
           summary = summarize_findings(findings)
 
           if findings["issues"].empty?
-            memory.store_success(
-              title: "Security review passed",
-              description: summary,
-              context: task,
-              tags: ["security", "pass"],
-              agent: name
-            )
+            res = safe_memory_write(attempted: { action: "store_episode", title: "Security review passed", outcome: "positive", agent: name }) do
+              memory.store_episode(
+                type: "episode",
+                title: "Security review passed",
+                description: summary,
+                context: task,
+                agent: name,
+                outcome: "positive"
+              )
+            end
+            return findings.merge(res) if res.is_a?(Hash) && res["confirmation_required"]
           else
-            memory.store_pitfall(
-              title: "Security findings detected",
-              description: summary,
-              context: task,
-              tags: ["security", "warning"],
-              agent: name
-            )
+            res = safe_memory_write(attempted: { action: "store_episode", title: "Security findings detected", outcome: "negative", agent: name }) do
+              memory.store_episode(
+                type: "episode",
+                title: "Security findings detected",
+                description: summary,
+                context: task,
+                agent: name,
+                outcome: "negative"
+              )
+            end
+            return findings.merge(res) if res.is_a?(Hash) && res["confirmation_required"]
           end
 
           findings.merge("best_practices" => @commands.best_practices)
         end
       end
 
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        assess(task: task, context: context)
+      end
+
       private
 
       def summarize_findings(findings)

data/lib/agentf/agents/specialist.rb

@@ -10,7 +10,7 @@ module Agentf
       COMMANDS = %w[read_file write_file run_command].freeze
       MEMORY_CONCEPTS = {
         "reads" => [],
-        "writes" => ["store_success", "store_pitfall"],
+        "writes" => ["store_episode"],
         "policy" => "Persist execution outcomes as lessons for downstream agents."
       }.freeze
 
@@ -52,7 +52,9 @@ module Agentf
         }
       end
 
-      def execute(subtask)
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        subtask = task.is_a?(Hash) ? task : (context["current_subtask"] || { "description" => task })
+
         normalized_subtask = subtask.merge(
           "id" => subtask["id"] || "ad-hoc",
           "description" => subtask["description"] || "Execute implementation step"
@@ -64,23 +66,37 @@ module Agentf
           success = normalized_subtask.fetch("success", true)
 
           if success
-            memory.store_success(
-              title: "Completed: #{normalized_subtask['description']}",
-              description: "Successfully executed subtask #{normalized_subtask['id']}",
-              context: "Working on #{normalized_subtask.fetch('task', 'unknown task')}",
-              tags: ["implementation", normalized_subtask.fetch("language", "general")],
-              agent: name
-            )
-            log "Stored success memory"
+            res = safe_memory_write(attempted: { action: "store_episode", title: "Completed: #{normalized_subtask['description']}", outcome: "positive", agent: name }) do
+              memory.store_episode(
+                type: "episode",
+                title: "Completed: #{normalized_subtask['description']}",
+                description: "Successfully executed subtask #{normalized_subtask['id']}",
+                context: "Working on #{normalized_subtask.fetch('task', 'unknown task')}",
+                agent: name,
+                outcome: "positive"
+              )
+            end
+
+            if res.is_a?(Hash) && res["confirmation_required"]
+              log "Memory confirmation required when storing success: #{res['confirmation_details'].inspect}"
+              return { "subtask_id" => normalized_subtask["id"], "success" => success, "result" => "Code executed", "confirmation_required" => true, "confirmation_details" => res["confirmation_details"], "attempted" => res["attempted"] }
+            end
           else
-            memory.store_pitfall(
-              title: "Failed: #{normalized_subtask['description']}",
-              description: "Subtask #{normalized_subtask['id']} failed",
-              context: "Working on #{normalized_subtask.fetch('task', 'unknown task')}",
-              tags: ["failure", "implementation"],
-              agent: name
-            )
-            log "Stored pitfall memory"
+            res = safe_memory_write(attempted: { action: "store_episode", title: "Failed: #{normalized_subtask['description']}", outcome: "negative", agent: name }) do
+              memory.store_episode(
+                type: "episode",
+                title: "Failed: #{normalized_subtask['description']}",
+                description: "Subtask #{normalized_subtask['id']} failed",
+                context: "Working on #{normalized_subtask.fetch('task', 'unknown task')}",
+                agent: name,
+                outcome: "negative"
+              )
+            end
+
+            if res.is_a?(Hash) && res["confirmation_required"]
+              log "Memory confirmation required when storing pitfall: #{res['confirmation_details'].inspect}"
+              return { "subtask_id" => normalized_subtask["id"], "success" => success, "result" => "Code executed", "confirmation_required" => true, "confirmation_details" => res["confirmation_details"], "attempted" => res["attempted"] }
+            end
           end
 
           { "subtask_id" => normalized_subtask["id"], "success" => success, "result" => "Code executed" }

data/lib/agentf/agents/tester.rb

@@ -11,7 +11,7 @@ module Agentf
       COMMANDS = %w[detect_framework generate_unit_tests run_tests].freeze
       MEMORY_CONCEPTS = {
         "reads" => [],
-        "writes" => ["store_success"],
+        "writes" => ["store_episode"],
         "policy" => "Persist test generation outcomes for future reuse."
       }.freeze
 
@@ -63,13 +63,21 @@ module Agentf
 
         template = @commands.generate_unit_tests(code_file)
 
-        memory.store_success(
-          title: "Generated #{test_type} tests for #{code_file}",
-          description: "Created #{template.test_file} with #{test_type} tests",
-          context: "Test framework: #{template.framework}",
-          tags: ["testing", test_type, code_file.split(".").last],
-          agent: name
-        )
+        res = safe_memory_write(attempted: { action: "store_episode", title: "Generated #{test_type} tests for #{code_file}", outcome: "positive", agent: name }) do
+          memory.store_episode(
+            type: "episode",
+            title: "Generated #{test_type} tests for #{code_file}",
+            description: "Created #{template.test_file} with #{test_type} tests",
+            context: "Test framework: #{template.framework}",
+            agent: name,
+            outcome: "positive"
+          )
+        end
+
+        if res.is_a?(Hash) && res["confirmation_required"]
+          log "Memory confirmation required when storing generated tests: #{res['confirmation_details'].inspect}"
+          return { "test_file" => template.test_file, "test_type" => test_type, "generated_code" => template.test_code, "confirmation_required" => true, "confirmation_details" => res["confirmation_details"], "attempted" => res["attempted"] }
+        end
 
         log "Created: #{template.test_file}"
 
@@ -90,6 +98,38 @@ module Agentf
 
         { "test_file" => test_file, "passed" => result["passed"] }
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+         # Support provider-driven TDD red-phase: when context signals a red phase,
+         # generate tests via the tester commands (if provided) and return a
+         # simulated failing test signature so orchestrator flows can short-circuit.
+         if context.to_h["tdd_phase"] == "red"
+           tester_commands = if commands.respond_to?(:fetch)
+                               commands.fetch("tester", nil)
+                             else
+                               commands["tester"]
+                             end
+
+           begin
+             tester_commands&.generate_unit_tests(context.to_h["source_file"]) if tester_commands&.respond_to?(:generate_unit_tests)
+           rescue StandardError
+             # ignore command errors for the simulated red phase
+           end
+
+           return { "tdd_phase" => "red", "passed" => false, "failure_signature" => "expected-failure-#{context.to_h["source_file"] || 'unspecified'}" }
+         end
+
+         action = context["action"] || (task.is_a?(String) ? "generate_tests" : context["action"])
+        case action
+        when "generate_tests"
+          code_file = task.is_a?(String) ? task : context["code_file"]
+          generate_tests(code_file, test_type: context["test_type"] || "unit")
+        when "run_tests"
+          run_tests(context["test_file"] || task)
+        else
+          { "error" => "Unknown action for Tester: #{action}" }
+        end
+      end
     end
   end
 end

data/lib/agentf/cli/agent.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "arg_parser"
+require_relative "../commands/registry"
+require_relative "../commands"
+require_relative "../agents"
+require_relative "../memory"
+
+module Agentf
+  module CLI
+    # CLI entry for running a single agent and returning JSON output.
+    class Agent
+      include ArgParser
+
+      def initialize
+        @memory = Agentf::Memory::RedisMemory.new
+      end
+
+      def run(args)
+        if args.empty? || args.include?("--help") || args.include?("help")
+          show_help
+          return
+        end
+
+        # Allow callers (like the TypeScript plugin) to append `--json` to
+        # request machine-readable output. Strip it here so it's not treated as
+        # part of the agent payload.
+        args = args.dup
+        json_output = !args.delete("--json").nil?
+        confirmed_write = parse_single_option(args, "--confirmed-write=")
+
+        agent_name = args.shift
+        payload = args.join(" ")
+
+        # Build command registry with default implementations
+        registry = Agentf::Commands::Registry.new
+        # Register known command providers
+        registry.register("explorer", Agentf::Commands::Explorer.new)
+        registry.register("tester", Agentf::Commands::Tester.new)
+        registry.register("debugger", Agentf::Commands::Debugger.new)
+        registry.register("designer", Agentf::Commands::Designer.new)
+        registry.register("security", Agentf::Commands::SecurityScanner.new)
+        registry.register("architecture", Agentf::Commands::Architecture.new)
+
+        # Load agents (classes already required via lib/agentf)
+        agents = {}
+        Agentf::Agents.constants.each do |const|
+          klass = Agentf::Agents.const_get(const)
+          next unless klass.is_a?(Class) && klass < Agentf::Agents::Base
+          agents[klass.typed_name] = klass.new(@memory)
+        end
+
+        agent = agents[agent_name.upcase]
+        unless agent
+          $stderr.puts JSON.generate({ ok: false, error: "Agent not found: #{agent_name}" })
+          exit 1
+        end
+
+        # Parse possible JSON payload
+        parsed = nil
+        begin
+          parsed = JSON.parse(payload) unless payload.strip.empty?
+        rescue StandardError
+          parsed = payload
+        end
+
+        previous = ENV["AGENTF_SUPPRESS_AGENT_LOGS"]
+        previous_auto_confirm = ENV["AGENTF_AUTO_CONFIRM_MEMORIES"]
+        ENV["AGENTF_SUPPRESS_AGENT_LOGS"] = "true" if json_output
+        ENV["AGENTF_AUTO_CONFIRM_MEMORIES"] = "true" unless confirmed_write.to_s.empty?
+
+        result = agent.execute(
+          task: parsed || payload,
+          context: { "confirmed_write" => confirmed_write },
+          agents: agents,
+          commands: registry,
+          logger: json_output ? nil : method(:puts)
+        )
+
+        puts JSON.generate(result)
+      ensure
+        ENV["AGENTF_SUPPRESS_AGENT_LOGS"] = previous if json_output
+        ENV["AGENTF_AUTO_CONFIRM_MEMORIES"] = previous_auto_confirm unless confirmed_write.to_s.empty?
+      end
+
+      def show_help
+        puts <<~HELP
+          Usage: agentf agent <AGENT_NAME> [payload] [--json] [--confirmed-write=<token>]
+
+          Runs a single agent and prints JSON result.
+        HELP
+      end
+    end
+  end
+end