narai-primitives 2.1.3 → 2.3.0

package/plugins/gcp-connector/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "gcp-connector-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Runtime manifest for gcp-connector-plugin. The SessionStart hook runs `npm install` on this manifest into ${CLAUDE_PLUGIN_DATA}.",
+  "dependencies": {
+    "narai-primitives": "^2.1.3"
+  }
+}

package/plugins/gcp-connector/plugin-config.json

@@ -0,0 +1,4 @@
+{
+  "name": "gcp",
+  "binPath": "narai-primitives/dist/connectors/gcp"
+}

package/plugins/{gcp-agent/skills/gcp-agent → gcp-connector/skills/gcp-connector}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gcp-agent
+name: gcp-connector
 description: |
   Use when the user asks about read-only GCP inventory — Cloud Run services,
   Cloud SQL instances, Pub/Sub topics, or Cloud Logging entries. Queries are
@@ -7,16 +7,16 @@ description: |
 context: fork
 ---
 
-# GCP Agent
+# GCP Connector
 
-Answer the user's question by invoking the `gcp-agent` binary exposed by
+Answer the user's question by invoking the `gcp-connector` binary exposed by
 this plugin. It delegates to `narai-primitives/gcp`, which speaks to
 GCP by shelling out to `gcloud` / `bq` with Application Default Credentials.
 
 ## Invocation
 
 ```
-gcp-agent --action <action> --params '<json>'
+gcp-connector --action <action> --params '<json>'
 ```
 
 The CLI writes a single JSON envelope to stdout and exits 0 on success, 1
@@ -35,7 +35,7 @@ orchestrator.
 Example:
 
 ```bash
-gcp-agent --action list_services --params '{"project_id":"acme-prod-123"}'
+gcp-connector --action list_services --params '{"project_id":"acme-prod-123"}'
 ```
 
 ## Credentials

package/plugins/git-connector/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "git-connector-plugin",
+  "version": "1.0.0",
+  "description": "Pre-tool-use hook that gates risky git commands (push, force-push, branch deletion, reset --hard, etc.). No agents or actions — hooks only.",
+  "author": "narailabs"
+}

