Skip to content

feat: Claude Code runner, Windows fixes, and workflow examples - #25

Merged
SammyBytes merged 7 commits into
mainfrom
feat/claude-code-runner
Nov 17, 2026
Merged

SammyBytes merged 7 commits into
mainfrom
feat/claude-code-runner

Conversation

@SammyBytes

Copy link
Copy Markdown
Owner

Summary

Adds a claude runner so Sam agents can run through the Claude Code CLI (claude -p), with structured output from a JSON schema or raw text through use unsafe.

What changed

  • Runner: ClaudeStrategy builds claude -p commands with model, system prompt, effort, permission mode, turn and budget limits, tool allow and deny lists, and --bare. It always requests the JSON envelope and only unwraps real envelopes (type: "result").
  • Windows: when claude resolves to an npm .cmd shim, the native claude.exe behind it is used. Bun refuses to pass JSON schema arguments to .cmd files.
  • Parser: temperature, max_tokens and retries are rejected for runner: claude, because the process executor ignores them. timeout still applies to every runner.
  • Examples: examples/workflows/ has three single-purpose flows (ticket readiness, PR review gate, iteration digest) and run_parallel.sh for fan-out over many inputs. Inputs are synthetic or come from this repository.
  • Skill: .claude/skills/sam-automation/SKILL.md teaches Claude to write, compile, dry-run and cost small .sb automations.
  • Roadmap: README entry for the follow-ups below.

Verification

  • bun test: 156 pass, 1 skip (platform-specific), 0 fail. Typecheck and the coverage gate pass on Windows. The same tests and typecheck pass in a Linux container.
  • Real runs on Windows with the claude.ai session: structured call through sam run, a schema-less use unsafe call, two concurrent flows with different models, sonnet-to-haiku delegation, a timeout (TIMEOUT_ERROR at 2 s, no leftover processes), and an unknown model (EXECUTION_ERROR).
  • Example flows: each compiles, passes a mock dry run, and runs for real on synthetic input.

Measured

Small benchmark on six code reviews, not a general claim:

  • Each separate claude -p call carries about $0.08 of fixed overhead.
  • One batched sonnet call covering six reviews cost about one fifth of six separate calls.
  • haiku was not cheaper per call than sonnet on this runner, because each model builds its own cache.

Known limits

  • Linux was verified with tests and typecheck only, not with a real Claude smoke run.
  • No parallel(...) in the DSL; fan-out is done with separate sam run processes.
  • Schemas cannot type lists (array is untyped), so batched results cannot be validated per item.
  • .sb has no comment syntax.
  • Timeouts in .sb are in seconds, while the runtime uses milliseconds.
  • Workspace writes and model permissions are not configurable yet.

Follow-up issues

#18 RunnerPool · #19 timeout units · #20 claude permissions · #21 typed lists · #22 parallel token · #23 missing workspace error · #24 comment syntax

🤖 Generated with Claude Code

SammyBytes and others added 7 commits November 17, 2026 07:43
Always request --output-format json so the response shape is known, and
only unwrap stdout when it is an envelope (type: "result"). Plain model
replies that happen to look like JSON, such as {"result": "hola"}, are
returned unchanged instead of being rewritten or treated as errors.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
temperature, max_tokens and retries only take effect for HTTP providers.
Process runners ignore them silently, so the parser now rejects them when
runner is claude. timeout is kept: the process executor enforces it for
every runner. Field docs in LocalAgentConfig describe where each applies.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
The npm install puts claude.cmd first on PATH. Bun refuses to pass
arguments with cmd special characters to .cmd files, and every structured
call carries a JSON schema with those characters, so the run failed before
Claude Code started. Resolve the claude.exe that the shim wraps when the
PATH entry is a .cmd or .bat file. Other platforms and installs are
unchanged.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Link the RunnerPool, DSL timeout unit, and permissions issues, and record
the measured per-call overhead of the claude runner.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Project skill that teaches Claude to write, compile, dry-run and cost
small Sam automations. Covers the verified syntax, timeout units, claude
runner rules, measured per-call cost, parallelism via separate sam run
processes, and known pitfalls.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Three single-purpose flows: ticket readiness check, PR review gate, and
iteration digest (use unsafe). Adds a parallel fan-out script that runs
one flow over a folder of inputs as separate sam run processes. Inputs
are synthetic or come from this public repository.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Sam PR Review

Verdict: request_changes · Risk: medium

The PR introduces new variables in generateAgent that are never used, which will trigger linting failures and may indicate incomplete implementation of the new Claude runner options. Additionally, the claudeStrategy does not handle the bare flag, which is required for API‑key based billing. These issues need to be addressed before the PR can be merged.

Findings

  • packages/compiler/src/codegen/generators/generateAgent.ts: unused variables permissionMode, maxTurns, fallbackModelProp, allowedToolsProp, disallowedToolsProp, maxBudgetUsd, bare
  • packages/runtime/src/strategies/agent/claudeStrategy.ts: missing handling of bare flag for API key usage

Suggested tests

  • Test that generateAgent emits correct config when permission_mode, max_turns, fallback_model, allowed_tools, disallowed_tools, max_budget_usd, and bare are set; test that claudeStrategy includes --bare when bare is true

Advisory review generated by Sam with Groq. It does not approve or block the pull request; ci.yml remains the required check.

@github-actions

Copy link
Copy Markdown

Sam Edition Guard

Risk: low · Affects edition 2026: false

The update adds optional properties and validation for Claude Code runner agents but does not alter existing 2026 syntax or defaults.

Recommendation: No action required for 2026 programs; new properties are optional and backward compatible.

Generated by Sam with Groq from the compiler diff. Deterministic fixture compilation always runs; this audit is advisory unless it reports an edition 2026 impact.

@SammyBytes
SammyBytes merged commit dcda76b into main Nov 17, 2026
9 checks passed
@SammyBytes
SammyBytes deleted the feat/claude-code-runner branch November 17, 2026 14:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant