narai-primitives 2.1.3 → 2.2.0

package/plugins/connector-creator/skills/connector-creator/lib/connector-registry.mjs

@@ -0,0 +1,43 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+
+/**
+ * Register a connector under <scope>/.connectors/config.yaml.
+ *
+ * Creates the file with `connectors: {}` if missing. Idempotent: re-running
+ * with the same slug overwrites that slug's block but does not duplicate.
+ */
+export function registerConnector(scope, slug, entry) {
+  const file = path.join(scope, ".connectors", "config.yaml");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  let parsed = { connectors: {} };
+  if (fs.existsSync(file)) {
+    let raw;
+    try {
+      raw = fs.readFileSync(file, "utf-8");
+      parsed = yaml.load(raw) ?? {};
+    } catch (err) {
+      // Fail closed: a malformed config.yaml (often from in-progress
+      // user edits) must not silently overwrite existing entries. Throw
+      // so the caller can surface the parse error and let the user fix
+      // their YAML before we mutate anything.
+      throw new Error(
+        `registerConnector: refusing to overwrite '${file}' — parse failed (${
+          err instanceof Error ? err.message : String(err)
+        })`,
+      );
+    }
+    if (!parsed.connectors || typeof parsed.connectors !== "object") {
+      parsed.connectors = {};
+    }
+  }
+
+  parsed.connectors[slug] = {
+    ...entry,
+    enabled: true,
+  };
+
+  fs.writeFileSync(file, yaml.dump(parsed, { lineWidth: 120 }));
+}

package/plugins/connector-creator/skills/connector-creator/lib/settings-wiring.mjs