package/plugins/git-connector/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to `git-connector`
+
+This plugin is small. Contributions usually land in one of three places:
+
+1. **A new default rule** — see [Adding a default rule](#adding-a-default-rule).
+2. **A bug in an existing rule** — false positive, missed pattern, edge case in the splitter. See [Fixing a rule](#fixing-a-rule).
+3. **Hook contract drift** — Claude Code changes the PreToolUse payload shape or output expectations. See [Hook contract](#hook-contract).
+
+For changes elsewhere in the repo (other connectors, toolkit, hub), follow the root [`CONTRIBUTING.md`](../../CONTRIBUTING.md). Plugin-specific guidance below.
+
+## Local dev loop
+
+```sh
+# from the repo root
+npm install
+npx vitest run tests/plugins/git-connector/
+```
+
+The plugin wires its `PreToolUse` hook to the shared `plugin-hooks/dispatcher.mjs` in `narai-primitives`. To smoke-test the gate end-to-end against a fake stdin payload, point `CLAUDE_PLUGIN_ROOT` at the plugin and run the dispatcher directly:
+
+```sh
+echo '{"tool_name":"Bash","tool_input":{"command":"git push origin main"},"hook_event_name":"PreToolUse"}' \
+  | CLAUDE_PLUGIN_ROOT=plugins/git-connector \
+    CLAUDE_PLUGIN_DATA=/tmp/git-connector-data \
+    node plugin-hooks/dispatcher.mjs pre-tool-use
+```
+
+Should print `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny",...}}` to stdout. A non-git or unmatched command produces no output (the dispatcher's signal that it has no opinion).
+
+## Adding a default rule
+
+Default rules live in [`gates.json`](gates.json). Each rule has the shape:
+
+```json
+{
+  "name": "rule_name",
+  "decision": "deny",
+  "reason": "Sentence shown to the user in the prompt.",
+  "pattern": "^git\\s+<verb>\\b..."
+}
+```
+
+`pattern` is a JavaScript regex source. The dispatcher splits each compound command on `&&`, `||`, `;`, `|`, strips leading env-prefixes and `sudo`/`nice`/`time`, then tests each segment against every rule. The strictest matching decision wins (`deny` > `ask` > `allow`).
+
+### Steps
+
+1. Add the rule object to the `rules` array in [`gates.json`](gates.json). Keep `deny` rules at the top, `ask` rules below, ordered roughly by specificity — more specific rules first so their reason text wins ties.
+
+2. Add a `describe` block in [`tests/plugins/git-connector/gates.test.ts`](../../tests/plugins/git-connector/gates.test.ts) covering:
+   - **Positive cases**: each command form your rule is meant to catch (use `it.each`).
+   - **Negative cases**: adjacent-but-safe commands that must not fire. This is where most rule-design bugs hide. If you skip negative cases, your rule will produce false positives in the wild.
+   - **Precedence interaction**: if your rule's decision can be overruled by an existing `deny` rule, add a test that verifies the strictest-wins resolution.
+
+3. Add an end-to-end case in [`tests/plugins/git-connector/smoke.test.ts`](../../tests/plugins/git-connector/smoke.test.ts) if the rule covers a category not already exercised.
+
+4. Document the rule in [`README.md`](README.md) under "Default rules". Match the existing table style.
+
+5. If the rule has known false-positive scenarios, document them under "Limitations" in `README.md` and mention that operators can disable via `NARAI_GATE_DISABLE=<rule_name>`.
+
+### Style guidance
+
+- **Keep the regex anchored.** All default rules anchor on `^git\s+<verb>` so a string like `echo "git push"` doesn't trigger them. The dispatcher strips env-prefixes (`FOO=bar`) and `sudo`/`nice`/`time` before rules see the segment.
+- **Avoid lookbehinds and back-references** unless you have a clear reason. They make the rule harder to read and slower; this code runs on every Bash call.
+- **Bias toward over-flagging.** A safe command flagged for confirmation is annoying; a dangerous command that slipped through is the failure mode this plugin exists to prevent.
+- **Don't push behaviour into the dispatcher.** Rules are pure regex; if you need git state (current branch, remote URL), that's a real proposal — open an issue first to discuss the added I/O cost on every Bash call.
+
+## Fixing a rule
+
+If you're chasing a false positive or missed pattern:
+
+1. Reproduce in a test first — add the failing case to `gates.test.ts` so the regression is captured. The fix should make the new case pass without breaking the existing tests.
+2. Prefer narrowing the regex over deleting the rule. If the rule is genuinely unsalvageable, delete it cleanly (rule object in `gates.json`, tests, README row, any `NARAI_GATE_DISABLE` guidance) in a single commit.
+3. If the false positive is rare and the rule is otherwise valuable, document it under "Limitations" rather than weakening the rule.
+
+## Hook contract
+
+The dispatcher reads stdin and writes stdout per the [Claude Code hook
+contract](https://code.claude.com/docs/en/hooks.md). The current shape
+the dispatcher relies on:
+
+- **Input**: `{tool_name: "Bash", tool_input: {command: string}, ...}`
+- **Output**: `{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow"|"deny"|"ask", permissionDecisionReason: string}}`
+- **Exit code**: `0` for any decision (the JSON is the signal). Non-zero is reserved for genuine dispatcher errors (missing `CLAUDE_PLUGIN_ROOT`, missing `plugin-config.json`, etc.).
+
+If Claude Code changes the contract:
+
+1. Update [`plugin-hooks/dispatcher.mjs`](../../plugin-hooks/dispatcher.mjs) and the README's "How it works" section.
+2. Bump `version` in `.claude-plugin/plugin.json` and `package.json`.
+3. Test against the new Claude Code version with the smoke-test command above before merging.
+
+The dispatcher is shared across every plugin in this repo — contract changes affect them all and need broader review.
+
+## Code conventions
+
+- **`gates.json` is the only file most rule changes touch.** Pure JSON, no JS. Keep formatting consistent with the existing entries.
+- **Runtime deps come via `package.json`.** The plugin declares `narai-primitives` as a dep so the SessionStart hook can `npm install` it into `CLAUDE_PLUGIN_DATA` before the dispatcher runs. Don't add other runtime deps without a strong reason.
+- **2-space indent.** Tests are TypeScript because Vitest's include glob is `**/*.test.ts`.
+- **No emojis** in source or docs (matches repo style).
+
+## Commit + PR hygiene
+
+- Commit messages follow conventional-commits style: `feat(git-connector): ...`, `fix(git-connector): ...`, `docs(git-connector): ...`, `test(git-connector): ...`.
+- One logical change per commit. If a rule fix needs a test update and a README update, those go in the same commit.
+- Run `npx vitest run tests/plugins/git-connector/` before pushing. The full repo suite (`npx vitest run`) should also pass — the plugin shares the dispatcher with every connector, so dispatcher-touching changes need the broader suite green.
+- Open the PR against `main`. The plugin lives outside the connector PR stack and ships independently.
+
+## Out of scope
+
+This plugin deliberately does NOT:
+
+- **Block the command.** The strictest decision is `deny`, which makes Claude refuse and surfaces the reason — but the user can still run the command themselves outside the session. See [SECURITY.md](SECURITY.md) for the full list of bypass paths and why they are intentional.
+- **Track git state.** No `git rev-parse`, no remote URL inspection, no branch detection. Rules operate on the literal command string. If you want behaviour gated on current branch (e.g., "deny rebase only when on main"), that's a real proposal — open an issue first to discuss whether the added I/O cost on every Bash call is worth it.
+- **Replace branch protection.** Server-side branch protection rules on the remote are the actual enforcement layer. This plugin reduces blast radius from agentic flows; it does not gate the remote.
+
+## License
+
+MIT — see `LICENSE` at the repo root.

package/plugins/git-connector/README.md

@@ -0,0 +1,94 @@
+# git-connector
+
+Claude Code plugin that gates risky `git` commands at the `PreToolUse` hook.
+No agents, no actions — pure permission gating.
+
+## Default rules
+
+| Rule | Decision | When it fires |
+|---|---|---|
+| `push_main` | **deny** | `git push` whose refspec targets `main` or `master` |
+| `force_push` | **ask** | `git push --force` / `-f` / `--force-with-lease` |
+| `delete_branch_remote` | **ask** | `git push --delete`, `git push -d`, or `git push <remote> :branch` |
+| `push` | **ask** | Any other `git push` |
+| `delete_branch_local` | **ask** | `git branch -D`, `git branch --delete --force` |
+| `reset_hard` | **ask** | `git reset --hard` |
+| `checkout_discard` | **ask** | `git checkout <pathspec>` / `git restore --worktree` / `git checkout .` |
+| `clean_force` | **ask** | `git clean -f…` (any `-f` variant, including `-fdx`) |
+
+Decision precedence: `deny` > `ask` > `allow`. If multiple rules match across
+a compound command (`a && b`), the strictest wins.
+
+If no rule matches, the hook emits no decision and Claude Code's default
+permission flow continues.
+
+## Disabling rules
+
+Set `NARAI_GATE_DISABLE` to a comma-separated list of rule names:
+
+```sh
+export NARAI_GATE_DISABLE=push,push_main
+```
+
+…disables both the plain-`push` ask and the protected-branch deny.
+
+## Adding rules
+
+Drop extra rules at `~/.connectors/connectors/<slug>/gates.json` — the
+shared dispatcher scans this path and layers the rules on top of the
+defaults shipped with this plugin:
+
+```json
+{
+  "rules": [
+    {
+      "name": "deny_release",
+      "decision": "deny",
+      "reason": "Pushing to release branches needs SRE approval.",
+      "pattern": "^git\\s+push\\s+\\S+\\s+release\\b"
+    },
+    {
+      "name": "ask_worktree_remove",
+      "decision": "ask",
+      "reason": "Removing a worktree is irreversible.",
+      "pattern": "^git\\s+worktree\\s+remove\\b"
+    }
+  ]
+}
+```
+
+`pattern` is a JavaScript regex source applied to each command segment
+(after splitting on `&&`, `||`, `;`, `|`). `decision` must be one of
+`allow`, `ask`, `deny`. `reason` is shown to the user in the prompt.
+
+Custom rules are evaluated alongside the defaults; the strictest match
+across all rules wins.
+
+## How it works
+
+`PreToolUse` hooks fire before any Bash invocation. The plugin wires
+this event to the shared `plugin-hooks/dispatcher.mjs` from
+`narai-primitives`, which loads this plugin's `gates.json` (the default
+rules), applies them to `tool_input.command`, and writes a JSON decision
+to stdout per the [hook contract](https://code.claude.com/docs/en/hooks.md).
+
+Compound commands (`cd repo && git push origin main`) split on `&&`, `||`,
+`;`, `|` and each segment is classified independently — the strictest
+decision wins. Leading env-var assignments (`FOO=bar git push`) and
+common prefixes (`sudo`, `nice`, `time`) are stripped before matching.
+
+## Limitations
+
+- The command splitter doesn't track quoted strings — a literal `&&`
+  inside single quotes will split the segment. Over-splitting is the
+  intended bias for a safety gate.
+- `push_main` matches any `main` or `master` token in the push args.
+  A branch literally named `feature/main` would trip this. Disable
+  `push_main` via `NARAI_GATE_DISABLE=push_main` if your repo has such names.
+- The hook runs on every Bash call. Performance is dominated by Node
+  startup (~30ms cold). The hook itself is O(rules × segments) regex
+  matching — negligible.
+
+## License
+
+MIT

package/plugins/git-connector/SECURITY.md

@@ -0,0 +1,143 @@
+# Security policy
+
+## What this plugin is
+
+A `PreToolUse` hook that classifies `git` invocations made through Claude
+Code's `Bash` tool and emits permission decisions (`allow` / `ask` /
+`deny`). It runs inside the user's Claude Code session, on the user's
+machine, with the user's privileges.
+
+## What this plugin is NOT
+
+**This plugin is not a security boundary.** It is a *speed bump* against
+accidental destructive commands — the same role as a shell alias that
+re-prompts on `rm -rf`. Treat it as a usability guardrail, not access
+control.
+
+A user (or anyone with write access to the user's environment) can defeat
+the plugin trivially by:
+
+- Running git outside Claude Code (a regular terminal, an IDE git panel, a
+  CI runner, etc.). The hook only fires for commands routed through
+  Claude Code's `Bash` tool.
+- Disabling the plugin in Claude Code (`/plugin disable git-connector`) or
+  removing the marketplace entry.
+- Toggling permission mode to `bypassPermissions` — that mode skips the
+  hook entirely.
+- Accepting the `ask` prompt at the moment it appears.
+- Setting `NARAI_GATE_DISABLE` to silence rules by name, or dropping
+  a custom `~/.connectors/connectors/<slug>/gates.json` (the dispatcher
+  trusts both unconditionally — see "Config file trust" below).
+- Writing a bash command that evades pattern matching (see
+  "Pattern-matching limits" below).
+
+If your threat model includes a malicious or curious user who has shell
+access on the same machine, this plugin does not help. Use repository
+permissions, branch protection rules on the remote, and CI policy
+checks instead — those run on infrastructure outside the user's control.
+
+## What it does help with
+
+- Stopping a model (or a sleepy human reviewing model output) from
+  running `git push origin main` without confirmation.
+- Catching `git reset --hard` and `git clean -fdx` before they execute.
+- Surfacing a confirmation prompt with operator-supplied reason text so
+  the user understands the consequences before approving.
+- Reducing blast radius from agentic flows that compose multiple git
+  commands in one Bash invocation — each compound segment is classified
+  independently.
+
+## Pattern-matching limits
+
+The classifier in [`gates.json`](gates.json) works on the literal command string.
+Several constructs can evade matching:
+
+- **Quoted operators**: a literal `&&` inside single quotes splits the
+  command for the segmenter. Over-splitting is the intended bias —
+  every sub-segment still gets classified — but the segments themselves
+  are not properly tokenised, so a quoted git argument can defeat
+  pattern anchors. Example: `eval 'git push --force'` is classified by
+  matching on `git push --force` (the quoted body), but `eval "$(echo
+  git push)"` is not.
+- **Indirection**: `bash -c "$cmd"` where `$cmd` expands to a git
+  command. The hook sees the outer `bash -c "..."`, not the inner
+  expansion, and will not match.
+- **Aliases / functions**: a shell alias `gpf=git push --force` invoked
+  as `gpf` does not match because the hook never sees the resolved
+  command.
+- **Custom branch names**: the `push_main` rule matches any
+  `\bmain\b` or `\bmaster\b` token in the push args. A literal branch
+  named `feature/main` will trip the rule. Disable via
+  `NARAI_GATE_DISABLE=push_main` if your repo uses such names.
+
+If you need defense-in-depth against these, add **server-side branch
+protection** on the remote and require status checks before merge. The
+plugin handles the local-side speed bump; the server enforces the rule.
+
+## Config file trust
+
+The dispatcher reads any `~/.connectors/connectors/<slug>/gates.json`
+files if present (and the same under the current working directory).
+Those files are trusted unconditionally — if an attacker can write to
+that path, they can:
+
+- Add a custom rule with `decision: "allow"` to short-circuit a default
+  `ask` (note: `allow` cannot beat a `deny` due to precedence, but it
+  can beat an `ask`).
+- Layer a rule with the same regex as a default but a softer decision,
+  effectively muffling the prompt with a less alarming reason.
+
+Mitigations:
+
+- Keep the parent directory (`~/.connectors/`) writable only by the
+  owner (`chmod 700`).
+- Treat write access to `~/.connectors/` as equivalent to shell access.
+  If your threat model includes someone who can modify files in `$HOME`
+  but not run git directly, the gate surface is one of many they could
+  weaponise.
+
+## Hook contract assumptions
+
+The plugin assumes Claude Code honours the documented hook contract
+(reads `tool_input.command` for `Bash` calls, respects
+`hookSpecificOutput.permissionDecision` of `"deny"`, etc.). If a future
+version of Claude Code changes the contract, the plugin may silently
+stop gating. Track the [hooks
+documentation](https://code.claude.com/docs/en/hooks.md) and verify
+behavior after Claude Code upgrades.
+
+The hook script itself is the shared `plugin-hooks/dispatcher.mjs` from
+`narai-primitives`. It reads only the stdin payload + on-disk gate
+manifests (`CLAUDE_PLUGIN_ROOT/gates.json`, `~/.connectors/connectors/*/gates.json`, and the same under cwd). It does not invoke `git`, write
+files in the gate path, or make network requests.
+
+## Reporting a vulnerability
+
+If you find a way for a `deny`-classified command to slip through the
+hook in default configuration (no env vars, no config file), please
+open an issue at
+<https://github.com/narailabs/narai-primitives/issues> with:
+
+- The command string the hook should have caught
+- The actual decision the hook produced (or null if none)
+- The Claude Code version and operating system
+
+Behaviour we consider intentional, not vulnerabilities:
+
+- Bypass via permission-mode toggling (`bypassPermissions`).
+- Bypass via env var or config file overrides.
+- Bypass via shell indirection (`bash -c`, `eval`, aliases) — see
+  "Pattern-matching limits".
+- False positives where a safe command matches a default rule (those
+  are usability bugs; please file them, but they are not security
+  issues).
+
+## Supported versions
+
+Only the latest published version of `git-connector` receives security
+fixes. Older versions are not maintained. Pin to a specific version
+only if you have a tested compatibility constraint.
+
+## License
+
+MIT — see `LICENSE` at the repo root.

package/plugins/git-connector/gates.json

@@ -0,0 +1,67 @@
+{
+  "version": 1,
+  "name": "git",
+  "enforcement": "fail_closed",
+  "rules": [
+    {
+      "name": "push_main",
+      "decision": "deny",
+      "reason": "Pushing to a protected branch is denied by policy. Open a PR instead.",
+      "pattern": "^git\\s+push\\b.*\\b__PROTECTED_BRANCHES__\\b"
+    },
+    {
+      "name": "force_push",
+      "decision": "deny",
+      "reason": "Force push rewrites remote history and is denied. Use --force-with-lease if a force is truly required.",
+      "pattern": "^git\\s+push\\b.*\\s(--force(?!-with-lease)\\b|-f\\b)"
+    },
+    {
+      "name": "force_with_lease",
+      "decision": "ask",
+      "reason": "Lease-guarded force push rewrites remote history. Confirm before proceeding.",
+      "pattern": "^git\\s+push\\b.*\\s--force-with-lease\\b"
+    },
+    {
+      "name": "mirror_push",
+      "decision": "deny",
+      "reason": "git push --mirror overwrites all remote refs and is denied.",
+      "pattern": "^git\\s+push\\b.*\\s--mirror\\b"
+    },
+    {
+      "name": "delete_branch_remote",
+      "decision": "ask",
+      "reason": "Deleting a remote branch is irreversible. Confirm.",
+      "pattern": "^git\\s+push\\b.*(\\s(--delete\\b|-d\\b)|\\s\\S+\\s+:[\\w./-]+)"
+    },
+    {
+      "name": "push",
+      "decision": "ask",
+      "reason": "Pushing publishes commits. Confirm before proceeding.",
+      "pattern": "^git\\s+push(\\s|$)"
+    },
+    {
+      "name": "delete_branch_local",
+      "decision": "ask",
+      "reason": "Force-deleting a local branch can lose unmerged commits.",
+      "pattern": "^git\\s+branch\\s+(?:.*\\s)?(-D\\b|--delete\\s+--force\\b|-Df\\b|-fD\\b)"
+    },
+    {
+      "name": "reset_hard",
+      "decision": "ask",
+      "reason": "git reset --hard discards working-tree and index changes.",
+      "pattern": "^git\\s+reset\\s+(?:.*\\s)?--hard\\b"
+    },
+    {
+      "name": "checkout_discard",
+      "decision": "ask",
+      "reason": "This checkout/restore discards working-tree changes.",
+      "pattern": "^git\\s+checkout\\s+(?:--\\s+|\\.|[^\\s-]\\S*\\.\\S*)|^git\\s+checkout\\s+\\S+\\s+--\\s+\\S|^git\\s+restore\\s+(?:.*\\s)?(--worktree\\b|-W\\b)|^git\\s+restore\\s+\\.$"
+    },
+    {
+      "name": "clean_force",
+      "decision": "ask",
+      "reason": "git clean -f removes untracked files (and -fdx removes ignored too).",
+      "pattern": "^git\\s+clean\\s+(?:.*\\s)?-[a-zA-Z]*f"
+    }
+  ]
+}

package/plugins/git-connector/hooks/hooks.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (mkdir -p \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/\" && cd \"${CLAUDE_PLUGIN_DATA}\" && npm install --no-audit --no-fund) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/git-connector/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "git-connector-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Runtime manifest for git-connector. SessionStart copies this manifest and runs npm install to fetch the shared dispatcher.",
+  "dependencies": {
+    "narai-primitives": "^2.1.3"
+  }
+}

package/plugins/git-connector/plugin-config.json

@@ -0,0 +1,4 @@
+{
+  "name": "git",
+  "kind": "hook-only"
+}

package/plugins/{github-agent → github-connector}/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "name": "github-agent-plugin",
+  "name": "github-connector-plugin",
   "version": "1.1.0",
   "description": "Read-only GitHub connector for Claude Code. Built on narai-primitives (subpath ./github).",
   "author": "narai"

package/plugins/github-connector/README.md

@@ -0,0 +1,48 @@
+# github-connector plugin
+
+Read and write GitHub data — repository info, code search, issues,
+pull requests, comments, releases, and Actions workflows — through the
+narai-primitives connector toolkit's policy gate.
+
+## Credentials
+
+Set `GITHUB_TOKEN` to a PAT.
+
+| Scope | Why |
+|---|---|
+| `repo` | Read + write on issues, PRs, comments, releases, file contents |
+| `workflow` | Required for Actions writes (`rerun_*`, `cancel_workflow_run`, `trigger_workflow_dispatch`) |
+
+Tokens without `workflow` will see `AUTH_ERROR` with a scope hint
+when invoking Actions-write endpoints.
+
+## Config
+
+Place YAML at `~/.github-agent/config.yaml` (user-level) or
+`<cwd>/.github-agent/config.yaml` (repo overlay). Repo overlay wins on
+collisions.
+
+```yaml
+policy:
+  read: success
+  write: escalate
+  admin: escalate              # enables merge_pull_request
+  aspects:
+    delete: escalate            # cannot be set to success — floored
+approval_mode: confirm_once
+github:
+  require_draft_pr: true       # forces every create_pull_request to draft=true
+```
+
+Runtime override: `GITHUB_REQUIRE_DRAFT_PR=1` forces drafts even when
+the YAML says false; `GITHUB_REQUIRE_DRAFT_PR=0` forces non-drafts.
+Invalid values throw at startup.
+
+## Action surface
+
+36 actions across reads (15), writes (20), and admin (1). See
+`skills/github-connector/SKILL.md` for the full table.
+
+## License
+
+See repo root.

package/plugins/{confluence-agent/bin/confluence-agent → github-connector/bin/github-connector}

@@ -2,14 +2,14 @@
 set -euo pipefail
 
 if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
-  echo "confluence-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  echo "github-connector: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
   exit 2
 fi
 
-CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/confluence/cli.js"
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/github/cli.js"
 
 if [ ! -f "$CLI" ]; then
-  echo "confluence-agent: connector CLI not found at $CLI" >&2
+  echo "github-connector: connector CLI not found at $CLI" >&2
   echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
   exit 2
 fi

package/plugins/github-connector/commands/github-connector.md

@@ -0,0 +1,6 @@
+---
+description: Run a GitHub action via the github-connector connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `github-connector` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/github-connector/hooks/hooks.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (mkdir -p \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/\" && cd \"${CLAUDE_PLUGIN_DATA}\" && npm install --no-audit --no-fund) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-start"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
+          }
+        ]
+      }
+    ]
+  }
+}