opencode-shell-safety 0.2.2 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandru Nedelcu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,10 @@
 # opencode-shell-safety
 
-An OpenCode v2 plugin that uses [Jev](https://en.wikipedia.org/wiki/Jev_(AI_model))
-to classify shell permission requests against the active agent definition and
-its filesystem policy.
+[![npm version](https://img.shields.io/npm/v/opencode-shell-safety)](https://www.npmjs.com/package/opencode-shell-safety)
+
+An OpenCode v2 plugin that uses [Jev](<https://en.wikipedia.org/wiki/Jev_(AI_model)>) to classify shell permission requests against the active agent definition and its filesystem policy.
+
+This project is part of [alexandru/agents-config](https://github.com/alexandru/agents-config). See it in use in my [OpenCode configuration](https://github.com/alexandru/opencode-config).
 
 ## Configuration
 
@@ -21,12 +23,12 @@ its filesystem policy.
         "integration": "opencode",
         "agents": {
           "Explorer": {
-            "enabled": true
-          }
-        }
-      }
-    }
-  ]
+            "enabled": true,
+          },
+        },
+      },
+    },
+  ],
 }
 ```
 
@@ -51,35 +53,35 @@ Get an API key from [TypeSafe AI](https://docs.typesafe.ai/introduction/quicksta
         "apiKeyEnv": "TYPESAFE_API_KEY",
         "agents": {
           "Explorer": {
-            "enabled": true
-          }
-        }
-      }
-    }
-  ]
+            "enabled": true,
+          },
+        },
+      },
+    },
+  ],
 }
 ```
 
 ## Options
 
-| Option | Description |
-| --- | --- |
-| `endpoint` | SystemOne HTTP endpoint. |
-| `model` | Model sent in each classification request. |
-| `integration` | OpenCode integration whose credential takes precedence over `apiKeyEnv`. |
-| `apiKeyEnv` | Environment variable to read if no integration credential is available. |
-| `allowProbability` | Minimum `withinPolicy` probability required to allow a command. |
-| `violationProbability` | Probability at or above which a filesystem, remote-mutation, or credential violation denies a command. |
-| `timeoutMs` | Timeout for one request attempt. |
-| `maxAttempts` | Maximum attempts for network, timeout, rate-limit, and server failures. |
-| `retryDelayMs` | Delay between retry attempts. |
-| `cache.capacity` | Maximum number of cached classification results. |
-| `cache.ttlMs` | Successful classification cache lifetime in milliseconds. |
-| `agents.<name>.enabled` | Enables classification for an agent. |
-| `agents.<name>.thresholds` | Optional per-agent probability thresholds. |
-| `agents.<name>.http` | Optional. Omission permits no HTTP methods or credential hosts. |
-| `agents.<name>.http.methods` | HTTP methods the policy permits. |
-| `agents.<name>.http.credentials` | Environment credential names mapped to allowed HTTPS hosts. |
+| Option                           | Description                                                                                            |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `endpoint`                       | SystemOne HTTP endpoint.                                                                               |
+| `model`                          | Model sent in each classification request.                                                             |
+| `integration`                    | OpenCode integration whose credential takes precedence over `apiKeyEnv`.                               |
+| `apiKeyEnv`                      | Environment variable to read if no integration credential is available.                                |
+| `allowProbability`               | Minimum `withinPolicy` probability required to allow a command.                                        |
+| `violationProbability`           | Probability at or above which a filesystem, remote-mutation, or credential violation denies a command. |
+| `timeoutMs`                      | Timeout for one request attempt.                                                                       |
+| `maxAttempts`                    | Maximum attempts for network, timeout, rate-limit, and server failures.                                |
+| `retryDelayMs`                   | Delay between retry attempts.                                                                          |
+| `cache.capacity`                 | Maximum number of cached classification results.                                                       |
+| `cache.ttlMs`                    | Successful classification cache lifetime in milliseconds.                                              |
+| `agents.<name>.enabled`          | Enables classification for an agent.                                                                   |
+| `agents.<name>.thresholds`       | Optional per-agent probability thresholds.                                                             |
+| `agents.<name>.http`             | Optional. Omission permits no HTTP methods or credential hosts.                                        |
+| `agents.<name>.http.methods`     | HTTP methods the policy permits.                                                                       |
+| `agents.<name>.http.credentials` | Environment credential names mapped to allowed HTTPS hosts.                                            |
 
 Set at least one of `integration` or `apiKeyEnv`.
 

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "opencode-shell-safety",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "OpenCode plugin that classifies shell permission requests against agent policy.",
+  "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "files": [
+    "LICENSE",
     "src",
     "README.md"
   ],