@@ -0,0 +1,71 @@
+/**
+ * settings-wiring.mjs — idempotent management of Claude Code's settings.json
+ * to register the connector-gate.mjs PreToolUse hook.
+ *
+ * Two functions:
+ *   - ensureSettingsHook(settingsPath, gatePath)
+ *   - hasConnectorGateHook(settingsPath, gatePath)
+ *
+ * Backs up the file with a timestamped suffix before any write.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function ensureSettingsHook(settingsPath, gatePath) {
+  const dir = path.dirname(settingsPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  let parsed = {};
+  if (fs.existsSync(settingsPath)) {
+    backup(settingsPath);
+    parsed = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  }
+
+  if (!parsed.hooks) parsed.hooks = {};
+  if (!parsed.hooks.PreToolUse) parsed.hooks.PreToolUse = [];
+
+  // Find an existing Bash matcher block; create one if missing.
+  let block = parsed.hooks.PreToolUse.find((b) => b.matcher === "Bash");
+  if (!block) {
+    block = { matcher: "Bash", hooks: [] };
+    parsed.hooks.PreToolUse.push(block);
+  }
+  if (!Array.isArray(block.hooks)) block.hooks = [];
+
+  const entry = { type: "command", command: `node "${gatePath}"` };
+  const exists = block.hooks.some(
+    (h) =>
+      h.type === "command" &&
+      typeof h.command === "string" &&
+      h.command.includes(gatePath),
+  );
+  if (!exists) block.hooks.push(entry);
+
+  fs.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n");
+}
+
+export function hasConnectorGateHook(settingsPath, gatePath) {
+  if (!fs.existsSync(settingsPath)) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    return false;
+  }
+  const blocks = parsed.hooks?.PreToolUse ?? [];
+  return blocks.some(
+    (b) =>
+      Array.isArray(b.hooks) &&
+      b.hooks.some(
+        (h) =>
+          h.type === "command" &&
+          typeof h.command === "string" &&
+          h.command.includes(gatePath),
+      ),
+  );
+}
+
+function backup(filePath) {
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  fs.copyFileSync(filePath, `${filePath}.bak-${ts}`);
+}

package/plugins/connector-creator/skills/connector-creator/references/connector-contract.md

@@ -0,0 +1,79 @@
+# Connector contract
+
+A connector is a directory at `<scope>/.connectors/connectors/<slug>/` that
+satisfies a thin contract. The runtime treats unknown files as opaque, so
+flavors can extend the layout without changing the contract.
+
+## Required
+
+- `SKILL.md` — model-facing description (frontmatter `name`, `description`,
+  `context: connector`). The skill describes when to invoke this connector
+  and what params it accepts.
+- Entry in `<scope>/.connectors/config.yaml` under `connectors:`:
+  ```yaml
+  connectors:
+    <slug>:
+      skill: <abs-path-to-connector-dir>
+      bin:   <abs-path-to-bin-or-null>
+      enabled: true
+  ```
+
+## Optional (any combination)
+
+- `index.mjs` — programmatic actions, built with `createConnector` from
+  `narai-primitives/toolkit`. Gives you the toolkit's policy gate,
+  classification, audit, and hardship logging for free. Invoked via
+  `gather()` or directly via the bin shim.
+- `gates.json` — declarative shell-command gates fired at PreToolUse:
+  ```json
+  {
+    "rules": [
+      { "name": "deny_x", "decision": "deny|ask|allow",
+        "reason": "...", "pattern": "<regex>" }
+    ]
+  }
+  ```
+  The runtime applies each rule's regex to the bash command (split on
+  `&&`/`||`/`;`/`|`); strictest decision wins (`deny` > `ask` > `allow`).
+- `bin/<slug>` — CLI shim that execs `index.mjs`. Required if `index.mjs`
+  is present.
+- (nothing) — knowledge-only connector. Just SKILL.md + config.yaml entry.
+
+## How the runtime finds connectors
+
+Two firing points:
+
+1. **Standalone runtime** — `connector-gate.mjs` at `<scope>/.connectors/`,
+   wired into `<scope>/.claude/settings.json` as a `PreToolUse` hook. Reads
+   `<scope>/.connectors/connectors/*/gates.json` and applies decisions.
+2. **Builtin Claude Code plugin** — when any narai builtin plugin is
+   installed (jira-agent, aws-agent, etc.), its dispatcher *also* discovers
+   user connectors at the same path and applies their gates. Defense in
+   depth.
+
+If both fire, `deny` precedence ensures consistency.
+
+## File-tree example
+
+```
+<scope>/
+├── .claude/
+│   └── settings.json              # PreToolUse hook → connector-gate.mjs
+└── .connectors/
+    ├── config.yaml                # connector registry
+    ├── connector-gate.mjs         # standalone runtime (stamped on first /create-connector)
+    └── connectors/
+        ├── stripe/                # API/SDK wrapper
+        │   ├── SKILL.md
+        │   ├── index.mjs
+        │   └── bin/stripe
+        ├── deploy-prod/           # shell-gate
+        │   ├── SKILL.md
+        │   └── gates.json
+        ├── linear-summary/        # composite orchestrator
+        │   ├── SKILL.md
+        │   ├── index.mjs
+        │   └── bin/linear-summary
+        └── runbook-ssh/           # knowledge-only
+            └── SKILL.md
+```

package/plugins/connector-creator/skills/connector-creator/references/flavor-authoring.md

@@ -0,0 +1,58 @@
+# Authoring a new flavor
+
+The create-connector skill recognizes 5 flavors today (api-wrapper,
+shell-gate, composite, knowledge, custom). Adding a 6th is additive —
+the runtime is contract-driven and does not need to know about the
+flavor.
+
+## What a flavor is
+
+A flavor is:
+- A trigger phrasing the skill listens for in the user's freeform
+  description.
+- A checklist of shape-specific questions the skill asks once the
+  flavor is identified.
+- A template directory at
+  `plugins/connector-creator/skills/connector-creator/assets/templates/<flavor>/`
+  containing the `.tmpl` files to stamp.
+
+## Adding a flavor
+
+1. Create the template directory: `assets/templates/<flavor>/`.
+2. Add `.tmpl` files for each artifact the flavor produces. Use double-
+   curly placeholders (`{{SLUG}}`, `{{DESCRIPTION}}`, `{{ServicePascal}}`,
+   etc.). Reuse existing placeholder names where the meaning is the same.
+3. Add a flavor section in `SKILL.md` with:
+   - Trigger phrasings (1-3 examples)
+   - Shape-specific questions checklist
+   - Which templates get stamped
+4. Add tests in `tests/plugins/connector-creator/templates.test.ts`
+   asserting the new template files exist with the expected placeholders.
+
+## Placeholder conventions
+
+| Placeholder | Substituted with |
+|---|---|
+| `{{SLUG}}` | lowercase, alphanumeric+hyphen connector slug |
+| `{{ServicePascal}}` | PascalCase form of slug for display |
+| `{{DESCRIPTION}}` | one-sentence connector description |
+| `{{DESCRIPTION_SHORT}}` | brief noun phrase for inline use |
+| `{{ACTIONS_TABLE_MD}}` | markdown table of action names + descriptions |
+| `{{ACTIONS_DICTIONARY}}` | JS object literal of action handlers (composite) |
+| `{{RULES}}` | JSON array of rule objects (shell-gate) |
+| `{{RULES_TABLE}}` | markdown table of pattern/decision/reason (shell-gate) |
+| `{{DEPENDENCIES}}` | comma-separated list of upstream connectors (composite) |
+| `{{DEPENDENCIES_TABLE}}` | markdown table of dependencies (composite) |
+| `{{FIRST_ACTION}}` | name of the first action, used in invocation example |
+| `{{USE_CASES}}` | bullet list of when to use this connector (knowledge) |
+| `{{STEPS}}` | numbered list of runbook steps (knowledge) |
+| `{{CAVEATS}}` | bullet list of warnings (knowledge) |
+
+When adding a new placeholder, document it here.
+
+## Custom flavor
+
+For shapes that don't fit a flavor, the skill falls back to pure code-gen.
+The skill writes whatever `index.mjs` / `gates.json` / `SKILL.md` makes
+sense for the user's description, anchored on the connector contract
+(see `connector-contract.md`). No template directory.

package/plugins/connector-creator/skills/connector-creator/references/research-patterns.md

@@ -0,0 +1,51 @@
+# Research patterns for create-connector
+
+The skill is open-ended: the user describes their need in their own
+words, and the skill identifies the right connector shape. For
+unfamiliar services, the skill researches before asking
+shape-specific questions.
+
+## When to research
+
+| User cue | Tool to use |
+|---|---|
+| Names a SaaS the skill doesn't recognize | `WebFetch` on `<service>.com/docs/api` (or whatever doc URL the user mentions) |
+| Mentions a Node/Python library | `context7` for current docs |
+| Says "like the jira-agent / aws-agent / etc." | Read the corresponding `src/connectors/<x>/index.ts` for structural reference |
+| Vague service description, no URL | `WebSearch` to find the official docs URL, then `WebFetch` |
+
+## What research informs
+
+Research findings inform the *questions* the skill asks. The skill
+never decides architectural shape unilaterally based on research — the
+user always chooses.
+
+Examples:
+
+- **API wrapper detected** → confirm auth scheme (bearer / api-key /
+  basic / oauth), confirm rate limits, ask which actions to expose.
+- **Webhook-only service** → push back on user, suggest knowledge-only
+  flavor instead since the model can't initiate calls.
+- **GraphQL only** → confirm with user, then generate `index.mjs` with
+  a thin GraphQL client (no `createConnector`-style typed actions).
+
+## Anti-patterns
+
+Don't:
+- Spend 5+ tool calls researching before asking the user. Surface what
+  you found in 1-2 fetches and ask the user.
+- Pretend to know an API you don't. If the docs are inaccessible, tell
+  the user and let them describe the API.
+- Auto-classify actions without asking. The user's name for an action
+  may not follow the `get_*`/`create_*` convention; confirm intent.
+
+## Reference connectors
+
+For "build me a connector like X", these are the canonical references:
+
+- **REST + bearer auth** → `src/connectors/jira/`
+- **REST + multi-secret auth** → `src/connectors/github/`
+- **GraphQL** → `src/connectors/linear/` (if PR #17 has merged)
+- **Stub pattern (auth pending)** → use the `oauth-with-refresh`
+  template from `references/auth-patterns.md`
+- **Hook-only / shell-gate** → `plugins/git-connector/hooks/rules.mjs`

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

@@ -1,18 +1,18 @@
 {
-  "name": "db-agent-plugin",
+  "name": "db-connector-plugin",
   "version": "1.1.0",
   "description": "Safe, read-only database query agent for Claude Code. Built on narai-primitives (subpath ./db). Every statement passes the policy gate before any driver loads or any connection is opened.",
   "author": {
     "name": "Narai Labs",
     "url": "https://github.com/narailabs"
   },
-  "homepage": "https://github.com/narailabs/narai-primitives/tree/main/plugins/db-agent",
+  "homepage": "https://github.com/narailabs/narai-primitives/tree/main/plugins/db-connector",
   "repository": "https://github.com/narailabs/narai-primitives",
   "license": "MIT",
   "keywords": ["database", "sql", "postgresql", "mysql", "sqlite", "policy-gate"],
   "userConfig": {
     "install_guardrails": {
-      "description": "Block direct DB-client invocations (psql, mysql, sqlite3, mongosh, pg_dump, aws dynamodb, ...) from Bash so all database access is routed through the db-agent CLI. Strongly recommended. Set to 'off' to disable.",
+      "description": "Block direct DB-client invocations (psql, mysql, sqlite3, mongosh, pg_dump, aws dynamodb, ...) from Bash so all database access is routed through the db-connector CLI. Strongly recommended. Set to 'off' to disable.",
       "sensitive": false
     }
   },

package/plugins/{db-agent → db-connector}/README.md

@@ -1,8 +1,8 @@
-# db-agent-plugin
+# db-connector-plugin
 
 Claude Code plugin that wraps [`narai-primitives/db`](https://www.npmjs.com/package/narai-primitives).
 
-Exposes the `db-agent` skill. Every query passes through the policy gate before any driver loads or any connection opens. V2.0 vocab and defaults:
+Exposes the `db-connector` skill. Every query passes through the policy gate before any driver loads or any connection opens. V2.0 vocab and defaults:
 
 - `read` (SELECT/EXPLAIN/SHOW/DESCRIBE/WITH) → executed through the driver with row/timeout caps
 - `write` (INSERT/UPDATE/REPLACE/MERGE/UPSERT) → escalates by default

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

@@ -2,14 +2,14 @@
 set -euo pipefail
 
 if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
-  echo "github-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  echo "db-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/github/cli.js"
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/db/cli.js"
 
 if [ ! -f "$CLI" ]; then
-  echo "github-agent: connector CLI not found at $CLI" >&2
+  echo "db-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/db-connector/commands/db-connector.md

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

package/plugins/db-connector/gates.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "name": "db-strict",
+  "enforcement": "fail_closed",
+  "rules": [
+    {
+      "name": "python_db_driver_import",
+      "decision": "deny",
+      "reason": "Importing a database driver in-process bypasses the connector. Route DB access through the sanctioned connector instead.",
+      "pattern": "[iI][mM][pP][oO][rR][tT]\\s+(psycopg2|psycopg|pymysql|MySQLdb|sqlite3|pymongo|pyodbc|asyncpg|sqlalchemy)\\b|[fF][rR][oO][mM]\\s+(psycopg2|psycopg|pymysql|MySQLdb|sqlite3|pymongo|pyodbc|asyncpg|sqlalchemy)\\s+[iI][mM][pP][oO][rR][tT]\\b"
+    },
+    {
+      "name": "node_db_driver_require",
+      "decision": "deny",
+      "reason": "Requiring a database driver in-process bypasses the connector. Route DB access through the sanctioned connector instead.",
+      "pattern": "[rR][eE][qQ][uU][iI][rR][eE]\\s*\\(\\s*['\"\\\\]+(pg|mysql2|mysql|mongodb|mssql|tedious|better-sqlite3|sqlite3|oracledb)['\"\\\\]+\\s*\\)"
+    },
+    {
+      "name": "jdbc_url",
+      "decision": "deny",
+      "reason": "A JDBC connection URL bypasses the connector. Route DB access through the sanctioned connector instead.",
+      "pattern": "[jJ][dD][bB][cC]:(postgresql|mysql|mariadb|sqlserver|oracle|sqlite|mongodb)://"
+    },
+    {
+      "name": "node_db_client_construct",
+      "decision": "deny",
+      "reason": "Constructing a database client in-process bypasses the connector. Route DB access through the sanctioned connector instead.",
+      "pattern": "[nN][eE][wW]\\s+(Pool|Client)\\s*\\([^)]*\\b(host|port|database|connectionString|user|password)\\b"
+    },
+    {
+      "name": "raw_dml_exec",
+      "decision": "deny",
+      "reason": "Executing raw DML/DDL inline bypasses the connector. Route DB access through the sanctioned connector instead.",
+      "pattern": "(-c\\b|-e\\b|--eval\\b|--command\\b|--query\\b|python3?|node|deno|ruby|perl|php)\\b.*([iI][nN][sS][eE][rR][tT]\\s+[iI][nN][tT][oO]|[uU][pP][dD][aA][tT][eE]\\s+.+\\s+[sS][eE][tT]\\b|[dD][eE][lL][eE][tT][eE]\\s+[fF][rR][oO][mM]|[dD][rR][oO][pP]\\s+[tT][aA][bB][lL][eE]|[tT][rR][uU][nN][cC][aA][tT][eE]\\s+([tT][aA][bB][lL][eE]\\s+)?)"
+    }
+  ]
+}

package/plugins/{db-agent → db-connector}/hooks/guardrails.json

@@ -19,8 +19,10 @@
         "mssql-cli",
         "duckdb"
       ],
-      "block_two_token_command": ["aws dynamodb"],
-      "redirect": "Route database access through the db-agent CLI: `db-agent --action query --params '{\"env\":\"<name>\",\"sql\":\"...\"}'` or use sqlite_path. Do NOT bypass — reformulate the intent."
+      "block_two_token_command": [
+        "aws dynamodb"
+      ],
+      "redirect": "Route database access through the db-connector CLI: `db-connector --action query --params '{\"env\":\"<name>\",\"sql\":\"...\"}'` or use sqlite_path. Do NOT bypass \u2014 reformulate the intent."
     }
   ]
 }

package/plugins/{aws-agent → db-connector}/hooks/hooks.json

@@ -9,12 +9,21 @@
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/reminder.mjs\" 2>/dev/null || true"
-          },
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-start"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit",
+        "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
-            "env": { "USAGE_CONNECTOR_NAME": "aws" }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use",
+            "env": {
+              "DB_AGENT_GUARDRAILS": "${user_config.install_guardrails}"
+            }
           }
         ]
       }
@@ -25,11 +34,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
-            "env": {
-              "USAGE_CONNECTOR_NAME": "aws",
-              "USAGE_BIN_HINT": "narai-primitives/dist/connectors/aws"
-            }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
           }
         ]
       }
@@ -39,8 +44,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
-            "env": { "USAGE_CONNECTOR_NAME": "aws" }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
           }
         ]
       }

package/plugins/{db-agent → db-connector}/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "db-agent-plugin-runtime",
+  "name": "db-connector-plugin-runtime",
   "version": "1.0.0",
   "private": true,
   "dependencies": {

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

@@ -0,0 +1,5 @@
+{
+  "name": "db",
+  "kind": "db",
+  "binPath": "narai-primitives/dist/connectors/db"
+}

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

@@ -1,5 +1,5 @@
 ---
-name: db-agent
+name: db-connector
 description: |
   Use when the user asks about reading data from a database — SELECT queries,
   schema introspection, "show me the rows/tables/columns…". Supports
@@ -11,16 +11,16 @@ description: |
 context: fork
 ---
 
-# Database Agent
+# Database Connector
 
-Answer the user's question by invoking the `db-agent` binary exposed by this
+Answer the user's question by invoking the `db-connector` binary exposed by this
 plugin. It delegates to `narai-primitives/db`, which enforces the
 policy gate before any backend is touched.
 
 ## Invocation
 
 ```
