localvault 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86be5d86ef86c74bcfc777561088264d1b908eaca92a2b501d5e23d937e5a906
-  data.tar.gz: d3d079c65ff54ca198907957ae3193a3a73520aa84169cf0067bc254967fea05
+  metadata.gz: f49d7a925b997780d6d03a2b071117e20da0827d24331d28c9cd5043a70b0056
+  data.tar.gz: 27b2be6fa5bb90d3df68eec4a27fcba483a175b574afd96f7aeba7dd0e175412
 SHA512:
-  metadata.gz: f0d5b4b8d1575b8b91fbd742afd0aef2f71401e72882149cf0b83e68cd233636592c5e0af85512007b4cff604d466ff38d5ac085ea7eea60e9b9446a3d7247a5
-  data.tar.gz: 98a51ac12f4857e0f381fa4b4449a63687d402fe3bf3d97e693f75bfc526440efbc0fd9df14f397c99771c4c871c9a8f164b51e29cca56a232bfa78c099ca8c9
+  metadata.gz: 7863c066d383db0a2ad4a98ae9665fe1fafc04de61b1fdbfec590d4af0ea04e47f31f1635a4c63d5886f0f71780a5f9f0ebd143348af23d404415991487dd214
+  data.tar.gz: b61cb7b5096ad2250560a1462f87ecfd81e538ed823971c46fe4820be3bb50443574055e40d0e080c7f4e5f7b7ce93d2d2f9cceedd03ea4f39a9a13141f35c44

data/README.md

@@ -41,10 +41,10 @@ sudo dnf install libsodium-devel
 # Create a vault (prompts for passphrase)
 localvault init
 
-# Store secrets
-localvault set OPENAI_API_KEY "sk-proj-..."
-localvault set STRIPE_SECRET_KEY "sk_live_..."
-localvault set DATABASE_URL "postgres://localhost/myapp"
+# Store secrets without putting values in shell history / process args
+printf '%s' "$OPENAI_API_KEY" | localvault set OPENAI_API_KEY --stdin
+printf '%s' "$STRIPE_SECRET_KEY" | localvault set STRIPE_SECRET_KEY --stdin
+printf '%s' "$DATABASE_URL" | localvault set DATABASE_URL --stdin
 
 # Retrieve a secret (raw, pipeable)
 localvault get OPENAI_API_KEY
@@ -69,8 +69,9 @@ localvault exec -- rails server
 | Command | Description |
 |---------|-------------|
 | `init [NAME]` | Create a vault (Argon2id key derivation) |
-| `set KEY VALUE` | Store a secret (supports dot-notation: `project.KEY`) |
-| `set --group GROUP KEY VALUE` | Store a secret in a named group |
+| `set KEY --stdin` | Store a secret from stdin without argv/history exposure |
+| `set KEY [VALUE]` | Store a secret (positional value kept for compatibility) |
+| `set --group GROUP KEY --stdin` | Store a secret in a named group from stdin |
 | `get KEY` | Retrieve a secret (raw, pipeable) |
 | `show` | Display all secrets in a table (masked by default) |
 | `show --reveal` | Display with values visible |
@@ -143,6 +144,10 @@ backward compatibility but the top-level forms are preferred.
 |---------|-------------|
 | `install-mcp [CLIENT]` | Configure MCP server in claude-code, cursor, or windsurf |
 | `mcp` | Start MCP server (stdio transport) |
+| `doctor` | Check install and PATH readiness, including brew/asdf shadowing |
+| `guard install` | Install Claude Code hooks that block secrets in agent commands (v1.9.0) |
+| `guard status` | Show guard hook installation state |
+| `guard hook` | Hook entrypoint (reads hook JSON on stdin; not run by hand) |
 
 All commands accept `--vault NAME` (or `-v NAME`) to target a specific vault. Default vault is `default`.
 
@@ -232,6 +237,9 @@ localvault unlock
 # Verify setup without starting the blocking stdio server
 localvault mcp --check
 
+# Diagnose brew/asdf PATH shadowing after upgrades
+localvault doctor
+
 # MCP tools available to the agent:
 #   localvault_whoami             — diagnose active vault/session state
 #   list_secrets(vault?, prefix?, query?) — list/search key names
@@ -305,6 +313,39 @@ Unlocking writes a derived key to `LOCALVAULT_SESSION` and also caches it with a
 
 ## Security
 
+### Agent Plaintext Containment (v1.9.0)
+
+Two layers keep secrets out of AI agent context and transcripts:
+
+**1. Plaintext refuses captured streams.** `get`, `env`, and `show --reveal`
+print values to an interactive terminal as always. When stdout is captured
+(a pipe or an agent's shell), a human confirms with one keypress on `/dev/tty`;
+an agent's shell has no `/dev/tty`, so it is refused and pointed at injection:
+
+```bash
+localvault get STRIPE_KEY              # human at a terminal: prints
+localvault get STRIPE_KEY | pbcopy     # human piping: "Print plaintext? [y/N]"
+# agent shell: refused → use localvault exec --map STRIPE_KEY=STRIPE_KEY -- CMD
+```
+
+There is deliberately no flag or environment variable to bypass this — the only
+override is a keypress on a real terminal. Headless automation uses
+`localvault exec` injection.
+
+**2. Guard hooks block secrets in agent commands.** `localvault guard install`
+wires Claude Code hooks that scan every Bash tool call against your unlocked
+vaults. A command containing a stored secret value is blocked before it runs,
+naming the key by fingerprint — never by value:
+
+```text
+LocalVault guard: blocked — this tool input contains the plaintext value of
+default/STRIPE.private_key (sha256:1a2b3c4d5e6f). Inject it instead:
+  localvault exec --map STRIPE.private_key=PRIVATE_KEY -- your-command
+```
+
+The installed hook fails open: locked vaults, an old binary, or a missing
+install allow the call rather than breaking your session.
+
 ### Crypto Stack
 
 | Layer | Algorithm | Purpose |

data/lib/localvault/cli/error_presenter.rb

@@ -60,8 +60,12 @@ module LocalVault
           when :ambiguous then "Error: group name is ambiguous. Existing groups: #{@error.candidates.join(", ")}."
           else "Error: group and key names may contain letters, digits, and underscores only."
           end
+        elsif @error.is_a?(CLI::SetValueSourceError) && @error.kind == :multiple
+          "Error: #{@error.message}"
         elsif group_save_attempt?
           "Error: saving in a group needs GROUP, KEY, and VALUE."
+        elsif @error.is_a?(CLI::SetValueSourceError)
+          "Error: #{@error.message}"
         elsif unknown_option
           "Error: unknown option `#{unknown_option}`."
         elsif context.command.nil?
@@ -97,7 +101,7 @@ module LocalVault
         end
 
         return group_save_suggestions if group_save_attempt?
-        return ["localvault set KEY VALUE", *group_save_suggestions] if context.command&.name == "set"
+        return set_suggestions if context.command&.name == "set"
         return show_group_suggestions if context.command&.name == "show" || unknown_option == "--group-by"
         return ["localvault add HANDLE", "localvault team add HANDLE"] if context.namespace == ["team"] && context.command&.name == "add"
 
@@ -117,6 +121,14 @@ module LocalVault
         ]
       end
 
+      def set_suggestions
+        [
+          %(printf '%s' "$SECRET" | localvault set KEY --stdin),
+          "localvault set KEY VALUE",
+          *group_save_suggestions
+        ]
+      end
+
       def show_group_suggestions
         [
           "localvault show --group GROUP",

data/lib/localvault/cli/guard.rb

@@ -0,0 +1,87 @@
+require "thor"
+require "json"
+require "fileutils"
+require_relative "../guard"
+
+module LocalVault
+  class CLI
+    class Guard < Thor
+      desc "hook", "Claude Code hook entrypoint (reads hook JSON on stdin)"
+      long_desc <<~DESC
+        Reads a Claude Code PreToolUse/PostToolUse event on stdin. Blocks tool
+        calls whose input contains a stored plaintext secret value from any
+        session-unlocked vault, naming the key by fingerprint — never by value.
+        Fails open on any error so a broken guard cannot block all work.
+      DESC
+      def hook
+        event = JSON.parse($stdin.read)
+        result = LocalVault::Guard.evaluate(event)
+        if result[:exit] != 0
+          $stderr.puts result[:message]
+          exit result[:exit]
+        end
+      rescue StandardError
+        # fail open
+      end
+
+      desc "install", "Install the guard hooks into Claude Code settings"
+      method_option :project, type: :boolean, default: false,
+        desc: "Install into ./.claude/settings.json instead of ~/.claude/settings.json"
+      def install
+        path = settings_path(options[:project])
+        settings = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+        if LocalVault::Guard.merge_hooks!(settings)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, JSON.pretty_generate(settings) + "\n")
+          $stdout.puts "Installed LocalVault guard hooks in #{path}"
+          $stdout.puts "Restart Claude Code sessions to pick up hook changes."
+        else
+          $stdout.puts "LocalVault guard hooks already installed in #{path}"
+        end
+        warn_if_path_binary_lacks_guard
+      rescue JSON::ParserError
+        $stderr.puts "Error: #{path} is not valid JSON; fix it before installing."
+      end
+
+      desc "status", "Show guard hook installation status"
+      def status
+        { "user" => settings_path(false), "project" => settings_path(true) }.each do |label, path|
+          state = if !File.exist?(path)
+            "not installed"
+          else
+            begin
+              LocalVault::Guard.installed?(JSON.parse(File.read(path))) ? "installed" : "not installed"
+            rescue JSON::ParserError
+              "unreadable JSON"
+            end
+          end
+          $stdout.puts "#{label} (#{path}): #{state}"
+        end
+      end
+
+      no_commands do
+        # The installed hook wraps the entrypoint to fail open, so an old or
+        # missing PATH binary never breaks the user's sessions — but it also
+        # silently guards nothing, which deserves a loud note at install time.
+        def warn_if_path_binary_lacks_guard
+          help_output = `localvault help 2>/dev/null`
+          return if help_output.include?("guard")
+
+          $stderr.puts "Note: the `localvault` on your PATH does not support `guard hook` " \
+                       "(old version or different install). The hook fails open and guards " \
+                       "nothing until you upgrade: brew upgrade localvault"
+        rescue StandardError
+          nil
+        end
+
+        def settings_path(project)
+          if project
+            File.join(Dir.pwd, ".claude", "settings.json")
+          else
+            File.join(Dir.home, ".claude", "settings.json")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/localvault/cli.rb

@@ -4,7 +4,9 @@ require "base64"
 require "lipgloss"
 require_relative "env_projection"
 require_relative "key_lookup"
+require_relative "plaintext_output"
 require_relative "session_cache"
+require_relative "stdin_secret_input"
 require_relative "vault_resolver"
 require_relative "group_catalog"
 
@@ -49,6 +51,18 @@ module LocalVault
         1
       end
     end
+    class SetValueSourceError < Thor::Error
+      attr_reader :kind
+
+      def initialize(kind, message)
+        @kind = kind
+        super(message)
+      end
+
+      def exit_status
+        1
+      end
+    end
 
     def self.start(given_args = ARGV, config = {})
       require_relative "cli/error_presenter"
@@ -105,7 +119,9 @@ module LocalVault
       shell.say "  localvault demo               Create a demo vault to explore commands"
       shell.say ""
       shell.say "SECRETS"
-      shell.say "  localvault set KEY VALUE      Store a secret"
+      shell.say "  printf '%s' \"$SECRET\" | localvault set KEY --stdin"
+      shell.say "                              Store a secret without argv/history exposure"
+      shell.say "  localvault set KEY VALUE      Store a secret (compatibility path)"
       shell.say "  localvault set --group G K V  Store a secret inside group G"
       shell.say "  localvault get KEY            Retrieve a secret"
       shell.say "  localvault show               Display all secrets (masked by default)"
@@ -169,6 +185,7 @@ module LocalVault
       shell.say "  localvault login --status     Show current login status"
       shell.say "  localvault logout             Log out"
       shell.say "  localvault version            Print version"
+      shell.say "  localvault doctor             Check install and PATH readiness"
       shell.say "  localvault help [COMMAND]     Full help for any command"
       shell.say ""
     end
@@ -197,10 +214,14 @@ module LocalVault
       abort_with e.message
     end
 
-    desc "set KEY VALUE", "Store a secret (supports dot-notation for nested keys)"
+    desc "set KEY [VALUE]", "Store a secret (supports dot-notation for nested keys)"
     long_desc <<~DESC
       Store a secret in the current vault.
 
+      SAFE INPUT (preferred):
+\x05    printf '%s' "$SECRET" | localvault set KEY --stdin
+\x05    printf '%s' "$SECRET" | localvault set --group GROUP KEY --stdin
+
       FLAT KEY (simple):
 \x05    localvault set DATABASE_URL postgres://localhost/myapp
 \x05    localvault set STRIPE_KEY sk_live_abc123
