feat: add scout references

Author: nexxeln

packages/opencode/src/agent/agent.ts

@@ -26,6 +26,9 @@ import * as OtelTracer from "@effect/opentelemetry/Tracer"
 import { zod } from "@/util/effect-zod"
 import { withStatics, type DeepMutable } from "@/util/schema"
 
+type ReferenceEntry = NonNullable<Config.Info["reference"]>[string]
+type ResolvedReference = { kind: "git"; repository: string; branch?: string } | { kind: "local"; path: string }
+
 export const Info = Schema.Struct({
   name: Schema.String,
   description: Schema.optional(Schema.String),
@@ -82,7 +85,11 @@ export const layer = Layer.effect(
       Effect.fn("Agent.state")(function* (ctx) {
         const cfg = yield* config.get()
         const skillDirs = yield* skill.dirs()
-        const whitelistedDirs = [Truncate.GLOB, path.join(Global.Path.tmp, "*"), ...skillDirs.map((dir) => path.join(dir, "*"))]
+        const whitelistedDirs = [
+          Truncate.GLOB,
+          path.join(Global.Path.tmp, "*"),
+          ...skillDirs.map((dir) => path.join(dir, "*")),
+        ]
         const readonlyExternalDirectory = {
           "*": "ask",
           ...Object.fromEntries(whitelistedDirs.map((dir) => [dir, "allow"])),
@@ -291,6 +298,73 @@ export const layer = Layer.effect(
           item.permission = Permission.merge(item.permission, Permission.fromConfig(value.permission ?? {}))
         }
 
+        function referencePath(value: string) {
+          if (value.startsWith("~/")) return path.join(Global.Path.home, value.slice(2))
+          return path.isAbsolute(value)
+            ? value
+            : path.resolve(ctx.worktree === "/" ? ctx.directory : ctx.worktree, value)
+        }
+
+        function resolveReference(reference: ReferenceEntry): ResolvedReference {
+          if (typeof reference === "string") {
+            if (reference.startsWith(".") || reference.startsWith("/") || reference.startsWith("~")) {
+              return { kind: "local", path: referencePath(reference) }
+            }
+            return { kind: "git", repository: reference }
+          }
+          if ("path" in reference) return { kind: "local", path: referencePath(reference.path) }
+          return { kind: "git", repository: reference.repository, branch: reference.branch }
+        }
+
+        function referencePrompt(name: string, reference: ResolvedReference) {
+          if (reference.kind === "local") {
+            return [
+              PROMPT_SCOUT,
+              `You are Scout reference @${name}. This reference points to a local directory outside or alongside the current workspace.`,
+              `Local directory: ${reference.path}`,
+              `When invoked, inspect this directory as the primary reference source. Prefer repo_overview with path ${JSON.stringify(reference.path)} before broader searches. Do not edit files.`,
+            ].join("\n\n")
+          }
+
+          return [
+            PROMPT_SCOUT,
+            `You are Scout reference @${name}. This reference points to a git repository.`,
+            `Repository: ${reference.repository}`,
+            ...(reference.branch ? [`Branch/ref: ${reference.branch}`] : []),
+            `When invoked, clone or refresh this repository with repo_clone, then inspect the cached repository as the primary reference source. Do not edit files.`,
+          ].join("\n\n")
+        }
+
+        for (const [name, reference] of Object.entries(cfg.reference ?? {})) {
+          if (agents[name]) continue
+          const resolved = resolveReference(reference)
+          const localPath = resolved.kind === "local" ? resolved.path : undefined
+          agents[name] = {
+            name,
+            description:
+              resolved.kind === "local"
+                ? `Scout reference for local directory ${resolved.path}`
+                : `Scout reference for repository ${resolved.repository}`,
+            permission: Permission.merge(
+              agents.scout.permission,
+              Permission.fromConfig(
+                localPath
+                  ? {
+                      external_directory: {
+                        [localPath]: "allow",
+                        [path.join(localPath, "*")]: "allow",
+                      },
+                    }
+                  : {},
+              ),
+            ),
+            prompt: referencePrompt(name, resolved),
+            options: { reference },
+            mode: "subagent",
+            native: false,
+          }
+        }
+
         // Ensure Truncate.GLOB is allowed unless explicitly configured
         for (const name in agents) {
           const agent = agents[name]

packages/opencode/src/config/config.ts

@@ -39,6 +39,7 @@ import { ConfigPaths } from "./paths"
 import { ConfigPermission } from "./permission"
 import { ConfigPlugin } from "./plugin"
 import { ConfigProvider } from "./provider"
+import { ConfigReference } from "./reference"
 import { ConfigServer } from "./server"
 import { ConfigSkills } from "./skills"
 import { ConfigVariable } from "./variable"
@@ -114,6 +115,9 @@ export const Info = Schema.Struct({
     description: "Command configuration, see https://opencode.ai/docs/commands",
   }),
   skills: Schema.optional(ConfigSkills.Info).annotate({ description: "Additional skill folder paths" }),
+  reference: Schema.optional(ConfigReference.Info).annotate({
+    description: "Named git or local directory references that can be @ mentioned as Scout-backed subagents",
+  }),
   watcher: Schema.optional(
     Schema.Struct({
       ignore: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),

packages/opencode/src/config/reference.ts

@@ -0,0 +1,27 @@
+export * as ConfigReference from "./reference"
+
+import { Schema } from "effect"
+import { zod } from "@/util/effect-zod"
+import { withStatics } from "@/util/schema"
+
+const Git = Schema.Struct({
+  repository: Schema.String.annotate({
+    description: "Git repository URL, host/path reference, or GitHub owner/repo shorthand",
+  }),
+  branch: Schema.optional(Schema.String).annotate({
+    description: "Branch or ref Scout should clone and inspect",
+  }),
+})
+
+const Local = Schema.Struct({
+  path: Schema.String.annotate({
+    description: "Absolute path, ~/ path, or workspace-relative path to a local reference directory",
+  }),
+})
+
+export const Entry = Schema.Union([Schema.String, Git, Local]).annotate({ identifier: "ReferenceConfigEntry" })
+
+export const Info = Schema.Record(Schema.String, Entry)
+  .annotate({ identifier: "ReferenceConfig" })
+  .pipe(withStatics((s) => ({ zod: zod(s) })))
+export type Info = Schema.Schema.Type<typeof Info>

packages/opencode/src/tool/repo_clone.ts

@@ -14,6 +14,9 @@ export const Parameters = Schema.Struct({
   refresh: Schema.optional(Schema.Boolean).annotate({
     description: "When true, fetches the latest remote state into the managed cache",
   }),
+  branch: Schema.optional(Schema.String).annotate({
+    description: "Branch or ref to clone and inspect",
+  }),
 })
 
 type Metadata = {
@@ -26,16 +29,19 @@ type Metadata = {
   branch?: string
 }
 
-function statusForRepository(input: { reuse: boolean; refresh?: boolean }) {
+function statusForRepository(input: { reuse: boolean; refresh?: boolean; branchMatches?: boolean }) {
   if (!input.reuse) return "cloned" as const
+  if (input.branchMatches === false) return "refreshed" as const
   if (input.refresh) return "refreshed" as const
   return "cached" as const
 }
 
 function resetTarget(input: {
+  requestedBranch?: string
   remoteHead: { code: number; stdout: string }
   branch: { code: number; stdout: string }
 }) {
+  if (input.requestedBranch) return `origin/${input.requestedBranch}`
   if (input.remoteHead.code === 0 && input.remoteHead.stdout) {
     return input.remoteHead.stdout.replace(/^refs\/remotes\//, "")
   }
@@ -45,6 +51,14 @@ function resetTarget(input: {
   return "HEAD"
 }
 
+function validateBranch(branch: string) {
+  if (!/^[A-Za-z0-9/_.-]+$/.test(branch) || branch.startsWith("-") || branch.includes("..")) {
+    throw new Error(
+      "Branch must contain only alphanumeric characters, /, _, ., and -, and cannot start with - or contain ..",
+    )
+  }
+}
+
 export const RepoCloneTool = Tool.define<typeof Parameters, Metadata, AppFileSystem.Service | Git.Service>(
   "repo_clone",
   Effect.gen(function* () {
@@ -57,7 +71,9 @@ export const RepoCloneTool = Tool.define<typeof Parameters, Metadata, AppFileSys
       execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context<Metadata>) =>
         Effect.gen(function* () {
           const reference = parseRepositoryReference(params.repository)
-          if (!reference) throw new Error("Repository must be a git URL, host/path reference, or GitHub owner/repo shorthand")
+          if (!reference)
+            throw new Error("Repository must be a git URL, host/path reference, or GitHub owner/repo shorthand")
+          if (params.branch) validateBranch(params.branch)
 
           const repository = reference.label
           const remote = reference.remote
@@ -73,6 +89,7 @@ export const RepoCloneTool = Tool.define<typeof Parameters, Metadata, AppFileSys
               remote,
               path: localPath,
               refresh: Boolean(params.refresh),
+              branch: params.branch,
             },
           })
 
@@ -87,37 +104,74 @@ export const RepoCloneTool = Tool.define<typeof Parameters, Metadata, AppFileSys
                 const origin = hasGitDir
                   ? yield* git.run(["config", "--get", "remote.origin.url"], { cwd: localPath })
                   : undefined
-                const originReference = origin?.exitCode === 0 ? parseRepositoryReference(origin.text().trim()) : undefined
-                const reuse = hasGitDir && Boolean(originReference && sameRepositoryReference(originReference, cloneTarget))
+                const originReference =
+                  origin?.exitCode === 0 ? parseRepositoryReference(origin.text().trim()) : undefined
+                const reuse =
+                  hasGitDir && Boolean(originReference && sameRepositoryReference(originReference, cloneTarget))
                 if (exists && !reuse) {
                   yield* fs.remove(localPath, { recursive: true }).pipe(Effect.orDie)
                 }
 
-                const status = statusForRepository({ reuse, refresh: params.refresh })
+                const currentBranch = hasGitDir ? yield* git.branch(localPath) : undefined
+                const status = statusForRepository({
+                  reuse,
+                  refresh: params.refresh,
+                  branchMatches: params.branch ? currentBranch === params.branch : undefined,
+                })
 
                 if (status === "cloned") {
-                  const clone = yield* git.run(["clone", "--depth", "100", remote, localPath], { cwd: path.dirname(localPath) })
+                  const clone = yield* git.run(
+                    [
+                      "clone",
+                      "--depth",
+                      "100",
+                      ...(params.branch ? ["--branch", params.branch] : []),
+                      remote,
+                      localPath,
+                    ],
+                    { cwd: path.dirname(localPath) },
+                  )
                   if (clone.exitCode !== 0) {
-                    throw new Error(clone.stderr.toString().trim() || clone.text().trim() || `Failed to clone ${repository}`)
+                    throw new Error(
+                      clone.stderr.toString().trim() || clone.text().trim() || `Failed to clone ${repository}`,
+                    )
                   }
                 }
 
                 if (status === "refreshed") {
                   const fetch = yield* git.run(["fetch", "--all", "--prune"], { cwd: localPath })
                   if (fetch.exitCode !== 0) {
-                    throw new Error(fetch.stderr.toString().trim() || fetch.text().trim() || `Failed to refresh ${repository}`)
+                    throw new Error(
+                      fetch.stderr.toString().trim() || fetch.text().trim() || `Failed to refresh ${repository}`,
+                    )
+                  }
+
+                  if (params.branch) {
+                    const checkout = yield* git.run(["checkout", "-B", params.branch, `origin/${params.branch}`], {
+                      cwd: localPath,
+                    })
+                    if (checkout.exitCode !== 0) {
+                      throw new Error(
+                        checkout.stderr.toString().trim() ||
+                          checkout.text().trim() ||
+                          `Failed to checkout ${params.branch}`,
+                      )
+                    }
                   }
 
                   const remoteHead = yield* git.run(["symbolic-ref", "refs/remotes/origin/HEAD"], { cwd: localPath })
                   const branch = yield* git.run(["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: localPath })
                   const target = resetTarget({
+                    requestedBranch: params.branch,
                     remoteHead: { code: remoteHead.exitCode, stdout: remoteHead.text().trim() },
                     branch: { code: branch.exitCode, stdout: branch.text().trim() },
                   })
 
                   const reset = yield* git.run(["reset", "--hard", target], { cwd: localPath })
                   if (reset.exitCode !== 0) {
-                    throw new Error(reset.stderr.toString().trim() || reset.text().trim() || `Failed to reset ${repository}`)
+                    throw new Error(
+                      reset.stderr.toString().trim() || reset.text().trim() || `Failed to reset ${repository}`,
+                    )
                   }
                 }
 

packages/opencode/test/agent/agent.test.ts

@@ -123,6 +123,59 @@ test("scout agent allows repo cloning and repo cache reads", async () => {
   })
 })
 
+test("reference config creates scout-backed subagents", async () => {
+  await using tmp = await tmpdir({
+    config: {
+      reference: {
+        effect: "github.com/effect/effect-smol",
+        effectFull: {
+          repository: "Effect-TS/effect",
+          branch: "main",
+        },
+        localdocs: "../docs",
+        localdocsFull: {
+          path: "../local-docs",
+        },
+      },
+    },
+  })
+  await Instance.provide({
+    directory: tmp.path,
+    fn: async () => {
+      const effect = await load(tmp.path, (svc) => svc.get("effect"))
+      const effectFull = await load(tmp.path, (svc) => svc.get("effectFull"))
+      const local = await load(tmp.path, (svc) => svc.get("localdocs"))
+      const localFull = await load(tmp.path, (svc) => svc.get("localdocsFull"))
+
+      expect(effect).toBeDefined()
+      expect(effect?.mode).toBe("subagent")
+      expect(effect?.prompt).toContain("Repository: github.com/effect/effect-smol")
+      expect(evalPerm(effect, "repo_clone")).toBe("allow")
+
+      expect(effectFull).toBeDefined()
+      expect(effectFull?.mode).toBe("subagent")
+      expect(effectFull?.prompt).toContain("Repository: Effect-TS/effect")
+      expect(effectFull?.prompt).toContain("Branch/ref: main")
+      expect(evalPerm(effectFull, "repo_clone")).toBe("allow")
+
+      expect(local).toBeDefined()
+      expect(local?.mode).toBe("subagent")
+      expect(local?.prompt).toContain(`Local directory: ${path.resolve(tmp.path, "../docs")}`)
+      expect(
+        Permission.evaluate(
+          "external_directory",
+          path.join(path.resolve(tmp.path, "../docs"), "README.md"),
+          local!.permission,
+        ).action,
+      ).toBe("allow")
+
+      expect(localFull).toBeDefined()
+      expect(localFull?.mode).toBe("subagent")
+      expect(localFull?.prompt).toContain(`Local directory: ${path.resolve(tmp.path, "../local-docs")}`)
+    },
+  })
+})
+
 test("general agent denies todo tools", async () => {
   await using tmp = await tmpdir()
   await Instance.provide({