agentf 0.4.1 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 289cd869806a950c6bb25a92b56cc05d5f90481f3bbe61af65d97af23768d321
-  data.tar.gz: 8f16969b26684677f01d01821c541d14a338b924a310ad9cdd83435e7b7896b3
+  metadata.gz: 5ba903d323be3e277a84ea8320af5b84a93456ad44b5d5aca0eb05e4c4ba29ae
+  data.tar.gz: 9a7125925e3a3fbf85b382b5ea278e3b39390c618dc9a571c1657acef86ec82d
 SHA512:
-  metadata.gz: 230df28afb68ed450b76c16185dc14227342cfc3048ed5ab25183a99aebb57c79833180d6185c3d35d33e89dac9d9a514b8ee6ebbeef8ecf64d3822f34db0b0f
-  data.tar.gz: 9347250f29a7402d17ed0784c16387e268461785c02aa1d3f94024bdab6a89f2022a065169b1055f6b168d4a0472a193000e88f5c428ea8ce4757ed2843ff066
+  metadata.gz: 7c5703863b0d31aa5318c124d690eb0dccb93839935e07155a6bd6265267741183c38475761d597b15bfa8f18ea3b7a515b7613c7d31a9327eb0e6162a186d09
+  data.tar.gz: d5b4072ee13a2e40d07f93c25c147298d63e8e782bfb75a66a03b10b90c4c8b844da396271fa0ed00f695be42067c009934ef3b4f8f5a01ad86d8272807abaf6

data/lib/agentf/agent_execution_contract.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Agentf
+  class AgentContractViolation < Agentf::Error
+    attr_reader :agent_name, :violations
+
+    def initialize(agent_name:, violations:)
+      @agent_name = agent_name
+      @violations = violations
+      super("Agent contract violated for #{agent_name}: #{violations.map { |v| v['code'] }.join(', ')}")
+    end
+  end
+
+  class AgentExecutionContract
+    def initialize(enabled:, mode:, policy: Agentf::AgentPolicy.new)
+      @enabled = enabled
+      @mode = normalize_mode(mode)
+      @policy = policy
+    end
+
+    def enabled?
+      @enabled && @mode != "off"
+    end
+
+    def enforcing?
+      enabled? && @mode == "enforcing"
+    end
+
+    def before!(agent_name:, boundaries:, context: {})
+      violations = @policy.validate(
+        agent_name: agent_name,
+        boundaries: boundaries,
+        context: context,
+        result: nil,
+        phase: :before
+      )
+      handle!(agent_name: agent_name, violations: violations)
+    end
+
+    def after!(agent_name:, boundaries:, context: {}, result:)
+      violations = @policy.validate(
+        agent_name: agent_name,
+        boundaries: boundaries,
+        context: context,
+        result: result,
+        phase: :after
+      ) + coding_execution_violations(agent_name: agent_name, result: result) + tdd_violations(agent_name: agent_name, context: context)
+      handle!(agent_name: agent_name, violations: violations)
+    end
+
+    private
+
+    def normalize_mode(value)
+      mode = value.to_s.strip.downcase
+      return mode if %w[advisory enforcing off].include?(mode)
+
+      "enforcing"
+    end
+
+    def handle!(agent_name:, violations:)
+      return if violations.empty? || !enabled?
+
+      raise Agentf::AgentContractViolation.new(agent_name: agent_name, violations: violations) if enforcing?
+    end
+
+    def tdd_violations(agent_name:, context:)
+      return [] unless [Agentf::AgentRoles::ENGINEER, Agentf::AgentRoles::UI_ENGINEER].include?(agent_name)
+
+      tdd_required = context["tdd_required"] == true || context.key?("tdd_phase")
+      return [] unless tdd_required
+
+      phase = context["tdd_phase"].to_s.strip
+      violations = []
+      if phase.empty?
+        violations << {
+          "code" => "missing_tdd_phase",
+          "severity" => "error",
+          "message" => "#{agent_name} requires explicit tdd_phase when TDD is enabled",
+          "agent" => agent_name,
+          "type" => "agent_contract"
+        }
+      end
+
+      if phase == "green" && context["expected_test_fix"].to_s.strip.empty?
+        violations << {
+          "code" => "missing_expected_test_fix",
+          "severity" => "error",
+          "message" => "#{agent_name} green phase requires expected_test_fix from failing test",
+          "agent" => agent_name,
+          "type" => "agent_contract"
+        }
+      end
+
+      violations
+    end
+
+    def coding_execution_violations(agent_name:, result:)
+      coding_agents = [Agentf::AgentRoles::ENGINEER, Agentf::AgentRoles::UI_ENGINEER, Agentf::AgentRoles::INCIDENT_RESPONDER]
+      return [] unless coding_agents.include?(agent_name)
+
+      unless result.is_a?(Hash) && [true, false].include?(result["success"])
+        return [
+          {
+            "code" => "invalid_success_flag",
+            "severity" => "error",
+            "message" => "#{agent_name} must return boolean success",
+            "agent" => agent_name,
+            "type" => "agent_contract"
+          }
+        ]
+      end
+
+      []
+    end
+  end
+end

