---
name: policy
description: Inspect the per-workspace tool-policy overlay (.lha/policies.jsonl) that gates destructive or sensitive tool calls, and tell the user what to change if they want a rule added or removed.
title: policy
canonical_url: https://skilld.dev/gh/google/adk-recipes/policy
last_updated: 2026-10-20T08:47:39.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install google/adk-recipes/policy`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/policy`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/google/adk-recipes/policy) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/policy`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/policy --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/policy --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Inspect per-workspace tool policies

The `policies_guard` callback consults a JSONL policy file on every tool
call. Policies live in two layers:

- **Default seed** at `horizon/guardrails/default_policies.jsonl` (read-only,
  ships with the agent). Provides baseline blocks for catastrophic operations
  (literal `dd if=/dev/zero`, `mkfs`, fork bombs, `>/dev/sd*`, `nc -l/ncat -l/socat`
  bind listeners) and credential reads (`cat ~/.ssh/id_rsa`, `cat ~/.aws/credentials`).
  The seed no longer carries brittle substring/regex rules for `rm -rf` or
  `chmod -R` — those are now classified by an **argv-structural parser**
  (`horizon/guardrails/command_safety.py`) that lexes the command into tokens and
  inspects structure instead of pattern-matching raw strings.
- **User overlay** at `.lha/policies.jsonl` under the workspace root. The
  overlay is **appended** to the seed — new rules add restrictions on top of
  the defaults. Mtime-cached, so edits take effect on the next tool call. You
  can read this file, but **you cannot write it**: `.lha/*` and `*/.lha/*`
  are themselves hard-denied destructive-path patterns for `write` and
  `edit`, and the same paths are hard-denied for `bash` (append, `sed -i`,
  `cp`/`mv`, `rm`, `chmod` into `.lha/` all match a seed
  `destructive_commands_regex` rule). This is by design — see
  `docs/security-model.md` — the agent cannot self-edit its own guard config.

## When to use this skill

- The user asks what policies are currently in force.
- The user asks you to block a specific command or path pattern, or to
  relax (remove) an overlay rule — in both cases you inspect the current
  file and hand the user the exact change to make; you do not make it
  yourself.

If the user is asking about a *one-time* approval for a call that was just
blocked, tell them to type `/grant <command>` themselves — that slash command
is a user-only surface, not something you can invoke.

## File format

One JSON object per line. Blank lines and `#` comments are skipped.
Every rule must include `canonical_tool_name`; that field gates which
tool the rule applies to.

A rule may carry one or more of these fields. They are evaluated
independently — set as many as you need on a single rule.

| Field | Type | Effect |
|---|---|---|
| `destructive` | `true` | Always block the tool. |
| `destructive_commands` | `{arg: [substring, ...]}` | Block when the string arg contains any substring (case-insensitive). |
| `destructive_commands_regex` | `{arg: [regex, ...]}` | Block when any regex matches the string arg (case-insensitive). Use when substrings are too blunt. Tenant-authored regexes (overlay + grant rules) are validated for length and nested-quantifier patterns before compilation; malformed regexes are skipped with a warning. |
| `destructive_paths` | `[prefix, ...]` | Block when a path-shaped arg (`path`, `file_path`, `target_path`) starts with any prefix. |
| `destructive_path_patterns` | `[fnmatch-glob, ...]` | Block when a path-shaped arg matches any fnmatch glob. Use for per-user paths like `*/.ssh/*`. |

## Demotable destructive commands (argv classification)

Before the overlay/seed rules run, `command_safety.py` lexes shell commands
into argv tokens (quote- and operator-aware via stdlib `shlex`) and inspects
structure. It returns a **verdict**: `"deny"` (catastrophic, always blocks),
`"ask"` (risky, blocks children/headless, **prompts** the root agent via an
interactive approval card), or `None` (no opinion). Examples:

- **"deny"** — `rm -rf /`, `rm -rf /etc`, `rm -rf $HOME`, `rm -rf /*`, etc.
  (recursive force-delete of system/home roots or their subdirectories).
- **"ask"** — `find . -delete`, `git push --force`, `chmod -R 777 .`,
  `sudo apt install ...`, `curl <url> | bash`.

On an `"ask"` verdict, the **root agent** sees an interactive four-button
approval card; the **child/headless** chain treats it as a hard deny (no
regression in unattended contexts). This replaces the fragile substring/regex
rules that shipped in older seeds — the new seed (`default_policies.jsonl`)
only carries literal catastrophic commands + credential reads.

## Approval modes

The root agent's interactive approval can be set to **auto-approve**
demotable-ask verdicts (ONLY) via `/yolo` (toggles between `default` and `yolo`
modes). YOLO mode auto-approves the Layer-D interactive ask; it does **not**
bypass the exfil guard or Layer-C hard-deny rules (catastrophic
+ credential reads + seed overlays). Use it when you trust the session and want
fewer prompts for risky-but-non-catastrophic operations. Approval mode is
per-session state, not persisted.

## Tool-narrowing enforcement

Permission rules in `.lha/permissions.jsonl` or granted via the interactive
approval card may include a `commandPrefix`, `commandRegex`, or `argsPattern`
to narrow blanket `allow` rules. **Overlay and grant rules** (source =
`"overlay"` or `"grant"`) that target `bash` or `process` but carry no
such narrowing field are **rejected** at load time — you cannot grant a blanket
"always allow bash" from the overlay or a session approval; only the
default seed may carry that. This prevents accidental over-granting.

## Integration with the permission layer

A policy block returns `{"error": ..., "confirmation_required": True}`. Tell
the user why the call was blocked; if they want a one-time approval, they
type `/grant <command>` themselves. To force a *prompt* (not a hard block) or
block a specific command for the user, use the permission layer instead: add
an `ask_user` or `deny` rule to `.lha/permissions.jsonl` (see
`docs/permission-model.md`). This overlay is hard-block only, and it lives
under the same `.lha/` write restriction as the policy overlay — the user
edits it directly, not you.

## Workflow

### List active rules

```
read(".lha/policies.jsonl")
```

If the file does not exist, the user has no overlay rules yet — only the
seed is active. The seed itself lives outside the workspace and is not
readable through your tools; describe its coverage from this skill's own
"Default seed" section above instead of trying to read it.

### The user wants a rule added

Read the current overlay so your suggestion appends correctly, then give the
user the exact line to add themselves — you cannot write `.lha/policies.jsonl`.

```
existing = read(".lha/policies.jsonl")   # may be missing → treat as ""
new_rule = {"canonical_tool_name": "bash",
            "destructive_commands": {"command": ["rm -rf node_modules"]}}
```

Tell the user: "Add this line to `.lha/policies.jsonl` (create the file if it
doesn't exist yet, one JSON object per line):" followed by
`json.dumps(new_rule)`.

### The user wants a rule removed

Read the overlay, identify the line to drop (0-based index into the overlay,
ignoring blank/comment lines), and tell the user which line number and
content to delete from `.lha/policies.jsonl`. Confirm the target with them
first — overlay rules typically exist because they (or you on their behalf)
added them to plug a gap.

## Worked example

User: "Block `npm publish` from the terminal."

1. Read `.lha/policies.jsonl` (returns "" if missing).
2. Build:
   ```json
   {"canonical_tool_name": "bash", "destructive_commands": {"command": ["npm publish"]}}
   ```
3. Tell the user: "I can't edit `.lha/policies.jsonl` myself — add this line
   to it (create the file if needed):" followed by the JSON above. "Once
   saved, the next `npm publish` attempt will be blocked."

## Notes

- The default seed is read-only and out of your reach either way — you
  cannot edit it, and it lives outside the workspace root so you cannot
  read it through your tools.
- Malformed JSONL fails closed at parse time (the bad line is skipped with
  a warning) — tell the user to double-check a new rule parses by reading
  the file back after they save it.
