# Quickstart: govern a coding agent

Connect Claude Code and prove allow, block, and human approval with a harmless command.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/start/coding-agent

## Prepare a test environment

You need a Kastra workspace with custom policy and approval access, an administrator to create the policy, an authorized approver, and Claude Code installed. [Install Edge](https://docs.kastra.ai/edge/install) and the [operator CLI](https://docs.kastra.ai/reference/cli). The commands below use a POSIX shell on macOS or Linux; [platform support](https://docs.kastra.ai/start/platform-support) covers other combinations.

```sh
kastra auth login
kastra env create docs-hooks
kastra-edge config show
kastra-edge config set default_environment docs-hooks
kastra-edge install-claude --dry-run
kastra-edge install-claude
kastra-edge doctor
```

Record your previous `default_environment` before changing it. Login is shared by the two CLIs. Use a fresh environment: if `docs-hooks` already exists, choose a new name and update the policy file's `metadata.environment`. In the console, select this environment and confirm enforcement is enabled rather than shadow mode. Restart Claude Code so it reloads the hook and configuration.

## Install the example policy

Download and inspect [coding-agent.kastra](https://docs.kastra.ai/examples/coding-agent.kastra). Its two rules match `x-kastra-attr-tool = Bash` and a specific marker in `x-kastra-attr-tool-input`: `kastra-docs-deny` blocks, and `kastra-docs-hold` requests approval. Other actions default to ALLOW. Approval expires after five minutes with a denial.

```sh
curl --fail --output coding-agent.kastra https://docs.kastra.ai/examples/coding-agent.kastra
kastra policy validate coding-agent.kastra
kastra policy add coding-agent.kastra --activate
```

Save the new policy ID printed by the command. Check the active policy in the console before proceeding. These example rules demonstrate control flow; they are not a general shell-security policy.

## Prove an allow

In Claude Code, ask: **Use the Bash tool to run exactly `printf 'kastra-docs-allow\n'`. Do not substitute another tool.**

The tool output should contain `kastra-docs-allow`. Find its event in Activity under `docs-hooks`, with source `claude_code` and tool `Bash`. Confirm ALLOW and the expected active policy. A sentence generated by the assistant is not the tool result.

## Prove a block

Ask: **Use the Bash tool to run exactly `printf 'kastra-docs-deny\n'`. If policy blocks it, stop; do not retry with another tool.**

Expect a policy denial before Bash runs. Activity should identify the matching documentation rule and DENY. The marker may appear in the denied request preview; it must not appear as successful command output.

## Prove approval

Ask the same way for `printf 'kastra-docs-hold\n'`. While it waits, open Approvals in the console, inspect the exact command and environment, and approve it. Expect the waiting Bash action to run once. Repeat as a new tool call and deny that checkpoint; it must not execute.

Resolve promptly: the host's wait budget and checkpoint expiry are separate. If the client stops waiting, inspect the checkpoint and follow [approval recovery](https://docs.kastra.ai/approvals/overview); do not treat a timeout as permission.

## Check the evidence and clean up

```sh
kastra evidence list --env docs-hooks --limit 20
kastra policy deactivate POLICY_ID
```

Replace `POLICY_ID` with the ID created for this walkthrough. Confirm the three outcomes and the approval resolution in the console. Restore the previous Edge environment with `kastra-edge config set default_environment PREVIOUS_NAME`, then restart Claude Code. Keep the inactive example policy and its evidence for review, or remove that example policy through the console when no longer needed.

If you installed the hook only for this exercise, use `kastra-edge uninstall-claude --dry-run`, then `kastra-edge uninstall-claude` and restart the client. If events are missing or actions unexpectedly proceed, use [Edge troubleshooting](https://docs.kastra.ai/edge/troubleshooting) before adding more rules.