@ashulab/agent-forge 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,6 @@
 # Agent Forge
 
-A small CLI for launching coding agents (`claude`, `codex`, `antigravity`) with a
-**GitHub App identity** and a provider CLI chosen at runtime.
+A small CLI for launching coding agents (`claude`, `codex`, `antigravity`) with a **GitHub App identity** and a provider CLI chosen at runtime.
 
 On each run the launcher:
 
@@ -9,18 +8,15 @@ On each run the launcher:
 - generates a GitHub App installation token
 - detects installed provider CLIs on your PATH
 - asks which provider to use (or takes it from a flag)
-- starts the provider with the GitHub token and a per-agent git identity injected
-  into the environment
-- writes the agent's `systemPrompt` into the provider's startup memory file
-  (`CLAUDE.md` / `AGENTS.md`) so subagents inherit the identity
+- starts the provider with the GitHub token and a per-agent git identity injected into the environment
+- writes the agent's `systemPrompt` into the provider's startup memory file (`CLAUDE.md` / `AGENTS.md`) so subagents inherit the identity
 
 Provider auth stays in the provider CLI — the launcher never handles provider API keys.
 
 ## Requirements
 
 - Node.js 24+
-- a GitHub App with an installation on the target account/org —
-  [how to create one](docs/github-app.md)
+- a GitHub App with an installation on the target account/org — [how to create one](docs/github-app.md)
 - the App private key stored locally (e.g. in `~/.ssh`)
 - one of these provider CLIs on your PATH: `claude`, `codex`, `agy` (antigravity)
 
@@ -38,22 +34,15 @@ pnpm dlx @ashulab/agent-forge --help
 
 ## Configuration
 
-Your agents live in a single machine-global registry — you launch the tool from
-inside each target repo, but the identities are not per-repo. The launcher reads
-`agents.json` from the first of these that exists:
+Your agents live in a single machine-global registry — you launch the tool from inside each target repo, but the identities are not per-repo. The launcher reads `agents.json` from the first of these that exists:
 
 1. `$AGENT_FORGE_CONFIG`
 2. `~/.config/agent-forge/agents.json` — the global registry (`agent-forge add` writes here)
 3. `./agents.json` — only if it already exists
 
-The easiest path is `agent-forge add` (see below), which creates the global
-file for you. Do **not** drop `agents.json` into a project you run the agent in:
-it holds real App / installation IDs and private-key paths and must stay out of
-version control.
+The easiest path is `agent-forge add` (see below), which creates the global file for you. Do **not** drop `agents.json` into a project you run the agent in: it holds real App / installation IDs and private-key paths and must stay out of version control.
 
-The shape, for reference — the `"$schema"` line points at the published schema so
-any editor that understands JSON Schema gives you field descriptions,
-required-field checks and typo detection:
+The shape, for reference — the `"$schema"` line points at the published schema so any editor that understands JSON Schema gives you field descriptions, required-field checks and typo detection:
 
 ```json
 {
@@ -63,7 +52,6 @@ required-field checks and typo detection:
       "name": "ops-agent",
       "label": "Ops Agent",
       "appId": "123456",
-      "installationId": "987654",
       "botName": "ops-agent",
       "privateKeyPath": "~/.ssh/ops-agent.private-key.pem",
       "systemPrompt": "You are Ops Agent, a senior DevOps engineer. Prefer safe, minimal changes and explain operational risks clearly."
@@ -72,28 +60,38 @@ required-field checks and typo detection:
 }
 ```
 
