fix(smithy): strip CLAUDECODE from spawned-claude env (closes #103)

[komoreka]

Summary

Closes #103.

packages/smithy/src/providers/claude/headless.ts and interactive.ts set CLAUDECODE: '1' in the env passed to the spawned claude subprocess. Modern claude versions read CLAUDECODE and refuse to start with Claude Code cannot be launched inside another Claude Code session. The Anthropic SDK surfaces this as Claude Code process exited with code 1, which the spawner swallows as the cryptic Session exited before init.

This blocks every spawn for users running stoneforge from inside a Claude Code session: anyone invoking sf from Claude Code's bash tool, or directors orchestrating workers from a Claude Code session.

The fix strips CLAUDECODE from the inherited env in both providers. Stoneforge IS the parent process; the spawned claude is a fresh top-level session, not nested. Issue #103 has the full diagnosis with a reproducer that captures the underlying SDK error.

Implementation

• New shared helper packages/smithy/src/providers/claude/env.ts: buildClaudeSpawnEnv(processEnv, options) performs the merge, strips CLAUDECODE regardless of source (inherited or caller-supplied via options.environmentVariables), and sets STONEFORGE_ROOT when provided.
• Both headless.ts and interactive.ts now call the helper instead of duplicating the env-build logic.
• Tests:
  • env.bun.test.ts: 7 unit tests for the helper (CLAUDECODE strip from inherited, strip from overrides, override precedence, STONEFORGE_ROOT injection, input non-mutation).
  • headless.bun.test.ts: 2 integration tests that verify the headless provider's SDK call actually receives an env without CLAUDECODE.

Why CLAUDECODE was set in the first place

Issue #32 (closed) added CLAUDECODE: '1' to fix Windows session permission/spawn issues. The intent was "signal to claude that this is a managed session". The current claude binary's check is the opposite: "if CLAUDECODE is set, refuse to nest." Since stoneforge IS the parent (the spawned claude is fresh top-level), CLAUDECODE should not be in the child env.

Windows verification welcome but not blocking. I have not retested #32's Windows scenario. If a Windows contributor can confirm whether the unconditional strip is sufficient or whether the env needs to be platform-gated, that would be valuable. The Linux/macOS bug is reproducible 100% of the time and blocks Claude-Code-resident workflows entirely, so I'd rather ship and let any Windows regression re-file than block on verification.

Test plan

• bun test packages/smithy/src/providers/claude — 37 pass, 0 fail (was 28 before, +9 new tests)
• NODE_ENV=development npx turbo run typecheck --filter=@stoneforge/smithy — clean
• NODE_ENV=development pnpm build — clean
• Manual: with daemon running on this branch in a project, ran sf agent start <worker-id> --prompt \"...\" from inside a Claude Code session. Pre-fix: Failed to start agent: Session exited before init. Post-fix: Spawned agent <id>, Status: running.
• Changeset added (@stoneforge/smithy: patch).

Related

• enhancement: surface underlying cause when "Session exited before init" fires (exit code, signal, last claude output) #102: spawner exit diagnostic enrichment. Had Session exited before init surfaced the underlying claude stderr (Claude Code cannot be launched inside another Claude Code session), this would have been a 5-minute fix instead of a multi-hour debugging session.
• bug: sf serve smithy silently allows multiple daemon instances on the same project (causes spawn race-kills) #101: singleton-daemon enforcement. Independent issue, originally suspected as the cause here but disproved.
• Windows: CLAUDECODE env var missing from interactive/headless session spawn #32: original Windows fix that introduced CLAUDECODE='1' (closed).

🤖 Generated with Claude Code