@@ -215,33 +236,42 @@ module LocalVault
 \x05    localvault set GROUP.KEY VALUE
 \x05    localvault groups [QUERY]
 
+      Positional values may be visible in process lists and shell history.
       The dot separates project from key name. One vault can hold many projects.
       Use `localvault show -p platepose -v vault` to view a single project.
       Use `localvault import` to bulk-load from a .env, .json, or .yml file.
     DESC
     method_option :group, type: :string, desc: "Store KEY and VALUE inside this named group"
-    def set(key, value)
+    method_option :stdin, type: :boolean, default: false, desc: "Read VALUE from stdin instead of argv"
+    def set(key, value = nil)
+      validate_secret_value_source!(value)
       vault = open_vault!
       if options[:group]
         group = canonical_group_name(vault, options[:group])
         validate_group_segment!(group)
         validate_group_segment!(key)
         raise GroupSaveError, :collision if vault.all.key?(group) && !vault.all[group].is_a?(Hash)
+        value = read_secret_value(value)
         vault.set("#{group}.#{key}", value)
         $stdout.puts "Set #{key} in group `#{group}` in vault `#{vault.name}`."
         $stdout.puts
         $stdout.puts "Stored as:"
         $stdout.puts "  #{group}.#{key}"
       else
+        value = read_secret_value(value)
         vault.set(key, value)
         $stdout.puts "Set #{key} in vault '#{vault.name}'"
       end
+    rescue StdinSecretInput::InteractiveInput, StdinSecretInput::InvalidEncoding => e
+      raise SetValueSourceError.new(:stdin, e.message)
     rescue Vault::InvalidKeyName => e
       raise GroupSaveError, :invalid if options[:group]
       abort_with e.message
+      CommandStatus.error
     rescue RuntimeError => e
       raise GroupSaveError, :collision if options[:group]
       abort_with e.message
+      CommandStatus.error
     end
 
     desc "get KEY", "Retrieve a secret value by key"
@@ -263,9 +293,9 @@ module LocalVault
       lookup = KeyLookup.lookup(vault, key)
 
       if lookup.exact?
-        $stdout.puts lookup.value
+        print_plaintext(key, lookup.value)
       elsif lookup.single_match?
-        $stdout.puts vault.get(lookup.matches.first)
+        print_plaintext(lookup.matches.first, vault.get(lookup.matches.first))
       elsif lookup.multiple_matches?
         $stderr.puts "Error: Multiple keys match '#{key}'. Be more specific:"
         lookup.matches.each { |k| $stderr.puts "  #{k}" }
@@ -374,6 +404,15 @@ module LocalVault
     method_option :profile, type: :string, desc: "Apply a built-in env mapping profile (aws)"
     def env
       vault = open_vault!
+      unless PlaintextOutput.permitted?(purpose: "Export plaintext values")
+        abort_with <<~MSG.strip
+          refusing to print plaintext env exports: stdout is a captured stream, not an interactive terminal.
+          Use process-scoped injection instead:
+            localvault exec [--only KEYS|--map KEY=ENV_NAME|--profile aws] -- your-command
+          A human at a terminal is asked to confirm; agents and CI must use injection.
+        MSG
+        return
+      end
       skip_warn = ->(k) { $stderr.puts "Warning: skipping unsafe key '#{k}'" }
       $stdout.puts vault.export_env(**env_projection_options(on_skip: skip_warn))
     rescue EnvProjection::InvalidMapping, EnvProjection::UnknownProfile => e
@@ -491,6 +530,7 @@ module LocalVault
     def show
       vault = open_vault!
       secrets = vault.all
+      reveal = options[:reveal] && reveal_permitted?
 
       named_group_query = options[:group] && ![GROUP_ALL_SENTINEL, GROUP_OFF_SENTINEL].include?(options[:group])
       if secrets.empty? && !named_group_query
@@ -504,21 +544,21 @@ module LocalVault
           abort_with "No project '#{options[:project]}' in vault '#{vault.name}'"
           return
         end
-        render_table(group.sort.to_h, "#{vault.name}/#{options[:project]}", reveal: options[:reveal])
+        render_table(group.sort.to_h, "#{vault.name}/#{options[:project]}", reveal: reveal)
       elsif options[:group] && ![GROUP_ALL_SENTINEL, GROUP_OFF_SENTINEL].include?(options[:group])
         match = GroupCatalog.new(secrets).resolve(options[:group])
         if match.group
           entries = match.group.entries.to_h { |entry| [entry.label, entry.value] }