-- `botId` is optional. When omitted it is resolved from the GitHub API using
-  `botName` so the git author email links commits to the bot. Set it explicitly
-  only to skip that lookup (e.g. offline).
+- The **installation id is not stored** — it is resolved on each run, in order: the owner of the repo you launch in, then `account`, then the App's sole installation. So the same agent works across every org the App is installed on, and it survives an uninstall/reinstall (which rotates the id).
+- Add `"account": "<org-or-user login>"` only when you run outside a matching repo and the App has more than one installation.
+- `installationId` is still accepted as an explicit override — set it to pin a specific id or skip the lookup (offline, or in a git credential helper).
+- `botId` is optional. When omitted it is resolved from the GitHub API using `botName` so the git author email links commits to the bot. Set it explicitly only to skip that lookup (e.g. offline).
 - Do not put provider-specific config here — providers are auto-detected from PATH.
 
 ### Least-privilege tokens (optional)
 
-By default the installation token carries the full installation scope. Narrow it
-per agent with either or both of:
+By default the installation token carries the full installation scope. Narrow it per agent with either or both of:
 
 ```json
 {
   "repositories": ["some-repo", "another-repo"],
-  "permissions": { "contents": "write", "pull_requests": "write" }
+  "permissions": { "contents": "read", "pull_requests": "write" }
 }
 ```
 
+**`permissions` is a complete allowlist, not a patch.** GitHub grants *only* the keys you list and drops everything else — even permissions the GitHub App itself has. If you set `permissions` at all, you must list every scope the agent needs. Common cases:
+
+| The agent needs to… | Minimum `permissions` |
+| --- | --- |
+| Push commits / open PRs | `{ "contents": "write", "pull_requests": "write" }` |
+| Review PRs (incl. inline comments) | `{ "contents": "read", "pull_requests": "write" }` |
+| Read-only (clone, read issues) | `{ "contents": "read" }` |
+
+Omitting the `permissions` key entirely is the safe default — the token then carries whatever the App grants. `repositories` works the same way: list it and the token can only touch those repos.
+
+On launch, `agent-forge` prints the scope GitHub actually granted (`token` row in the summary); `agent-forge token --agent <name>` prints it to stderr. If a call fails with `403 Resource not accessible by integration`, check that row first.
+
 ## Add an agent
 
-You need a GitHub App first — its **App ID**, a **private key**, and an
-**installation**. If you don't have one yet, follow
-[docs/github-app.md](docs/github-app.md).
+You need a GitHub App first — its **App ID**, a **private key**, and an **installation**. If you don't have one yet, follow [docs/github-app.md](docs/github-app.md).
 
 ### Guided (recommended)
 
@@ -101,19 +99,11 @@ You need a GitHub App first — its **App ID**, a **private key**, and an
 agent-forge add
 ```
 
-You provide the **GitHub App ID** and the **path to its private key**. The wizard
-derives the rest from the GitHub API — slug (`botName`), bot user id, and the
-installation (auto-selected when there is only one) — asks for a label and an
-optional system prompt, mints a test token to confirm it works, and writes the
-entry. It writes to the resolved config path — the global registry
-(`~/.config/agent-forge/agents.json`) unless `$AGENT_FORGE_CONFIG` or an
-existing `./agents.json` redirects it.
+You provide the **GitHub App ID** and the **path to its private key**. The wizard derives the rest from the GitHub API — slug (`botName`), bot user id, and the account (asked only when the App is installed on more than one) — asks for a label and an optional system prompt, mints a test token to confirm it works, and writes the entry. It writes to the resolved config path — the global registry (`~/.config/agent-forge/agents.json`) unless `$AGENT_FORGE_CONFIG` or an existing `./agents.json` redirects it.
 
 ### Manual
 
-Copy one agent object inside the `agents` array and set unique values for `name`,
-`label`, `appId`, `installationId`, `botName`, `privateKeyPath`. Make sure the
-private key file exists and is readable.
+Copy one agent object inside the `agents` array and set unique values for `name`, `label`, `appId`, `botName`, `privateKeyPath` — plus `account` if the App has more than one installation. Make sure the private key file exists and is readable.
 
 ## Launch
 
@@ -140,15 +130,9 @@ agent-forge --help
 ### Provider-specific prompt behavior
 
 - `claude`: passed via `--append-system-prompt` (lands in the real system prompt)
-- `codex` / `antigravity` (`agy`): no CLI flag — identity comes from `AGENTS.md`
-  only (`agy --prompt` is headless `--print`; a codex positional arg is a fake
-  first user turn)
+- `codex` / `antigravity` (`agy`): no CLI flag — identity comes from `AGENTS.md` only (`agy --prompt` is headless `--print`; a codex positional arg is a fake first user turn)
 
-The launcher also writes `systemPrompt` into the provider's startup memory file
-in the working directory (`CLAUDE.md` for claude, `AGENTS.md` for codex and
-antigravity), inside a managed `agent-forge:identity` block. This keeps the
-identity in place for subagents the provider spawns, not just its main thread.
-The block is rewritten on each run and safe to keep in version control.
+The launcher also writes `systemPrompt` into the provider's startup memory file in the working directory (`CLAUDE.md` for claude, `AGENTS.md` for codex and antigravity), inside a managed `agent-forge:identity` block. This keeps the identity in place for subagents the provider spawns, not just its main thread. The block is rewritten on each run and safe to keep in version control.
 
 ## Token refresh
 
@@ -165,6 +149,8 @@ git config credential.https://github.com.helper \
   '!f() { test "$1" = get && echo username=x-access-token && echo "password=$(agent-forge token --agent ops-agent)"; }; f'
 ```
 
