@drawbridge/drawbridge-agents 0.1.97 → 0.1.98

package/.claude-template/settings.json

@@ -56,6 +56,15 @@
   },
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Read|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./.claude/hooks/guard-secrets.js"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit|MultiEdit|NotebookEdit",
         "hooks": [

package/README.md

@@ -112,6 +112,9 @@ identical copy via the sync mirror (see "Delivery model").
   doc anchor and on `@story`-anchored code changed without a drawbridge-docs change (once per
   turn; the second attempt passes so the agent must answer), and **nudges** (non-blocking) when
   the graph looks stale. It skips plan-mode and turns with no source changes.
+- **Secrets guard.** `hooks/guard-secrets.js` (PreToolUse on Read/Bash) denies a Read of any
+  `.env*` file and a Bash command that displays one, prints the environment, or prints an `op`
+  value without a redirect. See `conventions/secrets.md`.
 - **Read-before-write hooks.** `hooks/consult-docs-record.js` (PostToolUse on Read/Bash) remembers
   that a drawbridge-docs page was read and a graph query ran in this session;
   `hooks/consult-docs-gate.js` (PreToolUse on Write/Edit) refuses the first source edit until

package/claude/CLAUDE.md

@@ -3,6 +3,7 @@
 @../conventions/karpathy-guidelines.md
 @../conventions/rules.md
 @../conventions/verification.md
+@../conventions/secrets.md
 @../conventions/javascript-formatting.md
 @../conventions/nested-objects.md
 @../conventions/jsx-fragments.md

package/conventions/secrets.md

@@ -0,0 +1,34 @@
+# Never put a secret in the transcript
+
+Nothing an agent prints, reads or echoes may carry a secret. The family's env files
+(`.env.local`, `.env.development`, `.env.production`, drawbridge-tests' `.env`) hold a 1Password
+service-account token and, in tests, live keys. A transcript is copied, summarized and shared,
+so a value that lands in one has to be rotated.
+
+The api's 1Password service-account token reached a session transcript twice, the second time
+on 2026-10-28. Darren: "That is the second time you have done that. You cannot fucking keep doing
+that." This page and `hooks/guard-secrets.js` exist so there is no third time.
+
+## The rule
+
+- Never `Read`, `cat`, `head`, `tail`, `less`, `grep`, `sed`, `awk` or `source` a `.env*` file.
+  Not to "see which Environment it names", not to copy one line, not to check it exists (`ls` and
+  `test -f` are fine; they show no content).
+- Never print `process.env`, `printenv`, bare `env`, or a value read from `op` (`op read`,
+  `op item get`, `op environment read`) to the console. Those commands are allowed only with
+  their output redirected to a file that nothing then displays.
+- Never paste a key, token, connection string, cookie or session value into a reply, a commit
+  message, an Asana comment, a doc or a script's console output.
+- A script that needs an env value runs under the repo's `scripts/op.sh`
+  (`ENV_FILE=.env.local sh scripts/op.sh node <script>`) and consumes the value inside the
+  process. `op run` conceals secret-looking strings in console output, which is why ids are
+  written to files and read back; it is not a licence to display the env file.
+- Copying an env file between checkouts (a worktree without `.env.development`) is `cp` with no
+  display, and the copy is deleted when the work is done.
+- If a secret does reach the transcript, say so at once, in one line, and name what to rotate.
+
+## Enforced
+
+`hooks/guard-secrets.js` is a PreToolUse hook on `Read` and `Bash`, mirrored into every repo's
+`.claude/hooks/`. It denies a `Read` of any `.env*` file and a Bash command that displays one,
+prints the environment, or prints an `op` value without a redirect. The denial names this page.

package/hooks/guard-secrets.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// PreToolUse hook (Read|Bash): nothing displays a secret. The family's env files carry a
+// 1Password service-account token, and that token reached a session transcript twice
+// (the second time 2026-10-28). A convention did not stop it, so this does: a Read of any
+// .env* file is denied, and so is a Bash command that displays one, prints the environment,
+// or prints an `op` value to the console. See conventions/secrets.md.
+const fs = require('fs')
+const path = require('path')
+
+const readStdin = () => {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8') || '{}')
+  } catch (error) {
+    return {}
+  }
+}
+
+const deny = (reason) => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    }
+  }))
+  process.exit(0)
+}
+
+const SEE = ' See conventions/secrets.md: run the script under scripts/op.sh and let it consume the value; never display it.'
+
+// `.env`, `.env.local`, `.env.development`, `.env.production`, `.env.example` is harmless but
+// treated the same: nothing needs to read any of them.
+const isEnvFile = (filePath) => /^\.env(\..+)?$/.test(path.basename(filePath))
+
+// A command whose argument list names an env file, by a tool that prints file content.
+const DISPLAYS_FILE = /(^|[|;&(\s])(cat|head|tail|less|more|bat|grep|rg|egrep|fgrep|sed|awk|cut|sort|uniq|strings|xxd|od|source|\.)\s+(?:[^|;&]*[\s/'"=])?\.env(\.[\w-]+)?(['"\s]|$)/m
+
+// The whole environment, printed.
+const PRINTS_ENV = /(^|[|;&(\s])(printenv|env)(\s*$|\s*[|;&)]|\s+-)/m
+
+// An `op` read whose output is not sent to a file.
+const OP_READ = /(^|[|;&(\s])op\s+(read|item\s+get|environment\s+read)\b/m
+
+const run = () => {
+  const input = readStdin()
+  const tool = input.tool_name || ''
+  const toolInput = input.tool_input || {}
+
+  if (tool === 'Read') {
+    const filePath = toolInput.file_path || ''
+    if (filePath && isEnvFile(filePath)) {
+      deny('Blocked: `' + path.basename(filePath) + '` holds a secret and is never read into the transcript.' + SEE)
+    }
+    process.exit(0)
+  }
+
+  if (tool !== 'Bash') process.exit(0)
+
+  const command = String(toolInput.command || '')
+  if (!command) process.exit(0)
+
+  if (DISPLAYS_FILE.test(command)) {
+    deny('Blocked: this command displays a .env file, which holds a secret.' + SEE)
+  }
+
+  if (PRINTS_ENV.test(command)) {
+    deny('Blocked: this command prints the whole environment, secrets included.' + SEE)
+  }
+
+  if (OP_READ.test(command) && !/>\s*\S/.test(command)) {
+    deny('Blocked: an `op` read prints a secret to the console. Redirect it to a file nothing displays, or run the consumer under scripts/op.sh.' + SEE)
+  }
+
+  process.exit(0)
+}
+
+try {
+  run()
+} catch (error) {
+  // Never break a user's turn because of a hook bug — fail open.
+  process.exit(0)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {