narai-primitives 2.0.0-rc.1

package/plugins/confluence-agent/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "confluence-agent-plugin",
+  "version": "1.0.0",
+  "description": "Read-only Confluence connector for Claude Code. Wraps @narai/confluence-agent-connector.",
+  "author": "narai"
+}

package/plugins/confluence-agent/README.md

@@ -0,0 +1,15 @@
+# confluence-agent-plugin
+
+Claude Code plugin that wraps `@narai/confluence-agent-connector` as a read-only Confluence skill and slash command. Same layout as aws/gcp/notion-agent-plugin.
+
+## Credentials
+
+```bash
+export CONFLUENCE_SITE_URL="https://your.atlassian.net"
+export CONFLUENCE_EMAIL="you@example.com"
+export CONFLUENCE_API_TOKEN="…"
+```
+
+## License
+
+MIT

package/plugins/confluence-agent/bin/confluence-agent

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

package/plugins/confluence-agent/commands/confluence-agent.md

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

package/plugins/confluence-agent/hooks/hooks.json

@@ -0,0 +1,49 @@
+{
+  "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_ROOT}/plugin/hooks/reminder.mjs\" 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "confluence" }
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
+            "env": {
+              "USAGE_CONNECTOR_NAME": "confluence",
+              "USAGE_BIN_HINT": "@narai/confluence-agent-connector"
+            }
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "confluence" }
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/confluence-agent/hooks/reminder.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * SessionStart curation reminder. Runs after the install hook.
+ *
+ * Imports `evaluateNudge` from the installed toolkit (lives under
+ * `${CLAUDE_PLUGIN_DATA}/node_modules`), checks thresholds + user skip
+ * state in `~/.claude/connectors/curation-prefs.json`, and prints one
+ * banner line if the Confluence connector has uncurated hardship entries
+ * worth reviewing.
+ *
+ * Non-failing: any error (missing toolkit, unreadable prefs, etc.) is
+ * swallowed. A missing nudge is better than a noisy session start.
+ */
+try {
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (!data) process.exit(0);
+  const toolkitEntry = `${data}/node_modules/@narai/connector-toolkit/dist/plugin/reminder.js`;
+  const mod = await import(toolkitEntry);
+  const decision = mod.evaluateNudge({ connectors: ["confluence"] });
+  if (decision.nudge) {
+    process.stdout.write(decision.banner + "\n");
+  }
+} catch {
+  // best-effort — reminder never blocks startup
+}

package/plugins/confluence-agent/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "confluence-agent-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@narai/confluence-agent-connector": "file:.."
+  }
+}

