@neurocode-ai/core 1.18.8

package/src/permission.ts

@@ -0,0 +1,310 @@
+export * as PermissionV2 from "./permission"
+
+import { makeLocationNode } from "./effect/app-node"
+import { Context, Deferred, Effect as EffectRuntime, Layer, Schema } from "effect"
+import { Permission } from "@neurocode-ai/schema/permission"
+import { EventV2 } from "./event"
+import { Location } from "./location"
+import { AgentV2 } from "./agent"
+import { SessionV2 } from "./session"
+import { SessionStore } from "./session/store"
+import { Wildcard } from "./util/wildcard"
+import { PermissionSaved } from "./permission/saved"
+
+export { Effect, Rule, Ruleset } from "@neurocode-ai/schema/permission"
+const missingAgentPermissions: Permission.Ruleset = [{ action: "*", resource: "*", effect: "deny" }]
+
+export const ID = Permission.ID
+export type ID = typeof ID.Type
+
+export const Source = Permission.Source
+export type Source = typeof Source.Type
+
+const RequestFields = {
+  sessionID: Permission.Request.fields.sessionID,
+  action: Permission.Request.fields.action,
+  resources: Permission.Request.fields.resources,
+  save: Permission.Request.fields.save,
+  metadata: Permission.Request.fields.metadata,
+  source: Permission.Request.fields.source,
+}
+
+export const Request = Permission.Request
+export type Request = typeof Request.Type
+
+export const Reply = Permission.Reply
+export type Reply = typeof Reply.Type
+
+export const AssertInput = Schema.Struct({
+  id: ID.pipe(Schema.optional),
+  ...RequestFields,
+  agent: AgentV2.ID.pipe(Schema.optional),
+}).annotate({ identifier: "PermissionV2.AssertInput" })
+export type AssertInput = typeof AssertInput.Type
+
+export const ReplyInput = Schema.Struct({
+  requestID: ID,
+  reply: Reply,
+  message: Schema.String.pipe(Schema.optional),
+}).annotate({ identifier: "PermissionV2.ReplyInput" })
+export type ReplyInput = typeof ReplyInput.Type
+
+export const AskResult = Schema.Struct({
+  id: ID,
+  effect: Permission.Effect,
+}).annotate({ identifier: "PermissionV2.AskResult" })
+export type AskResult = typeof AskResult.Type
+
+export const Event = Permission.Event
+
+export class DeclinedError extends Schema.TaggedErrorClass<DeclinedError>()("PermissionV2.DeclinedError", {}) {}
+
+export class CorrectedError extends Schema.TaggedErrorClass<CorrectedError>()("PermissionV2.CorrectedError", {
+  feedback: Schema.String,
+}) {}
+
+export class BlockedError extends Schema.TaggedErrorClass<BlockedError>()("PermissionV2.BlockedError", {
+  rules: Permission.Ruleset,
+}) {}
+
+export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("PermissionV2.NotFoundError", {
+  requestID: ID,
+}) {}
+
+export type Error = BlockedError | CorrectedError
+
+export function evaluate(action: string, resource: string, ...rulesets: Permission.Ruleset[]): Permission.Rule {
+  return (
+    rulesets
+      .flat()
+      .findLast((rule) => Wildcard.match(action, rule.action) && Wildcard.match(resource, rule.resource)) ?? {
+      action,
+      resource: "*",
+      effect: "ask",
+    }
+  )
+}
+
+export function merge(...rulesets: Permission.Ruleset[]): Permission.Ruleset {
+  return rulesets.flat()
+}
+
+export interface Interface {
+  readonly ask: (input: AssertInput) => EffectRuntime.Effect<AskResult, SessionV2.NotFoundError>
+  readonly assert: (input: AssertInput) => EffectRuntime.Effect<void, Error | SessionV2.NotFoundError>
+  readonly reply: (input: ReplyInput) => EffectRuntime.Effect<void, NotFoundError>
+  readonly get: (id: ID) => EffectRuntime.Effect<Request | undefined>
+  readonly forSession: (sessionID: SessionV2.ID) => EffectRuntime.Effect<ReadonlyArray<Request>>
+  readonly list: () => EffectRuntime.Effect<ReadonlyArray<Request>>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@neurocode/v2/Permission") {}
+
+interface Pending {
+  readonly request: Request
+  readonly agent?: AgentV2.ID
+  readonly deferred: Deferred.Deferred<void, DeclinedError | CorrectedError>
+}
+
+const layer = Layer.effect(
+  Service,
+  EffectRuntime.gen(function* () {
+    const events = yield* EventV2.Service
+    const location = yield* Location.Service
+    const agents = yield* AgentV2.Service
+    const sessions = yield* SessionStore.Service
+    const saved = yield* PermissionSaved.Service
+    const pending = new Map<ID, Pending>()
+
+    yield* EffectRuntime.addFinalizer(() =>
+      EffectRuntime.forEach(pending.values(), (item) => Deferred.fail(item.deferred, new DeclinedError()), {
+        discard: true,
+      }).pipe(
+        EffectRuntime.ensuring(
+          EffectRuntime.sync(() => {
+            pending.clear()
+          }),
+        ),
+      ),
+    )
+
+    const savedRules = EffectRuntime.fnUntraced(function* () {
+      return (yield* saved.list({ projectID: location.project.id })).map(
+        (item): Permission.Rule => ({ action: item.action, resource: item.resource, effect: "allow" }),
+      )
+    })
+
+    const configured = EffectRuntime.fn("PermissionV2.configured")(function* (
+      sessionID: SessionV2.ID,
+      agentID?: AgentV2.ID,
+    ) {
+      const session = yield* sessions.get(sessionID)
+      if (!session) return yield* new SessionV2.NotFoundError({ sessionID })
+      const agent = yield* agents.resolve(agentID ?? session.agent)
+      return agent?.permissions ?? missingAgentPermissions
+    })
+
+    function denied(input: AssertInput, rules: Permission.Ruleset) {
+      return input.resources.some((resource) => evaluate(input.action, resource, rules).effect === "deny")
+    }
+
+    function relevant(input: AssertInput, rules: Permission.Ruleset) {
+      return rules.filter((rule) => Wildcard.match(input.action, rule.action))
+    }
+
+    const evaluateInput = EffectRuntime.fnUntraced(function* (input: AssertInput) {
+      const rules = yield* configured(input.sessionID, input.agent)
+      if (denied(input, rules)) return { effect: "deny" as const, rules }
+      const all = [...rules, ...(yield* savedRules())]
+      const effects = input.resources.map((resource) => evaluate(input.action, resource, all).effect)
+      const effect: Permission.Effect = effects.includes("deny") ? "deny" : effects.includes("ask") ? "ask" : "allow"
+      return { effect, rules: all }
+    })
+
+    function request(input: AssertInput): Request {
+      return {
+        id: input.id ?? ID.create(),
+        sessionID: input.sessionID,
+        action: input.action,
+        resources: input.resources,
+        save: input.save,
+        metadata: input.metadata,
+        source: input.source,
+      }
+    }
+
+    const create = (request: Request, agent?: AgentV2.ID) =>
+      EffectRuntime.uninterruptible(
+        EffectRuntime.gen(function* () {
+          const deferred = yield* Deferred.make<void, DeclinedError | CorrectedError>()
+          const item = { request, agent, deferred }
+          if (pending.has(request.id)) return yield* EffectRuntime.die(`Duplicate pending permission ID: ${request.id}`)
+          pending.set(request.id, item)
+          yield* events
+            .publish(Event.Asked, request)
+            .pipe(EffectRuntime.onError(() => EffectRuntime.sync(() => pending.delete(request.id))))
+          return item
+        }),
+      )
+
+    const ask = EffectRuntime.fn("PermissionV2.ask")(function* (input: AssertInput) {
+      const result = yield* evaluateInput(input)
+      const value = request(input)
+      if (result.effect === "ask") yield* create(value, input.agent)
+      return { id: value.id, effect: result.effect }
+    })
+
+    const assert = EffectRuntime.fn("PermissionV2.assert")((input: AssertInput) =>
+      EffectRuntime.uninterruptibleMask((restore) =>
+        EffectRuntime.gen(function* () {
+          const result = yield* evaluateInput(input)
+          if (result.effect === "deny") {
+            return yield* new BlockedError({
+              rules: relevant(input, result.rules),
+            })
+          }
+          if (result.effect === "allow") return
+          const item = yield* create(request(input), input.agent)
+          return yield* restore(Deferred.await(item.deferred)).pipe(
+            EffectRuntime.catchTag("PermissionV2.DeclinedError", (error) => EffectRuntime.die(error)),
+            EffectRuntime.ensuring(
+              EffectRuntime.sync(() => {
+                pending.delete(item.request.id)
+              }),
+            ),
+          )
+        }),
+      ),
+    )
+
+    const reply = EffectRuntime.fn("PermissionV2.reply")((input: ReplyInput) =>
+      EffectRuntime.uninterruptible(
+        EffectRuntime.gen(function* () {
+          const existing = pending.get(input.requestID)
+          if (!existing) return yield* new NotFoundError({ requestID: input.requestID })
+          yield* events.publish(Event.Replied, {
+            sessionID: existing.request.sessionID,
+            requestID: existing.request.id,
+            reply: input.reply,
+          })
+
+          if (input.reply === "reject") {
+            yield* Deferred.fail(
+              existing.deferred,
+              input.message ? new CorrectedError({ feedback: input.message }) : new DeclinedError(),
+            )
+            pending.delete(input.requestID)
+            for (const [id, item] of pending) {
+              if (item.request.sessionID !== existing.request.sessionID) continue
+              yield* events.publish(Event.Replied, {
+                sessionID: item.request.sessionID,
+                requestID: item.request.id,
+                reply: "reject",
+              })
+              yield* Deferred.fail(item.deferred, new DeclinedError())
+              pending.delete(id)
+            }
+            return
+          }
+
+          if (input.reply === "always" && existing.request.save?.length) {
+            yield* saved.add({
+              projectID: location.project.id,
+              action: existing.request.action,
+              resources: existing.request.save,
+            })
+          }
+          yield* Deferred.succeed(existing.deferred, undefined)
+          pending.delete(input.requestID)
+          if (input.reply !== "always" || !existing.request.save?.length) return
+
+          const rememberedRules = yield* savedRules()
+          for (const [id, item] of pending) {
+            const input = { ...item.request }
+            const rules = yield* configured(item.request.sessionID, item.agent).pipe(
+              EffectRuntime.catchTag("Session.NotFoundError", () => EffectRuntime.succeed(undefined)),
+            )
+            if (!rules) continue
+            if (denied(input, rules)) continue
+            const effective = [...rules, ...rememberedRules]
+            if (
+              !item.request.resources.every(
+                (resource) => evaluate(item.request.action, resource, effective).effect === "allow",
+              )
+            )
+              continue
+            yield* events.publish(Event.Replied, {
+              sessionID: item.request.sessionID,
+              requestID: item.request.id,
+              reply: "always",
+            })
+            yield* Deferred.succeed(item.deferred, undefined)
+            pending.delete(id)
+          }
+        }),
+      ),
+    )
+
+    const list = EffectRuntime.fn("PermissionV2.list")(function* () {
+      return Array.from(pending.values(), (item) => item.request)
+    })
+
+    const get = EffectRuntime.fn("PermissionV2.get")(function* (id: ID) {
+      return pending.get(id)?.request
+    })
+
+    const forSession = EffectRuntime.fn("PermissionV2.forSession")(function* (sessionID: SessionV2.ID) {
+      return Array.from(pending.values(), (item) => item.request).filter((request) => request.sessionID === sessionID)
+    })
+
+    return Service.of({ ask, assert, reply, get, forSession, list })
+  }),
+)
+
+export const locationLayer = layer.pipe(Layer.provideMerge(AgentV2.locationLayer))
+
+export const node = makeLocationNode({
+  service: Service,
+  layer,
+  deps: [EventV2.node, Location.node, AgentV2.node, SessionStore.node, PermissionSaved.node],
+})

package/src/plugin/agent.ts

@@ -0,0 +1,206 @@
+export * as AgentPlugin from "./agent"
+
+import path from "path"
+import { define } from "./internal"
+import { Effect } from "effect"
+import { AgentV2 } from "../agent"
+import { Global } from "../global"
+import { Location } from "../location"
+import { PermissionV2 } from "../permission"
+
+const TRUNCATION_GLOB = path.join(Global.Path.data, "tool-output", "*")
+const BUILD_SYSTEM =
+  "You are an AI coding agent. Help the user accomplish software engineering tasks by inspecting the workspace, making targeted changes, and using tools according to the configured permissions."
+
+const PROMPT_EXPLORE = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use Glob for broad file pattern matching
+- Use Grep for searching file contents with regex
+- Use Read when you know the specific file path you need to read
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Return file paths as absolute paths in your final response
+- For clear communication, avoid using emojis
+- Do not create any files, or run bash commands that modify the user's system state in any way
+
+Complete the user's search request efficiently and report your findings clearly.`
+
+const PROMPT_COMPACTION = `You are an anchored context summarization assistant for coding sessions.
+
+Summarize only the conversation history you are given. The newest turns may be kept verbatim outside your summary, so focus on the older context that still matters for continuing the work.
+
+If the prompt includes a <previous-summary> block, treat it as the current anchored summary. Update it with the new history by preserving still-true details, removing stale details, and merging in new facts.
+
+Always follow the exact output structure requested by the user prompt. Keep every section, preserve exact file paths and identifiers when known, and prefer terse bullets over paragraphs.
+
+Do not answer the conversation itself. Do not mention that you are summarizing, compacting, or merging context. Respond in the same language as the conversation.`
+
+const PROMPT_TITLE = `You are a title generator. You output ONLY a thread title. Nothing else.
+
+<task>
+Generate a brief title that would help the user find this conversation later.
+
+Follow all rules in <rules>
+Use the <examples> so you know what a good title looks like.
+Your output must be:
+- A single line
+- <=50 characters
+- No explanations
+</task>
+
+<rules>
+- you MUST use the same language as the user message you are summarizing
+- Title must be grammatically correct and read naturally - no word salad
+- Never include tool names in the title (e.g. "read tool", "bash tool", "edit tool")
+- Focus on the main topic or question the user needs to retrieve
+- Vary your phrasing - avoid repetitive patterns like always starting with "Analyzing"
+- When a file is mentioned, focus on WHAT the user wants to do WITH the file, not just that they shared it
+- Keep exact: technical terms, numbers, filenames, HTTP codes
+- Remove: the, this, my, a, an
+- Never assume tech stack
+- Never use tools
+- NEVER respond to questions, just generate a title for the conversation
+- The title should NEVER include "summarizing" or "generating" when generating a title
+- DO NOT SAY YOU CANNOT GENERATE A TITLE OR COMPLAIN ABOUT THE INPUT
+- Always output something meaningful, even if the input is minimal.
+- If the user message is short or conversational (e.g. "hello", "lol", "what's up", "hey"):
+  -> create a title that reflects the user's tone or intent (such as Greeting, Quick check-in, Light chat, Intro message, etc.)
+</rules>
+
+<examples>
+"debug 500 errors in production" -> Debugging production 500 errors
+"refactor user service" -> Refactoring user service
+"why is app.js failing" -> app.js failure investigation
+"implement rate limiting" -> Rate limiting implementation
+"how do I connect postgres to my API" -> Postgres API connection
+"best practices for React hooks" -> React hooks best practices
+"@src/credential.ts can you add refresh token support" -> Credential refresh token support
+"@utils/parser.ts this is broken" -> Parser bug fix
+"look at @config.json" -> Config review
+"@App.tsx add dark mode toggle" -> Dark mode toggle in App
+</examples>`
+
+const PROMPT_SUMMARY = `Summarize what was done in this conversation. Write like a pull request description.
+
+Rules:
+- 2-3 sentences max
+- Describe the changes made, not the process
+- Do not mention running tests, builds, or other validation steps
+- Do not explain what the user asked for
+- Write in first person (I added..., I fixed...)
+- Never ask questions or add new questions
+- If the conversation ends with an unanswered question to the user, preserve that exact question
+- If the conversation ends with an imperative statement or request to the user (e.g. "Now please run the command and paste the console output"), always include that exact request in the summary`
+
+export const Plugin = define({
+  id: "agent",
+  effect: Effect.fn(function* (ctx) {
+    const location = yield* Location.Service
+    const worktree = location.directory
+    const whitelistedDirs = [TRUNCATION_GLOB, path.join(Global.Path.tmp, "*")]
+    const readonlyExternalDirectory: PermissionV2.Ruleset = [
+      { action: "external_directory", resource: "*", effect: "ask" },
+      ...whitelistedDirs.map(
+        (resource): PermissionV2.Rule => ({ action: "external_directory", resource, effect: "allow" }),
+      ),
+    ]
+    const defaults: PermissionV2.Ruleset = [
+      { action: "*", resource: "*", effect: "allow" },
+      ...readonlyExternalDirectory,
+      { action: "question", resource: "*", effect: "deny" },
+      { action: "plan_enter", resource: "*", effect: "deny" },
+      { action: "plan_exit", resource: "*", effect: "deny" },
+      { action: "read", resource: "*", effect: "allow" },
+      { action: "read", resource: "*.env", effect: "ask" },
+      { action: "read", resource: "*.env.*", effect: "ask" },
+      { action: "read", resource: "*.env.example", effect: "allow" },
+    ]
+
+    yield* ctx.agent.transform((draft) => {
+      draft.update(AgentV2.defaultID, (item) => {
+        item.description = "The default agent. Executes tools based on configured permissions."
+        item.system ??= BUILD_SYSTEM
+        item.mode = "primary"
+        item.permissions.push(
+          ...PermissionV2.merge(defaults, [
+            { action: "question", resource: "*", effect: "allow" },
+            { action: "plan_enter", resource: "*", effect: "allow" },
+          ]),
+        )
+      })
+
+      draft.update(AgentV2.ID.make("plan"), (item) => {
+        item.description = "Plan mode. Disallows all edit tools."
+        item.mode = "primary"
+        item.permissions.push(
+          ...PermissionV2.merge(defaults, [
+            { action: "question", resource: "*", effect: "allow" },
+            { action: "plan_exit", resource: "*", effect: "allow" },
+            { action: "external_directory", resource: path.join(Global.Path.data, "plans", "*"), effect: "allow" },
+            { action: "edit", resource: "*", effect: "deny" },
+            { action: "edit", resource: path.join(".neurocode", "plans", "*.md"), effect: "allow" },
+            {
+              action: "edit",
+              resource: path.relative(worktree, path.join(Global.Path.data, "plans", "*.md")),
+              effect: "allow",
+            },
+          ]),
+        )
+      })
+
+      draft.update(AgentV2.ID.make("general"), (item) => {
+        item.description =
+          "General-purpose agent for researching complex questions and executing multi-step tasks. Use this agent to execute multiple units of work in parallel."
+        item.mode = "subagent"
+        item.permissions.push(...PermissionV2.merge(defaults, [{ action: "todowrite", resource: "*", effect: "deny" }]))
+      })
+
+      draft.update(AgentV2.ID.make("explore"), (item) => {
+        item.description =
+          'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.'
+        item.system = PROMPT_EXPLORE
+        item.mode = "subagent"
+        item.permissions.push(
+          ...PermissionV2.merge(
+            defaults,
+            [
+              { action: "*", resource: "*", effect: "deny" },
+              { action: "grep", resource: "*", effect: "allow" },
+              { action: "glob", resource: "*", effect: "allow" },
+              { action: "webfetch", resource: "*", effect: "allow" },
+              { action: "websearch", resource: "*", effect: "allow" },
+              { action: "read", resource: "*", effect: "allow" },
+            ],
+            readonlyExternalDirectory,
+          ),
+        )
+      })
+
+      draft.update(AgentV2.ID.make("compaction"), (item) => {
+        item.mode = "primary"
+        item.hidden = true
+        item.system = PROMPT_COMPACTION
+        item.permissions.push(...PermissionV2.merge(defaults, [{ action: "*", resource: "*", effect: "deny" }]))
+      })
+
+      draft.update(AgentV2.ID.make("title"), (item) => {
+        item.mode = "primary"
+        item.hidden = true
+        item.system = PROMPT_TITLE
+        item.permissions.push(...PermissionV2.merge(defaults, [{ action: "*", resource: "*", effect: "deny" }]))
+      })
+
+      draft.update(AgentV2.ID.make("summary"), (item) => {
+        item.mode = "primary"
+        item.hidden = true
+        item.system = PROMPT_SUMMARY
+        item.permissions.push(...PermissionV2.merge(defaults, [{ action: "*", resource: "*", effect: "deny" }]))
+      })
+    })
+  }),
+})

package/src/plugin/command/initialize.txt

@@ -0,0 +1,65 @@
+Create or update `AGENTS.md` for this repository.
+
+The goal is a compact instruction file that helps future OpenCode sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.
+
+User-provided focus or constraints (honor these):
+$ARGUMENTS
+
+## How to investigate
+
+Read the highest-value sources first:
+- `README*`, root manifests, workspace config, lockfiles
+- build, test, lint, formatter, typecheck, and codegen config
+- CI workflows and pre-commit / task runner config
+- existing instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
+- repo-local OpenCode config such as `opencode.json`
+
+If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.
+
+Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.
+
+## What to extract
+
+Look for the highest-signal facts for an agent working in this repo:
+- exact developer commands, especially non-obvious ones
+- how to run a single test, a single package, or a focused verification step
+- required command order when it matters, such as `lint -> typecheck -> test`
+- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
+- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
+- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
+- important constraints from existing instruction files worth preserving
+
+Good `AGENTS.md` content is usually hard-earned context that took reading multiple files to infer.
+
+## Questions
+
+Only ask the user questions if the repo cannot answer something important. Use the `question` tool for one short batch at most.
+
+Good questions:
+- undocumented team conventions
+- branch / PR / release expectations
+- missing setup or test prerequisites that are known but not written down
+
+Do not ask about anything the repo already makes clear.
+
+## Writing rules
+
+Include only high-signal, repo-specific guidance such as:
+- exact commands and shortcuts the agent would otherwise guess wrong
+- architecture notes that are not obvious from filenames
+- conventions that differ from language or framework defaults
+- setup requirements, environment quirks, and operational gotchas
+- references to existing instruction sources that matter
+
+Exclude:
+- generic software advice
+- long tutorials or exhaustive file trees
+- obvious language conventions
+- speculative claims or anything you could not verify
+- content better stored in another file referenced via `opencode.json` `instructions`
+
+When in doubt, omit.
+
+Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarize the few structural facts that actually change how an agent should work.
+
+If `AGENTS.md` already exists at `${path}`, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.

package/src/plugin/command/review.txt

@@ -0,0 +1,100 @@
+You are a code reviewer. Your job is to review code changes and provide actionable feedback.
+
+---
+
+Input: $ARGUMENTS
+
+---
+
+## Determining What to Review
+
+Based on the input provided, determine which type of review to perform:
+
+1. **No arguments (default)**: Review all uncommitted changes
+   - Run: `git diff` for unstaged changes
+   - Run: `git diff --cached` for staged changes
+   - Run: `git status --short` to identify untracked (net new) files
+
+2. **Commit hash** (40-char SHA or short hash): Review that specific commit
+   - Run: `git show $ARGUMENTS`
+
+3. **Branch name**: Compare current branch to the specified branch
+   - Run: `git diff $ARGUMENTS...HEAD`
+
+4. **PR URL or number** (contains "github.com" or "pull" or looks like a PR number): Review the pull request
+   - Run: `gh pr view $ARGUMENTS` to get PR context
+   - Run: `gh pr diff $ARGUMENTS` to get the diff
+
+Use best judgement when processing input.
+
+---
+
+## Gathering Context
+
+**Diffs alone are not enough.** After getting the diff, read the entire file(s) being modified to understand the full context. Code that looks wrong in isolation may be correct given surrounding logic—and vice versa.
+
+- Use the diff to identify which files changed
+- Use `git status --short` to identify untracked files, then read their full contents
+- Read the full file to understand existing patterns, control flow, and error handling
+- Check for existing style guide or conventions files (CONVENTIONS.md, AGENTS.md, .editorconfig, etc.)
+
+---
+
+## What to Look For
+
+**Bugs** - Your primary focus.
+- Logic errors, off-by-one mistakes, incorrect conditionals
+- If-else guards: missing guards, incorrect branching, unreachable code paths
+- Edge cases: null/empty/undefined inputs, error conditions, race conditions
+- Security issues: injection, auth bypass, data exposure
+- Broken error handling that swallows failures, throws unexpectedly or returns error types that are not caught.
+
+**Structure** - Does the code fit the codebase?
+- Does it follow existing patterns and conventions?
+- Are there established abstractions it should use but doesn't?
+- Excessive nesting that could be flattened with early returns or extraction
+
+**Performance** - Only flag if obviously problematic.
+- O(n²) on unbounded data, N+1 queries, blocking I/O on hot paths
+
+**Behavior Changes** - If a behavioral change is introduced, raise it (especially if it's possibly unintentional).
+
+---
+
+## Before You Flag Something
+
+**Be certain.** If you're going to call something a bug, you need to be confident it actually is one.
+
+- Only review the changes - do not review pre-existing code that wasn't modified
+- Don't flag something as a bug if you're unsure - investigate first
+- Don't invent hypothetical problems - if an edge case matters, explain the realistic scenario where it breaks
+- If you need more context to be sure, use the tools below to get it
+
+**Don't be a zealot about style.** When checking code against conventions:
+
+- Verify the code is *actually* in violation. Don't complain about else statements if early returns are already being used correctly.
+- Some "violations" are acceptable when they're the simplest option. A `let` statement is fine if the alternative is convoluted.
+- Excessive nesting is a legitimate concern regardless of other style choices.
+
+---
+
+## Tools
+
+Use these to inform your review:
+
+- **Explore agent** - Find how existing code handles similar problems. Check patterns, conventions, and prior art before claiming something doesn't fit.
+- **Exa Code Context** - Verify correct usage of libraries/APIs before flagging something as wrong.
+- **Web Search** - Research best practices if you're unsure about a pattern.
+
+If you're uncertain about something and can't verify it with these tools, say "I'm not sure about X" rather than flagging it as a definite issue.
+
+---
+
+## Output
+
+1. If there is a bug, be direct and clear about why it is a bug.
+2. Clearly communicate severity of issues. Do not overstate severity.
+3. Critiques should clearly and explicitly communicate the scenarios, environments, or inputs that are necessary for the bug to arise. The comment should immediately indicate that the issue's severity depends on these factors.
+4. Your tone should be matter-of-fact and not accusatory or overly positive. It should read as a helpful AI assistant suggestion without sounding too much like a human reviewer.
+5. Write so the reader can quickly understand the issue without reading too closely.
+6. AVOID flattery, do not give any comments that are not helpful to the reader.