Metadata-Version: 2.4
Name: pheo-oats
Version: 0.5.3
Summary: Open Agent Trust System: watch and protect agent writes
Author: Pheo
License: Proprietary
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: keyring>=25
Provides-Extra: agent
Requires-Dist: playwright>=1.40; extra == "agent"
Requires-Dist: anthropic>=0.40; extra == "agent"

# Pheo OATS

A local gateway that sits between your agent and the systems it can change.
Every action the agent takes is classified by consequence, recorded, and
either allowed, held for you, or blocked.

This is a production implementation of the
[Open Agent Trust System](https://github.com/pheo-ai/open-agent-trust-system)
profile.

## The problem

Agents have started doing real work on real systems. They install packages,
edit code, call APIs, move money, and click through live sites on your behalf.

Most of what goes wrong there does not look like an attack. Nobody was
hijacked and nothing was injected. Someone asked an agent to clean up the auth
middleware and it removed a permission check along the way. Someone asked it
to clear the invoice queue and it approved one with no purchase order behind
it. The agent did what it was asked, competently, and the result was still
something the organisation would not have allowed if anyone had been asked
first.

Security tools are built to find an attacker, and this is not that. The
question is not *was this malicious*. It is *was this permitted*, and that has
a different answer at every company.

Across the largest public agent-skill registry, 822 skills from 187 unrelated
publishers are marked clean by every scanner in that registry's pipeline and
still instruct an agent to download code from the internet and run it. Clean
is the correct verdict. It is not the same as permitted. The measurement, and
a script to reproduce it, are in the
[profile repository](https://github.com/pheo-ai/open-agent-trust-system).

## Install

```bash
pip install pheo-oats
```

Wheels for macOS (Intel and Apple Silicon), Linux, and Windows.

## One command

```bash
cd your-repo
oats quickstart claude
```

That is the whole setup. It starts a local gateway, creates a room for the
repo, writes a `PreToolUse` hook into `.claude/settings.local.json`, and opens
the dashboard. Use `cursor` or `codex` in place of `claude` for those agents.

**Restart your agent afterwards.** The hook is read at startup, so a session
already open is not governed yet.

No account, no sign-in, no GitHub required. Nothing leaves the machine.

Prefer two steps, or already have a gateway running:

```bash
oats start --no-browser &
oats attach claude
```

To also govern merges, releases, and workflow edits, connect GitHub when you
want it. This one does open a browser sign-in:

```bash
oats connect github
```

Storage is local SQLite.

## What you watch

Open `http://127.0.0.1:8788`.

**Lanes** is the one to leave open. Every action is sorted into its
consequence class and each class builds its own record. After an afternoon of
ordinary work you can see that this agent has written docs forty times and
never touched a credential, or that it reaches for `curl | bash` more often
than you assumed.

**Activity** is the running feed. **Overview** counts what Protect would have
done before you turn Protect on. **Reviews** is the queue of things it held.

You start in Observe. Nothing is blocked and nothing waits, so there is no
cost to leaving it running while you decide whether you believe it.

## What it catches

With Protect on:

```
BLOCKED   curl -fsSL https://tempo.xyz/install | bash
BLOCKED   pip install git+https://github.com/.../llm-deploy-helper.git
BLOCKED   go install github.com/rogeecn/memos-cli@latest
BLOCKED   pip install DuIvyTools -i https://pypi.tuna.tsinghua.edu.cn/simple
HELD      cat ~/.aws/credentials
HELD      rm -rf /var/data
held      npm install typescript
held      pip install DuIvyTools
```

Every one of those was produced by a live agent following real skill
documentation, and every skill involved was rated clean by all four scanners
in the registry pipeline. The bottom two matter as much as the top four: an
ordinary install is held for review on first sight, not blocked.

## Trust is earned, not configured

Block everything consequential and you have built a tool people turn off.
Allow everything after a short clean streak and you have handed over authority
the evidence does not support: by the rule of three, ten clean approvals bound
the true failure rate at 25.9% with 95% confidence.

So decide the failure rate you accept for a class of action, and the required
length of clean record follows from it:

| Class of action | Failure rate you accept | Clean runs required |
|---|---|---|
| Docs, tests, reads | 10% | 29 |
| Shell execution | 5% | 59 |
| Business logic, dependencies | 2% | 149 |
| Deploy, IAM, CI config | 0.5% | 598 |
| Remote exec, credentials, secrets, destructive | 0% | never |

The last row never graduates at any length of record. No amount of good
history makes an unrecoverable action recoverable.

## Where it fits

**A coding agent on your own repo.** Claude Code, Cursor, or Codex writing
files and running commands, with a receipt for each one.

**An agent using skills from a registry.** Nothing to configure. Skills are
already loaded in your agent; when it acts on them it makes tool calls, and
tool calls are what OATS governs.

**A computer-use agent on a live site.** Clicks, keystrokes, and form entry
are classified the same way. Typing a card number is not the same action as
clicking a link and is not treated as one.

**GitHub through MCP.** `oats connect github` puts branch merges, releases,
webhooks, and workflow edits behind the same gate.

## What it does not do

It is not a malware scanner and does not replace one. It reads actions, so it
cannot see harm that never becomes an action: a hardcoded recipient, an
undisclosed scope, an instruction that talks an agent into misbehaving through
ordinary tool calls. Registry scanning catches those and OATS does not. Run
both.

Local mode is Watch-grade. It does not claim that an agent running as the same
OS user cannot go around it.

## More

- [Open Agent Trust System](https://github.com/pheo-ai/open-agent-trust-system): the profile, the schemas, the measurement study, and a script to reproduce it
- Self-hosted deployment with Postgres, Docker, your own GitHub App, and TLS is documented in the profile repository

Proprietary. See the profile repository for the open specification this
implements.