package/plugins/confluence-agent/skills/confluence-agent/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: confluence-agent
+description: |
+  Use when the user asks about read-only Confluence content — search via
+  CQL, single page retrieval, or space metadata. Never modifies
+  Confluence content.
+context: fork
+---
+
+# Confluence Agent
+
+Answer the user's question by invoking the `confluence-agent` binary
+exposed by this plugin. It delegates to
+`@narai/confluence-agent-connector` via Atlassian's Confluence REST v1.
+
+## Invocation
+
+```
+confluence-agent --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Supported actions
+
+| Action | Required params |
+|---|---|
+| `cql_search` | `cql`, optional `max_results` |
+| `get_page` | `page_id` (numeric), optional `expand` |
+| `get_space` | `space_key` (e.g. `DEV`) |
+
+## Credentials
+
+Set `CONFLUENCE_SITE_URL`, `CONFLUENCE_EMAIL`, `CONFLUENCE_API_TOKEN`
+before use.
+
+## Safety
+
+Read-only — only GET requests are permitted by the connector's HTTP
+method whitelist.

package/plugins/db-agent/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "db-agent-plugin",
+  "version": "1.0.0",
+  "description": "Safe, read-only database query agent for Claude Code. Wraps @narai/db-agent-connector. 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/db-agent-connector",
+  "repository": "https://github.com/narailabs/db-agent-connector",
+  "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.",
+      "sensitive": false
+    }
+  },
+  "hooks": "./hooks/hooks.json"
+}

package/plugins/db-agent/README.md

@@ -0,0 +1,13 @@
+# db-agent-plugin
+
+Claude Code plugin that wraps [`@narai/db-agent-connector`](https://www.npmjs.com/package/@narai/db-agent-connector).
+
+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:
+
+- `read` (SELECT/EXPLAIN/SHOW/DESCRIBE/WITH) → executed through the driver with row/timeout caps
+- `write` (INSERT/UPDATE/REPLACE/MERGE/UPSERT) → escalates by default
+- `delete` (DELETE/TRUNCATE) → returned as formatted SQL, never executed
+- `admin` (CREATE/DROP/ALTER/RENAME) → returned as formatted SQL, never executed
+- `privilege` (GRANT/REVOKE) → hard-denied
+
+Install via Claude Code's plugin marketplace. The `SessionStart` hook installs `@narai/db-agent-connector` into the plugin's data directory on first use.

package/plugins/db-agent/bin/db-agent

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "db-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/@narai/db-agent-connector/dist/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "db-agent: connector CLI not found at $CLI" >&2
+  echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
+  exit 2
+fi
+
+exec node "$CLI" "$@"

package/plugins/db-agent/commands/db-agent.md

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

package/plugins/db-agent/hooks/db-guard.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// hooks/db-guard.mjs — db-agent-connector PreToolUse guardrail.
+//
+// V2.0: thin stub. Loads `plugin/hooks/guardrails.json` and delegates to
+// the toolkit's `findBlockingRule`. The hub's unified `guardrails.mjs`
+// reads the same manifest when the hub is installed; this file is the
+// standalone fallback when only db-agent is installed.
+//
+// V2.0 regression: deny-event audit logging is no longer written from
+// this hook (the toolkit's matcher doesn't log). The audit module still
+// records executed-query events.
+//
+// Best-effort, not a security boundary. Fails open on any error.
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MANIFEST_PATH = join(__dirname, "guardrails.json");
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+async function loadToolkit() {
+  const candidates = [
+    // 1. Bundle: db-guard at narai-primitives/plugins/db-agent/hooks/;
+    //    toolkit at narai-primitives/dist/toolkit/guardrail.js (3 ups)
+    join(__dirname, "..", "..", "..", "dist", "toolkit", "guardrail.js"),
+    // 2. Bundle installed as a Claude Code plugin
+    process.env.CLAUDE_PLUGIN_DATA
+      ? join(process.env.CLAUDE_PLUGIN_DATA, "node_modules", "narai-primitives", "dist", "toolkit", "guardrail.js")
+      : null,
+    // 3. Legacy plugin install
+    process.env.CLAUDE_PLUGIN_DATA
+      ? join(process.env.CLAUDE_PLUGIN_DATA, "node_modules", "@narai", "connector-toolkit", "dist", "guardrail.js")
+      : null,
+    join(homedir(), "src", "connectors", "connector-toolkit", "dist", "guardrail.js"),
+    // 4. Local resolution from this file's nearest node_modules (dev sandbox).
+    join(__dirname, "..", "..", "node_modules", "@narai", "connector-toolkit", "dist", "guardrail.js"),
+  ].filter((p) => p !== null);
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      return await import(pathToFileURL(p).href);
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+async function main() {
+  const raw = readStdin();
+  if (!raw) return;
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  if (payload?.tool_name !== "Bash") return;
+  if (process.env.DB_AGENT_GUARDRAILS === "off") return;
+
+  const command = payload?.tool_input?.command;
+  if (typeof command !== "string" || !command.trim()) return;
+
+  if (!existsSync(MANIFEST_PATH)) return;
+
+  const toolkit = await loadToolkit();
+  if (!toolkit) return;
+  const { findBlockingRule, defaultDenyMessage, loadGuardrailManifest } = toolkit;
+  if (typeof findBlockingRule !== "function") return;
+
+  let manifest;
+  try {
+    manifest = loadGuardrailManifest(MANIFEST_PATH);
+  } catch {
+    return;
+  }
+
+  const match = findBlockingRule(command, [manifest]);
+  if (!match) return;
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: defaultDenyMessage(match),
+      },
+    }),
+  );
+}
+
+try {
+  await main();
+  process.exit(0);
+} catch (err) {
+  process.stderr.write(`db-guard: fail-open (${(err && err.message) || err})\n`);
+  process.exit(0);
+}

package/plugins/db-agent/hooks/guardrails.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "name": "db-agent-connector",
+  "rules": [
+    {
+      "block_first_token_basename": [
+        "psql",
+        "mysql",
+        "mariadb",
+        "sqlite3",
+        "mongosh",
+        "mongo",
+        "mongodump",
+        "mongorestore",
+        "pg_dump",
+        "pg_restore",
+        "mysqldump",
+        "sqlcmd",
+        "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."
+    }
+  ]
+}

package/plugins/db-agent/hooks/hooks.json

@@ -0,0 +1,61 @@
+{
+  "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_ROOT}/plugin/hooks/reminder.mjs\" 2>/dev/null || true"
+        },
+        {
+          "type": "command",
+          "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
+          "env": { "USAGE_CONNECTOR_NAME": "db" }
+        }
+      ]
+    }
+  ],
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node ${CLAUDE_PLUGIN_ROOT}/plugin/hooks/db-guard.mjs",
+          "env": {
+            "DB_AGENT_GUARDRAILS": "${user_config.install_guardrails}"
+          }
+        }
+      ]
+    }
+  ],
+  "PostToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
+          "env": {
+            "USAGE_CONNECTOR_NAME": "db",
+            "USAGE_BIN_HINT": "@narai/db-agent-connector"
+          }
+        }
+      ]
+    }
+  ],
+  "SessionEnd": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
+          "env": { "USAGE_CONNECTOR_NAME": "db" }
+        }
+      ]
+    }
+  ]
+}

package/plugins/db-agent/hooks/reminder.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * SessionStart curation reminder for the db-agent connector.
+ */
+try {
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (!data) process.exit(0);
+  const toolkitEntry = `${data}/node_modules/@narai/connector-toolkit/dist/plugin/reminder.js`;
+  const mod = await import(toolkitEntry);
+  const decision = mod.evaluateNudge({ connectors: ["db"] });
+  if (decision.nudge) {
+    process.stdout.write(decision.banner + "\n");
+  }
+} catch {
+  // best-effort — reminder never blocks startup
+}

package/plugins/db-agent/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "db-agent-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@narai/db-agent-connector": "file:.."
+  }
+}

package/plugins/db-agent/skills/db-agent/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: db-agent
+description: |
+  Use when the user asks about reading data from a database — SELECT queries,
+  schema introspection, "show me the rows/tables/columns…". Supports
+  PostgreSQL, MySQL, SQLite, SQL Server, MongoDB, DynamoDB, and Oracle via
+  pluggable drivers. Every statement passes the policy gate BEFORE any
+  driver loads or any connection opens: write statements escalate, delete
+  and admin statements return formatted SQL without executing, privilege
+  statements are hard-denied.
+context: fork
+---
+
+# Database Agent
+
+Answer the user's question by invoking the `db-agent` binary exposed by this
+plugin. It delegates to `@narai/db-agent-connector`, which enforces the
+policy gate before any backend is touched.
+
+## Invocation
+
+```
+db-agent --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Supported actions
+
+| Action   | Required params                               | Optional params                                                   |
+|----------|-----------------------------------------------|-------------------------------------------------------------------|
+| `query`  | `env` + `sql` (or `sqlite_path` + `sql`)      | `max_rows` (default 1000), `timeout_ms` (default 30000), `approval_mode`, `config_path` |
+| `schema` | `env` (or `sqlite_path`)                      | `filter` (table-name pattern like `users%`), `config_path`        |
+
+## Envelope statuses
+
+- `ok` — read succeeded; `rows` / `tables` / `row_count` / `columns` / `truncated` populated.
+- `present_only` — formatted SQL returned, **never executed**. Default for `delete` (DELETE/TRUNCATE) and `admin` (CREATE/DROP/ALTER/RENAME).
+- `denied` — `privilege` (GRANT/REVOKE) always; or the configured policy denied.
+- `escalate` — needs approval. Default for `write` (INSERT/UPDATE/REPLACE/MERGE/UPSERT); also `grant_required` mode and unbounded SELECT.
+- `error` — driver or SQL error after an allowed verdict.
+
+## Safety
+
+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
+config to weaken a policy decision; report the decision instead.

