fix(agents): hired OpenCode agents inherit the hiring agent's OpenRouter key reference (#19977)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents can hire teammates. A hired agent inherits the credential
references of the agent that hired it, so it can run without a separate
setup step.
> - The inheritance map covers Claude, Codex and Grok. It does not cover
OpenCode.
> - An OpenCode CEO hires a QA agent. The board approves the hire. The
new agent has no OpenRouter key, and verification fails with
`harness_auth_failed`.
> - The person approved a working hire, but they get a broken agent that
they must fix by hand.
> - This pull request adds `OPENROUTER_API_KEY` to the inheritance map
for `opencode_local`.
> - The benefit is that an approved OpenCode hire becomes ready with the
same account as the agent that proposed it.

## Linked Issues or Issue Description

Refs #13268 (the change that added credential inheritance for hires).

**What happened**

A native OpenCode CEO (provider `opencode`, `OPENROUTER_API_KEY` stored
as a `secret_ref`) proposed a QA hire with `inheritRuntimeFrom: caller`.
The company requires board approval for new agents. The board approved
the hire. The agent lifecycle verification then failed with
`failureCode: "harness_auth_failed"`, and the agent did not become
ready. The hired agent's `adapterConfig` had no `env`.

**Expected behavior**

The hired agent gets the same OpenRouter secret reference as the hiring
agent. After approval, verification passes and the agent becomes ready.

**Steps to reproduce**

1. Create a company with `requireBoardApprovalForNewAgents: true`.
2. Create a `paperclip_runner` agent with `provider: "opencode"` and
`env.OPENROUTER_API_KEY` as a `secret_ref`.
3. As that agent, call `POST /api/companies/:companyId/agent-hires` with
`adapterType: "paperclip_runner"` and `inheritRuntimeFrom: "caller"`.
4. Read the new agent. Its `adapterConfig.env` has no
`OPENROUTER_API_KEY`.
5. Approve the hire. Verification fails with `harness_auth_failed`.

## What Changed

- `server/src/routes/agents.ts`: add `opencode_local:
["OPENROUTER_API_KEY"]` to `INHERITABLE_AGENT_CREDENTIAL_ENV_KEYS`. This
is the key that AI connections bind for `opencode_local`
(`packages/shared/src/ai-connections.ts`).
- `server/src/__tests__/agent-hire-auth-inheritance-routes.test.ts`: add
a regression test. A native OpenCode parent hires with
`inheritRuntimeFrom: caller` under board approval. The child gets the
same `secret_ref` (with its version). The plain
`OPENCODE_CONFIG_CONTENT` value is not copied.

## Verification

- `cd server && pnpm exec vitest run
src/__tests__/agent-hire-auth-inheritance-routes.test.ts`: 27 passed.
The new test fails without the route change (`expected undefined to
match object { type: 'secret_ref', … }`).
- `cd server && pnpm exec vitest run
src/__tests__/agent-adapter-validation-routes.test.ts
src/__tests__/agent-permissions-routes.test.ts
src/__tests__/agent-hire-ai-connections.test.ts
src/__tests__/ai-connections.test.ts`: 446 passed.
- The failure was seen in the `agents.hire-needs-approval` chat eval
(runner-opencode profile). The approved hire failed verification with
`harness_auth_failed`. An end-to-end rerun with this change follows on
the eval branch.

## Risks

- Low risk. The existing inheritance rules still apply: only
`secret_ref` and `user_secret_ref` values are copied, a key the hire
request supplies wins, the parent must be in the same company and use
the same harness, and a parent with a managed AI connection passes
nothing.
- An OpenCode hire can now use the parent's OpenRouter account. This
matches the existing behavior for Claude, Codex and Grok hires.
- Other OpenCode provider keys (for example `OPENAI_API_KEY`) are not
added. AI connections bind only OpenRouter for `opencode_local`.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code
execution in Claude Code.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

server/src/__tests__/agent-hire-auth-inheritance-routes.test.ts

@@ -265,6 +265,28 @@ describeEmbeddedPostgres("hired agent provider credential inheritance", () => {
     expect(childEnvOf(res).XAI_API_KEY).toMatchObject({ type: "secret_ref", secretId: secret.id });
   });
 
+  it("inherits a native OpenCode parent's OPENROUTER_API_KEY reference when the hire inherits the caller runtime", async () => {
+    const companyId = await seedCompany();
+    await db.update(companies).set({ requireBoardApprovalForNewAgents: true }).where(eq(companies.id, companyId));
+    const secret = await createCompanySecret(companyId, "openrouter-parent-key");
+    const parent = await seedParentAgent(companyId, "paperclip_runner", {});
+    await db.update(agents).set({ adapterConfig: {
+      provider: "opencode", model: "openrouter/deepseek/deepseek-v4.1-flash-1017", opencodePermissionMode: "allow",
+      env: { OPENROUTER_API_KEY: secretRef(secret.id, { version: "latest" }), OPENCODE_CONFIG_CONTENT: "{\"provider\":{}}" },
+    } }).where(eq(agents.id, parent.id));
+
+    const res = await hire(agentActor(companyId, parent.id), companyId, {
+      name: "OpenCode Child", role: "qa", adapterType: "paperclip_runner", inheritRuntimeFrom: "caller",
+    });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect(res.body.agent.status).toBe("pending_approval");
+    const [child] = await db.select().from(agents).where(eq(agents.id, res.body.agent.id));
+    const env = (child!.adapterConfig as { env?: Record<string, unknown> }).env ?? {};
+    expect(env.OPENROUTER_API_KEY).toMatchObject({ type: "secret_ref", secretId: secret.id, version: "latest" });
+    expect(env.OPENCODE_CONFIG_CONTENT).toBeUndefined();
+  });
+
   it.each(["create", "hire"] as const)("blocks native Claude credential redirection before %s inheritance", async mode => {
     const companyId = await seedCompany();
     const secret = await createCompanySecret(companyId, "fixture-parent-credential");

server/src/routes/agents.ts

@@ -2302,6 +2302,9 @@ export function agentRoutes(
     claude_local: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"],
     codex_local: ["OPENAI_API_KEY", "CODEX_API_KEY"],
     grok_local: ["XAI_API_KEY"],
+    // OpenCode reaches its models through OpenRouter, the provider account
+    // AI connections bind for opencode_local.
+    opencode_local: ["OPENROUTER_API_KEY"],
   };
 
   function isInheritableCredentialReference(value: unknown): value is Record<string, unknown> {