All Articles
Let Claude Actually See the Images Your Tools Return — Use Image Blocks in tool_result and Cut Tokens by Roughly 10x
Stuffing a base64 string into a tool_result makes the same image cost roughly 10–20x more tokens. Here is how to return it as an image content block instead, with SDK code, a token-cost estimate, and the gotchas I hit in production.
When Context Editing Made My Agent Re-run the Same Search — Field Notes on Clear Boundaries and Cache Invalidation
After turning on Context Editing to auto-clear tool results, the agent forgot what it had just read, re-ran the same tool, and the cache rebuilt every turn so costs went up. Field notes on instrumenting the silent regression and setting trigger, keep, and clear_at_least from measured data.
Did That Post Actually Go Through? Safely Retrying an Interrupted MCP Write Without Double-Executing
When an MCP write tool call is interrupted by a dropped connection, you can't tell whether the server ran it. Here's why naive retries cause double-execution, and a working wrapper that uses idempotency keys and a reconcile read to retry safely — with examples from an unattended pipeline.
Measure Streaming CPU and Dropped Chunks to Stabilize Long Batch Jobs
You start an overnight batch, and by morning only half of it finished. The culprits were CPU pinned during streaming and a quiet connection drop. Here is a monitor wrapper that measures stream CPU and throughput, and resumes from interruptions.
Every Tool Call Succeeds, Yet Nothing Moves Forward: Detecting Stagnation in Unattended Agents
No errors, yet the agent keeps replaying the same move while your budget quietly drains. Here is how to detect a success-but-no-progress loop using a progress oracle and action fingerprints, with a working Python implementation that halts safely.
A Silent Drop to a Weaker Model Is Scarier Than an Error: Designing a Capability Floor for Claude API Fallback
When a model becomes unavailable in an unattended pipeline, automatically dropping to a weaker model is dangerous. Drawing on years of running automated indie pipelines, this is how to use per-task capability contracts and a degradation budget to decide where to stop.
Designing the Give-Up Condition in Self-Repair Loops: Four Error Classes, Four Retry Budgets
LLM self-repair loops break on the fantasy that 'if you keep fixing, it eventually passes.' Classify errors into four classes, give each its own retry budget. Working TypeScript and real cost numbers included.
When Claude API Streaming Stops Without an Error: Detecting Silent Stalls and Resuming Mid-Stream
How to catch the 'silent stall' where Claude API streaming stops with no exception at all, using a content-level watchdog that times the gap between tokens, plus a resume path that carries received text forward as an assistant prefill, and a four-layer timeout budget for long-running automation.
Stop the Bill Before It Balloons: Designing API Key Blast Radius for Unattended Pipelines
Designing for leaks instead of pretending they won't happen: workspace-scoped keys, zero-downtime rotation, and a usage watchdog that flags spikes with a rolling baseline and median absolute deviation — wired into a scheduled run.
When the Same Model Name Starts Behaving Differently: A Startup Canary for Unattended Pipelines
An in-place Opus upgrade can change your output, and an unattended publishing pipeline will never notice. Here is a lightweight startup canary that fingerprints behavior, catches drift, and halts the batch — with measured cost and latency.
Generating localized App Store listing metadata within character limits using the Claude API
Raw translations overflow App Store Connect's character limits. Generate per-locale listing metadata within them using Claude API structured output and a repair loop.
Reach a Remote MCP Server in a Single API Request: Implementing the Messages API MCP Connector
How to call a remote MCP server's tools using only the Messages API's mcp_servers and mcp_toolset—no local MCP client. Covers allowlist/denylist design, response handling, and the pitfalls to avoid before unattended production use.