@craftsamo/agent-github 0.1.0 → 0.2.0

package/.antigravity-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-github",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "GitHub tools for coding agents: issues, project boards, pull requests, repositories, releases and Actions.",
   "author": {
     "name": "craftsamo",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-github",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "GitHub tools for coding agents: issues, project boards, pull requests, repositories, releases and Actions.",
   "author": {
     "name": "craftsamo",
@@ -10,7 +10,7 @@
   "repository": "https://github.com/craftsamo/agent-github",
   "license": "MIT",
   "mcpServers": {
-    "github": {
+    "agent-github": {
       "command": "node",
       "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp.js"]
     }

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agent-github": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp.js"]
+    }
+  }
+}

package/README.md

@@ -15,6 +15,9 @@ agent harness in the form that suits it best.
 | Hermes Agent   | native plugin (Python, calls the command line)   | the release commit, as the SHA                |
 | other MCP host | MCP server from npm                              | the version in the package                    |
 
+0.2.0 renamed the MCP server from `github` to `agent-github`, so allow rules
+and MCP configurations written for 0.1.0 change.
+
 The tools need [Node.js](https://nodejs.org/) 24 or later and the
 [GitHub CLI](https://cli.github.com/), authenticated as you.
 [`docs/conventions.md`](docs/conventions.md) describes how the tools are named
@@ -42,7 +45,8 @@ OpenCode V2 takes the package and its options in `opencode.json`:
       "package": "@craftsamo/agent-github@<version>",
       "options": { "toolsets": ["issues", "pull_requests", "projects"] }
     }
-  ]
+  ],
+  "permissions": [{ "action": "github_*", "resource": "*", "effect": "ask" }]
 }
 ```
 
@@ -50,12 +54,25 @@ OpenCode V1 takes the package as a string, or as a pair with its options:
 
 ```json
 {
-  "plugin": [["@craftsamo/agent-github@<version>", { "toolsets": ["issues", "pull_requests", "projects"] }]]
+  "plugin": [["@craftsamo/agent-github@<version>", { "toolsets": ["issues", "pull_requests", "projects"] }]],
+  "permission": { "github_*": "ask" }
 }
 ```
 
-V1 registers no skills. Unpack the package (`npm pack @craftsamo/agent-github@<version>`)
-and copy its `skills/*` folders into `~/.config/opencode/skills/`.
+OpenCode allows any action no rule names, so the plugin's request is granted
+silently unless a rule says `ask`. Read tools never ask, so the `github_*` glob
+is safe.
+
+V1 registers no skills. Unpack the package and copy its `skills/*` folders into
+`~/.config/opencode/skills/`:
+
+```sh
+npm pack @craftsamo/agent-github@<version>
+tar -xzf craftsamo-agent-github-<version>.tgz
+mkdir -p ~/.config/opencode/skills
+cp -r package/skills/* ~/.config/opencode/skills/
+rm -rf package craftsamo-agent-github-<version>.tgz
+```
 
 ### Claude Code
 
@@ -71,6 +88,10 @@ codex plugin marketplace add craftsamo/agent-github --ref v<version>
 codex plugin add agent-github@craftsamo
 ```
 
+Codex starts the MCP server in the plugin's install directory, so name issues
+as `owner/repo#N` or pass `repo` (a bare number fails there with a message saying
+so).
+
 ### Grok Build
 
 ```sh
@@ -89,10 +110,11 @@ agy plugin install https://github.com/craftsamo/agent-github/tree/v<version>
 
 ### Hermes Agent
 
-Hermes installs a commit, not a tag:
+Hermes installs a commit, not a tag, and the plugin installs disabled:
 
 ```sh
 hermes plugins install craftsamo/agent-github --ref <sha>
+hermes plugins enable agent-github
 ```
 
 ### Any other MCP host
@@ -102,7 +124,7 @@ Add the server to the host's MCP configuration. Flags go in `args`:
 ```json
 {
   "mcpServers": {
-    "github": {
+    "agent-github": {
       "command": "npx",
       "args": ["-y", "@craftsamo/agent-github@<version>", "--toolsets", "issues,pull_requests,projects"]
     }
@@ -112,7 +134,8 @@ Add the server to the host's MCP configuration. Flags go in `args`:
 
 ## Tools and skills
 
-Each toolset comes with a skill that tells an agent how to use its tools.
+Each toolset comes with a skill that tells an agent how to use its tools. A
+toolset with no tools yet registers none (0.2.0 ships the `issues` tools).
 
 ### Issues (`issues`)
 
@@ -131,19 +154,28 @@ The skill is [`github-issues`](skills/github-issues/SKILL.md). An issue's kind
 is the organization's Issue Type of that name when it defines one, otherwise a
 `type:<kind>` label.
 
-## Read tools without asking
+## Reads and writes
+
+Every read tool is named `github_<domain>_read`. Reads can run unasked; writes
+are confirmed by the harness.
+
+| Harness     | Reads without asking                                                                                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
+| OpenCode    | always; the plugin asks only before a write                                                                               |
+| Claude Code | the rule `mcp__plugin_agent-github_agent-github__*_read` in `permissions.allow` of `~/.claude/settings.json` or a project |
+| Codex       | always; Codex runs tools that declare `readOnlyHint` unasked, as the read tools do                                        |
+| Grok Build  | `grok --allow 'MCPTool(agent-github__*_read)'`                                                                            |
+| Antigravity | an Allow rule `mcp(agent-github/<tool>)` for each read tool; not yet verified                                             |
+| Hermes      | always; the plugin asks only before a write                                                                               |
 
-Every read tool is named `github_<domain>_read`. Writes are confirmed by the
-harness.
+Where a write is asked about, and where it is not:
 
-| Harness     | Reads without asking                                                                                                             |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| OpenCode    | always; the plugin asks only before a write                                                                                      |
-| Claude Code | `permissions.allow` rule `mcp__plugin_agent-github_github__*_read`; a glob is allowed after the literal `mcp__<server>__` prefix |
-| Codex       | always; Codex runs tools that declare `readOnlyHint` unasked, as the read tools do                                               |
-| Grok Build  | `grok --allow 'MCPTool(github__*_read)'`                                                                                         |
-| Antigravity | an Allow rule `mcp(github/<tool>)` for each read tool; not yet verified                                                          |
-| Hermes      | always; the plugin asks only before a write                                                                                      |
+- **OpenCode** grants any action no rule names, so a write runs unasked unless
+  a rule asks for it: add the `github_*` rule shown under [OpenCode](#opencode).
+- **Codex** under `codex exec`, and **Grok Build** under `grok -p`, refuse a
+  write they cannot ask about, unless it is allowed beforehand.
+- **Hermes** `hermes chat -q` refuses a write it cannot ask about; `hermes -z`
+  and `--yolo` skip approval, so writes then run unasked.
 
 ## Settings
 
@@ -174,9 +206,13 @@ Lists are comma-separated in a flag or a variable. Where each harness reads them
           exclude_tools: [github_pr_merge]
   ```
 
-- **The plugins for Claude Code, Codex, Grok Build and Antigravity** start the
-  server without flags, so set the variables in the environment the harness runs
-  in, or use the MCP configuration above, which takes flags.
+- **Claude Code and Antigravity** start the plugin's server without flags; Claude
+  Code passes the client's environment, so set the variables in the environment
+  the harness runs in.
+- **Codex and Grok Build** pass no environment to a plugin's MCP server, so the
+  `AGENT_GITHUB_*` variables have no effect there. To change settings in Codex,
+  add the server under `[mcp_servers]` in Codex's config with flags in `args` (as
+  in [Any other MCP host](#any-other-mcp-host)) instead of using the plugin.
 
 ## Layout
 
@@ -188,11 +224,12 @@ Lists are comma-separated in a flag or a variable. Where each harness reads them
 - `src/hermes/`, `plugin.yaml` and `__init__.py` — the Hermes plugin.
 - `skills/` — one skill per toolset, `skills/<name>/SKILL.md`, which every
   harness that takes skills loads from the package or plugin root.
-- `plugin.json`, `mcp.json`, `.claude-plugin/`, `.agents/plugins/`,
+- `plugin.json`, `mcp.json`, `.mcp.json`, `.claude-plugin/`, `.agents/plugins/`,
   `.antigravity-plugin/` and `mcp_config.json` — the plugin manifests of the
-  other harnesses. Claude Code's server is declared inside
-  `.claude-plugin/plugin.json`, since a `.mcp.json` in the repository root would
-  be read as this project's own MCP configuration.
+  other harnesses. The root `.mcp.json` is the configuration Grok Build reads
+  (with `${CLAUDE_PLUGIN_ROOT}`, the variable both Grok Build and Claude Code
+  expand); when working on this repository in Claude Code, decline the project
+  MCP server it offers from that file.
 
 How a release is made is in [`RELEASING.md`](RELEASING.md).
 

package/dist/cli.js

@@ -5,6 +5,13 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/entry/package-root.ts
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+function packageRoot(bundleUrl) {
+  return dirname(dirname(fileURLToPath(bundleUrl)));
+}
+
 // node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -20205,13 +20212,13 @@ async function ensureLabel(repo, name, ctx) {
 function isTypeFailure(error62) {
   return isToolError(error62) && TYPE_FAILURE_CODES.includes(error62.code) && TYPE_MENTION.test(error62.message);
 }
-async function withKindFallback(kind, placement, attempt) {
+async function withKindFallback(kind, placement, attempt2) {
   try {
-    return { placement, result: await attempt(placement) };
+    return { placement, result: await attempt2(placement) };
   } catch (error62) {
     if (placement.via !== "type" || !isTypeFailure(error62)) throw error62;
     const fallback = labelKind(kind);
-    return { placement: fallback, result: await attempt(fallback) };
+    return { placement: fallback, result: await attempt2(fallback) };
   }
 }
 async function kindFlags(placement, repo, ctx) {
@@ -20513,6 +20520,8 @@ async function readSubIssues(parent, ctx) {
 }
 
 // src/core/refs.ts
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, sep } from "node:path";
 var DEFAULT_HOST = "github.com";
 var SSH_ALIAS_HOST = "ssh.github.com";
 var GIT_CONFIG_ENV = ["GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_CONFIG_NOSYSTEM"];
@@ -20596,11 +20605,25 @@ function gitEnv() {
   }
   return { ...env, GIT_TERMINAL_PROMPT: "0" };
 }
-async function repoFromOrigin(cwd, signal) {
+async function isWithin(dir, root) {
+  try {
+    const path = relative(await realpath(root), await realpath(dir));
+    return path === "" || !(path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path));
+  } catch {
+    return false;
+  }
+}
+async function repoFromOrigin(cwd, signal, ownDir) {
   const env = gitEnv();
-  const unresolved = (why) => invalid(
-    `Cannot tell which repository to use: ${why}. Run the call inside a clone of a GitHub repository, or pass \`repo\` as owner/name.`
+  const unresolved = (why, advice = "") => invalid(
+    `Cannot tell which repository to use: ${why}. Run the call inside a clone of a GitHub repository, or pass \`repo\` as owner/name.${advice}`
   );
+  if (ownDir !== void 0 && await isWithin(cwd, ownDir)) {
+    throw unresolved(
+      `${cwd} is where these tools are installed, not a project`,
+      " An issue can be given as `owner/repo#N`."
+    );
+  }
   let result;
   try {
     result = await exec(["git", "remote", "get-url", "origin"], { cwd, env, signal });
@@ -20615,7 +20638,10 @@ async function repoFromOrigin(cwd, signal) {
   return repo;
 }
 async function resolveRepo(repo, ctx) {
-  return repo === void 0 || repo.trim() === "" ? repoFromOrigin(ctx.cwd, ctx.signal) : parseRepo(repo);
+  return repo === void 0 || repo.trim() === "" ? repoFromOrigin(ctx.cwd, ctx.signal, ctx.ownDir) : parseRepo(repo);
+}
+function isBareNumber(ref) {
+  return BARE_NUMBER_PATTERN.test(ref.trim());
 }
 function parseNumber(digits, ref) {
   const number4 = Number.parseInt(digits, 10);
@@ -20666,10 +20692,9 @@ async function parseNumberRef(ref, repoArg, ctx, options = {}) {
 }
 
 // src/core/github/issue-refs.ts
-var BARE_NUMBER = /^#?\d+$/;
 async function resolveRelatedIssue(ref, target, ctx) {
   const text = ref.trim();
-  return parseNumberRef(text, BARE_NUMBER.test(text) ? target.full : void 0, ctx, { accept: "issue" });
+  return parseNumberRef(text, isBareNumber(text) ? target.full : void 0, ctx, { accept: "issue" });
 }
 function issueLabel(issue2) {
   return `${issue2.repo.full}#${issue2.number}`;
@@ -20697,6 +20722,10 @@ function defineTool(spec) {
   if (!(spec.output instanceof external_exports.ZodObject)) {
     throw new Error(`Tool "${spec.id}" must have an object output schema, since a result is an object.`);
   }
+  const unknownTarget = Object.keys(spec.targets ?? {}).find((name) => !Object.hasOwn(spec.input.shape, name));
+  if (unknownTarget !== void 0) {
+    throw new Error(`Tool "${spec.id}" declares the target "${unknownTarget}", which is not one of its arguments.`);
+  }
   return spec;
 }
 var CLASS_HINTS = {
@@ -20802,6 +20831,7 @@ var StepErrors = class {
 // src/core/issues/write-support.ts
 var REPO_DESCRIPTION = "owner/name; defaults to the working tree's repository (its origin). Used for a bare number.";
 var ISSUE_DESCRIPTION = "The issue, as 12, #12, owner/repo#12 or its URL.";
+var ISSUE_TARGETS = { issue: "issue", repo: "repo" };
 var LIST_SYNTAX = /[,"\r\n]/;
 var URL_LINE = /^https?:\/\/\S+$/;
 function invalid2(message) {
@@ -20871,6 +20901,7 @@ var issueClose = defineTool({
   ].join(" "),
   toolset: "issues",
   class: "overwrite",
+  targets: ISSUE_TARGETS,
   input: input2,
   output: output2,
   async execute(args, ctx) {
@@ -20927,6 +20958,7 @@ var issueComment = defineTool({
   ].join(" "),
   toolset: "issues",
   class: "add",
+  targets: ISSUE_TARGETS,
   input: input3,
   output: output3,
   async execute(args, ctx) {
@@ -21044,6 +21076,7 @@ var issueCreate = defineTool({
   ].join(" "),
   toolset: "issues",
   class: "add",
+  targets: { repo: "repo", parent: "issue", blocked_by: "issues" },
   input: input4,
   output: output4,
   async execute(args, ctx) {
@@ -21191,6 +21224,7 @@ var issueDevelop = defineTool({
   ].join(" "),
   toolset: "issues",
   class: "idempotent",
+  targets: { ...ISSUE_TARGETS, branch_repo: "repo" },
   input: input5,
   output: output5,
   async execute(args, ctx) {
@@ -21338,6 +21372,7 @@ var issueEdit = defineTool({
   ].join(" "),
   toolset: "issues",
   class: "overwrite",
+  targets: ISSUE_TARGETS,
   input: input6,
   output: output6,
   async execute(args, ctx) {
@@ -21362,14 +21397,14 @@ var issueEdit = defineTool({
     if (change.removeMilestone) flags.push("--remove-milestone");
     const named = new Set([...change.addLabels, ...change.removeLabels].map((label) => label.toLowerCase()));
     const swapped = (where) => where.via === "label" ? otherKindLabels(current?.labels ?? [], where.name).filter((label) => !named.has(label.toLowerCase())).flatMap((label) => ["--remove-label", label]) : [];
-    const attempt = async (where) => editIssue(
+    const attempt2 = async (where) => editIssue(
       target,
       issue2.number,
       where ? [...flags, ...await kindFlags(where, target, ctx), ...swapped(where)] : flags,
       ctx,
       body
     );
-    const applied = kind ? await withKindFallback(kind.name, kind.placement, attempt) : { placement: void 0, result: await attempt() };
+    const applied = kind ? await withKindFallback(kind.name, kind.placement, attempt2) : { placement: void 0, result: await attempt2() };
     return {
       repo: target.full,
       issue: issue2.number,
@@ -21696,6 +21731,16 @@ var issueRelate = defineTool({
   ].join(" "),
   toolset: "issues",
   class: "idempotent",
+  targets: {
+    ...ISSUE_TARGETS,
+    parent: "issue",
+    add_sub_issues: "issues",
+    remove_sub_issues: "issues",
+    add_blocked_by: "issues",
+    remove_blocked_by: "issues",
+    add_blocking: "issues",
+    remove_blocking: "issues"
+  },
   input: input8,
   output: output8,
   async execute(args, ctx) {
@@ -21794,6 +21839,7 @@ var issueReopen = defineTool({
   ].join(" "),
   toolset: "issues",
   class: "overwrite",
+  targets: ISSUE_TARGETS,
   input: input9,
   output: output9,
   async execute(args, ctx) {
@@ -21824,17 +21870,69 @@ var ALL_TOOLS = [
   issueDevelop
 ];
 
-// src/entry/permission.ts
-var ANY_RESOURCE = "*";
-async function permissionResource(args, ctx) {
-  const repo = typeof args === "object" && args !== null ? args.repo : void 0;
-  if (repo !== void 0 && typeof repo !== "string") return ANY_RESOURCE;
+// src/core/targets.ts
+var ANY_TARGET = "*";
+var ISSUE_ARGUMENT = "issue";
+async function attempt(fn) {
   try {
-    return (await resolveRepo(repo, ctx)).full.toLowerCase();
+    return await fn();
   } catch (error62) {
     if (isAbortError(error62)) throw error62;
-    return ANY_RESOURCE;
+    return void 0;
+  }
+}
+function isBlank(value) {
+  return typeof value === "string" && value.trim() === "";
+}
+function ownRepository(spec, args, ctx) {
+  const repo = args.repo;
+  const issue2 = args[ISSUE_ARGUMENT];
+  let pending;
+  async function resolve() {
+    if (spec.targets?.[ISSUE_ARGUMENT] === "issue" && typeof issue2 === "string" && !isBareNumber(issue2)) {
+      const named = await attempt(() => parseNumberRef(issue2, void 0, ctx, { accept: "issue" }));
+      if (named) return named.repo;
+    }
+    if (repo !== void 0 && typeof repo !== "string") return void 0;
+    return attempt(() => resolveRepo(repo, ctx));
+  }
+  return () => pending ??= resolve();
+}
+async function issueRepository(value, own2, ctx) {
+  if (typeof value !== "string") return void 0;
+  const bare = isBareNumber(value);
+  const repoArg = bare ? (await own2())?.full : void 0;
+  if (bare && repoArg === void 0) return void 0;
+  return attempt(async () => (await parseNumberRef(value, repoArg, ctx, { accept: "issue" })).repo);
+}
+async function targetRepository(kind, value, own2, ctx) {
+  if (kind !== "repo") return issueRepository(value, own2, ctx);
+  return typeof value === "string" ? attempt(() => parseRepo(value)) : void 0;
+}
+async function writeTargets(spec, args, ctx) {
+  const given3 = typeof args === "object" && args !== null ? args : {};
+  const own2 = ownRepository(spec, given3, ctx);
+  const found = /* @__PURE__ */ new Set();
+  const add = (repo) => found.add(repo ? repo.full.toLowerCase() : ANY_TARGET);
+  add(await own2());
+  for (const [name, kind] of Object.entries(spec.targets ?? {})) {
+    const value = given3[name];
+    if (value === void 0) continue;
+    if (kind === "issues" && !Array.isArray(value)) {
+      add(void 0);
+      continue;
+    }
+    for (const item of kind === "issues" ? value : [value]) {
+      if (!isBlank(item)) add(await targetRepository(kind, item, own2, ctx));
+    }
   }