data/lib/agentf/agent_policy.rb

@@ -4,19 +4,34 @@ module Agentf
   class AgentPolicy
     REQUIRED_KEYS = %w[always ask_first never].freeze
 
-    def validate(agent_name:, boundaries:, context: {}, result: nil)
+    def validate(agent_name:, boundaries:, context: {}, result: nil, phase: :any)
       errors = []
       boundaries = normalize(boundaries)
 
-      required_inputs = Array(boundaries["required_inputs"])
-      missing_inputs = required_inputs.reject { |key| context.key?(key) }
-      unless missing_inputs.empty?
-        errors << violation(
-          code: "missing_required_inputs",
-          severity: "error",
-          message: "#{agent_name} missing required inputs: #{missing_inputs.join(', ')}",
-          agent: agent_name
-        )
+      if %i[any before].include?(phase)
+        required_inputs = Array(boundaries["required_inputs"])
+        missing_inputs = required_inputs.reject { |key| context.key?(key) }
+        unless missing_inputs.empty?
+          errors << violation(
+            code: "missing_required_inputs",
+            severity: "error",
+            message: "#{agent_name} missing required inputs: #{missing_inputs.join(', ')}",
+            agent: agent_name
+          )
+        end
+      end
+
+      if %i[any after].include?(phase)
+        required_outputs = Array(boundaries["required_outputs"])
+        missing_outputs = required_outputs.reject { |key| output_present?(result, key) }
+        unless missing_outputs.empty?
+          errors << violation(
+            code: "missing_required_outputs",
+            severity: "error",
+            message: "#{agent_name} missing required outputs: #{missing_outputs.join(', ')}",
+            agent: agent_name
+          )
+        end
       end
 
       if result.is_a?(Hash) && result["error"]
@@ -41,6 +56,14 @@ module Agentf
 
     private
 
+    def output_present?(result, key)
+      return false unless result.is_a?(Hash)
+      return false unless result.key?(key)
+
+      value = result[key]
+      !value.nil?
+    end
+
     def violation(code:, severity:, message:, agent:)
       {
         "code" => code,

data/lib/agentf/agents/base.rb

@@ -55,11 +55,36 @@ module Agentf
       def initialize(memory)
         @memory = memory
         @name = self.class.typed_name
+        @execution_contract = Agentf::AgentExecutionContract.new(
+          enabled: Agentf.config.agent_contract_enabled,
+          mode: Agentf.config.agent_contract_mode
+        )
       end
 
       def log(message)
         puts "\n[#{@name}] #{message}"
       end
+
+      private
+
+      def execute_with_contract(context: {})
+        @execution_contract.before!(
+          agent_name: name,
+          boundaries: self.class.policy_boundaries,
+          context: context
+        )
+
+        result = yield
+
+        @execution_contract.after!(
+          agent_name: name,
+          boundaries: self.class.policy_boundaries,
+          context: context,
+          result: result
+        )
+
+        result
+      end
     end
   end
 end

data/lib/agentf/agents/debugger.rb

@@ -48,8 +48,8 @@ module Agentf
           "always" => ["Return analysis with root causes and suggested fix", "Persist debugging lesson"],
           "ask_first" => ["Applying speculative fixes without reproducible error"],
           "never" => ["Discard stack trace context when available"],
-          "required_inputs" => [],
-          "required_outputs" => ["analysis"]
+          "required_inputs" => ["error_text"],
+          "required_outputs" => ["analysis", "success"]
         }
       end
 
@@ -59,32 +59,35 @@ module Agentf
       end
 
       def diagnose(error, context: nil)