-          render_table(entries, "#{vault.name}/#{match.group.name}", reveal: options[:reveal])
+          render_table(entries, "#{vault.name}/#{match.group.name}", reveal: reveal)
         elsif match.kind == :ambiguous
           raise GroupSelectionError.new(:ambiguous, query: options[:group], candidates: match.groups.map(&:name))
         else
           raise GroupSelectionError.new(:absent, query: options[:group])
         end
       elsif options[:group] != GROUP_OFF_SENTINEL && (options[:group] || secrets.values.any? { |v| v.is_a?(Hash) })
-        render_grouped_table(secrets, vault.name, reveal: options[:reveal])
+        render_grouped_table(secrets, vault.name, reveal: reveal)
       else
-        render_table(secrets.sort.to_h, vault.name, reveal: options[:reveal])
+        render_table(secrets.sort.to_h, vault.name, reveal: reveal)
       end
     end
 
@@ -725,7 +765,9 @@ module LocalVault
     require_relative "cli/keys"
     require_relative "cli/team"
     require_relative "cli/sync"
+    require_relative "cli/guard"
 
+    register(Guard, "guard", "guard SUBCOMMAND", "Block plaintext secrets in agent tool traffic (Claude Code hooks)")
     register(Keys, "keys", "keys SUBCOMMAND", "Manage your X25519 keypair for vault sharing")
     register(Team, "team", "team SUBCOMMAND", "Manage vault team access")
     register(Sync, "sync", "sync SUBCOMMAND", "Sync vaults to InventList cloud")
@@ -1463,6 +1505,46 @@ module LocalVault
       $stdout.puts "localvault #{VERSION}"
     end
 
+    desc "doctor", "Check install and PATH readiness"
+    long_desc <<~DESC
+      Check whether the localvault executable selected by PATH matches the
+      install you expect.
+
+      This catches common Homebrew/asdf shadowing issues after upgrades:
+\x05    localvault doctor
+\x05    which -a localvault
+    DESC
+    def doctor
+      paths = localvault_paths
+      warnings = localvault_path_warnings(paths)
+
+      $stdout.puts "LocalVault doctor"
+      $stdout.puts "Version: localvault #{VERSION}"
+      $stdout.puts "Home: #{Config.root_path}"
+
+      if paths.empty?
+        $stdout.puts "Executable selected by PATH: not found"
+      else
+        $stdout.puts "Executable selected by PATH: #{paths.first}"
+        $stdout.puts "All localvault executables on PATH:"
+        paths.each_with_index { |path, index| $stdout.puts "  #{index + 1}. #{path}" }
+      end
+
+      if warnings.empty?
+        $stdout.puts "PATH: ok"
+        CommandStatus.ok
+      else
+        $stdout.puts
+        warnings.each { |warning| $stdout.puts "Warning: #{warning}" }
+        $stdout.puts
+        $stdout.puts "Suggested checks:"
+        $stdout.puts "  asdf reshim ruby"
+        $stdout.puts "  hash -r"
+        $stdout.puts "  which -a localvault"
+        CommandStatus.error
+      end
+    end
+
     def self.exit_on_failure?
       false
     end
@@ -1489,6 +1571,22 @@ module LocalVault
 
     private
 
+    def validate_secret_value_source!(value)
+      if options[:stdin] && !value.nil?
+        raise SetValueSourceError.new(:multiple, "Use either a positional VALUE or --stdin, not both.")
+      end
+
+      return if options[:stdin] || !value.nil?
+
+      raise SetValueSourceError.new(:missing, "Provide a VALUE or read one with --stdin.")
+    end
+
+    def read_secret_value(value)
+      return value unless options[:stdin]
+
+      StdinSecretInput.read($stdin)
+    end
+
     def canonical_group_name(vault, supplied)
       groups = GroupCatalog.new(vault.all).groups
       return supplied if groups.any? { |group| group.name == supplied }
@@ -1830,6 +1928,29 @@ module LocalVault
       $stderr.puts "Error: #{message}"
     end
 
+    # --- plaintext gating (see docs/plans/07-agent-plaintext-containment.md) ---
+
+    def print_plaintext(key, value)
+      unless PlaintextOutput.permitted?(purpose: "Print plaintext value of '#{key}'")
+        env_name = key.split(".").last.upcase
+        abort_with <<~MSG.strip
+          refusing to print plaintext for '#{key}': stdout is a captured stream, not an interactive terminal.
+          Use process-scoped injection instead:
+            localvault exec --map #{key}=#{env_name} -- your-command
+          A human at a terminal is asked to confirm; agents and CI must use injection.
+        MSG
+        return
+      end
+      $stdout.puts value
+    end
+
+    def reveal_permitted?
+      return true if PlaintextOutput.permitted?(purpose: "Reveal plaintext values")
+
+      $stderr.puts "Masking values: stdout is a captured stream. Use `localvault exec` for injection."
+      false
+    end
+
     # --- install-mcp helpers ---
 
     # Claude Code: use `claude mcp add --scope user` so the server is
@@ -1903,14 +2024,47 @@ module LocalVault
 
     no_commands do
       def find_binary(name)
-        path = `which #{name} 2>/dev/null`.strip
-        path.empty? ? nil : path
+        executable_paths_for(name).first
       end
 
       def system_command_exists?(cmd)
         !find_binary(cmd).nil?
       end
 
+      def localvault_paths
+        executable_paths_for("localvault")
+      end
+
+      def executable_paths_for(name)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).filter_map do |directory|
+          next if directory.empty?
+
+          path = File.join(directory, name)
+          path if File.executable?(path) && !File.directory?(path)
+        end.uniq
+      end
+
+      def localvault_path_warnings(paths)
+        warnings = []
+        if paths.empty?
+          warnings << "localvault is not on PATH. Brew upgrades may be installed but unreachable."
+          return warnings
+        end
+
+        if paths.first.include?("/.asdf/shims/") && paths.any? { |path| homebrew_localvault_path?(path) }
+          warnings << "PATH selects an asdf shim before Homebrew localvault. " \
+            "A stale shim can hide the upgraded brew executable."
+        elsif paths.length > 1
+          warnings << "Multiple localvault executables are on PATH. Confirm the first entry is the one you intend."
+        end
+
+        warnings
+      end
+
+      def homebrew_localvault_path?(path)
+        path.start_with?("/opt/homebrew/bin/", "/usr/local/bin/")
+      end
+
       def cursor_settings_path
         File.expand_path("~/.cursor/mcp.json")
       end

data/lib/localvault/guard.rb

@@ -0,0 +1,148 @@
+require "json"
+require "digest"
+require_relative "store"
+require_relative "session_cache"
+
+module LocalVault
+  # Scans agent tool traffic (Claude Code hook events) for stored plaintext
+  # secret values, so a value already in an agent's context — retrieved or
+  # freshly generated, once stored — can never pass through a command line
+  # unnoticed.
+  #
+  # Failure posture is fail-open: locked vaults, unreadable stores, and
+  # malformed events all allow the tool call. A locked vault cannot have fed
+  # values into the session, and a guard that blocks all work when it cannot
+  # check gets uninstalled.
+  module Guard
+    MIN_VALUE_LENGTH = 8
+    HOOK_ENTRYPOINT = "localvault guard hook".freeze
+    # The installed command must fail open on machines where the binary is
+    # old, missing, or broken — otherwise every Bash call errors for users
+    # whose settings outlive their localvault install. Only a genuine deny
+    # (exit 2) is allowed through; every other exit becomes a silent allow.
+    HOOK_COMMAND = %(sh -c 'out=$(#{HOOK_ENTRYPOINT} 2>&1); s=$?; if [ $s -eq 2 ]; then echo "$out" >&2; exit 2; fi; exit 0').freeze
+    HOOK_EVENTS = %w[PreToolUse PostToolUse].freeze
+    ALLOW = { exit: 0, message: nil }.freeze
+
+    Match = Struct.new(:vault, :key, :fingerprint, keyword_init: true)
+
+    # Plaintext values from every session-unlocked vault.
+    #
+    # @return [Array<Hash>] entries with :vault, :key, :value
+    def self.unlocked_secrets
+      Store.list_vaults.flat_map do |name|
+        master_key = SessionCache.get(name)
+        next [] unless master_key
+
+        begin
+          vault = Vault.new(name: name, master_key: master_key)
+          flatten(vault.all).map { |key, value| { vault: name, key: key, value: value } }
+        rescue StandardError
+          []
+        end
+      end
+    end
+
+    def self.flatten(hash, prefix = nil)
+      hash.each_with_object({}) do |(k, v), out|
+        key = prefix ? "#{prefix}.#{k}" : k.to_s
+        if v.is_a?(Hash)
+          out.merge!(flatten(v, key))
+        else
+          out[key] = v.to_s
+        end
+      end
+    end
+
+    # @return [Array<Match>] stored secret values appearing in +text+
+    def self.scan(text, secrets = unlocked_secrets)
+      return [] if text.nil? || text.empty?
+
+      secrets.filter_map do |entry|
+        value = entry[:value]
+        next if value.nil? || value.length < MIN_VALUE_LENGTH
+        next unless text.include?(value)
+
+        Match.new(vault: entry[:vault], key: entry[:key], fingerprint: fingerprint(value))
+      end
+    end
+
+    def self.fingerprint(value)
+      Digest::SHA256.hexdigest(value)[0, 12]
+    end
+
+    def self.strings_in(node)
+      case node
+      when String then [node]
+      when Hash then node.values.flat_map { |v| strings_in(v) }
+      when Array then node.flat_map { |v| strings_in(v) }
+      else []
+      end
+    end
+
+    # Evaluate a parsed Claude Code hook event.
+    #
+    # @return [Hash] +{exit: Integer, message: String|nil}+ — exit 2 blocks a
+    #   PreToolUse call / surfaces a PostToolUse warning to the agent
+    def self.evaluate(event, secrets = unlocked_secrets)
+      case event["hook_event_name"]
+      when "PreToolUse"
+        matches = scan(strings_in(event["tool_input"]).join("\n"), secrets)
+        matches.empty? ? ALLOW : { exit: 2, message: deny_message(matches) }
+      when "PostToolUse"
+        matches = scan(strings_in(event["tool_response"]).join("\n"), secrets)
+        matches.empty? ? ALLOW : { exit: 2, message: exposure_message(matches) }
+      else
+        ALLOW
+      end
+    rescue StandardError
+      ALLOW
+    end
+
+    def self.deny_message(matches)
+      first = matches.first
+      env_name = first.key.split(".").last.upcase
+      <<~MSG.strip
+        LocalVault guard: blocked — this tool input contains the plaintext value of #{name_list(matches)}.
+        Never place secret values in commands or arguments. Inject them instead:
+          localvault exec --map #{first.key}=#{env_name} -- your-command
+        or pipe a new value with: printf '%s' "$VALUE" | localvault set KEY --stdin
+      MSG
+    end
+
+    def self.exposure_message(matches)
+      <<~MSG.strip
+        LocalVault guard: this command's output contained the plaintext value of #{name_list(matches)} and has entered the transcript.
+        Treat the value as exposed: rotate it, then store the replacement via --stdin.
+        Avoid commands that print secrets; use scoped injection (localvault exec --only/--map).
+      MSG
+    end
+
+    def self.name_list(matches)
+      matches.map { |m| "#{m.vault}/#{m.key} (sha256:#{m.fingerprint})" }.join(", ")
+    end
+
+    # Idempotently add the guard hook entries to a Claude Code settings hash.
+    #
+    # @return [Boolean] whether the settings were modified
+    def self.merge_hooks!(settings)
+      changed = false
+      hooks = settings["hooks"] ||= {}
+      HOOK_EVENTS.each do |event|
+        entries = hooks[event] ||= []
+        next if entries.any? { |e| (e["hooks"] || []).any? { |h| h["command"].to_s.include?(HOOK_ENTRYPOINT) } }
+
+        entries << { "matcher" => "Bash", "hooks" => [{ "type" => "command", "command" => HOOK_COMMAND }] }
+        changed = true
+      end
+      changed
+    end
+
+    def self.installed?(settings)
+      hooks = settings["hooks"] || {}
+      HOOK_EVENTS.all? do |event|
+        (hooks[event] || []).any? { |e| (e["hooks"] || []).any? { |h| h["command"].to_s.include?(HOOK_ENTRYPOINT) } }
+      end
+    end
+  end
+end

data/lib/localvault/plaintext_output.rb

