agentperm 0.1.0__tar.gz

agentperm-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+.coverage
+.python-version
+.env
+.claude/
+.codex/
+.gemini/
+.opencode/
+zellij-plugin/target/

agentperm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jackson Cooper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentperm-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: agentperm
+Version: 0.1.0
+Summary: Permission policy mediator for Claude Code, Codex, OpenCode, and Gemini CLI.
+Project-URL: Homepage, https://github.com/jacks0n/agentperm
+Project-URL: Repository, https://github.com/jacks0n/agentperm
+Project-URL: Issues, https://github.com/jacks0n/agentperm/issues
+Author-email: Jackson Cooper <jackson@jacksonc.com>
+License: MIT License
+        
+        Copyright (c) 2026 Jackson Cooper
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,agentic,agentic-ai,agentic-tools,ai,ai-agent,ai-agents,ai-coding-assistant,ai-tools,anthropic,claude,claude-code,codex,codex-cli,coding-agent,coding-assistant,developer-tools,gemini,gemini-cli,hooks,llm,llm-agent,llm-tools,mcp,mediator,openai,opencode,permissions,policy,policy-engine,shell,tree-sitter,tree-sitter-bash
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pyjson5<3,>=2.0
+Requires-Dist: tomlkit<0.14,>=0.13
+Requires-Dist: tree-sitter-bash<0.26,>=0.25
+Requires-Dist: tree-sitter<0.26,>=0.25
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentperm
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+
+One permission policy file for coding agents. Configure [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex), or [OpenCode](https://opencode.ai) to call the bridge from their hook systems, and they can all consult `~/.agent-permissions.jsonc` before tools run — so the same allow / ask / deny rules apply everywhere.
+
+## Why
+
+Every agent ships its own permission system, and none of them parse compound shell commands the way a shell does. `cat foo 2>/dev/null | head -60` is two read-only segments separated by a pipe, but the native config typically can't reason about pipes, redirects, `&&`, `for ... do ... done`, or `bash -c "..."` — so it asks, every time. The bridge parses the command with the Tree-sitter Bash grammar, evaluates each executable segment against your policy, and returns a single decision.
+
+It also gives you one source of truth instead of four, plus a richer rule grammar (e.g. "ask before `sed -i`, allow `sed` otherwise").
+
+## Install
+
+```sh
+pipx install agentperm
+# or
+uv tool install agentperm
+```
+
+Then:
+
+```sh
+agentperm import    # pulls existing native rules into ~/.agent-permissions.jsonc
+agentperm install   # wires the bridge into Claude Code, Codex, OpenCode, and Gemini hooks
+agentperm edit      # opens the policy in $EDITOR (creates a default if missing)
+```
+
+`install` auto-detects whether you use [Rulesync](https://github.com/dyoshikawa/rulesync) — if `~/.rulesync/` exists, it merges hook entries into `~/.rulesync/hooks.json` and you re-run `rulesync` to materialise per-tool configs. Otherwise it writes per-tool configs (`~/.claude/settings.json`, `~/.codex/hooks.json`+`config.toml`, `~/.gemini/settings.json`) directly. The OpenCode plugin shim is always installed at `~/.config/opencode/plugins/agentperm.js` because rulesync has no schema for `permission.ask` plugins. Pass `--mode rulesync|direct` to override detection or `--dry-run` to preview.
+
+Per-project overrides live in `<project>/.agent-permissions.jsonc` — both files merge at decision time, deny wins.
+
+## Quickstart
+
+```jsonc
+{
+  "version": 1,
+  "permissions": {
+    "allow": [
+      "Bash(git status:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Read",
+      "Grep",
+      "WebFetch(domain:github.com)"
+    ],
+    "ask": [
+      {
+        "tool": "Bash",
+        "command": ["sed", "gsed"],
+        "when": { "hasOption": ["-i", "--in-place"] },
+        "reason": "sed in-place editing changes files"
+      }
+    ],
+    "deny": [
+      "Bash(sudo:*)",
+      "Bash(rm -rf /*)"
+    ]
+  }
+}
+```
+
+A compound like `cat foo 2>&1 | head -60` passes through silently with the policy above — every segment matches an allow rule, the redirect is a safe `2>&1` fd-dup, and the bridge returns `allow`.
+
+`sed -i s/foo/bar/ x.txt` surfaces a prompt with the rationale `"sed in-place editing changes files"` — the `ask` rule beats the `allow` rule on `sed`.
+
+`rm -rf /tmp/*` is denied without prompting.
+
+## Bypass mode (zellij)
+
+A per-pane "skip prompts" toggle for users running their agents inside [zellij](https://zellij.dev). Bind a key to flip a flag file for the focused pane; while the flag is on, `agentperm` coerces `Ask` and `NoOpinion` verdicts to `Allow` — but only in that pane, and `Deny` rules still bite. (Claude's own `bypassPermissions` is different: there agentperm defers entirely and lets Claude handle everything.) The toggle and indicator live in a small WASM plugin shipped at [`zellij-plugin/`](zellij-plugin/README.md).
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — domain model, AST parsing, aggregation, bypass coercion
+- [Policy reference](docs/policy-reference.md) — full grammar of `.agent-permissions.jsonc`
+- [CLI reference](docs/cli.md) — `install`, `import`, `check`, `edit`, pane bypass
+- [Adapter notes](docs/adapters.md) — agent-specific behavior and limits
+- [Troubleshooting](docs/troubleshooting.md) — diagnosing prompts, the trace env var, common pitfalls
+- [zellij plugin](zellij-plugin/README.md) — per-pane bypass toggle and indicator
+- [Contributing](CONTRIBUTING.md) — dev setup, tests, PR conventions
+- [Changelog](CHANGELOG.md)
+
+## What it doesn't do
+
+- **Manage MCP servers** — use Rulesync, native agent config, or your own dotfile tooling.
+- **Replace native permission settings** — those keep working as fast paths. The bridge layers on top.
+- **Sandbox commands** — the bridge is a policy engine, not an enforcement engine. Commands the agent decides to run still run with your shell's privileges.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agentperm-0.1.0/README.md

@@ -0,0 +1,93 @@
+# agentperm
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+
+One permission policy file for coding agents. Configure [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex), or [OpenCode](https://opencode.ai) to call the bridge from their hook systems, and they can all consult `~/.agent-permissions.jsonc` before tools run — so the same allow / ask / deny rules apply everywhere.
+
+## Why
+
+Every agent ships its own permission system, and none of them parse compound shell commands the way a shell does. `cat foo 2>/dev/null | head -60` is two read-only segments separated by a pipe, but the native config typically can't reason about pipes, redirects, `&&`, `for ... do ... done`, or `bash -c "..."` — so it asks, every time. The bridge parses the command with the Tree-sitter Bash grammar, evaluates each executable segment against your policy, and returns a single decision.
+
+It also gives you one source of truth instead of four, plus a richer rule grammar (e.g. "ask before `sed -i`, allow `sed` otherwise").
+
+## Install
+
+```sh
+pipx install agentperm
+# or
+uv tool install agentperm
+```
+
+Then:
+
+```sh
+agentperm import    # pulls existing native rules into ~/.agent-permissions.jsonc
+agentperm install   # wires the bridge into Claude Code, Codex, OpenCode, and Gemini hooks
+agentperm edit      # opens the policy in $EDITOR (creates a default if missing)
+```
+
+`install` auto-detects whether you use [Rulesync](https://github.com/dyoshikawa/rulesync) — if `~/.rulesync/` exists, it merges hook entries into `~/.rulesync/hooks.json` and you re-run `rulesync` to materialise per-tool configs. Otherwise it writes per-tool configs (`~/.claude/settings.json`, `~/.codex/hooks.json`+`config.toml`, `~/.gemini/settings.json`) directly. The OpenCode plugin shim is always installed at `~/.config/opencode/plugins/agentperm.js` because rulesync has no schema for `permission.ask` plugins. Pass `--mode rulesync|direct` to override detection or `--dry-run` to preview.
+
+Per-project overrides live in `<project>/.agent-permissions.jsonc` — both files merge at decision time, deny wins.
+
+## Quickstart
+
+```jsonc
+{
+  "version": 1,
+  "permissions": {
+    "allow": [
+      "Bash(git status:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Read",
+      "Grep",
+      "WebFetch(domain:github.com)"
+    ],
+    "ask": [
+      {
+        "tool": "Bash",
+        "command": ["sed", "gsed"],
+        "when": { "hasOption": ["-i", "--in-place"] },
+        "reason": "sed in-place editing changes files"
+      }
+    ],
+    "deny": [
+      "Bash(sudo:*)",
+      "Bash(rm -rf /*)"
+    ]
+  }
+}
+```
+
+A compound like `cat foo 2>&1 | head -60` passes through silently with the policy above — every segment matches an allow rule, the redirect is a safe `2>&1` fd-dup, and the bridge returns `allow`.
+
+`sed -i s/foo/bar/ x.txt` surfaces a prompt with the rationale `"sed in-place editing changes files"` — the `ask` rule beats the `allow` rule on `sed`.
+
+`rm -rf /tmp/*` is denied without prompting.
+
+## Bypass mode (zellij)
+
+A per-pane "skip prompts" toggle for users running their agents inside [zellij](https://zellij.dev). Bind a key to flip a flag file for the focused pane; while the flag is on, `agentperm` coerces `Ask` and `NoOpinion` verdicts to `Allow` — but only in that pane, and `Deny` rules still bite. (Claude's own `bypassPermissions` is different: there agentperm defers entirely and lets Claude handle everything.) The toggle and indicator live in a small WASM plugin shipped at [`zellij-plugin/`](zellij-plugin/README.md).
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — domain model, AST parsing, aggregation, bypass coercion
+- [Policy reference](docs/policy-reference.md) — full grammar of `.agent-permissions.jsonc`
+- [CLI reference](docs/cli.md) — `install`, `import`, `check`, `edit`, pane bypass
+- [Adapter notes](docs/adapters.md) — agent-specific behavior and limits
+- [Troubleshooting](docs/troubleshooting.md) — diagnosing prompts, the trace env var, common pitfalls
+- [zellij plugin](zellij-plugin/README.md) — per-pane bypass toggle and indicator
+- [Contributing](CONTRIBUTING.md) — dev setup, tests, PR conventions
+- [Changelog](CHANGELOG.md)
+
+## What it doesn't do
+
+- **Manage MCP servers** — use Rulesync, native agent config, or your own dotfile tooling.
+- **Replace native permission settings** — those keep working as fast paths. The bridge layers on top.
+- **Sandbox commands** — the bridge is a policy engine, not an enforcement engine. Commands the agent decides to run still run with your shell's privileges.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agentperm-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentperm"
+version = "0.1.0"
+description = "Permission policy mediator for Claude Code, Codex, OpenCode, and Gemini CLI."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+authors = [{ name = "Jackson Cooper", email = "jackson@jacksonc.com" }]
+keywords = [
+    "ai",
+    "ai-agent",
+    "ai-agents",
+    "ai-tools",
+    "agent",
+    "agentic",
+    "agentic-ai",
+    "agentic-tools",
+    "ai-coding-assistant",
+    "anthropic",
+    "tree-sitter",
+    "tree-sitter-bash",
+    "claude",
+    "claude-code",
+    "codex",
+    "codex-cli",
+    "coding-agent",
+    "coding-assistant",
+    "developer-tools",
+    "gemini",
+    "gemini-cli",
+    "hooks",
+    "llm",
+    "llm-agent",
+    "llm-tools",
+    "mcp",
+    "mediator",
+    "opencode",
+    "openai",
+    "permissions",
+    "policy",
+    "policy-engine",
+    "shell",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Shells",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pyjson5>=2.0,<3",
+    "tomlkit>=0.13,<0.14",
+    "tree-sitter>=0.25,<0.26",
+    "tree-sitter-bash>=0.25,<0.26",
+]
+
+[project.urls]
+Homepage = "https://github.com/jacks0n/agentperm"
+Repository = "https://github.com/jacks0n/agentperm"
+Issues = "https://github.com/jacks0n/agentperm/issues"
+
+[project.scripts]
+agentperm = "agentperm:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "basedpyright>=1.13",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentperm"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]
+
+[tool.basedpyright]
+include = ["src", "tests"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+# tree-sitter-bash stubs are partial. We narrow at the parser boundary so domain
+# code never sees Unknown.
+reportMissingTypeStubs = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownArgumentType = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"