-        log "Diagnosing error"
-        log "  Error: #{error[0..100]}..."
-
-        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
-        )
-
-        log "Root cause: #{analysis.possible_causes.first}"
-        log "Suggested fix: #{analysis.suggested_fix}"
-
-        {
-          "error" => error,
-          "analysis" => {
-            "error_type" => analysis.error_type,
-            "possible_causes" => analysis.possible_causes,
-            "suggested_fix" => analysis.suggested_fix,
-            "stack_trace" => analysis.stack_trace
+        payload = { "error_text" => error, "context" => context }
+        execute_with_contract(context: payload) do
+          log "Diagnosing error"
+          log "  Error: #{error[0..100]}..."
+
+          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
+          )
+
+          log "Root cause: #{analysis.possible_causes.first}"
+          log "Suggested fix: #{analysis.suggested_fix}"
+
+          {
+            "success" => true,
+            "analysis" => {
+              "error_type" => analysis.error_type,
+              "possible_causes" => analysis.possible_causes,
+              "suggested_fix" => analysis.suggested_fix,
+              "stack_trace" => analysis.stack_trace
+            }
           }
-        }
+        end
       end
     end
   end

data/lib/agentf/agents/designer.rb

@@ -48,8 +48,8 @@ module Agentf
           "always" => ["Return generated component details", "Persist successful implementation pattern"],
           "ask_first" => ["Changing primary UI framework"],
           "never" => ["Return empty generated code for successful design task"],
-          "required_inputs" => [],
-          "required_outputs" => ["component", "generated_code"]
+          "required_inputs" => ["design_spec"],
+          "required_outputs" => ["component", "generated_code", "success"]
         }
       end
 
@@ -59,26 +59,29 @@ module Agentf
       end
 
       def implement_design(design_spec, framework: "react")
-        log "Implementing design: #{design_spec}"
-
-        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
-        )
-
-        log "Created component: #{spec.name}"
-
-        {
-          "design_spec" => design_spec,
-          "component" => spec.name,
-          "framework" => framework,
-          "generated_code" => spec.code
-        }
+        execute_with_contract(context: { "design_spec" => design_spec, "framework" => framework }) do
+          log "Implementing design: #{design_spec}"
+
+          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
+          )
+
+          log "Created component: #{spec.name}"
+
+          {
+            "design_spec" => design_spec,
+            "component" => spec.name,
+            "framework" => framework,
+            "generated_code" => spec.code,
+            "success" => true
+          }
+        end
       end
     end
   end

data/lib/agentf/agents/reviewer.rb

@@ -47,33 +47,35 @@ module Agentf
           "always" => ["Report approval decision", "Highlight known pitfalls in review findings"],
           "ask_first" => ["Approving with unresolved critical security issues"],
           "never" => ["Approve without any review evidence"],
-          "required_inputs" => [],
+          "required_inputs" => ["execution"],
           "required_outputs" => ["approved", "issues"]
         }
       end
 
       def review(subtask_result)
-        log "Reviewing subtask #{subtask_result['subtask_id']}"
+        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_pitfalls(limit: 5)
+          memories = memory.get_recent_memories(limit: 5)
 
-        issues = []
+          issues = []
 
-        pitfalls.each do |pitfall|
-          issues << "Warning: Known pitfall - #{pitfall['title']}" if pitfall["type"] == "pitfall"
-        end
+          pitfalls.each do |pitfall|
+            issues << "Warning: Known pitfall - #{pitfall['title']}" if pitfall["type"] == "pitfall"
+          end
 
-        approved = issues.empty?
+          approved = issues.empty?
 
-        if approved
-          log "Approved (no issues found)"
-        else
-          log "Issues found: #{issues.size}"
-          issues.each { |issue| log "  - #{issue}" }
-        end
+          if approved
+            log "Approved (no issues found)"
+          else
+            log "Issues found: #{issues.size}"
+            issues.each { |issue| log "  - #{issue}" }
+          end
 
-        { "approved" => approved, "issues" => issues }
+          { "approved" => approved, "issues" => issues }
+        end
       end
     end
   end

data/lib/agentf/agents/security.rb

@@ -48,7 +48,7 @@ module Agentf
           "always" => ["Return issue list and best practices", "Persist outcome as success or pitfall"],
           "ask_first" => ["Allowing known secret patterns in context"],
           "never" => ["Echo raw secrets in output"],
-          "required_inputs" => [],
+          "required_inputs" => ["task"],
           "required_outputs" => ["issues", "best_practices"]
         }
       end
@@ -59,30 +59,32 @@ module Agentf
       end
 
       def assess(task:, context: {})
