claudecode

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Overview

Package claudecode is the Claude Code CLI harness adapter (design/workstreams/agent/LLD/ harness-adapters.md §Claude Code). It runs only in a VM workspace (`factory-agent run`, workspace-run.md §Harnesses in the VM), where the VM is the boundary.

Prepare writes a settings file (no marketplace plugins, the reasoning effort, and a PreToolUse hook that refuses `git push` and gh writes and keeps the file tools' writes in the run's writable directories) and an MCP config with the Effector, both in a scratch directory of the workspace's HOME, and makes the scratch CLAUDE_CONFIG_DIR; the skills are the pipeline's plugin directories, passed as they are. Run starts `claude -p --output-format stream-json` with the resolved model, the headless preamble appended to the system prompt and the Result schema, with harness.Placeholder as the credential (the gateway outside the VM replaces it with the real one), streams its events into the EventSink, stops on a rate or plan limit, and kills the whole process group when its context ends. Repair resumes the same session with the validation problems.

Every claude flag, file, settings key and event name the adapter relies on is in flags.go, the unchecked ones marked UNVERIFIED until a VM workspace run exercises them.

Index

Constants

View Source
const (
	AuthSubscription = "subscription"
	AuthAPIKey       = "apiKey"
)

Auth modes in a HarnessOffer.

View Source
const DefaultKillGrace = 5 * time.Second

DefaultKillGrace is how long claude gets to exit after SIGTERM before its process group is killed.

View Source
const DefaultThrottle = clirun.DefaultThrottle

DefaultThrottle is how long a rate-limited agent waits when the error gives no reset (harness-adapters.md: else +15 min).

View Source
const (
	HookOp = "claude-hook"
)

HookOp is the `factory` CLI op (`factory-agent fx claude-hook pre-tool-use --write <dir>…`) that claude runs as its PreToolUse hook; hookEventArg its one event.

Name is the harness's name.

Variables

This section is empty.

Functions

func HookMain

func HookMain(args []string, stdin io.Reader, stderr io.Writer) int

HookMain is the PreToolUse hook. It reads claude's call from stdin and exits 0 to allow it, or hookExitBlock with the reason on stderr (claude gives it to the model) to block it:

  • the file tools (Write, Edit, MultiEdit, NotebookEdit) may write only under a --write directory (the run's out/ and tmp/, and the checkouts it may write), symlinks resolved;
  • Bash may not `git push` or write to GitHub with gh (`gh pr|issue <write>`, `gh api` with a write method or fields, a GraphQL mutation): writes go through the factory CLI.

It fails closed: unreadable input or arguments block the call. It is a second layer that guards against mistakes and injected instructions: what a Bash command writes or reads is bounded by the VM and its gateway, and the token scopes stay the boundary.

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter is the claude-code harness adapter. It keeps no per-run state in memory (the session to resume is in the workspace), so one Adapter serves concurrent runs.

func New

func New(o Options) *Adapter

New returns the adapter.

func (*Adapter) Capabilities

func (a *Adapter) Capabilities() v1alpha1.AdapterCapabilities

Capabilities implements harness.Adapter: the effort mapping and claude's features.

func (*Adapter) Name

func (a *Adapter) Name() string

Name implements harness.Adapter.

func (*Adapter) Prepare

func (a *Adapter) Prepare(_ context.Context, ws harness.Workspace, t v1alpha1.Task) error

Prepare implements harness.Adapter: every plugin directory must have its manifest, the scratch CLAUDE_CONFIG_DIR is made, and the scratch directory gets the settings file (no marketplace plugin, t's reasoning effort, the PreToolUse hook; no sandbox block and no permission rules: the VM is the boundary) and the MCP config (the Effector, with the run's variables passed by name).

func (*Adapter) Repair

func (a *Adapter) Repair(ctx context.Context, ws harness.Workspace, problems []string, sink harness.EventSink) (harness.Raw, error)

Repair implements harness.Adapter: the same session resumed (`claude -p --resume <id>`) with the problems, asking for a valid Result only, in at most repairMaxTurns turns. Without a session to resume, a new run gets the original prompt followed by the problems.

func (*Adapter) Run

Run implements harness.Adapter: `claude -p` on the prompt (stdin) with the task's resolved model and auth, in the workspace's working directory, the write tools disallowed unless the primary checkout is writable.

type Options

type Options struct {
	// Config is the claude-code harness's config: vmrun makes it from the task's resolved
	// harness (Default is the model when the task names none).
	Config config.Harness
	// Binary is the claude executable. Default: "claude" on PATH.
	Binary string
	// Clock stamps events and rate-limit resets. Default: clock.Real.
	Clock clock.Clock
	// KillGrace is the SIGTERM-to-SIGKILL delay on cancel. Default: DefaultKillGrace.
	KillGrace time.Duration
	// Throttle is the wait on a rate limit without a reset. Default: DefaultThrottle.
	Throttle time.Duration
	// Getuid is the run's user id: a root run sets IS_SANDBOX. Default: os.Getuid.
	Getuid func() int
}

Options configure an Adapter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL