# panto-agent

The `agent.*` extension suite for [pantograph](https://github.com/travisp/pantograph)'s
`panto` CLI: coding-agent conveniences packaged as a luarocks rock.

## Extensions

- **`agent.rules`** — at session start, injects the contents of `AGENTS.md`
  (or `CLAUDE.md` when no `AGENTS.md` exists — never both) into the system
  prompt, from each of: the base layer agent dir
  (`${XDG_DATA_HOME:-~/.local/share}/panto/agent`), the user layer dir
  (`${XDG_CONFIG_HOME:-~/.config}/panto`), and the project root (cwd).
  Symlinks are resolved; each file becomes one system message headed
  `context from <path>:`.

  It also hooks `std.read` results (a `tool_result` event handler using
  the writable `output` field): reading a file (or directory) below the
  project root appends any `AGENTS.md`/`CLAUDE.md` found between the read
  location and the root (root excluded — the system prompt covers it) to
  the tool result as `---`-separated `context from <path>:` sections.
  Each real file is injected at most once per session. The transcript
  keeps the read's own output, with a `+ rules: <path>` line per attached
  file below it.

- **`agent.skill`** — an `agent.skill` tool for loading
  [Agent Skills](https://agentskills.io) on demand. At activation it
  discovers skills (subdirectories containing a `SKILL.md` with YAML
  frontmatter) from, lowest priority first:
  `${XDG_DATA_HOME:-~/.local/share}/panto/agent/skills`,
  `${XDG_CONFIG_HOME:-~/.config}/panto/skills`, `~/.agent/skills`,
  `<cwd>/.panto/skills`, and `<cwd>/.agent/skills`. The frontmatter
  `name` (not the directory name) is the skill's identity; later
  directories shadow same-named skills from earlier ones. Surviving
  names and descriptions are baked into the tool's description and its
  input schema's enum. Calling the tool returns the skill's `SKILL.md`
  instructions (frontmatter stripped) behind a preamble that tells the
  model to resolve the skill's relative paths against its directory.
  With no skills discovered, the tool is not registered.

## Install

Via the rock (once published):

```toml
[extensions]
rocks = ["panto-agent"]
```

Or as a local checkout:

```toml
[extensions]
paths = ["/path/to/panto-agent"]
```

Individual extensions can be toggled with the usual policy globs, e.g.
`deny = ["agent.rules"]`.

## Development

Run the self-check (needs `panto` for its embedded Lua + luv):

```sh
panto lua _selfcheck.lua
```

Layout note: the sources live under `panto-agent/` (matching the installed
module tree) so `require` works identically installed and from a checkout;
`_selfcheck.lua` is `_`-prefixed so panto's directory scan skips it.