dsh-approval-auto-review

English | 中文

Automatic approval reviewer for DeepSeek Harness. The plugin handles approval requests whose reviewer is auto-review, evaluates the exact planned action with a locked-down Guardian agent, and returns a single approval decision for that request.

Each parent agent has one reusable Guardian trunk. The first review sends a bounded transcript and the planned action. Later reviews send only the current action delta to the same trunk. When that trunk is busy, the plugin starts an independent ephemeral reviewer so concurrent approval requests do not queue behind one another.

Features

• Separate reviewer model route with optional inheritance from the parent agent.
• Provider and model overrides for specific parent model ids.
• Empty tool allowlist and a dedicated reviewer persona for every reviewer agent.
• Bounded transcripts and tool arguments.
• Fail-closed handling for timeouts, malformed output, provider failures, and unresolved routes.
• Denial circuit that stops a parent turn after repeated automatic rejections.
• Review metadata recorded with the approval decision.

Install

Install the repository as a DSH profile bundle:

dsh plugin --profile web add github:perlied03/dsh-approval-auto-review

For a local checkout:

dsh plugin --profile web add ./dsh-approval-auto-review

The package declares dsh.bundle, so dsh plugin adds its configuration layer to the profile automatically. The layer registers the reviewer and provides three permission choices: Request approval, Approve for me, and Full access. The same package declares dsh.client, so the Web profile discovers its reviewer-model settings card from the installed package. Select Approve for me in the conversation permission menu to route approval requests to the Guardian.

A GitHub install runs the package's prepare build. With pnpm 10 or later, add dsh-approval-auto-review: true under allowBuilds in the profile's pnpm-workspace.yaml when pnpm asks for build approval, then repeat the install command.

The host composition must provide these DSH services and plugins:

• dsh-agent
• dsh-session
• dsh-settings
• dsh-user-approval
• dsh-subagent
• an in-process spawn provider registered under the configured provider name
• an in-process fork provider registered under the configured ephemeralProvider name

The fork provider handles concurrent reviews while preserving the reusable trunk path. Deployments that do not need that path may use the same provider name for both settings.

Configure

Register the plugin in the Cordis composition:

import * as ApprovalAutoReview from 'dsh-approval-auto-review'

await ctx.plugin(ApprovalAutoReview, {
  provider: 'spawn',
  ephemeralProvider: 'fork',
  modelProvider: 'deepseek-official',
  model: 'deepseek-v4-flash',
  fallback: 'parent',
})

The equivalent Loader row is:

- id: approval-auto-review
  name: 'dsh-approval-auto-review'
  config:
    provider: spawn
    ephemeralProvider: fork
    modelProvider: deepseek-official
    model: deepseek-v4-flash
    fallback: parent

Configuration fields:

• provider: subagent provider for the reusable Guardian trunk. Default: spawn.
• ephemeralProvider: subagent provider for concurrent one-shot reviews. Default: fork.
• modelProvider and model: optional reviewer route.
• modelOverrides: optional map keyed by parent model id. Each entry may set provider, model, and maxTokens.
• fallback: parent inherits missing route fields from the parent agent; reject fails closed when a route is incomplete. Default: parent.
• timeoutMs: deadline for one review attempt. Default: 30000.
• maxAttempts: retry limit after a failed attempt. Default: 3.
• maxTranscriptChars: maximum serialized parent transcript sent to a full review. Default: 60000.
• maxToolArgumentsChars: maximum raw tool-argument characters sent to a review. Default: 20000.
• maxTokens: optional reviewer output-token ceiling.
• activationPreset: permission preset that activates review on DSH builds without native reviewer routing. When omitted on such builds, the plugin handles every approval request. The bundled layer sets approve-for-me.

Enable automatic review through the existing approval/reviewer session setting or the permission preset that selects approve-for-me. The plugin does not create a persistent allow rule; each decision applies to one approval request.

DSH compatibility

On reviewer-aware DSH builds, the plugin handles requests whose native reviewer is auto-review and attaches structured review evidence to approval/decided. Requests for the user reviewer continue to the human approval channel.

On earlier DSH builds, the bundle uses the durable permission/preset selection instead. Approve for me activates the Guardian and Request approval continues to the human channel. Legacy approval services accept only string outcomes, so timeouts are returned as rejections and structured review metadata is unavailable, while the allow/deny behavior remains fail-closed.

Web settings

The package's Web client entry contributes an Automatic approval review card to the existing Plugins settings section. The card edits modelProvider and model through the approval-auto-review settings namespace and uses the same model directory as the DSH Models page. Select a provider first to filter the model list, or leave both fields on Follow the parent agent to inherit the parent route. Changes apply to the next review without restarting the process.