package/plugins/gcp-agent/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "gcp-agent-plugin",
+  "version": "1.0.0",
+  "description": "Read-only GCP connector for Claude Code. Wraps @narai/gcp-agent-connector. Cloud Run, Cloud SQL, Pub/Sub, Cloud Logging.",
+  "author": "narai"
+}

package/plugins/gcp-agent/README.md

@@ -0,0 +1,31 @@
+# gcp-agent-plugin
+
+Claude Code plugin that wraps [`@narai/gcp-agent-connector`](https://www.npmjs.com/package/@narai/gcp-agent-connector) 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.
+
+## How install works
+
+On first `SessionStart` the hook in `hooks/hooks.json`:
+
+1. compares the plugin's `package.json` with `${CLAUDE_PLUGIN_DATA}/package.json`;
+2. if different or missing, copies the manifest and runs `npm install --no-audit --no-fund` inside `${CLAUDE_PLUGIN_DATA}`;
+3. if the install fails, removes the stale copy so the hook re-runs next session.
+
+After install,
+`${CLAUDE_PLUGIN_DATA}/node_modules/@narai/gcp-agent-connector/dist/cli.js`
+exists and `bin/gcp-agent` exec's it.
+
+## Credentials
+
+Install the Google Cloud SDK and authenticate:
+
+```bash
+gcloud auth application-default login
+```
+
+## License
+
+MIT

package/plugins/gcp-agent/bin/gcp-agent

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# gcp-agent — thin shim over @narai/gcp-agent-connector.
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "gcp-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/@narai/gcp-agent-connector/dist/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "gcp-agent: connector CLI not found at $CLI" >&2
+  echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
+  exit 2
+fi
+
+exec node "$CLI" "$@"

package/plugins/gcp-agent/commands/gcp-agent.md

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

package/plugins/gcp-agent/hooks/hooks.json

@@ -0,0 +1,49 @@
+{
+  "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_ROOT}/plugin/hooks/reminder.mjs\" 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "gcp" }
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
+            "env": {
+              "USAGE_CONNECTOR_NAME": "gcp",
+              "USAGE_BIN_HINT": "@narai/gcp-agent-connector"
+            }
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "gcp" }
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/gcp-agent/hooks/reminder.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * SessionStart curation reminder for the GCP connector.
+ */
+try {
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (!data) process.exit(0);
+  const toolkitEntry = `${data}/node_modules/@narai/connector-toolkit/dist/plugin/reminder.js`;
+  const mod = await import(toolkitEntry);
+  const decision = mod.evaluateNudge({ connectors: ["gcp"] });
+  if (decision.nudge) {
+    process.stdout.write(decision.banner + "\n");
+  }
+} catch {
+  // best-effort — reminder never blocks startup
+}

package/plugins/gcp-agent/package.json

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