False-Refusal Wrapper Half (WT-3) Implementation Plan¶

// in internal/transcript/result.go
// FailedCriticalOutcome scans the LAST turn region of the JSONL transcript at
// path for a critical-outcome MCP tool call (decline_implementation /
// already_done, under any MCP namespace prefix) whose tool_result came back
// is_error:true. Returns the bare tool name (e.g. "decline_implementation"),
// the error text the operator returned, and found=true on a hit. found=false
// with nil error means no failed critical-outcome call (the common case).
func FailedCriticalOutcome(path string) (tool, errText string, found bool, err error)

// TestFailedCriticalOutcome covers the rejected-decline detection that the
// wrapper uses to re-prompt the agent instead of finishing a turn silently.
func TestFailedCriticalOutcome(t *testing.T) {
    tests := []struct {
        name      string
        lines     []string
        wantTool  string
        wantErrSub string
        wantFound bool
    }{
        {
            name: "rejected decline_implementation",
            lines: []string{
                `{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"t1","name":"mcp__tatara__decline_implementation","input":{"reason":"   "}}]}}`,
                `{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","is_error":true,"content":"400: reason must not be blank"}]}}`,
            },
            wantTool:   "decline_implementation",
            wantErrSub: "reason must not be blank",
            wantFound:  true,
        },
        {
            name: "rejected already_done",
            lines: []string{
                `{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"a9","name":"mcp__tatara__already_done","input":{}}]}}`,
                `{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"a9","is_error":true,"content":"400: reason required"}]}}`,
            },
            wantTool:   "already_done",
            wantErrSub: "reason required",
            wantFound:  true,
        },
        {
            name: "successful decline is not a hit",
            lines: []string{
                `{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"t1","name":"mcp__tatara__decline_implementation","input":{"reason":"blocked on creds"}}]}}`,
                `{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","is_error":false,"content":"ok"}]}}`,
            },
            wantFound: false,
        },
        {
            name: "unrelated failing tool is not a hit",
            lines: []string{
                `{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"b1","name":"Bash","input":{"command":"false"}}]}}`,
                `{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"b1","is_error":true,"content":"exit 1"}]}}`,
            },
            wantFound: false,
        },
        {
            name: "later successful retry supersedes earlier failure",
            lines: []string{
                `{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"t1","name":"mcp__tatara__decline_implementation","input":{"reason":""}}]}}`,
                `{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","is_error":true,"content":"400"}]}}`,
                `{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"t2","name":"mcp__tatara__decline_implementation","input":{"reason":"real"}}]}}`,
                `{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t2","is_error":false,"content":"ok"}]}}`,
            },
            wantFound: false,
        },
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            dir := t.TempDir()
            path := filepath.Join(dir, "t.jsonl")
            require.NoError(t, os.WriteFile(path, []byte(strings.Join(tt.lines, "\n")+"\n"), 0o644))

            tool, errText, found, err := transcript.FailedCriticalOutcome(path)
            require.NoError(t, err)
            require.Equal(t, tt.wantFound, found)
            if tt.wantFound {
                require.Equal(t, tt.wantTool, tool)
                require.Contains(t, errText, tt.wantErrSub)
            }
        })
    }
}

func TestFailedCriticalOutcome_MissingFileErrors(t *testing.T) {
    _, _, _, err := transcript.FailedCriticalOutcome(filepath.Join(t.TempDir(), "nope.jsonl"))
    require.Error(t, err)
}

// criticalOutcomeTools is the set of MCP outcome tools whose rejection by the
// operator must be propagated back to the agent (a silently dropped decline is
// what produced the false "refused-no-explanation" park). Matched on the bare
// tool name after stripping any MCP namespace prefix (mcp__<server>__<name>).
var criticalOutcomeTools = map[string]bool{
    "decline_implementation": true,
    "already_done":           true,
}

// bareToolName strips an MCP namespace prefix ("mcp__tatara__decline_implementation"
// -> "decline_implementation"). A non-prefixed name is returned unchanged.
func bareToolName(name string) string {
    if i := strings.LastIndex(name, "__"); i >= 0 {
        return name[i+2:]
    }
    return name
}

