---
title: "Exploring Claude Code Hooks with the Coding Agent Explorer (.NET)"
description: "Claude Code hooks: PreToolUse, PostToolUse and Stop, how a hook blocks a tool call with an exit code, and how to watch them fire in the Coding Agent Explorer."
url: https://nestenius.se/ai/exploring-claude-code-hooks-with-the-coding-agent-explorer-net/
date: 2026-03-20
updated: 2026-11-09
author: "Tore Nestenius"
category: "AI"
tags: ["coding-agents", "developer-tools"]
site: https://nestenius.se/
---

# Exploring Claude Code Hooks with the Coding Agent Explorer (.NET)

Ever wondered what [Claude Code](https://claude.com/product/claude-code) is actually doing while it works? Every file it reads, every command it runs, every permission it requests. Claude Code exposes all of this through a hook system that lets you intercept and observe each step.

In this post, you’ll learn what hooks are, how to set them up, and how to use the [Coding Agent Explorer](https://github.com/tndata/CodingAgentExplorer) to visualize hook events in real time.

The post is part of a multi-part series on the [Coding Agent Explorer](https://github.com/tndata/CodingAgentExplorer), an open-source .NET tool for inspecting what AI coding agents do under the hood. You can jump to the section you need, but for background and context, it’s best to start here:

- [Part 1 - Introducing the Coding Agent Explorer (.NET)](https://nestenius.se/ai/introducing-the-coding-agent-explorer-net/)
- **Part 2 - Exploring Claude Code Hooks with the Coding Agent Explorer**
- [Part 3 - Visualizing Claude Code MCP Requests with Coding Agent Explorer](https://nestenius.se/ai/visualizing-claude-code-mcp-requests-with-coding-agent-explorer/)

To make this more concrete, the diagram below shows how Claude Code emits hook events, how each event triggers a call to HookAgent, and how those events are then forwarded to the Coding Agent Explorer for visualization.

![Claude Code Hooks Flow with HookAgent and Coding Agent Explorer](https://nestenius.se/_astro/claude-code-hooks-hookagent-coding-agent-explorer-diagram-1024x511.C9ESRDCd_Z1awJS8.webp)

Each time a hook event occurs, Claude Code invokes HookAgent, which receives the event data and forwards it to the Coding Agent Explorer, where it appears in the dashboard in real time.

## What Are Claude Code Hooks?

When things happen inside Claude Code, it can execute a hook. For example, when Claude Code is:

- Reading or writing a file
- Running a shell command
- Requesting a permission
- Starting or ending a session
- Submitting a user prompt

The diagram below highlights several of the hook events that Claude Code generates during execution.

![Claude Code hook events diagram showing SessionStart, PreToolUse, Notification, and SubagentStart events](https://nestenius.se/_astro/Claude_code_exposing_hooks.Fv_NDHiF_QjKSf.webp)

A hook is, in its most common form, a shell command that Claude Code runs at that point, passing a JSON payload describing the event via **standard input (stdin)**. This gives you a way to extend, observe, and control Claude Code’s behavior from the outside.

There are five handler types in total. Besides `command`, you can use `http` (Claude Code POSTs the event JSON to a URL), `mcp_tool` (calls a tool on an MCP server), `prompt` (a single-turn evaluation by a Claude model) and `agent` (a subagent that can use tools to check a condition, still experimental). All examples in this post use command hooks.

## What can hooks be used for?

Hooks turn Claude Code from a black box into something you can observe, control, and extend. In practice, they let you:

- Enforce security policies before tools run
- Log and audit tool usage
- Trigger external automation
- Notify external systems (Slack, CI, etc.)

In short, hooks let you move from observing the agent to controlling how it behaves.

## Example: Block access to secret files

A classic use case is intercepting **PreToolUse** **events** to block the agent from accessing files it should not touch.

Let’s say we have a file named **Secret.key** that we never want Claude Code to read. When the agent attempts to access it, your PreToolUse hook intercepts the request, inspects the file path, and blocks the operation by returning exit code **2** with an error message on stderr. Claude Code respects the response and continues without ever opening the file.

The diagram below illustrates how the **PreToolUse** hook intercepts and blocks the request.

![Diagram illustrating how a PreToolUse hook prevents Claude Code from accessing a sensitive file like secret.key](https://nestenius.se/_astro/claude-code-hooks-block-file-access-secret-key-1024x258.D2925JxK_ZSG1km.webp)

Here’s what Claude Code sends to the hook via **stdin** when it tries to read **secret.key**:

```json
{
  "session_id": "9ec4714b-3475-4773-b4af-3f70d7fe68f7",
  "transcript_path": "C:\\Users\\xxxxx\\.claude\\projects\\C--Conf\\9ec4714b-3475-4773-b4af-3f70d7fe68f7.jsonl",
  "cwd": "C:\\MyApp",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Read",
  "tool_input": {
    "file_path": "C:\\MyApp\\Secret.key"
  },
  "tool_use_id": "toolu_01BQ4EQBtbxbFRoTEc1CXRgf"
}
```

## How can a hook control Claude Code?

Hooks are not just for observing behavior; they can actively influence what Claude Code is allowed to do.

When a hook runs, it returns an exit code and an optional message. Claude Code uses this response to decide what happens next:

- **Exit code 0**  
    success: the action proceeds. The hook can also print a JSON decision on stdout to control Claude Code
- **Exit code 2**  
    a blocking error: the action is blocked, and the message on stderr is passed back to Claude
- **Any other non-zero exit code**  
    a non-blocking error: Claude Code shows a hook error notice, and the action still goes ahead

Be careful here: exit code 1, the usual "something failed" code, does **not** block anything. If your hook is meant to enforce a rule, use exit code 2. A hook can also block by exiting with 0 and printing a JSON decision on stdout, for example a PreToolUse `permissionDecision` of `"deny"`.

What exit code 2 actually does depends on the event. Here are a few common ones:

| Event | What happens on exit code 2 |
| :- | :- |
| `PreToolUse` | Blocks the tool call |
| `UserPromptSubmit` | Blocks the prompt, so it never reaches Claude |
| `Stop` | Prevents Claude from stopping, continues the conversation |
| `PostToolUse` | Shows stderr to Claude; the tool already ran |
| `SessionStart` | Shows stderr to the user only |
| `Notification` | Exit code and stderr are ignored |

Source: [Claude Code hooks reference: exit code 2 behavior per event](https://code.claude.com/docs/en/hooks#exit-code-2-behavior-per-event). The reference lists every event, and the same section explains the [exit codes](https://code.claude.com/docs/en/hooks#exit-code-output) in more detail.

The optional message is just as important. When an action is blocked, the message is passed back to Claude Code and becomes part of the model’s context. Instead of just failing, the agent receives feedback it can use to adjust its behavior.

**In other words, the exit code enforces the decision, while the message helps guide what happens next.**

## Which events can we hook into?

Claude Code exposes 33 hook events (as of November 2026). I like to group these events into five categories:

- **Tool Events** - PreToolUse, PostToolUse, PermissionRequest, ...
- **Session Events** - SessionStart, SessionEnd, PreCompact, ...
- **Agent and Task Events** - SubagentStart, SubagentStop, TaskCompleted, ...
- **User Interaction** - UserPromptSubmit, Notification, MessageDisplay, ...
- **Worktree Events** - WorktreeCreate, WorktreeRemove

![Claude Code's hook events grouped into five categories: tool, session, agent and task, user interaction, and worktree events.](https://nestenius.se/_astro/claude-code-hook-events-categories-diagram.Dikn7ga2_Zt5eex.webp)

A list of the most useful events is included later in this post.

## Why Hooks Matter for Every Project

Beyond observability, hooks are one of the most important control points available in any Claude Code project. By registering a **PreToolUse** **hook**, you get to run your own code before any tool executes, giving you the opportunity to inspect, block, or log every action the agent attempts.

This is a practical and effective way to restrict how Claude Code interacts with tools and files. You can block reads and writes to sensitive files and directories (credentials, `.env` files, private keys, config folders), prevent specific shell commands from running, and define clear rules around what the agent is allowed to touch.

Because your hook runs **in your environment**, it is always invoked before the tool executes and cannot be skipped through prompt manipulation alone. However, the effectiveness of the protection depends on how your hook validates and enforces its rules.

Hooks also provide a meaningful defense against **prompt injection attacks**. If a malicious file or web page contains hidden instructions telling Claude Code to exfiltrate data or modify a sensitive file, a PreToolUse hook can catch the attempt before the tool executes and block it with exit code 2. Claude Code reads your error message and stops, preventing the action from reaching the file system.

In practice, hooks act as a powerful guardrail and auditing layer. For **stronger guarantees**, especially when shell access is enabled, they should be combined with environment-level controls such as filesystem restrictions or sandboxing.

**In other words, hooks are one layer in a broader security model and should be combined with other controls for robust protection.**

## How to Observe Claude Code Hooks in Real Time

But how can we observe exactly when hooks are called and what data is passed to them? That is where the [Coding Agent Explorer](https://github.com/tndata/CodingAgentExplorer) and its [HookAgent tool](https://github.com/tndata/CodingAgentExplorer/tree/main/HookAgent) come in.

Here is what the rest of this post covers:

- How the HookAgent tool bridges Claude Code and the dashboard
- How to set everything up in a few minutes
- What you can actually see once it is running

## Introducing HookAgent

**HookAgent** is a small companion CLI tool that ships with the [Coding Agent Explorer](https://github.com/tndata/CodingAgentExplorer). It acts as the bridge between Claude Code’s hook system and the Coding Agent Explorer.

The diagram below shows how HookAgent receives hook events from Claude Code and forwards them to the Coding Agent Explorer.

![Diagram showing how HookAgent receives hook events from Claude Code via stdin, returns an exit code, and forwards the event to the Coding Agent Explorer over HTTP](https://nestenius.se/_astro/claude-code-hookagent-event-flow-diagram-1024x234.yCD1NgCJ_2jsxpd.webp)

To use it, configure Claude Code to call HookAgent for each hook event you want to capture. From that point on, every time Claude Code fires a hook, it runs HookAgent and passes the event data via **stdin**.

HookAgent’s core responsibility is simple:

- Read the incoming event from **stdin**
- Collect the Claude Code environment variables **CLAUDE\_PROJECT\_DIR**, **CLAUDE\_CODE\_REMOTE**, **CLAUDE\_ENV\_FILE** and **CLAUDE\_PLUGIN\_ROOT** (when set). The session ID is not an environment variable: it comes from the hook's JSON input on stdin
- Forward everything to the Coding Agent Explorer via a single HTTP POST request.
- When the Explorer receives a hook event, it updates the dashboard in real time.

If the Explorer is not running when a hook fires, HookAgent exits immediately and Claude Code continues normally. Observability is always optional.

### FACT: stdin and exit codes

**stdin** (standard input) is a standard way for one process to send data to another; in this case, Claude Code passes the hook event JSON as text to HookAgent via stdin.

The **exit code** is how a process reports the result back: **0** (zero) means success, while any non-zero value signals an error. For Claude Code hooks, only exit code **2** blocks an action. Other non-zero values are reported as hook errors, and the action still goes ahead.

## Getting Started with HookAgent

Getting hooks running takes about five minutes. Here is what you need.

### Prerequisites

Before you get started, make sure you have the following installed and ready:

- [.NET 10 SDK](https://dotnet.microsoft.com/) installed.
- [Coding Agent Explorer](https://github.com/tndata/CodingAgentExplorer) source code downloaded.
- Claude Code installed

See [Introducing the Coding Agent Explorer](https://nestenius.se/ai/introducing-the-coding-agent-explorer-net/) for installation and setup instructions.

### Step 1: Build HookAgent

Open a terminal in the root folder of the Coding Agent Explorer and run the appropriate publish script for your platform:

#### Windows:

```text
publish.bat
```

#### macOS / Linux:

```bash
bash publish.sh
```

This builds both the Coding Agent Explorer and HookAgent into the **Published** folder:

- **Published/CodingAgentExplorer**  
    The proxy and dashboard.
- **Published/HookAgent/HookAgent.exe**  
    HookAgent (Windows: .exe, macOS/Linux: no extension).

### Step 2: Create a working directory

Create a fresh folder where you will run claude (in this example, we name it **MyApp**), then copy the **HookAgent** folder from the **Published** folder into it. After copying, your working directory should look like this:

**Windows:**

```bat
C:\MyApp\HookAgent\HookAgent.exe
```

**macOS / Linux:**

```bash
~/MyApp/HookAgent/HookAgent
```

### Step 3: Configure Claude Code hooks

The Coding Agent Explorer includes ready-to-use sample **settings.json** files for each platform.

1. Create a **.claude** folder in your working directory (**MyApp**) if it does not already exist.
2. Copy the sample **settings.json** for your platform into that **.claude** folder.

Use one of these sample files:

- Windows: **HookAgent\Sample-Settings-Windows\settings.json**
- macOS / Linux: **HookAgent/Sample-Settings-LinuxMacOS/settings.json**

Your working directory should now look like this:  
**Windows:**

```text
C:\MyApp\
    HookAgent\HookAgent.exe
    .claude\settings.json
```

**macOS / Linux:**

```text
~/MyApp/
    HookAgent/HookAgent
    .claude/settings.json
```

This registers **HookAgent** for 31 of the 33 Claude Code hook events. I left out **WorktreeCreate** and **WorktreeRemove** on purpose. A WorktreeCreate hook replaces git's own worktree handling, and Claude Code reads the path the hook prints, so a hook that prints nothing breaks `--worktree`. Feel free to remove any events you do not need. The full list of supported events and the **settings.json** syntax is documented in the [Claude Code hooks reference](https://code.claude.com/docs/en/hooks).

The **"matcher": ".\*"** field is a regex pattern applied to the tool name. **.\*** matches all tools, so the hook fires for every tool call under that event. You can narrow it down. For example, **"matcher": "Bash"** would only fire for Bash tool calls. Not all events support a matcher. 

**Note:** On Windows, Claude Code runs hook commands through Git Bash, or through PowerShell when Git Bash is not installed. Always use forward slashes in the command path. The Windows sample uses **HookAgent/HookAgent.exe**. The macOS/Linux sample uses **HookAgent/HookAgent** with no .exe extension.

### Step 4: Verify the hooks are registered

Start Claude Code from your working directory and run the **/hooks** command:

```text
/hooks
```

Claude Code will list every configured hook event and the command registered for each one. You should see the registered hook events pointing to HookAgent. If the list is empty or events are missing, check that **.claude/settings.json** is in the right folder and that the JSON is valid.

Once you have confirmed the hooks are registered, exit Claude Code and move on to the next step.

### Step 5: Start the Coding Agent Explorer

From the Coding Agent Explorer folder, start the Explorer:

```bash
dotnet run
```

Then open the dashboard at `https://localhost:5001` in your browser. If you start it from Visual Studio, the browser opens for you.

Don’t forget to enable the proxy in Claude Code as described in the previous post in this series.

### Step 6: Test HookAgent

With the Explorer running, test **HookAgent** from your working directory before starting a full Claude Code session:

**Windows (PowerShell):**

```powershell
'{"hook_event_name":"UserPromptSubmit","session_id":"test"}' | HookAgent\HookAgent.exe
```

**Windows (cmd):**

```bat
echo {"hook_event_name":"UserPromptSubmit","session_id":"test"} | HookAgent\HookAgent.exe
```

**macOS / Linux:**

```bash
echo '{"hook_event_name":"UserPromptSubmit","session_id":"test"}' | HookAgent/HookAgent
```

A **UserPromptSubmit** event should appear in the **Conversation** **View** immediately. Make sure the “**Hook Events**” checkbox in the Conversation View is checked. If the Explorer is not running, the command exits silently and Claude Code is never affected.

### Step 7: Run Claude

From your working directory (**C:\MyApp** on Windows, **~/MyApp** on macOS/Linux), run:

```text
claude
```

**Hook events** will start appearing in the **Conversation View** as soon as Claude Code starts up, and then for every action it takes. Make sure the "Hook Events" checkbox in the Conversation View is checked, otherwise hook events will be hidden.

## Seeing Claude Code Hooks and Tool Calls in Real Time

Once everything is running, the Conversation View becomes a live timeline of everything Claude Code does, with hook events interleaved alongside the API calls. You get a complete picture that was previously invisible.

Here is what a typical interaction looks like on the timeline when you ask Claude Code to fix a bug:

```text
13:42:01 SessionStart
13:42:03 UserPromptSubmit "Fix the null reference exception in UserService.cs"
13:42:03 POST /v1/messages (Claude thinks about what to do)
13:42:05 PreToolUse Read (about to read UserService.cs)
13:42:05 PostToolUse Read (file contents returned)
13:42:05 POST /v1/messages (Claude analyses the code)
13:42:08 PreToolUse Edit (about to write the fix)
13:42:08 PostToolUse Edit (file updated)
13:42:08 POST /v1/messages (Claude confirms the fix)
13:42:10 Stop
```

In under 10 seconds, Claude Code made 3 LLM calls and 2 tool calls. Without hooks, you only see the API requests. With hooks, you see the full story.

![Screenshot of the Coding Agent Explorer Conversation View showing a PreToolUse and a PostToolUse hook event for the Glob tool, each with session ID, working directory, permission mode and the hook's stdout](https://nestenius.se/_astro/claude-code-hookagent-stdin-exit-code-flow.DAXbSmiZ_Z1jp3Yp.webp)

Clicking any hook event in the timeline opens the full JSON payload. For a **PreToolUse** event, for example, you see the tool name, the exact input parameters, the session ID, and the working directory. For a **PermissionRequest**, you see exactly what Claude Code wants to do and why.

```json
{
  "session_id": "299fa1e1-6310-43e7-b217-b28da4e97bec",
  "transcript_path": "C:\\Users\\xxxxx\\.claude\\projects\\C--Conf\\299fa1e1-6310-43e7-b217-b28da4e97bec.jsonl",
  "cwd": "C:\\Conf",
  "prompt_id": "7dc78733-6d7e-42a8-9382-7a12ef9e42b8",
  "permission_mode": "auto",
  "effort": {
    "level": "medium"
  },
  "hook_event_name": "PreToolUse",
  "tool_name": "PowerShell",
  "tool_input": {
    "command": "Get-ChildItem -Force C:\\Conf",
    "description": "List files in the folder"
  },
  "tool_use_id": "toolu_01WWNAYb7yEM768sVSaUyeqb"
}
```

Newer versions of Claude Code add two fields here: `prompt_id`, which links the event to the prompt that triggered it, and `effort`, the current effort level. HookAgent also picks up the effort level from the `CLAUDE_EFFORT` environment variable.

Subagents get their own identity. When I asked Claude Code to use a subagent to list the files, the **SubagentStart** event looked like this:

```json
{
  "session_id": "299fa1e1-6310-43e7-b217-b28da4e97bec",
  "transcript_path": "C:\\Users\\xxxxx\\.claude\\projects\\C--Conf\\299fa1e1-6310-43e7-b217-b28da4e97bec.jsonl",
  "cwd": "C:\\Conf",
  "prompt_id": "bc042426-a9a8-4af5-a157-abc9e23282db",
  "agent_id": "a7a41d5af62a58c03",
  "agent_type": "general-purpose",
  "hook_event_name": "SubagentStart"
}
```

`agent_id` identifies this subagent, and `agent_type` tells you which kind of agent Claude Code started. The session ID is the same as the main conversation, so you can follow the subagent's work inside the same session.

## Why Seeing Hook Events Live Helps

The question many developers ask when they start with coding agents is:  

_**But what is it actually doing? And what data is actually passed to my hooks?**_

The Conversation View with hooks answers that question directly. You can watch every session event, tool call, and permission request appear in real time as Claude Code works, and it is easy to put the dashboard on a shared screen for a demo or a team session. It turns the agent from a magic black box into a system that you can reason about, question, and understand.

Once you see the full picture, a lot of things click. You understand why the agent reads files before editing them. You see how it loops back to the LLM after each tool call. You notice where token costs accumulate. And you start writing better prompts as a result.

If you want to go further into how coding agents work under the hood, see the talk at the end of this post.

## Common Claude Code Hook Events

Claude Code supports 33 hook events (as of November 2026), and new ones are added regularly. These are the ones I find most useful. For the full and up-to-date list, see the [Claude Code hooks documentation](https://code.claude.com/docs/en/hooks#hook-events).

- **SessionStart**  
    Session begins or resumes
- **Setup**  
    Claude Code starts with `--init-only` or a similar init flag, for one-time setup in CI or scripts
- **UserPromptSubmit**  
    User submits a prompt
- **PreToolUse**  
    Fires before any tool executes
- **PostToolUse**  
    Fires after a tool succeeds
- **PostToolUseFailure**  
    Fires after a tool fails
- **PermissionRequest**  
    Claude Code requests permission to perform an action
- **PermissionDenied**  
    Auto mode denies a tool call
- **Stop**  
    Claude finishes responding
- **StopFailure**  
    The turn ends because of an API error
- **SubagentStart**  
    A subagent is started
- **SubagentStop**  
    A subagent finishes execution
- **Notification**  
    Claude Code sends a notification
- **PreCompact**  
    Fires before context compaction
- **PostCompact**  
    Fires after context compaction completes
- **InstructionsLoaded**  
    A CLAUDE.md or `.claude/rules/*.md` file is loaded into context
- **ConfigChange**  
    A settings file changes
- **CwdChanged**  
    The working directory changes, for example after a `cd` command
- **FileChanged**  
    A watched file changes on disk (the matcher lists the file names, for example `.env|.envrc`)
- **TeammateIdle**  
    Agent team coordination event
- **TaskCompleted**  
    A task is marked as complete
- **SessionEnd**  
    Session terminates

The **PreToolUse** and **PostToolUse** events are the most useful in practice. They fire for every tool call, whether it is a file read, a bash command, a web fetch, or an MCP tool invocation. Together, they give you a complete record of every action the agent takes.

- **PreToolUse** is where you enforce rules: block access to sensitive files, reject dangerous shell commands, or log what the agent is about to do.
- **PostToolUse** fires after a tool succeeds and is where you react to what just happened. When a tool fails, PostToolUseFailure fires instead and provides the error details.

**Common uses include:**

- Run your test suite automatically after the agent edits a file
- Trigger a linter or code formatter after a write
- Log the completed action to an audit trail
- Notify an external system (Slack, CI pipeline) that a file changed
- Inspect the tool output before the agent continues

### Example: InstructionsLoaded

**InstructionsLoaded** fires every time Claude Code loads a CLAUDE.md file (or a rule file in `.claude/rules/`) into its context. This is what HookAgent received when I started Claude Code in `C:\Conf`:

```json
{
  "session_id": "299fa1e1-6310-43e7-b217-b28da4e97bec",
  "transcript_path": "C:\\Users\\xxxxx\\.claude\\projects\\C--Conf\\299fa1e1-6310-43e7-b217-b28da4e97bec.jsonl",
  "cwd": "C:\\Conf",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "C:\\Conf\\CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}
```

`file_path` tells you which file was loaded, `memory_type` what kind of instruction file it is, and `load_reason` why it was loaded. This makes it easy to see which instruction files Claude Code actually reads, and when.

## I Want Your Feedback

The Coding Agent Explorer is open-source and I want to improve it with your help. If you find a bug, have a feature request, or want to share your experience, please create an [issue on GitHub](https://github.com/tndata/CodingAgentExplorer/issues). I read every issue and appreciate all feedback.

Contributions are also very welcome. The codebase is intentionally kept simple (a single NuGet dependency, a vanilla JS frontend) to make it easy for anyone to jump in.

## My Talk: How Coding Agents Actually Work

If you want to go one level deeper, I give a talk called [How Coding Agents Actually Work: Tools, MCP, and the Agent Loop](https://tn-data.se/talks/ai-development/). It opens the black box and shows how an agent talks to the language model, how tools and MCP give a text-only model access to your code, and how the agent loop ties it all together. If you’d like me to give it at your company, meetup or conference, you’ll find the details there.

## Claude Code Hooks FAQ

Here are answers to common questions about how hooks work in Claude Code, how to configure them, and what to expect in practice.

### Does HookAgent slow down Claude Code?

No. HookAgent makes a single HTTP POST per event and exits. The call is fast, and if the dashboard is not running it returns immediately. In practice, you will not notice any difference in Claude Code’s responsiveness.

### Do I need to change my project or code to use hooks?

No. You only need to create or update the **.claude/settings.json** file in the directory where you run claude. Nothing in your project code changes.

### Can I use only some of the hook events?

Yes. You can remove any hook entries from **settings.json** that you don’t want. For example, if you only care about tool calls, keep PreToolUse and PostToolUse and remove the rest.

### Does this work on macOS and Linux?

Yes. Use **publish.bat** on Windows or bash **publish.sh** on macOS and Linux. Each script detects the current platform and builds a single-file HookAgent executable for it. On Linux and macOS the executable has no .exe extension, so use **HookAgent/HookAgent** as the command path in your **settings.json**.

### Is this tool suitable for production use?

No. The Coding Agent Explorer is designed as a development and teaching tool. It is not intended for production use.

### Can I block all sensitive file access using PreToolUse?

Not completely. PreToolUse lets you block **direct** tool calls (like reading **secret.key**), but it does not provide a true sandbox.

For example, the model might:

- Generate a script (e.g. Bash or PowerShell) that reads files indirectly
- Request access to a broader directory (e.g. "load all files in this folder")
- Use other tools or workflows that bypass your specific path checks

If you give Claude Code **shell access** (Bash, command line, PowerShell, etc.), it can effectively do anything you can do within that environment; including reading sensitive files through indirect means.

Even for direct tool calls, your hook logic must be implemented carefully. Naive checks (for example simple string matching on file paths) can sometimes be bypassed using variations in path representation, encoding, or traversal patterns. In practice, you need to normalize and validate inputs rigorously.

**In other words, you are filtering requests, not enforcing OS-level isolation.**

### What does it take to truly secure file access?

If you need strong guarantees, you need to move beyond hooks and enforce restrictions at the environment level:

- **Run Claude Code in a sandbox**  
    (container, VM, or restricted workspace)
- **Limit filesystem permissions**  
    (only expose allowed directories)
- **Disable or tightly restrict shell access**  
    (for example by disabling the Bash tool or restricting what commands can be executed, since it can be used to invoke other interpreters like PowerShell or cmd)
- **Use allowlists instead of blocklists**  
    (explicitly permit safe paths only)

Hooks are best used as a **guardrail and observability layer**, not as your primary security boundary.

## Next: Part 3, Visualizing Claude Code MCP Requests

Hooks show what Claude Code does on your machine. The next part of the series looks at the other side: what it says to the MCP servers it uses. I walk through the MCP Observer, which sits between Claude Code and any HTTP MCP server, so you can see exactly how MCP tools like Microsoft Learn and Context7 work under the hood.

Continue with Part 3: [Visualizing Claude Code MCP Requests with Coding Agent Explorer](https://nestenius.se/ai/visualizing-claude-code-mcp-requests-with-coding-agent-explorer/).

## Related posts

- [Introducing the Coding Agent Explorer (.NET)](https://nestenius.se/ai/introducing-the-coding-agent-explorer-net/)
- [Implementing BFF Pattern in ASP.NET Core for SPAs](https://nestenius.se/net/implementing-bff-pattern-in-asp-net-core-for-spas/)
- [Introducing the Data Protection API Key Ring Debugger](https://nestenius.se/net/introducing-the-data-protection-api-key-ring-debugger/)
- [DefaultAzureCredentials Under the Hood](https://nestenius.se/azure/default-azure-credentials-under-the-hood/)