-        log "Running security assessment"
-
-        findings = @commands.scan(task: task, context: context)
-        summary = summarize_findings(findings)
-
-        if findings["issues"].empty?
-          memory.store_success(
-            title: "Security review passed",
-            description: summary,
-            context: task,
-            tags: ["security", "pass"],
-            agent: name
-          )
-        else
-          memory.store_pitfall(
-            title: "Security findings detected",
-            description: summary,
-            context: task,
-            tags: ["security", "warning"],
-            agent: name
-          )
+        execute_with_contract(context: context.merge("task" => task)) do
+          log "Running security assessment"
+
+          findings = @commands.scan(task: task, context: context)
+          summary = summarize_findings(findings)
+
+          if findings["issues"].empty?
+            memory.store_success(
+              title: "Security review passed",
+              description: summary,
+              context: task,
+              tags: ["security", "pass"],
+              agent: name
+            )
+          else
+            memory.store_pitfall(
+              title: "Security findings detected",
+              description: summary,
+              context: task,
+              tags: ["security", "warning"],
+              agent: name
+            )
+          end
+
+          findings.merge("best_practices" => @commands.best_practices)
         end
-
-        findings.merge("best_practices" => @commands.best_practices)
       end
 
       private

data/lib/agentf/agents/specialist.rb

@@ -47,37 +47,44 @@ module Agentf
           "always" => ["Persist execution outcome", "Return deterministic success boolean"],
           "ask_first" => ["Applying architecture style changes across unrelated modules"],
           "never" => ["Claim implementation complete without execution result"],
-          "required_inputs" => [],
+          "required_inputs" => ["description"],
           "required_outputs" => ["subtask_id", "success"]
         }
       end
 
       def execute(subtask)
-        log "Executing: #{subtask['description']}"
+        normalized_subtask = subtask.merge(
+          "id" => subtask["id"] || "ad-hoc",
+          "description" => subtask["description"] || "Execute implementation step"
+        )
 
-        success = subtask.fetch("success", true)
+        execute_with_contract(context: normalized_subtask) do
+          log "Executing: #{normalized_subtask['description']}"
 
-        if success
-          memory.store_success(
-            title: "Completed: #{subtask['description']}",
-            description: "Successfully executed subtask #{subtask['id']}",
-            context: "Working on #{subtask.fetch('task', 'unknown task')}",
-            tags: ["implementation", subtask.fetch("language", "general")],
-            agent: name
-          )
-          log "Stored success memory"
-        else
-          memory.store_pitfall(
-            title: "Failed: #{subtask['description']}",
-            description: "Subtask #{subtask['id']} failed",
-            context: "Working on #{subtask.fetch('task', 'unknown task')}",
-            tags: ["failure", "implementation"],
-            agent: name
-          )
-          log "Stored pitfall memory"
-        end
+          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"
+          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"
+          end
 
-        { "subtask_id" => subtask["id"], "success" => success, "result" => "Code executed" }
+          { "subtask_id" => normalized_subtask["id"], "success" => success, "result" => "Code executed" }
+        end
       end
     end
   end

data/lib/agentf/cli/router.rb

@@ -85,6 +85,8 @@ module Agentf
             AGENTF_METRICS_ENABLED=true|false   Enable/disable workflow metrics capture and CLI
             AGENTF_WORKFLOW_CONTRACT_ENABLED=true|false   Enable/disable workflow contract checks
             AGENTF_WORKFLOW_CONTRACT_MODE=advisory|enforcing|off   Contract behavior mode
+            AGENTF_AGENT_CONTRACT_ENABLED=true|false   Enable/disable per-agent contract checks
+            AGENTF_AGENT_CONTRACT_MODE=advisory|enforcing|off   Per-agent contract behavior mode
             AGENTF_DEFAULT_PACK=generic|rails_standard|rails_37signals|rails_feature_spec
             AGENTF_GEM_PATH=/path/to/gem   Path to agentf gem (for OpenCode plugin binary resolution)
 

data/lib/agentf/installer.rb

@@ -353,7 +353,7 @@ module Agentf
     end
 
     def render_opencode_plugin
-      <<~TYPESCRIPT
+      <<~'TYPESCRIPT'
         import { execFile } from "node:child_process";
         import { promisify } from "node:util";
         import path from "node:path";
@@ -362,44 +362,127 @@ module Agentf
 
         const execFileAsync = promisify(execFile);
 