// outcomeLine is the minimal view of a transcript line carrying tool_use and
// tool_result blocks, used by FailedCriticalOutcome. content is decoded as an
// array of blocks; genuine string-content user prompts simply fail to unmarshal
// into the array and are skipped.
type outcomeLine struct {
    Type    string `json:"type"`
    Message *struct {
        Content []struct {
            Type      string `json:"type"`
            ID        string `json:"id"`
            Name      string `json:"name"`
            ToolUseID string `json:"tool_use_id"`
            IsError   bool   `json:"is_error"`
            Content   json.RawMessage `json:"content"`
        } `json:"content"`
    } `json:"message"`
}

// FailedCriticalOutcome scans the JSONL transcript at path for a critical-outcome
// MCP tool call (decline_implementation / already_done, under any MCP namespace
// prefix) whose tool_result came back is_error:true. It returns the bare tool
// name, the operator's error text, and found=true on a hit. found=false (nil
// error) is the common no-failure case. A later non-error result for the same
// tool_use_id supersedes an earlier failure (the agent already corrected).
func FailedCriticalOutcome(path string) (tool, errText string, found bool, err error) {
    f, oerr := os.Open(path)
    if oerr != nil {
        return "", "", false, fmt.Errorf("open transcript: %w", oerr)
    }
    defer func() { _ = f.Close() }()

    criticalUseID := map[string]string{} // tool_use_id -> bare critical tool name
    failed := map[string]string{}        // tool_use_id -> error text (only failures)

    sc := bufio.NewScanner(f)
    sc.Buffer(make([]byte, 1024*1024), maxPartialBytes)
    for sc.Scan() {
        var ol outcomeLine
        if err := json.Unmarshal(sc.Bytes(), &ol); err != nil || ol.Message == nil {
            continue
        }
        for _, b := range ol.Message.Content {
            switch b.Type {
            case "tool_use":
                if name := bareToolName(b.Name); criticalOutcomeTools[name] && b.ID != "" {
                    criticalUseID[b.ID] = name
                }
            case "tool_result":
                if b.ToolUseID == "" {
                    continue
                }
                if b.IsError {
                    failed[b.ToolUseID] = jsonContentString(b.Content)
                } else {
                    // A later success for the same call clears an earlier failure.
                    delete(failed, b.ToolUseID)
                }
            }
        }
    }
    if err := sc.Err(); err != nil {
        return "", "", false, fmt.Errorf("scan transcript: %w", err)
    }

    for id, et := range failed {
        if name, ok := criticalUseID[id]; ok {
            return name, et, true, nil
        }
    }
    return "", "", false, nil
}

// jsonContentString renders a tool_result content field as a human-readable
// string. The field is either a JSON string ("400: ...") or an array of blocks;
// in the array case the raw JSON is returned so the message is never empty.
func jsonContentString(raw json.RawMessage) string {
    if isJSONString(raw) {
        var s string
        if json.Unmarshal(raw, &s) == nil {
            return s
        }
    }
    return string(raw)
}

func CommitAndPush(dir, branch, message string, git GitRunner) (pushed bool, err error)
func CommitAndPushAll(workspace string, repos []RepoSpec, branch, message string, git GitRunner) (pushed []string, err error)

  pushed, err := bootstrap.CommitAndPush("/tmp/dir", "feat/x", "tatara agent: feat/x", fakeGit)
  require.NoError(t, err)
  require.True(t, pushed, "dirty tree must report pushed=true")

  pushed, err := bootstrap.CommitAndPush("/tmp/dir", "feat/x", "msg", fakeGit)
  require.NoError(t, err)
  require.False(t, pushed, "clean tree must report pushed=false")

  pushedRepos, err := bootstrap.CommitAndPushAll("/tmp/ws", repos, "feat/x", "msg", fakeGit)
  require.NoError(t, err)
  require.Equal(t, []string{"good"}, pushedRepos, "only the valid-namespace repo must be reported pushed")

// TestCommitAndPushAll_ReturnsOnlyDirtyRepos asserts the returned list contains
// exactly the repos that had a diff and pushed; a clean repo is omitted.
func TestCommitAndPushAll_ReturnsOnlyDirtyRepos(t *testing.T) {
    // dirtyByDir[dir]=true makes "diff --cached --quiet" report dirty for that dir.
    dirtyByDir := map[string]bool{
        filepath.Join("/tmp/ws", "owner", "dirtyrepo"): true,
    }
    fakeGit := func(dir string, args ...string) error {
        if len(args) >= 2 && args[0] == "diff" && args[1] == "--cached" {
            if dirtyByDir[dir] {
                return errFake("dirty")
            }
            return nil // clean
        }
        return nil
    }

    repos := []bootstrap.RepoSpec{
        {Name: "dirty", URL: "https://github.com/owner/dirtyrepo"},
        {Name: "clean", URL: "https://github.com/owner/cleanrepo"},
    }
    pushed, err := bootstrap.CommitAndPushAll("/tmp/ws", repos, "feat/x", "msg", fakeGit)
    require.NoError(t, err)
    require.Equal(t, []string{"dirty"}, pushed)
}

// CommitAndPush stages all changes, and when something is staged commits and
// pushes the branch to origin. A clean tree is left untouched: nothing is
// committed or pushed, so no empty remote branch is created. Returns pushed=true
// only when a commit was made and the push succeeded.
func CommitAndPush(dir, branch, message string, git GitRunner) (pushed bool, err error) {
    if err := git(dir, "add", "-A"); err != nil {
        return false, err
    }
    // `diff --cached --quiet` exits zero (nil) when the tree is clean.
    if git(dir, "diff", "--cached", "--quiet") == nil {
        return false, nil
    }
    if err := git(dir, "commit", "--no-verify", "-m", message); err != nil {
        return false, err
    }
    if err := git(dir, "push", "--no-verify", "-u", "origin", branch); err != nil {
        return false, err
    }
    return true, nil
}

// CommitAndPushAll runs CommitAndPush in each repo dir under workspace and
// returns the Name of every repo that had a diff and pushed, so the caller can
// report the exact touched-repo set to the operator.
func CommitAndPushAll(workspace string, repos []RepoSpec, branch, message string, git GitRunner) (pushed []string, err error) {
    for _, r := range repos {
        ns := namespacePath(r.URL)
        if ns == "" || filepath.Clean(filepath.Join(workspace, ns)) == filepath.Clean(workspace) {
            continue // no valid namespace: skip to avoid operating on the workspace root
        }
        dir := filepath.Join(workspace, ns)
        ok, perr := CommitAndPush(dir, branch, message, git)
        if perr != nil {
            return pushed, fmt.Errorf("commit/push %s: %w", r.Name, perr)
        }
        if ok {
            pushed = append(pushed, r.Name)
        }
    }
    return pushed, nil
}

// in internal/turn/turn.go, on type Record
PushedRepos []string `json:"pushedRepos,omitempty"`

// in internal/metrics/metrics.go, on type Metrics
OutcomeRepromptTotal *prometheus.CounterVec // labels: tool=decline_implementation|already_done, result=reprompted|budget_exhausted

    // PushedRepos is the set of project repos this turn actually committed and
    // pushed (had a diff). Reported to the operator on the callback so it knows
    // which repos were touched in a multi-repo task (Defect A). Empty/absent for
    // a turn that pushed nothing or a single-repo task with no diff.
    PushedRepos []string `json:"pushedRepos,omitempty"`

    // Outcome-rejection re-prompt counter (rule 13): a critical outcome tool
    // (decline_implementation/already_done) the operator rejected, surfaced back
    // to the agent for correction instead of finishing the turn silently.
    OutcomeRepromptTotal *prometheus.CounterVec // labels: tool, result=reprompted|budget_exhausted

        OutcomeRepromptTotal: prometheus.NewCounterVec(prometheus.CounterOpts{
            Name: "ccw_outcome_reprompt_total", Help: "Critical-outcome MCP tool rejections re-prompted to the agent, by tool and result."}, []string{"tool", "result"}),

        m.AuthTotal, m.TurnResumes, m.OutcomeRepromptTotal, m.BootstrapRenderTotal,

    // repromptMu guards outcomeReprompts, the per-pod count of times a rejected
    // critical-outcome MCP tool call (decline_implementation/already_done) was
    // surfaced back to the agent via a re-prompt instead of finishing the turn
    // silently (Defect C). Capped at maxOutcomeReprompts so a perpetually-failing
    // agent still reaches the operator's empty-retry cap rather than looping here.
    repromptMu       sync.Mutex
    outcomeReprompts int

    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/transcript"