+Resolution still works here — the repo you push from is the one used. Setting `installationId` explicitly just skips the lookup on every push.
+
 ## Contributing
 
 See [CONTRIBUTING.md](.github/CONTRIBUTING.md) and [AGENTS.md](./AGENTS.md).

package/dist/launcher.cjs

@@ -4015,7 +4015,7 @@ var require_jsonwebtoken = __commonJS({
 });
 
 // src/launcher.js
-var import_node_child_process2 = require("node:child_process");
+var import_node_child_process3 = require("node:child_process");
 var import_node_path4 = require("node:path");
 var import_node_util3 = require("node:util");
 
@@ -5219,7 +5219,7 @@ ${r2}
 var import_node_fs = require("node:fs");
 var import_node_os = require("node:os");
 var import_node_path = require("node:path");
-var REQUIRED_FIELDS = ["name", "appId", "installationId", "privateKeyPath"];
+var REQUIRED_FIELDS = ["name", "appId", "privateKeyPath"];
 var SCHEMA_URL = "https://raw.githubusercontent.com/AshuLab/agent-forge/main/schema/agents.schema.json";
 var CONFIG_HOME = process.env.XDG_CONFIG_HOME || (0, import_node_path.join)((0, import_node_os.homedir)(), ".config");
 var GLOBAL_CONFIG = (0, import_node_path.join)(CONFIG_HOME, "agent-forge", "agents.json");
@@ -5270,25 +5270,31 @@ function validateAgents(agents) {
     seen.add(agent.name);
   });
 }