@@ -0,0 +1,48 @@
+module LocalVault
+  # Gate for printing plaintext secret values.
+  #
+  # Plaintext may flow to an interactive terminal (a human is watching). When
+  # stdout is captured (pipe, command substitution, agent shell), a human can
+  # confirm with one keystroke on /dev/tty. An agent's shell has no /dev/tty,
+  # and there is deliberately no flag, environment variable, or config bypass:
+  # anything discoverable from the binary would be discovered by an agent.
+  module PlaintextOutput
+    TTY_PATH = "/dev/tty".freeze
+
+    class << self
+      # In-process overrides for tests only — unreachable from the installed
+      # binary, unlike an env var or CLI flag would be.
+      attr_accessor :assume_tty
+      attr_accessor :tty_override # {input: IO, output: IO}
+    end
+
+    # @param out [IO] the stream plaintext would be written to
+    # @param purpose [String] short description used in the /dev/tty prompt
+    # @return [Boolean] whether plaintext may be printed to +out+
+    def self.permitted?(out: $stdout, purpose: "Print plaintext")
+      return true if assume_tty
+      return true if out.respond_to?(:tty?) && out.tty?
+
+      confirm("#{purpose}? [y/N] ")
+    end
+
+    def self.confirm(prompt)
+      with_tty do |input, output|
+        output.write(prompt)
+        output.flush
+        answer = input.gets
+        !answer.nil? && %w[y yes].include?(answer.strip.downcase)
+      end
+    end
+
+    def self.with_tty(&block)
+      if tty_override
+        return yield(tty_override[:input], tty_override[:output])
+      end
+
+      File.open(TTY_PATH, "r+") { |tty| yield(tty, tty) }
+    rescue SystemCallError, IOError
+      false
+    end
+  end
+end

data/lib/localvault/stdin_secret_input.rb

@@ -0,0 +1,22 @@
+module LocalVault
+  class StdinSecretInput
+    class InteractiveInput < StandardError; end
+    class InvalidEncoding < StandardError; end
+
+    PIPE_EXAMPLE = %(printf '%s' "$SECRET" | localvault set KEY --stdin).freeze
+
+    def self.read(input = $stdin)
+      if input.respond_to?(:tty?) && input.tty?
+        raise InteractiveInput, "Refusing to read secret from interactive stdin. " \
+          "Pipe it instead: #{PIPE_EXAMPLE}"
+      end
+
+      input.binmode if input.respond_to?(:binmode)
+      value = input.read || ""
+      value = value.dup.force_encoding(Encoding::UTF_8)
+      raise InvalidEncoding, "Secret value must be valid UTF-8" unless value.valid_encoding?
+
+      value
+    end
+  end
+end

data/lib/localvault/version.rb

@@ -1,3 +1,3 @@
 module LocalVault
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end

data/lib/localvault.rb

@@ -5,6 +5,9 @@ require_relative "localvault/store"
 require_relative "localvault/env_projection"
 require_relative "localvault/key_lookup"
 require_relative "localvault/vault_resolver"
+require_relative "localvault/stdin_secret_input"
+require_relative "localvault/plaintext_output"
+require_relative "localvault/guard"
 require_relative "localvault/vault"
 require_relative "localvault/identity"
 require_relative "localvault/share_crypto"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: localvault
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -109,6 +109,7 @@ files:
 - lib/localvault/api_client.rb
 - lib/localvault/cli.rb
 - lib/localvault/cli/error_presenter.rb
+- lib/localvault/cli/guard.rb
 - lib/localvault/cli/keys.rb
 - lib/localvault/cli/sync.rb
 - lib/localvault/cli/team.rb
@@ -117,6 +118,7 @@ files:
 - lib/localvault/crypto.rb
 - lib/localvault/env_projection.rb
 - lib/localvault/group_catalog.rb
+- lib/localvault/guard.rb
 - lib/localvault/identity.rb
 - lib/localvault/input_validation.rb
 - lib/localvault/key_lookup.rb
@@ -124,8 +126,10 @@ files:
 - lib/localvault/mcp/exec_command_builder.rb
 - lib/localvault/mcp/server.rb
 - lib/localvault/mcp/tools.rb
+- lib/localvault/plaintext_output.rb
 - lib/localvault/session_cache.rb
 - lib/localvault/share_crypto.rb
+- lib/localvault/stdin_secret_input.rb
 - lib/localvault/store.rb
 - lib/localvault/sync_bundle.rb
 - lib/localvault/sync_state.rb