// maxOutcomeReprompts bounds how many times this pod re-prompts the agent after
// the operator rejects a critical-outcome tool call. Beyond this the finaliser
// delivers the callback normally and the operator's empty-retry cap takes over.
const maxOutcomeReprompts = 2

          if cfg.TaskBranch != "" {
              pushStart := time.Now()
              var err error
              if len(cfg.Repos) > 0 {
                  err = bootstrap.CommitAndPushAll(cfg.Workspace, cfg.Repos, cfg.TaskBranch, "tatara agent: "+cfg.TaskBranch, gitRunner())
              } else {
                  // Single-repo clones into workspace/<owner>/<repo>, not the
                  // workspace root, so commit/push must target that subdir.
                  repoDir := bootstrap.RepoDir(cfg.Workspace, cfg.RepoURL)
                  if repoDir == "" {
                      err = fmt.Errorf("cannot derive repo dir from REPO_URL %q for commit/push", cfg.RepoURL)
                  } else {
                      err = bootstrap.CommitAndPush(repoDir, cfg.TaskBranch, "tatara agent: "+cfg.TaskBranch, gitRunner())
                  }
              }
              if err != nil {
                  m.CommitPushTotal.WithLabelValues("fail").Inc()
                  log.Error("commit/push failed", "action", "commit_push", "branch", cfg.TaskBranch, "error", err, "duration_ms", time.Since(pushStart).Milliseconds())
              } else {
                  m.CommitPushTotal.WithLabelValues("ok").Inc()
                  log.Info("commit/push succeeded", "action", "commit_push", "branch", cfg.TaskBranch, "duration_ms", time.Since(pushStart).Milliseconds())
              }
          }

          if cfg.TaskBranch != "" {
              pushStart := time.Now()
              var err error
              if len(cfg.Repos) > 0 {
                  var pushedRepos []string
                  pushedRepos, err = bootstrap.CommitAndPushAll(cfg.Workspace, cfg.Repos, cfg.TaskBranch, "tatara agent: "+cfg.TaskBranch, gitRunner())
                  rec.PushedRepos = pushedRepos
              } else {
                  // Single-repo clones into workspace/<owner>/<repo>, not the
                  // workspace root, so commit/push must target that subdir.
                  repoDir := bootstrap.RepoDir(cfg.Workspace, cfg.RepoURL)
                  if repoDir == "" {
                      err = fmt.Errorf("cannot derive repo dir from REPO_URL %q for commit/push", cfg.RepoURL)
                  } else {
                      var pushed bool
                      pushed, err = bootstrap.CommitAndPush(repoDir, cfg.TaskBranch, "tatara agent: "+cfg.TaskBranch, gitRunner())
                      if pushed {
                          rec.PushedRepos = []string{primaryRepoName(cfg)}
                      }
                  }
              }
              if err != nil {
                  m.CommitPushTotal.WithLabelValues("fail").Inc()
                  log.Error("commit/push failed", "action", "commit_push", "branch", cfg.TaskBranch, "error", err, "duration_ms", time.Since(pushStart).Milliseconds())
              } else {
                  m.CommitPushTotal.WithLabelValues("ok").Inc()
                  log.Info("commit/push succeeded", "action", "commit_push", "branch", cfg.TaskBranch,
                      "pushed_repos", rec.PushedRepos, "duration_ms", time.Since(pushStart).Milliseconds())
              }
          }

          // Defect C: a critical outcome tool (decline_implementation/already_done)
          // the operator rejected (e.g. blank reason -> 400) shows up in the turn
          // transcript as an is_error tool_result. Rather than let the turn finish
          // silently (which the operator misreads as "refused-no-explanation"),
          // re-prompt the agent to retry with a non-blank reason, and skip THIS
          // turn's callback - the re-prompted turn delivers its own. Bounded by
          // maxOutcomeReprompts so a stuck agent still reaches the operator's cap.
          if path := a.sess.TranscriptPath(); path != "" {
              toolName, errText, found, ferr := transcript.FailedCriticalOutcome(path)
              if ferr != nil {
                  log.Warn("outcome-reprompt scan failed; delivering callback as-is",
                      "action", "outcome_reprompt", "turn_id", rec.ID, "error", ferr)
              } else if found {
                  if a.reprompt(toolName, errText, rec.CallbackURL) {
                      m.OutcomeRepromptTotal.WithLabelValues(toolName, "reprompted").Inc()
                      log.Info("re-prompted agent after rejected outcome tool; suppressing this turn's callback",
                          "action", "outcome_reprompt", "turn_id", rec.ID, "tool", toolName, "error", errText)
                      return
                  }
                  m.OutcomeRepromptTotal.WithLabelValues(toolName, "budget_exhausted").Inc()
                  log.Warn("outcome re-prompt budget exhausted; delivering callback so the operator cap applies",
                      "action", "outcome_reprompt", "turn_id", rec.ID, "tool", toolName)
              }
          }