-function readAgents() {
+function readAgentsOrEmpty() {
   const path = resolveConfigPath();
-  if (!(0, import_node_fs.existsSync)(path)) {
-    throw new Error(
-      `No agents.json found. Run "agent-forge add" to create one at ${GLOBAL_CONFIG}, or point AGENT_FORGE_CONFIG at an existing file.`
-    );
-  }
+  if (!(0, import_node_fs.existsSync)(path)) return [];
   let parsed;
   try {
     parsed = JSON.parse((0, import_node_fs.readFileSync)(path, "utf8"));
   } catch (error) {
     throw new Error(`agents.json is not valid JSON: ${error.message}`);
   }
-  if (!Array.isArray(parsed.agents) || parsed.agents.length === 0) {
-    throw new Error("agents.json: no agents defined");
-  }
+  if (!Array.isArray(parsed.agents) || parsed.agents.length === 0) return [];
   validateAgents(parsed.agents);
   return parsed.agents;
 }
+function readAgents() {
+  const agents = readAgentsOrEmpty();
+  if (agents.length === 0) {
+    if (!(0, import_node_fs.existsSync)(resolveConfigPath())) {
+      throw new Error(
+        `No agents.json found. Run "agent-forge add" to create one at ${GLOBAL_CONFIG}, or point AGENT_FORGE_CONFIG at an existing file.`
+      );
+    }
+    throw new Error("agents.json: no agents defined");
+  }
+  return agents;
+}
 function listAgents() {
   const agents = readAgents();
   const rows = agents.map(
@@ -5298,6 +5304,7 @@ function listAgents() {
 }
 
 // src/github.js
+var import_node_child_process = require("node:child_process");
 var import_node_fs2 = require("node:fs");
 var import_node_os2 = require("node:os");
 var import_node_path2 = require("node:path");
@@ -5349,42 +5356,104 @@ async function resolveBotId(agent) {
   }
   return String(data.id);
 }
+async function listInstallations(jwtToken) {
+  const items = await githubApi("/app/installations", { jwtToken });
+  return items.map((item) => ({
+    id: String(item.id),
+    account: item.account?.login || item.account?.slug || "unknown"
+  }));
+}
 async function fetchAppMetadata(appId, privateKeyPath) {
   const privateKey = readPrivateKey(privateKeyPath, `app ${appId}`);
   const jwtToken = signAppJwt(appId, privateKey);
   const app = await githubApi("/app", { jwtToken });
-  const installations = await githubApi("/app/installations", { jwtToken });
   return {
     slug: app.slug,
     name: app.name || app.slug,
-    installations: installations.map((item) => ({
-      id: String(item.id),
-      account: item.account?.login || item.account?.slug || "unknown"
-    }))
+    installations: await listInstallations(jwtToken)
   };
 }
-async function generateGithubAppToken(agent) {
-  const privateKey = readPrivateKey(agent.privateKeyPath, agent.name || agent.appId);
-  const jwtToken = signAppJwt(agent.appId, privateKey);
+function pickInstallation(installations, agent) {
+  if (installations.length === 0) {
+    throw new Error(`GitHub App ${agent.appId} has no installations. Install it on an account or org first.`);
+  }
+  if (agent.account) {
+    const want = String(agent.account).toLowerCase();
+    const match = installations.find((item) => item.account.toLowerCase() === want);
+    if (!match) {
+      throw new Error(
+        `GitHub App ${agent.appId} is not installed on "${agent.account}". Installed on: ${installations.map((item) => item.account).join(", ")}.`
+      );
+    }
+    return match.id;
+  }
+  if (installations.length === 1) return installations[0].id;
+  throw new Error(
+    `GitHub App ${agent.appId} is installed on ${installations.length} accounts (${installations.map((item) => item.account).join(", ")}). Run inside a repo under one of them, or add "account" to agent "${agent.name}".`
+  );
+}
+function parseGithubRemote(url) {
+  const match = String(url).trim().match(/github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+  return match ? { owner: match[1], repo: match[2] } : null;
+}
+function currentRepoSlug() {
+  try {
+    const url = (0, import_node_child_process.execFileSync)("git", ["remote", "get-url", "origin"], {
+      stdio: ["ignore", "pipe", "ignore"]
+    }).toString();
+    return parseGithubRemote(url);
+  } catch {
+    return null;
+  }
+}
+async function installationForRepo(slug, jwtToken) {
+  try {
+    const data = await githubApi(`/repos/${slug.owner}/${slug.repo}/installation`, { jwtToken });
+    return String(data.id);
+  } catch {
+    return null;
+  }
+}
+async function resolveInstallationId(agent, jwtToken) {
+  if (agent.installationId) return String(agent.installationId);
+  const slug = currentRepoSlug();
+  if (slug) {
+    const id = await installationForRepo(slug, jwtToken);
+    if (id) return id;
+  }
+  return pickInstallation(await listInstallations(jwtToken), agent);
+}
+function buildTokenScope(agent) {
   const scope = {};
   if (Array.isArray(agent.repositories)) scope.repositories = agent.repositories;
   if (agent.permissions && typeof agent.permissions === "object") scope.permissions = agent.permissions;
-  const data = await githubApi(`/app/installations/${agent.installationId}/access_tokens`, {
+  return scope;
+}
+async function generateGithubAppToken(agent) {
+  const privateKey = readPrivateKey(agent.privateKeyPath, agent.name || agent.appId);
+  const jwtToken = signAppJwt(agent.appId, privateKey);
+  const installationId = await resolveInstallationId(agent, jwtToken);
+  const data = await githubApi(`/app/installations/${installationId}/access_tokens`, {
     jwtToken,
-    body: Object.keys(scope).length > 0 ? scope : {}
+    body: buildTokenScope(agent)
   });
-  return data.token;
+  return {
+    token: data.token,
+    // What GitHub actually granted, after both the App's config and our scoping.
+    permissions: data.permissions || {},
+    repositorySelection: data.repository_selection || "all"
+  };
 }
 
 // src/providers.js
-var import_node_child_process = require("node:child_process");
+var import_node_child_process2 = require("node:child_process");
 var PROVIDER_OPTIONS = [
   { value: "claude", label: "Claude", defaultCommand: "claude" },
   { value: "codex", label: "Codex", defaultCommand: "codex" },
   { value: "antigravity", label: "Antigravity", defaultCommand: "agy", aliases: ["antigravity", "agy"] }
 ];
 function isCommandInstalled(command) {
-  const result = (0, import_node_child_process.spawnSync)(process.platform === "win32" ? "where" : "which", [command], { stdio: "ignore" });
+  const result = (0, import_node_child_process2.spawnSync)(process.platform === "win32" ? "where" : "which", [command], { stdio: "ignore" });
   return result.status === 0;
 }
 function detectAvailableProviders() {
@@ -5477,8 +5546,8 @@ function keep(value) {
   }
   return value;
 }
-async function addAgentWizard() {
-  intro("Add agent");
+async function addAgentWizard({ embedded = false } = {}) {
+  if (!embedded) intro("Add agent");
   const appId = keep(
     await text({
       message: "GitHub App ID",
@@ -5500,14 +5569,14 @@ async function addAgentWizard() {
   if (meta.installations.length === 0) {
     throw new Error("This App has no installations. Install it on an account or org first.");
   }
-  let installationId = meta.installations[0].id;
+  let account;
   if (meta.installations.length === 1) {
-    note(`${meta.installations[0].account} (${installationId})`, "Installation");
+    note(`${meta.installations[0].account} \u2014 resolved automatically each run`, "Installation");
   } else {
-    installationId = keep(
+    account = keep(
       await select({
-        message: "Installation",
-        options: meta.installations.map((i2) => ({ value: i2.id, label: `${i2.account} (${i2.id})` }))
+        message: "Which account is this agent for?",
+        options: meta.installations.map((i2) => ({ value: i2.account, label: `${i2.account} (${i2.id})` }))
       })
     );
   }
@@ -5518,48 +5587,63 @@ async function addAgentWizard() {
     name,
     label,
     appId,
-    installationId,
     botName: meta.slug,
     privateKeyPath,
+    ...account ? { account } : {},
     ...systemPrompt ? { systemPrompt } : {}
   };
   const check = spinner();
   check.start("Minting a test token");
-  await generateGithubAppToken(agent);
-  check.stop("Test token ok");
+  const { permissions } = await generateGithubAppToken(agent);
+  const scope = Object.entries(permissions).map(([name2, level]) => `${name2}:${level}`).join(" ");
+  check.stop(scope ? `Test token ok \xB7 ${scope}` : "Test token ok");
   const path = addAgent(agent);
-  outro(`Wrote ${path}`);
+  if (embedded) {
+    note(`Wrote ${path}`, "Agent added");
+  } else {
+    outro(`Wrote ${path}`);
+  }
+  return agent.name;
 }
 async function interactiveSelection(defaults = {}) {
   const availableProviders = detectAvailableProviders();
   if (availableProviders.length === 0) {
     throw new Error("No installed provider was detected. Install claude, codex, or antigravity before running the launcher.");
   }
-  let providerChoice = defaults.provider;
-  if (providerChoice && !availableProviders.some((provider) => provider.value === providerChoice)) {
-    throw new Error(`The provider ${providerChoice} is not installed or not available in PATH.`);
-  }
-  if (!providerChoice) {
-    providerChoice = keep(
-      await select({
-        message: "Which provider do you want to use?",
-        options: availableProviders.map((provider) => ({ value: provider.value, label: provider.label }))
-      })
-    );
+  let agents = readAgentsOrEmpty();
+  if (agents.length === 0 && !defaults.agent) {
+    note("No agents configured yet. Each agent is a GitHub App identity the launcher runs under.", "First run");
+    if (!keep(await confirm({ message: "Add one now?" }))) {
+      cancel(`Run "agent-forge add" when you're ready.`);
+      process.exit(0);
+    }
+    await addAgentWizard({ embedded: true });
+    agents = readAgents();
   }
-  const agents = readAgents();
   let agentChoice = defaults.agent;
   if (agentChoice && !agents.some((agent) => agent.name === agentChoice)) {
     throw new Error(`Agent not found: ${agentChoice}`);
   }
   if (!agentChoice) {
-    agentChoice = keep(
+    agentChoice = agents.length === 1 ? agents[0].name : keep(
       await select({
         message: "Which agent do you want to launch?",
         options: agents.map((agent) => ({ value: agent.name, label: agent.label || agent.name }))
       })
     );
   }
+  let providerChoice = defaults.provider;
+  if (providerChoice && !availableProviders.some((provider) => provider.value === providerChoice)) {
+    throw new Error(`The provider ${providerChoice} is not installed or not available in PATH.`);
+  }
+  if (!providerChoice) {
+    providerChoice = availableProviders.length === 1 ? availableProviders[0].value : keep(
+      await select({
+        message: "Which provider do you want to use?",
+        options: availableProviders.map((provider) => ({ value: provider.value, label: provider.label }))
+      })
+    );
+  }
   if (!keep(await confirm({ message: `Launch ${agentChoice} with ${providerChoice}?` }))) {
     cancel("Cancelled.");
     process.exit(0);
@@ -5619,7 +5703,7 @@ async function launchAgent(agentName, providerName) {
   const providerInfo = getProviderInfo(providerName, agent);
   const s = spinner();
   s.start("Minting installation token");
-  const githubToken = await generateGithubAppToken(agent);
+  const { token: githubToken, permissions, repositorySelection } = await generateGithubAppToken(agent);
   const botId = await resolveBotId(agent);
   const gitIdentity = buildGitIdentity(agent, botId);
   s.stop(`Token ready for ${(0, import_node_util3.styleText)("green", gitIdentity.GIT_AUTHOR_NAME)}`);
@@ -5630,17 +5714,20 @@ async function launchAgent(agentName, providerName) {
     GH_TOKEN: githubToken,
     ...gitIdentity
   };
+  const scopeEntries = Object.entries(permissions);
+  const scopeText = scopeEntries.length ? scopeEntries.map(([name, level]) => `${name}:${level}`).join(" ") : "full installation scope";
   const row = (label, value) => `${(0, import_node_util3.styleText)("dim", label.padEnd(10))}${value}`;
   const summary = [
     row("provider", (0, import_node_util3.styleText)(["cyan", "bold"], providerName)),
-    row("identity", (0, import_node_util3.styleText)("green", gitIdentity.GIT_AUTHOR_NAME))
+    row("identity", (0, import_node_util3.styleText)("green", gitIdentity.GIT_AUTHOR_NAME)),
+    row("token", (0, import_node_util3.styleText)("dim", repositorySelection === "selected" ? `${scopeText} \xB7 selected repos` : scopeText))
   ];
   if (identityFile) {
     summary.push(row("memory", (0, import_node_util3.styleText)("dim", (0, import_node_path4.relative)(process.cwd(), identityFile) || identityFile)));
   }
   note(summary.join("\n"), (0, import_node_util3.styleText)("bold", agent.label || agent.name));
   const providerArgs = getProviderPromptArgs(providerName, agent);
-  const child = (0, import_node_child_process2.spawn)(providerInfo.command, providerArgs, {
+  const child = (0, import_node_child_process3.spawn)(providerInfo.command, providerArgs, {
     stdio: "inherit",
     env: runtimeEnv,
     shell: false
@@ -5672,7 +5759,11 @@ async function main() {
     if (!flags.agent) {
       throw new Error("Usage: agent-forge token --agent <name>");
     }
-    process.stdout.write(await generateGithubAppToken(findAgent(flags.agent)));
+    const minted = await generateGithubAppToken(findAgent(flags.agent));
+    const scope = Object.entries(minted.permissions).map(([name, level]) => `${name}:${level}`).join(" ");
+    if (scope) process.stderr.write(`scope: ${scope}${minted.repositorySelection === "selected" ? " (selected repos)" : ""}
+`);
+    process.stdout.write(minted.token);
     return;
   }
   showIntro();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashulab/agent-forge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Give claude/codex/antigravity their own GitHub identity: a bot account, a scoped token minted per run, git attribution to match",
   "license": "MIT",
   "author": "Diego Ghersi <ghersidl@gmail.com>",

package/schema/agents.example.json

@@ -5,7 +5,6 @@
       "name": "ops-agent",
       "label": "Ops Agent",
       "appId": "000000",
-      "installationId": "00000000",
       "botName": "ops-agent",
       "privateKeyPath": "~/.ssh/ops-agent.private-key.pem",
       "systemPrompt": "You are Ops Agent, a senior DevOps engineer. Prefer safe, minimal changes and explain operational risks clearly."

package/schema/agents.schema.json

@@ -11,7 +11,7 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["name", "label", "appId", "installationId", "botName", "privateKeyPath"],
+        "required": ["name", "label", "appId", "botName", "privateKeyPath"],
         "properties": {
           "name": {
             "type": "string",
@@ -25,9 +25,13 @@
             "type": "string",
             "description": "GitHub App ID (numeric, stored as a string)"
           },
+          "account": {
+            "type": "string",
+            "description": "Account/org login where the App is installed. Fallback for installation-id resolution when you run outside a matching repo. Needed only when the App has more than one installation. Resolution order: repo owner, then account, then the sole installation."
+          },
           "installationId": {
             "type": "string",
-            "description": "GitHub App installation ID for the target account/org"
+            "description": "Optional override. Normally the installation id is resolved (repo owner, then account, then the sole installation). Set this to pin a specific id or skip the lookup (offline, or in a git credential helper)."
           },
           "botName": {
             "type": "string",
@@ -61,7 +65,7 @@
           "permissions": {
             "type": "object",
             "additionalProperties": { "type": "string" },
-            "description": "Least-privilege: limit the installation token permissions, e.g. { \"contents\": \"write\" }"
+            "description": "Least-privilege: complete allowlist of installation token permissions. GitHub grants ONLY these keys and drops the rest, even ones the App has. Reviewing PRs needs { \"contents\": \"read\", \"pull_requests\": \"write\" }. Omit this key to inherit the App's full grant."
           },
           "providers": {
             "type": "object",