← Back to AI Insights
Gemini Executive Synthesis

shepherd-ai's integration with the Claude CLI agent lane, specifically its authentication and execution within a jailed environment on macOS.

Technical Positioning
Ensuring reliable, secure, and platform-consistent execution of AI agents (like Claude) within shepherd-ai's reversible, Git-like trace runtime, particularly concerning native-jail and claude-auth mechanisms. The goal is seamless agent supervision, optimization, and training.
SaaS Insight & Market Implications
This issue highlights critical platform-specific authentication and execution failures within shepherd-ai's Claude CLI integration on macOS, despite passing `doctor` checks. The `ProviderInvocationError: confined body refused (rc=1)` indicates a security confinement or permission issue preventing the Claude model invocation. The empty result envelope further complicates debugging by truncating critical error messages. While a temporary OAuth token workaround exists, the core problem points to an underlying divergence in macOS/auth path handling compared to Linux. This directly impacts shepherd-ai's promise of reliable, reversible agent execution across environments, particularly for meta-agents supervising and training others. Unreliable agent execution due to environmental discrepancies undermines developer trust and adoption, necessitating robust cross-platform consistency in security and authentication mechanisms.
Proprietary Technical Taxonomy
ProviderInvocationError confined body refused (rc=1) empty result envelope modelUsage shepherd doctor claude native-jail claude-auth OAuth token

Raw Developer Origin & Technical Request

Source Icon GitHub Issue Jul 5, 2026
Repo: shepherd-agents/shepherd
claude CLI agent lane fails: ProviderInvocationError "confined body refused (rc=1)" with empty envelope (claude CLI 2.1.201)

## Summary

The `claude` agent lane from the quickstart (`shepherd demo write claude-readme`) fails immediately with `ProviderInvocationError: confined body refused (rc=1)` and an **empty result envelope** (no model iterations, empty `modelUsage`), even though `shepherd doctor claude` reports every check green. The model is never actually called. The offline/deterministic lane works perfectly on the same host.

## Environment

- macOS (Darwin 27.0.0, Apple Silicon)
- Python 3.13.13
- `shepherd-ai` 0.2.0 (pip, fresh venv)
- `claude` CLI **2.1.201** (Claude Code), signed-in via OAuth (Claude subscription), on `PATH` as an alias `claude=claude-oauth`
- `shepherd doctor claude` → all green, incl. `native-jail: available` and `claude-auth: signed-in 'claude' CLI (login is seeded into jailed runs)`

## Repro

```bash
python -m venv .venv && . .venv/bin/activate
pip install shepherd-ai
mkdir ws && cd ws
shepherd init
shepherd doctor claude # all green
# seed a small README.md and commit it, then:
shepherd demo write claude-readme > agent_task.py
python agent_task.py # fails
```

## Observed

```
RunStartError: run run-XXXX failed: ProviderInvocationError: confined body refused (rc=1):
..."service_tier":"standard","cache_creation":{...},"inference_geo":"",
"iterations":[],..."modelUsage":{},"permission_denials":[],
"terminal_reason":"completed","fast_mode_state":"off","uuid":"..."}
```

- `shepherd run show ` → `status: failed`, `enforcement: jail (laun...

Developer Debate & Comments

dcx • Jul 5, 2026
Thanks for the detailed writeup! That is odd – this should work, I've been using the CLI lane internally. Investigating now.
dcx • Jul 5, 2026
Update: Your repro does work fine on my machine (*as in, it's not failing)! I'm continuing to investigate, but have run into an unrelated logging issue. I think this workaround may get you up and running in the meantime: 1. Run `claude setup-token` to get an OAuth token. 2. Make this available via `export CLAUDE_CODE_OAUTH_TOKEN=…` 3. Proceed with `python agent_task.py`, etc. I hope that works! I'll be back to get to the bottom of this in a couple of hours either way – have an IRL commitment.
giorgosn • Jul 6, 2026
**Datapoint: the CLI lane works on Linux at 0.2.0 with `claude` 2.1.201.** Just ran the exact repro on WSL2 Ubuntu 24.04 (Landlock jail), Python 3.12, `shepherd-ai` 0.2.0 (fresh venv), `claude` CLI 2.1.201 signed in via OAuth (subscription, no env keys): ``` shepherd demo write claude-readme > agent_task.py python agent_task.py # → run retained, README.md edited ``` `run show --json` → `status: retained`, `enforcement: syscall_jail / confined_process`, changeset holds the README edit. So this doesn't look like global CLI-contract drift at 2.1.201 — the divergence is somewhere in the macOS/auth path. **Why the envelope looks empty (and where the real error is).** The refusal message is built as `(stderr+stdout)[-300:]` (`shepherd_dialect/providers.py`, `ClaudeHeadlessProvider`). When the headless CLI fails, it emits a JSON *result envelope* with the human-readable error in the `result` field — which sits near the **front** of the JSON. The last 300 chars are just the `usage…termin...

