Skip to content

Docs: guard a Claude Agent SDK app with cloudpin (#142) - #144

Merged
paureis merged 8 commits into
mainfrom
docs/142-agent-sdk
Nov 4, 2026
Merged

paureis merged 8 commits into
mainfrom
docs/142-agent-sdk

Conversation

@paureis

@paureis paureis commented Oct 24, 2026 •

Copy link
Copy Markdown
Owner

Closes #142.

docs/agent-sdk.md covers guarding a Claude Agent SDK app with cloudpin:

  • No code needed when the app loads project settings: cloudpin install-hook claude already guards it.
  • A Python and a TypeScript PreToolUse callback for apps with setting_sources=[]. On Windows they start cloudpin through %SystemRoot%\System32\cmd.exe with NoDefaultCurrentDirectoryInExePath=1, the form install-hook writes for Codex and Copilot. A planted cloudpin.cmd in the app's folder never runs. shutil.which and a bare cross-spawn would search the current folder.
  • Fail closed. In a real session, a callback that raises lets the command run, so each snippet turns every error into a deny.
  • Timeouts, ask answers, and the MCP server as advice.

docs/mcp.md links the page.

Evidence (owner-approved real SDK sessions, read-only gh repo view, fake pin)

  • Python claude-agent-sdk 0.2.174 and TypeScript @anthropic-ai/claude-agent-sdk 0.3.310 (each bundles Claude Code 2.1.310), model haiku; 7 sessions, about $0.07.
  • Project hook, no code: a wrong pin was blocked with cloudpin's reason.
  • Python and TypeScript callbacks (setting_sources=[]): a wrong pin was denied, and the right pin ran ({"name":"cli"}).
  • Direct calls, deny every time:
    • cloudpin not found, exit 3, output not JSON, cmd.exe missing, deadline, abort;
    • invalid UTF-8 output (Python), a synchronous throw and an already-aborted signal (TypeScript), and a JSON answer that isn't an object.
  • tsc passes on the TypeScript snippet against the SDK's types.

Checks

  • test/agent-sdk.test.ts (new, 13 tests):
    • cloudpin hook claude answers the SDK's PreToolUse shape, and the pin comes from the input's cwd;
    • the snippets stay short, deny on any error and load no settings.
  • Mutation checks: three, all caught.
  • npm run typecheck: exit 0. npm test: 1280 passed, 8 skipped.
  • Not tested: the snippets on Linux/macOS, ask in an SDK app, the MCP option inside a session, and a --user hook.

🤖 Generated with Claude Code

paureis and others added 6 commits October 23, 2026 20:39
docs/agent-sdk.md: an SDK app loads the project's .claude/settings.json by
default, so `cloudpin install-hook claude` already guards it; with
setting_sources=[] a PreToolUse callback (Python and TypeScript) pipes the
hook input to `cloudpin hook claude` and fails closed. Covers Windows (cmd.exe
with NoDefaultCurrentDirectoryInExePath, why not shutil.which or the .cmd shim
directly), timeouts, "ask" answers and the MCP server as advice.

Both snippets were run in real SDK sessions (claude-agent-sdk 0.2.174,
@anthropic-ai/claude-agent-sdk 0.3.310, Claude Code 2.1.310) against a made-up
GitHub pin and the active one, read-only commands only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cloudpin hook claude, fed the SDK's PreToolUse input with its extra fields,
answers with exactly an SDK PreToolUse output or nothing, and takes the pin
from the input's cwd. The page's two callbacks stay under 40 lines, start
cloudpin through cmd.exe with a fixed line and no current-folder search,
never use a shell, shutil.which or "allow", and load no settings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The plugin line was not tested in an SDK session, so it goes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…#142)

A callback that raises lets the command run (measured with Claude Code
2.1.310). The Python callback caught only OSError and TimeoutError, so output
that isn't UTF-8 raised past it; a synchronous throw in the TypeScript
Promise executor became a rejection. Both now catch everything around the
whole body and deny, and deny an answer that isn't a JSON object. Called
directly, both deny for invalid UTF-8 (Python), a BigInt input and an
already-aborted signal (TypeScript), and JSON that isn't an object.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Checks both callbacks catch any error and an answer that isn't an object,
and counts snippet lines without the trailing newline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paureis paureis added this to the 1.3.0 milestone Oct 24, 2026
@paureis
paureis marked this pull request as ready for review November 4, 2026 22:44
@paureis
paureis merged commit eeaa7f3 into main Nov 4, 2026
6 checks passed
@paureis
paureis deleted the docs/142-agent-sdk branch November 4, 2026 22:45
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.

Docs: guard a Claude Agent SDK app with cloudpin

1 participant