-db-agent --action <action> --params '<json>'
+db-connector --action <action> --params '<json>'
 ```
 
 Return the connector's JSON envelope verbatim.
@@ -46,5 +46,5 @@ Read-only by design. The policy gate rejects every non-read statement before
 any driver loads. WRITE escalates by default; DELETE/ADMIN return formatted
 SQL with no execution; PRIVILEGE is hard-denied. Never shell out to `psql`,
 `mysql`, `sqlite3`, `mongosh`, `pg_dump`, `duckdb`, or `aws dynamodb` — the
-`db-agent` binary is the only sanctioned channel. Never edit the operator's
+`db-connector` binary is the only sanctioned channel. Never edit the operator's
 config to weaken a policy decision; report the decision instead.

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

@@ -1,5 +1,5 @@
 {
-  "name": "gcp-agent-plugin",
+  "name": "gcp-connector-plugin",
   "version": "1.1.0",
   "description": "Read-only GCP connector for Claude Code. Built on narai-primitives (subpath ./gcp). Cloud Run, Cloud SQL, Pub/Sub, Cloud Logging.",
   "author": "narai"

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

@@ -1,10 +1,10 @@
-# gcp-agent-plugin
+# gcp-connector-plugin
 
 Claude Code plugin that wraps [`narai-primitives/gcp`](https://www.npmjs.com/package/narai-primitives) as a read-only GCP skill and slash command.
 
-- **Skill** `gcp-agent` — automatic invocation for Cloud Run / Cloud SQL / Pub/Sub / Cloud Logging questions.
-- **Slash command** `/gcp-agent <action> <params-json>`.
-- **Binary** `gcp-agent` — thin shim over the installed connector CLI.
+- **Skill** `gcp-connector` — automatic invocation for Cloud Run / Cloud SQL / Pub/Sub / Cloud Logging questions.
+- **Slash command** `/gcp-connector <action> <params-json>`.
+- **Binary** `gcp-connector` — thin shim over the installed connector CLI.
 
 ## How install works
 
@@ -16,7 +16,7 @@ On first `SessionStart` the hook in `hooks/hooks.json`:
 
 After install,
 `${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/gcp/cli.js`
-exists and `bin/gcp-agent` exec's it.
+exists and `bin/gcp-connector` exec's it.
 
 ## Credentials
 

package/plugins/{gcp-agent/bin/gcp-agent → gcp-connector/bin/gcp-connector}

@@ -1,16 +1,16 @@
 #!/usr/bin/env bash
-# gcp-agent — thin shim over narai-primitives (CLI at dist/connectors/gcp).
+# gcp-connector — thin shim over narai-primitives (CLI at dist/connectors/gcp).
 set -euo pipefail
 
 if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
-  echo "gcp-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  echo "gcp-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/gcp/cli.js"
 
 if [ ! -f "$CLI" ]; then
-  echo "gcp-agent: connector CLI not found at $CLI" >&2
+  echo "gcp-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/gcp-connector/commands/gcp-connector.md

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

package/plugins/{github-agent → gcp-connector}/hooks/hooks.json

@@ -9,12 +9,18 @@
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/reminder.mjs\" 2>/dev/null || true"
-          },
+            "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/stale-summarize.mjs\" 2>/dev/null || true",
-            "env": { "USAGE_CONNECTOR_NAME": "github" }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
           }
         ]
       }
@@ -25,11 +31,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
-            "env": {
-              "USAGE_CONNECTOR_NAME": "github",
-              "USAGE_BIN_HINT": "narai-primitives/dist/connectors/github"
-            }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
           }
         ]
       }
@@ -39,8 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
-            "env": { "USAGE_CONNECTOR_NAME": "github" }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
           }
         ]
       }

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"
+}