package/src/index.ts

@@ -161,10 +161,12 @@ export const resolveAgentDefinition = (agent: Agent.Info): ResolvedAgentDefiniti
     .map((rule) => ({ resource: rule.resource, effect: rule.effect })),
 })
 
+export type ClassificationVerdict = "allow" | "deny"
+
 export const permissionFromAssessment = (
   assessment: SafetyAssessment,
   thresholds: Thresholds,
-): PermissionEffect => {
+): ClassificationVerdict => {
   const hasViolation =
     assessment.filesystemViolation.noul >= thresholds.violationProbability ||
     assessment.remoteMutation.noul >= thresholds.violationProbability ||
@@ -172,6 +174,9 @@ export const permissionFromAssessment = (
   return assessment.withinPolicy.noul >= thresholds.allowProbability && !hasViolation ? "allow" : "deny"
 }
 
+export const fallbackEffect = (configured: PermissionEffect): PermissionEffect =>
+  configured === "allow" ? "deny" : configured
+
 const noulQuestion = (instructions: string, yes: string, no: string): NoulQuestion => ({
   type: "noul",
   instructions,
@@ -221,7 +226,6 @@ export const buildRequest = (
         |
         |Rules:
         |- Decide whether "shellCommand" complies with those instructions and with "state.policy".
-        |- OpenCode invokes this classifier only after permission resolution returns "ask".
         |- An "ask" rule means this classifier must decide from the command's actual effects; it is not a violation.
         |- Shell deny rules remain final.
         |- Apply ordered permission rules with the last matching rule winning.
@@ -387,16 +391,17 @@ const findPolicy = (options: Options, agent: string): AgentPolicy | undefined =>
 const hasShellControlSyntax = (resources: ReadonlyArray<string>): boolean =>
   resources.some((resource) => /[;&|<>`$]/.test(resource))
 
-const summary = (assessment: SafetyAssessment, effect: PermissionEffect): string => {
+const summary = (assessment: SafetyAssessment, verdict: ClassificationVerdict, effect: PermissionEffect): string => {
   const classification =
-    `Jev shell classification: ${effect} (` +
+    `Jev shell classification: ${verdict} (` +
     `withinPolicy=${assessment.withinPolicy.noul.toFixed(3)}, ` +
     `filesystemViolation=${assessment.filesystemViolation.noul.toFixed(3)}, ` +
     `remoteMutation=${assessment.remoteMutation.noul.toFixed(3)}, ` +
     `credentialViolation=${assessment.credentialViolation.noul.toFixed(3)})`
+  if (verdict === "allow") return classification
   return effect === "deny"
     ? `${classification}. Rewrite the command to comply with your system prompt and permissions, or report the limitation if no compliant form exists.`
-    : classification
+    : `${classification}. Jev rejected this command.`
 }
 
 const classificationSucceeded = (assessment: SafetyAssessment): ClassificationResult => ({ ok: true, assessment })
@@ -443,19 +448,22 @@ export const createPermissionEvaluator = (
       const policy = findPolicy(options, agent)
       if (!policy?.enabled) return Effect.void
       const classifiedEvent = { ...event, agent }
+      const fallback = fallbackEffect(event.effect)
 
       return Effect.gen(function* () {
-        event.effect = "deny"
         if (!projectDirectory) {
+          event.effect = fallback
           event.message = "Jev could not classify this command because the session directory is unavailable."
           return
         }
         if (!assessmentCache) {
+          event.effect = fallback
           event.message = "Jev could not classify this command because no OpenCode Zen credential is available."
           return
         }
         const agentDefinition = yield* resolveAgentDefinition(agent)
         if (!agentDefinition) {
+          event.effect = fallback
           event.message = `Jev could not classify this command because the resolved ${agent} definition is unavailable.`
           return
         }
@@ -468,12 +476,14 @@ export const createPermissionEvaluator = (
           Effect.catch((error) => Effect.succeed(classificationFailed(error))),
         )
         if (!result.ok) {
+          event.effect = fallback
           event.message = `Jev could not classify this command (${requestFailure(result.error, options)}).`
           return
         }
 
-        event.effect = permissionFromAssessment(result.assessment, policy.thresholds ?? options)
-        event.message = summary(result.assessment, event.effect)
+        const verdict = permissionFromAssessment(result.assessment, policy.thresholds ?? options)
+        event.effect = verdict === "allow" ? "allow" : fallback
+        event.message = summary(result.assessment, verdict, event.effect)
       })
     }
   })