The standalone card uses a lower slot priority than default contributions. When the Host also contributes an approval-auto-review card, the standalone card renders and the Host card remains registered but shadowed.

The Host plugin registers that namespace with DSH's configuration API Proxy when ctx.apiProxy.exposeSettingsNamespace() is available. DSH 0.1.0-rc.7 serves registered settings namespaces directly, so the same card works there without that method. A Host that restricts settings namespaces and does not provide the explicit exposure method still runs automatic review, but requires the route in the profile's cordis.patch.yml.

Model routing

The reviewer route is resolved in this order:

1. modelOverrides[parent.options.model], when an entry exists.
2. The plugin-level modelProvider and model values.
3. The corresponding parent agent route when fallback is parent.
4. A fail-closed error when fallback is reject and the route is incomplete.

Provider and model names are deployment values. The plugin does not assume that a Codex or OpenAI model id is available from a DSH provider.

Review policy

The Guardian evaluates only the exact action supplied by the approval request. Direct user messages and content explicitly loaded from AGENTS.md are trusted authorization evidence. Assistant messages, tool calls, tool results, file contents, command output, and ordinary plugin context are untrusted.

The default policy allows low- and medium-risk actions unless a specific deny rule or prompt injection applies. High-risk actions require at least medium trusted authorization and a narrow scope. Critical risk, obvious secret exfiltration, broad destructive actions without exact authorization, and broad persistent security weakening are denied.

Every reviewer agent has an empty tool allowlist, a dedicated persona, structured output requirements, and a delegated approval policy that prevents the reviewer from creating another approval request.

Failure behavior

• A timeout injects a retry-or-ask notice into the parent session and returns a timed-out approval result.
• A provider failure or malformed reviewer response is retried up to maxAttempts, then returns a rejection.
• An unresolved route rejects when fallback is reject; with parent, missing fields inherit from the parent agent.
• A rejected automatic review injects its rationale and an anti-circumvention notice into the parent session.
• Three consecutive automatic denials, or ten denials among the latest fifty automatic reviews in one turn, cancel the parent turn.

Completed approval/decided evidence includes the risk and authorization classification, selected provider and model when available, reviewer session kind, attempt count, whether the reviewer had prior context, and whether the action arguments were truncated.

Model Experience

Parent session

What the model sees

The parent model receives the approval-policy context produced by dsh-user-approval. A rejection adds the reviewer rationale and an anti-circumvention notice. A timeout adds a separate retry-or-ask notice. The Guardian transcript and review metadata are not copied into the parent model request.

Token effect

Only approval-policy context and injected rejection or timeout notices can add tokens to a later parent request. The reviewer transcript is not duplicated in the parent request.

KV Cache effect

Approval-policy context and injected notices may change the prefix of the next parent request. A successful approval adds no notice.

Guardian reviewer

What the model sees

The first trunk review receives one bounded parent transcript and the exact planned action. Later trunk reviews receive the current bounded action delta and the prior review count. An ephemeral review receives a new bounded transcript and the current action.

Token effect

Every approval review is a separate model request. Transcript and argument limits cap the material sent to each request.

KV Cache effect

Trunk reviews append deltas to one child session, allowing a provider to reuse a stable prefix. Each review still creates a new model request. Ephemeral reviews use independent sessions and do not reuse the trunk prefix.

Known Limitations and Deferred Work

• The deployment must provide subagent providers that support personas, empty tool filters, structured output, continuations, and cancellation.
• The Guardian has no filesystem or network tools. Its bounded parent evidence is the complete review input; adding tools would introduce another prompt-injection and authorization source.
• Provider and model availability is controlled by the deployment. An unavailable route fails closed instead of being silently replaced.
• The Web settings card requires either DSH 0.1.0-rc.7 namespace discovery or the explicit ctx.apiProxy.exposeSettingsNamespace() Host extension; a Host with neither mechanism uses profile configuration for the reviewer route.
• Reviewer-unaware DSH builds cannot persist structured review evidence or a distinct timeout outcome; the bundle retains the permission choice through permission/preset and fails closed with string outcomes.
• A GitHub install runs prepare to build lib/. pnpm 10 or later requires an explicit allowBuilds entry when the profile has not trusted this package before.

Development

pnpm install
pnpm test
pnpm run typecheck
pnpm run build

The package resolves DSH imports from published packages. prepare builds the Host exports and the lib/client.js bundle discovered through dsh.client.