-        async function resolveAgentfBinary(directory: string): Promise<string> {
+        type AgentfBinaryResolution = {
+          binaryPath: string;
+          source: string;
+          attempts: string[];
+        };
+
+        type PreflightCache = {
+          workspaceRoot: string;
+          binaryPath: string;
+        };
+
+        let preflightCache: PreflightCache | null = null;
+
+        function buildPreflightError(attempts: string[], extraDetails?: string): Error {
+          const lines = [
+            "Agentf plugin preflight failed: unable to run a compatible agentf binary.",
+            "",
+            "Resolution attempts:",
+            ...attempts.map((attempt) => `- ${attempt}`),
+            "",
+            "Remediation:",
+            "- Set AGENTF_GEM_PATH to your installed agentf gem path (contains bin/agentf).",
+            "- Ensure your Ruby version manager shims are on PATH (rbenv/asdf/mise), then retry.",
+            "- Verify with: agentf version",
+          ];
+
+          if (extraDetails) {
+            lines.push("", "Details:", extraDetails);
+          }
+
+          return new Error(lines.join("\n"));
+        }
+
+        function formatExecFailure(error: unknown): string {
+          const failure = error as {
+            message?: string;
+            stdout?: Buffer | string;
+            stderr?: Buffer | string;
+          };
+
+          const stdout = failure.stdout?.toString().trim();
+          const stderr = failure.stderr?.toString().trim();
+          const message = failure.message?.trim();
+          const parts = [
+            message ? `message: ${message}` : null,
+            stderr ? `stderr: ${stderr}` : null,
+            stdout ? `stdout: ${stdout}` : null,
+          ].filter(Boolean);
+
+          return parts.length > 0 ? parts.join("\n") : "No additional process output.";
+        }
+
+        async function resolveAgentfBinary(directory: string): Promise<AgentfBinaryResolution> {
+          const attempts: string[] = [];
           const gemPath = process.env.AGENTF_GEM_PATH;
           if (gemPath) {
             const binaryPath = path.join(gemPath, "bin", "agentf");
             if (fs.existsSync(binaryPath)) {
-              return binaryPath;
+              attempts.push(`AGENTF_GEM_PATH succeeded: ${binaryPath}`);
+              return { binaryPath, source: "AGENTF_GEM_PATH", attempts };
             }
+            attempts.push(`AGENTF_GEM_PATH set but missing executable: ${binaryPath}`);
+          } else {
+            attempts.push("AGENTF_GEM_PATH is not set");
           }
 
           const projectRoot = path.resolve(directory);
           const projectBinary = path.join(projectRoot, "bin", "agentf");
           if (fs.existsSync(projectBinary)) {
-            return projectBinary;
+            attempts.push(`Project bin fallback succeeded: ${projectBinary}`);
+            return { binaryPath: projectBinary, source: "project-bin", attempts };
           }
+          attempts.push(`Project bin fallback missing: ${projectBinary}`);
 
           try {
             const { stdout } = await execFileAsync("command", ["-v", "agentf"], { shell: true });
             const whichPath = stdout.toString().trim();
             if (whichPath && fs.existsSync(whichPath)) {
-              return whichPath;
+              attempts.push(`PATH fallback succeeded: ${whichPath}`);
+              return { binaryPath: whichPath, source: "PATH", attempts };
             }
+            attempts.push("PATH fallback returned empty or non-existent path");
           } catch {
-            // command -v failed
+            attempts.push("PATH fallback failed: command -v agentf did not resolve");
           }
 
-          throw new Error(
-            "agentf binary not found. Set AGENTF_GEM_PATH environment variable to the path where agentf gem is installed, " +
-            "or ensure bin/agentf exists in your project root. " +
-            "Example: AGENTF_GEM_PATH=$(bundle show agentf) opencode run \"your task\""
-          );
+          throw buildPreflightError(attempts);
+        }
+
+        async function ensureAgentfPreflight(directory: string): Promise<string> {
+          const workspaceRoot = path.resolve(directory);
+          if (preflightCache && preflightCache.workspaceRoot === workspaceRoot) {
+            return preflightCache.binaryPath;
+          }
+
+          const resolution = await resolveAgentfBinary(workspaceRoot);
+
+          try {
+            await execFileAsync(resolution.binaryPath, ["version"], {
+              cwd: workspaceRoot,
+              env: process.env,
+              maxBuffer: 1024 * 1024,
+            });
+          } catch (error) {
+            throw buildPreflightError(
+              resolution.attempts,
+              [`Resolved via ${resolution.source}: ${resolution.binaryPath}`, formatExecFailure(error)].join("\n")
+            );
+          }
+
+          preflightCache = { workspaceRoot, binaryPath: resolution.binaryPath };
+          return resolution.binaryPath;
         }
 
         async function runAgentfCli(directory: string, subcommand: string, command: string, args: string[]) {
-          const binaryPath = await resolveAgentfBinary(directory);
-          const commandArgs = ["exec", "ruby", binaryPath, subcommand, command, ...args, "--json"];
+          const workspaceRoot = path.resolve(directory);
+          const binaryPath = await ensureAgentfPreflight(workspaceRoot);
+          const commandArgs = [subcommand, command, ...args, "--json"];
 
-          const { stdout } = await execFileAsync("bundle", commandArgs, {
-            cwd: path.resolve(directory),
+          const { stdout } = await execFileAsync(binaryPath, commandArgs, {
+            cwd: workspaceRoot,
             env: process.env,
             maxBuffer: 1024 * 1024 * 5,
           });
@@ -409,6 +492,8 @@ module Agentf
         }
 
         export const agentfPlugin: Plugin = async () => {
+          await ensureAgentfPreflight(process.env.PWD || process.cwd());
+
           return {
             tools: {
               "agentf-code-glob": tool({

data/lib/agentf/service/providers.rb

@@ -125,6 +125,8 @@ module Agentf
           logger&.call("→ #{agent_name} Complete")
           result
         rescue StandardError => e
+          raise if e.is_a?(Agentf::AgentContractViolation)
+
           logger&.call("→ #{agent_name} Error: #{e.message}")
           { "error" => e.message, "agent" => agent_name }
         end

data/lib/agentf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agentf
-  VERSION = "0.4.1"
+  VERSION = "0.4.4"
 end

data/lib/agentf/workflow_engine.rb

@@ -166,6 +166,10 @@ module Agentf
         enriched_context["expected_test_fix"] = @workflow_state.dig("tdd", "failure_signature")
       end
 
+      if agent_name == Agentf::AgentRoles::REVIEWER
+        enriched_context["execution"] = @workflow_state["results"].last&.fetch("result", {}) || {}
+      end
+
       result = @provider.execute_agent(
         agent_name: agent_name,
         task: @workflow_state["task"],
@@ -179,7 +183,8 @@ module Agentf
         agent_name: agent_name,
         boundaries: @agents.fetch(agent_name).class.policy_boundaries,
         context: enriched_context,
-        result: result
+        result: result,
+        phase: :after
       )
       append_policy_violations(policy_violations)
 

data/lib/agentf.rb

@@ -15,7 +15,8 @@ module Agentf
   class Config
     attr_reader :redis_url
     attr_accessor :project_name, :base_path, :metrics_enabled, :workflow_contract_enabled,
-                  :workflow_contract_mode, :default_pack, :gem_path
+                  :workflow_contract_mode, :agent_contract_enabled, :agent_contract_mode,
+                  :default_pack, :gem_path
 
     def initialize
       @redis_url = normalize_redis_url(ENV.fetch("REDIS_URL", "redis://localhost:6379"))
@@ -29,6 +30,13 @@ module Agentf
       @workflow_contract_mode = normalize_contract_mode(
         ENV.fetch("AGENTF_WORKFLOW_CONTRACT_MODE", "advisory")
       )
+      @agent_contract_enabled = parse_boolean(
+        ENV.fetch("AGENTF_AGENT_CONTRACT_ENABLED", "true"),
+        default: true
+      )
+      @agent_contract_mode = normalize_contract_mode(
+        ENV.fetch("AGENTF_AGENT_CONTRACT_MODE", "enforcing")
+      )
       @default_pack = ENV.fetch("AGENTF_DEFAULT_PACK", "generic").to_s.strip.downcase
       @gem_path = ENV.fetch("AGENTF_GEM_PATH", nil)
     end
@@ -81,6 +89,7 @@ require_relative "agentf/service/providers"
 require_relative "agentf/context_builder"
 require_relative "agentf/packs"
 require_relative "agentf/agent_policy"
+require_relative "agentf/agent_execution_contract"
 require_relative "agentf/workflow_contract"
 require_relative "agentf/workflow_engine"
 require_relative "agentf/installer"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agentf
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.4
 platform: ruby
 authors:
 - Neal Deters
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-08 00:00:00.000000000 Z
+date: 2026-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -94,6 +94,7 @@ extra_rdoc_files: []
 files:
 - bin/agentf
 - lib/agentf.rb
+- lib/agentf/agent_execution_contract.rb
 - lib/agentf/agent_policy.rb
 - lib/agentf/agent_roles.rb
 - lib/agentf/agents.rb