Adjacent Repository Pain Points

Other highly discussed features and pain points extracted from shepherd-agents/shepherd.

Extracted Positioning
Integration of Mitos' full-VM snapshot-forking capabilities into shepherd-agents/shepherd as a device backend, extending shepherd's current filesystem-scoped fork semantics to full-state (memory, processes, open sockets) for enhanced agent environment management.
Elevating shepherd's core reversibility and agent supervision capabilities beyond filesystem-only state to encompass full-VM state. This aims to improve the fidelity and utility of shepherd for complex agent scenarios (e.g., running servers, warm interpreters) and to establish a more comprehensive "fork contract" and reversibility tiers, aligning with advanced sandbox runtime standards.
Top Replies
dcx • Jul 5, 2026
Hello, thanks for writing! These are all very interesting questions: 1. We have some solutions cooking for full-VM – we'd like to support Firecracker, Modal, etc. Would love to bounce this around w...
stubbi • Jul 5, 2026
Amazing! Thanks for coming back so quickly and happy to discuss anytime really (based in CEST)!
Extracted Positioning
VcsCore's binding contract caching mechanism, specifically a performance regression where describe() calls are redundantly executed on subsequent exec calls under the "always-on carrier."
Maintaining shepherd's performance and efficiency guarantees, particularly for its core VcsCore component which manages agent execution environments. The goal is to ensure that driver binding contract resolution, schema validation, and compilation occur only once per VcsCore lifetime, minimizing overhead for exec operations and upholding the intended caching invariant.
Extracted Positioning
Integration of Hermes Agent support into shepherd-agents/shepherd.
Expanding shepherd's compatibility and utility as a universal runtime substrate for various AI agents. By supporting Hermes Agent, shepherd aims to broaden its appeal to developers using different agent frameworks, reinforcing its role in supervising, optimizing, and training a wider ecosystem of agents.

Frequently Asked Questions

Market intelligence mapped to shepherd-ai's integration with the Claude CLI agent lane, specifically its authentication and execution within a jailed environment on macOS..

How is shepherd-ai's integration with the Claude CLI agent lane, specifically its authentication and execution within a jailed environment on macOS. positioned in the market?
Based on our AI analysis of the original developer request, its primary technical positioning is: Ensuring reliable, secure, and platform-consistent execution of AI agents (like Claude) within shepherd-ai's reversible, Git-like trace runtime, particularly concerning native-jail and claude-auth mechanisms. The goal is seamless agent supervision, optimization, and training.
How is the developer community reacting to shepherd-ai's integration with the Claude CLI agent lane, specifically its authentication and execution within a jailed environment on macOS.?
Yes, we have tracked 3 direct responses and active debates regarding this specific topic originating from GitHub Issue.
Which technical concepts are associated with shepherd-ai's integration with the Claude CLI agent lane, specifically its authentication and execution within a jailed environment on macOS.?
Our proprietary extraction maps shepherd-ai's integration with the Claude CLI agent lane, specifically its authentication and execution within a jailed environment on macOS. to adjacent architectural concepts including ProviderInvocationError, confined body refused (rc=1), empty result envelope, modelUsage.
How does the GitHub community build with shepherd-ai's integration with the Claude CLI agent lane, specifically its authentication and execution within a jailed environment on macOS.?
Yes, open-source adoption is correlated. An active project titled 'RunanywhereAI/RCLI' explores similar frameworks: Talk to your Mac, query your docs, no cloud required. On-device voice AI + RAG

Engagement Signals

3
Replies
open
Issue Status

Cross-Market Term Frequency

Quantifies the cross-market adoption of foundational terms like copy-on-write fork and OAuth token by tracking occurrence frequency across active SaaS architectures and enterprise developer debates.