Build scoped matter tools with the Agent SDK (stretch)

list_documents, grep, search and read as in-process Claude Agent SDK tools, built per request with the tenant and matter fixed in a closure, document IDs checked against an allow-list, regexes run with a timeout, and every call logged; seven hostile document IDs and a backtracking regex try to escape the scope, and the 30-question set runs through the SDK on OpenRouter or Ollama for comparison with the headless results.

Back to the exercise

Before you start

Before you start:Install Claude Code Python with uv Get an OpenRouter key Local models with Ollama

This exercise calls a model. Run it either way

Any model through OpenRouterOne key for Claude, GPT, Gemini, Llama and more. Pay per token, with a credit limit.A local open-source modelFree and private with Ollama. Weaker on hard tasks.

Which should I pick? →

The tool layer is one function, build_tools(store, tenant_id, matter_id), called once per request with values from the session. Everything the model can reach is decided inside it, before the model sees a single tool: the matter's documents, the current-versus-superseded split and the search index. The decision that matters most is that document_id is never turned into a path. It is looked up in this matter's own dictionary of documents, so a traversal string or another matter's ID fails the lookup and comes back as an error that lists the valid IDs. The agent runs through query() from the Claude Agent SDK, so it needs an API endpoint: your own OpenRouter key or a local model through Ollama, set in .env.

Answers Lesson 6: Agentic retrieval

Step-by-step answer

Stretch 90 min6 steps