// reprompt submits a corrective turn telling the agent its critical outcome
// tool call was rejected and must be retried with a non-blank reason. It returns
// true when a re-prompt was issued, false when the budget is exhausted or the
// session would not accept a new turn (in which case the caller delivers the
// callback so the operator's empty-retry cap applies). The corrective text reuses
// the same callback URL so the eventual completion still reaches the operator.
func (a *app) reprompt(tool, errText, callbackURL string) bool {
    a.repromptMu.Lock()
    if a.outcomeReprompts >= maxOutcomeReprompts {
        a.repromptMu.Unlock()
        return false
    }
    a.outcomeReprompts++
    a.repromptMu.Unlock()

    msg := fmt.Sprintf("Your %s call was rejected by the operator: %s. "+
        "This is mandatory: call %s again with a clear, non-blank `reason` explaining the decision. "+
        "Do not finish the turn until the call succeeds.", tool, strings.TrimSpace(errText), tool)
    if _, err := a.sess.Submit(msg, callbackURL); err != nil {
        // Roll back the budget consumption: no turn was actually submitted.
        a.repromptMu.Lock()
        a.outcomeReprompts--
        a.repromptMu.Unlock()
        a.log.Warn("outcome re-prompt submit failed; delivering callback instead",
            "action", "outcome_reprompt", "tool", tool, "error", err)
        return false
    }
    return true
}

// primaryRepoName is the human-facing name of the single repo a non-cross-repo
// pod is bound to, derived from the namespace path of REPO_URL ("owner/repo").
// Used to populate PushedRepos in single-repo mode where there is no RepoSpec.
func primaryRepoName(cfg config) string {
    if dir := bootstrap.RepoDir(cfg.Workspace, cfg.RepoURL); dir != "" {
        return filepath.Base(dir)
    }
    return cfg.RepoURL
}

    // submitFn is the turn-submit primitive reprompt() uses; production wires it
    // to a.sess.Submit. Injectable so the re-prompt budget logic is unit-testable
    // without a live PTY session.
    submitFn func(text, callbackURL string) (string, error)

  a.submitFn = a.sess.Submit

  if _, err := a.submitFn(msg, callbackURL); err != nil {

package main

import (
    "errors"
    "sync"
    "testing"

    "github.com/stretchr/testify/require"
)

func TestReprompt_BudgetAndRollback(t *testing.T) {
    t.Run("re-prompts up to the cap then refuses", func(t *testing.T) {
        var calls int
        a := &app{log: testLogger(), submitFn: func(text, cb string) (string, error) {
            calls++
            require.Contains(t, text, "rejected by the operator")
            require.Contains(t, text, "non-blank")
            require.Equal(t, "https://cb/x", cb)
            return "turn-1", nil
        }}
        require.True(t, a.reprompt("decline_implementation", "400: blank reason", "https://cb/x"))
        require.True(t, a.reprompt("decline_implementation", "400", "https://cb/x"))
        require.False(t, a.reprompt("decline_implementation", "400", "https://cb/x"),
            "third re-prompt must be refused once the budget is exhausted")
        require.Equal(t, maxOutcomeReprompts, calls)
    })

    t.Run("submit failure rolls back the budget", func(t *testing.T) {
        fail := true
        var calls int
        a := &app{log: testLogger(), submitFn: func(text, cb string) (string, error) {
            calls++
            if fail {
                return "", errors.New("session busy")
            }
            return "turn-2", nil
        }}
        require.False(t, a.reprompt("already_done", "400", ""), "a failed submit must not count against the budget")
        fail = false
        require.True(t, a.reprompt("already_done", "400", ""), "budget must be intact after a failed submit")
        require.Equal(t, 2, calls)
    })

    t.Run("concurrent re-prompts never exceed the cap", func(t *testing.T) {
        var mu sync.Mutex
        var calls int
        a := &app{log: testLogger(), submitFn: func(text, cb string) (string, error) {
            mu.Lock()
            calls++
            mu.Unlock()
            return "t", nil
        }}
        var wg sync.WaitGroup
        for i := 0; i < 10; i++ {
            wg.Add(1)
            go func() { defer wg.Done(); a.reprompt("decline_implementation", "e", "") }()
        }
        wg.Wait()
        require.LessOrEqual(t, calls, maxOutcomeReprompts)
    })
}

func testLogger() *slog.Logger { return slog.New(slog.NewTextHandler(io.Discard, nil)) }