Engineering reference
Building a Prompt Hook for Claude Workflows
A first-person account of a prompt interceptor's architecture, sinc format, integration, and an unexpected failure.
Methods, definitions, and examples for the topic discussed here. Check applicability against the task and operating conditions.
I built a Python server that receives Claude prompts, rewrites them into a structured format, and supplies that version before model execution. Compare its operating costs and outputs against the original workflow.
Here is how I built it.
The Architecture
The interceptor is a Python FastAPI server. It runs on your own machine. Claude Code uses a PreToolUse hook. That hook fires every time you send a message. The hook sends the raw prompt text to localhost:8461/scatter via HTTP POST. The server reads the prompt and returns structured sinc JSON. That JSON goes into the system message before Claude reads your prompt.
# Simplified core of scatter_server.py
from fastapi import FastAPI
import anthropic, json
app = FastAPI()
client = anthropic.Anthropic()
SCATTER_SYSTEM = """
Decompose the user's prompt into sinc JSON with 6 fragments:
n=0 PERSONA, n=1 CONTEXT, n=2 DATA, n=3 CONSTRAINTS (longest),
n=4 FORMAT, n=5 TASK. Return ONLY valid JSON.
"""
@app.post("/scatter")
async def scatter(payload: dict):
prompt = payload.get("prompt", "")
# Pass-through if already sinc JSON
if is_sinc_json(prompt):
return {"scattered": prompt, "passthrough": True}
response = client.messages.create(
model="claude-haiku-4-5",
max_tokens=1024,
system=SCATTER_SYSTEM,
messages=[{"role": "user", "content": prompt}]
)
sinc_json = json.loads(response.content[0].text)
return {"scattered": json.dumps(sinc_json), "passthrough": False}
The Sinc Format
The structured output follows the sinc-LLM format. There are six fragments. Each fragment has an index (n), a type (t), and the content (x). The formula is stored as a header field. It is the math foundation of the whole system.
Review the task-specific CONSTRAINTS field before using the structured prompt. Check the response afterward for compliance and factual correctness.
The Failure I Didn't Anticipate
My first version blocked every prompt while it waited for the Haiku API to reply. If the API was slow or down, everything stopped. I watched Claude Code freeze while the scatter call timed out.
The described implementation adds a 25-second timeout and a template-based fallback for API failure. Check fallback behavior and workflow interruption in your environment.
I also added pass-through rules. If the prompt starts with @agent (going to a sub-agent), or /slash (a slash command), or it is already valid sinc JSON, the server skips scatter. There is no point rewriting something that is already structured or already routed.
The Claude Code Hook Integration
In Claude Code, hooks are set up in settings.json. Here is the hook entry that connects the scatter server to every user message:
{
"hooks": {
"PreToolUse": [
{
"matcher": ".*",
"hooks": [{
"type": "command",
"command": "py -X utf8 C:/Users/Mario/scatter_hook.py"
}]
}
]
}
}
The scatter_hook.py script reads the prompt from stdin, POSTs it to localhost:8461/scatter, and writes sinc JSON to the system-message injection point. Measure the complete round-trip latency for your setup.
Operating Measurements to Record
Record prompts processed, responses per prompt, token usage, scatter overhead, and output checks. A dashboard record needs its workload and measurement window for a cost comparison.
The code is open source on GitHub. Leave a comment and I will drop the link. I want to make sure people find it useful before I share it widely.
// Production AI Engineering
Build AI systems that hold up in production.
sinc-LLM designs, audits, and stabilises production AI infrastructure: from vendor evaluation and cost accountability to incident controls and MCP architecture.
See what we do →Scope and context
sinc-LLM About Blog Services
DOI: 10.5281/zenodo.19152668 · © 2026 sinc-LLM · Mario Alexandre
sinc-LLM

