@element47/ag 4.4.5 → 4.5.2

package/README.md

@@ -127,6 +127,46 @@ export default {
 
 That's it. No config, no registry. Use `/tools` in the REPL to see what's loaded.
 
+### Permission Keys
+
+By default, custom tools require approval for every call (or you allow all calls with `toolname(*)`). To enable fine-grained permission patterns, add a `permissionKey` to your tool:
+
+```js
+// .ag/tools/deploy.mjs
+export default {
+  type: "function",
+  function: {
+    name: "deploy",
+    description: "Deploy to an environment",
+    parameters: {
+      type: "object",
+      properties: {
+        target: { type: "string", enum: ["staging", "production"] },
+        branch: { type: "string" }
+      },
+      required: ["target"]
+    }
+  },
+  permissionKey: { qualifier: "target" },
+  execute: async ({ target, branch }) => { /* ... */ }
+};
+```
+
+Now permission patterns can target specific argument values:
+
+| Pattern | Effect |
+|---------|--------|
+| `deploy(staging)` | Allow staging deploys |
+| `deploy(production)` | Allow production deploys |
+| `deploy(*)` | Allow all deploys |
+
+**`permissionKey` fields:**
+
+- `qualifier` (required) — arg name whose value becomes the pattern qualifier. E.g., `{ qualifier: "target" }` + `target: "staging"` produces `deploy(staging)`.
+- `value` (optional) — arg name whose value is matched by the glob portion. E.g., `{ qualifier: "action", value: "path" }` produces `mytool(read:configs/**)`.
+
+Without `permissionKey`, the only available pattern is `toolname(*)`.
+
 ## Skills
 
 Skills are reusable prompt instructions (with optional tools) that the agent activates on-demand. Browse and install from [skills.sh](https://skills.sh):
@@ -234,22 +274,84 @@ Or set it permanently:
 
 ## Permissions
 
-In REPL mode, ag prompts before executing mutating operations:
+In REPL mode, ag prompts before executing mutating operations. You can allow once, remember for the session, or save to the project:
 
 ```
-  ? bash: npm test (y/n) y
+  ? bash: npm test (y)es / (a)lways / (p)roject / (n)o a
+  + Session rule: bash(npm:*)
   ✓ [bash] All tests passed
-  ? file(write): src/utils.ts (y/n) y
+  ? file(write): src/utils.ts (y)es / (a)lways / (p)roject / (n)o p
+  + Saved to .ag/permissions.json: file(write:src/**)
   ✓ [file] Wrote src/utils.ts (24 lines, 680B)
 ```
 
+**Prompt options:**
+- **y** — allow this one time
+- **a** — allow and remember the pattern for this session
+- **p** — allow and save the pattern to project (`.ag/permissions.json`)
+- **n** — deny this one time
+
+### Pattern Syntax
+
+Patterns use `Tool(qualifier:glob)` format:
+
+| Pattern | Matches |
+|---------|---------|
+| `bash(npm:*)` | Any bash command starting with `npm` |
+| `bash(git:*)` | Any bash command starting with `git` |
+| `file(write:src/**)` | File writes anywhere under `src/` |
+| `file(edit:*)` | All file edits |
+| `git(commit)` | Git commit |
+| `web(fetch:*github.com*)` | Fetch from GitHub domains |
+| `bash(*)` | All bash commands |
+| `*` | Everything |
+
+### Rule Scopes
+
+| Scope | Storage | Lifetime |
+|-------|---------|----------|
+| Session | In-memory | Until REPL exits |
+| Project | `.ag/permissions.json` | Persists across sessions |
+| Global | `~/.ag/permissions.json` | Persists everywhere |
+
+Deny rules always override allow rules. Use `/permissions` to manage rules interactively.
+
+### Built-in Classifications
+
 **Always allowed (no prompt):** `file(read)`, `file(list)`, `grep(*)`, `memory(*)`, `plan(*)`, `skill(*)`, `git(status)`, `web(search)`
 
 **Prompted:** `bash`, `file(write)`, `file(edit)`, `git(commit/push/branch)`, `web(fetch)`
 
 **Always blocked:** `rm -rf /`, fork bombs, `sudo rm`, pipe-to-shell (enforced in code regardless of approval)
 
-Skip prompts with `ag -y` or `--yes`. One-shot mode (`ag "query"`) auto-approves.
+Skip all prompts with `ag -y` or `--yes`. One-shot mode (`ag "query"`) auto-approves.
+
+## Guardrails
+
+All externally-loaded tools and skills are scanned at load time for prompt injection and other security issues. This applies to:
+
+- Custom tools (`.mjs` files in `~/.ag/tools/` and `.ag/tools/`)
+- Skills (`SKILL.md` files in `~/.ag/skills/` and `.ag/skills/`)
+- Skills installed from the registry via `/skill add`
+
+**What gets checked:**
+
+| Category | Severity | Examples |
+|----------|----------|---------|
+| Direct injection | Block | "ignore previous instructions", "system override", "reveal prompt" |
+| Encoded payloads | Block | Base64-encoded injection attempts, HTML entity obfuscation |
+| Hidden content | Block | HTML comments with instructions, zero-width characters, control chars |
+| Exfiltration | Block/Warn | `fetch()` calls in descriptions (block), URLs/emails (warn) |
+| Suspicious overrides | Warn | "bypass security", "auto-approve", "run without permission" |
+
+**Blocked** items are skipped entirely with a warning. **Warned** items still load but emit a warning to stderr:
+
+```
+Warning: evil-tool.mjs blocked by guardrails: tool "evil" description: prompt injection: "ignore previous instructions"
+Warning: shady-tool.mjs: tool "shady" description: description contains URL
+```
+
+When installing a skill from the registry, files are scanned before being written to disk. If the core `SKILL.md` is blocked, the entire installation is aborted.
 
 ## Streaming
 

package/dist/cli/repl.d.ts

@@ -1,14 +1,19 @@
 import { Interface } from 'node:readline';
 import { Agent } from '../core/agent.js';
+import { PermissionManager } from '../core/permissions.js';
 import type { ConfirmToolCall } from '../core/types.js';
 export declare function createConfirmCallback(sharedRl?: Interface): ConfirmToolCall & {
     pauseSpinner: (() => void) | null;
 };
+export declare function createPermissionCallback(pm: PermissionManager, sharedRl?: Interface): ConfirmToolCall & {
+    pauseSpinner: (() => void) | null;
+};
 export declare class REPL {
     private readonly agent;
     private readonly rl;
-    private readonly confirmCb;
-    constructor(agent: Agent, confirmCb?: ReturnType<typeof createConfirmCallback>);
+    private readonly pm;
+    private confirmCb;
+    constructor(agent: Agent, pm?: PermissionManager, confirmCb?: ReturnType<typeof createPermissionCallback>);
     start(): Promise<void>;
     private handleCommand;
     private ask;

package/dist/cli/repl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../src/cli/repl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAKjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAoBxD,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG;IAAE,YAAY,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAuBnH;AAmBD,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkD;gBAEhE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC;IAcxE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YA6Id,aAAa;IAmU3B,OAAO,CAAC,GAAG;CAGZ"}
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../src/cli/repl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAsB,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAKjE,OAAO,EAAE,iBAAiB,EAAgB,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,kBAAkB,CAAC;AAqCvE,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG;IAAE,YAAY,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAgBnH;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,iBAAiB,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG;IAAE,YAAY,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAiD7I;AA8GD,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAA2B;IAC9C,OAAO,CAAC,SAAS,CAAqD;gBAE1D,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC;IAqBnG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAwMd,aAAa;IA8Y3B,OAAO,CAAC,GAAG;CAGZ"}