+  const repos = [...found].filter((repo) => repo !== ANY_TARGET).sort();
+  return found.has(ANY_TARGET) ? [...repos, ANY_TARGET] : repos;
+}
+
+// src/entry/permission.ts
+function permissionResources(spec, args, ctx) {
+  return writeTargets(spec, args, ctx);
 }
 
 // src/entry/settings.ts
@@ -22014,7 +22112,11 @@ async function runTool(command, io) {
   const spec = command.selected.find((candidate) => candidate.id === command.toolId);
   if (!spec) return writeError(io, "invalid_argument", `Unknown tool "${command.toolId}".`);
   try {
-    const result = await invoke(spec, await readArguments(io), { cwd: command.cwd, signal: io.signal });
+    const result = await invoke(spec, await readArguments(io), {
+      cwd: command.cwd,
+      ownDir: io.ownDir,
+      signal: io.signal
+    });
     writeJson(io, { result });
     return EXIT_OK;
   } catch (error62) {
@@ -22026,9 +22128,15 @@ async function runTool(command, io) {
   }
 }
 async function targetOf(command, io) {
+  const spec = io.specs.find((candidate) => candidate.id === command.toolId);
+  if (!spec) return writeError(io, "invalid_argument", `Unknown tool "${command.toolId}".`);
   try {
-    const resource = await permissionResource(await readArguments(io), { cwd: command.cwd, signal: io.signal });
-    writeJson(io, { resource });
+    const resources = await permissionResources(spec, await readArguments(io), {
+      cwd: command.cwd,
+      ownDir: io.ownDir,
+      signal: io.signal
+    });
+    writeJson(io, { resources });
     return EXIT_OK;
   } catch (error62) {
     if (isToolError(error62)) return writeError(io, error62.code, error62.message);
@@ -22076,6 +22184,7 @@ async function main() {
   process.exitCode = await runCli(process.argv.slice(2), {
     specs: ALL_TOOLS,
     env: process.env,
+    ownDir: packageRoot(import.meta.url),
     readStdin,
     stdout: (text) => process.stdout.write(text),
     stderr: (text) => process.stderr.write(text),