Build within bounds

The Investigator found the bug and wrote a specification. The Builder receives only the approved scope, evidence, and tools required to implement it.

approved specification + candidate branch + scoped tools

One station may edit code. Its permission begins at the supported specification and ends at a pushed factory branch.

Give One Station the Write Tools

Create an isolated Builder that implements approved work without touching protected branches.

Hands-on Exercise 4.1

Create agent/subagents/builder/sandbox.ts with the same repository helpers as the Investigator. This produces a fresh checkout. Disposable reproduction work cannot leak into implementation.

Now create agent/subagents/builder/agent.ts:

agent/subagents/builder/agent.ts

import { defineAgent } from "eve";
import { MODELS } from "../../lib/models.js";
 
export default defineAgent({
  description:
    "Implement an approved work order in an isolated checkout. Create a factory branch, make only the specified change, run checks, commit, and push.",
  model: MODELS.builder,
  outputSchema: {
    additionalProperties: false,
    properties: {
      base: { type: "string" },
      branch: { type: "string" },
      changes: {
        items: {
          additionalProperties: false,
          properties: {
            path: { type: "string" },
            summary: { type: "string" },
          },
          required: ["path", "summary"],
          type: "object",
        },
        type: "array",
      },
      deviations: { items: { type: "string" }, type: "array" },
      pushed: { type: "boolean" },
    },
    required: ["branch", "base", "pushed", "changes", "deviations"],
    type: "object",
  },
});

Create agent/subagents/builder/tools/checkout_branch.ts and push_branch.ts. Both tools validate the branch before opening a sandbox or minting a GitHub installation token:

agent/subagents/builder/tools/push_branch.ts

import { defineTool } from "eve/tools";
import { z } from "zod";
import { githubCredentials } from "../../../lib/github/credentials.js";
import {
  brokerPolicy,
  mintInstallationToken,
  REMOTE_URL,
  REPO_DIR,
  validateBranch,
} from "../../../lib/github/git-remote.js";
 
export default defineTool({
  description: "Push a committed factory feature branch. Protected branches are rejected before Git runs.",
  async execute(input, ctx) {
    const refusal = validateBranch(input.branch);
    if (refusal) {
      return { error: refusal, success: false as const };
    }
 
    const sandbox = await ctx.getSandbox();
    const token = await mintInstallationToken(githubCredentials);
    await sandbox.setNetworkPolicy(brokerPolicy(token));
 
    try {
      const result = await sandbox.run({
        command: `git -C ${REPO_DIR} push ${REMOTE_URL} 'refs/heads/${input.branch}:refs/heads/${input.branch}'`,
      });
      return result.exitCode === 0
        ? { branch: input.branch, success: true as const }
        : { error: String(result.stderr || result.stdout).trim(), success: false as const };
    } finally {
      await sandbox.setNetworkPolicy("allow-all");
    }
  },
  inputSchema: z.object({ branch: z.string().min(1) }),
});

These helpers come from the starter rather than an unshown library:

validateBranch rejects malformed, ref-style, and protected branch names.
githubCredentials reads short-lived credentials from the GITHUB_CONNECTOR configured in Lesson 3.1.
mintInstallationToken resolves the connector's current installation token.
brokerPolicy injects that token only into requests to github.com.
REPO_DIR is /workspace/repo; REMOTE_URL is built from FACTORY_REPO.

Run one explicit Git ref while the broker policy is active, then restore allow-all in finally. Credentials never enter the prompt, repository files, or command arguments. Build checkout_branch.ts with the same validation and network-policy shape, using git fetch followed by git checkout -B instead of git push.

Add agent/subagents/builder/instructions.md:

agent/subagents/builder/instructions.md

# Builder
 
You implement one approved work order in `/workspace/repo`. The delegation contains the source issue, route, evidence, specification, acceptance criteria, and any revision findings.
 
For fresh work, create `factory/<lane>-<short-slug>`. Change only what the approved scope requires. Match existing conventions. Run relevant tests and type checks, commit the finished change, and call `push_branch`.
 
You cannot push to `main` or `master`, open a pull request, or merge. If the specification cannot be implemented safely, leave `pushed` false and record the reason in `deviations`.

Add the Builder handoff to the root instructions. Send the approved specification and evidence, not the Investigator's hidden reasoning.

Try It

Run the static checks:

pnpm typecheck
pnpm exec eve info

eve should report two subagents. Invoke the uppercase-channel issue:

pnpm exec eve invoke "$(cat fixtures/issues/bug-example.md)"

Inspect the Builder result. The branch must begin with factory/, changes should name only the relevant SDK files, and pushed should be true after the commit reaches GitHub.

Try main as a branch input. The tool should refuse it before requesting credentials or sandbox work.

Add tempting cleanup

Include an unrelated formatting change in the Builder prompt. A bounded Builder should omit it or record the conflict as a deviation.

The Builder reuses investigation state

Keep a separate sandbox.ts under builder/. Shared state makes reproduction artifacts part of the candidate by accident.

A protected branch reaches Git

Call validateBranch before ctx.getSandbox() and mintInstallationToken().

Commit

git add agent/subagents/builder agent/instructions.md
git commit -m "feat(factory): build within approved bounds"

Done-When

The Builder receives a supported specification
Implementation runs in a fresh sandbox
Factory branches use the required prefix
Protected branches fail before credential work
The Builder cannot open or merge a pull request

The candidate branch exists inside its boundary. Its commands and results still need to travel with it.

Solution

The complete protected execution shape appears in the exercise. Both branch tools validate first, apply the broker policy only around Git, and restore allow-all in finally; compare their files with the solution branch if either invariant fails.