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
- func HookMain(args []string, stdin io.Reader, stderr io.Writer) int
- type Adapter
- func (a *Adapter) Capabilities() v1alpha1.AdapterCapabilities
- func (a *Adapter) Name() string
- func (a *Adapter) Prepare(_ context.Context, ws harness.Workspace, t v1alpha1.Task) error
- func (a *Adapter) Repair(ctx context.Context, ws harness.Workspace, problems []string, ...) (harness.Raw, error)
- func (a *Adapter) Run(ctx context.Context, ws harness.Workspace, t v1alpha1.Task, prompt string, ...) (harness.Raw, error)
- type Options
Constants ¶
const ( AuthSubscription = "subscription" AuthAPIKey = "apiKey" )
Auth modes in a HarnessOffer.
const DefaultKillGrace = 5 * time.Second
DefaultKillGrace is how long claude gets to exit after SIGTERM before its process group is killed.
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).
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.
const Name = config.HarnessClaudeCode
Name is the harness's name.
Variables ¶
This section is empty.
Functions ¶
func HookMain ¶
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 (*Adapter) Capabilities ¶
func (a *Adapter) Capabilities() v1alpha1.AdapterCapabilities
Capabilities implements harness.Adapter: the effort mapping and claude's features.
func (*Adapter) Prepare ¶
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 ¶
func (a *Adapter) Run(ctx context.Context, ws harness.Workspace, t v1alpha1.Task, prompt string, sink harness.EventSink) (harness.Raw, error)
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.