kward 0.77.0 → 0.79.0

data/lib/kward/pan/server.rb

@@ -13,11 +13,12 @@ require_relative "../plugin_registry"
 require_relative "../prompts/commands"
 require_relative "../rpc/transcript_normalizer"
 require_relative "../session_store"
+require_relative "../skills/capture"
 require_relative "../session_trash"
 require_relative "../tools/tool_call"
 require_relative "../tools/registry"
 require_relative "../version"
-require_relative "../workspace"
+require_relative "../workspace_factory"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -33,7 +34,11 @@ module Kward
       @client = client
       @output = output
       @udp_socket_class = udp_socket_class
-      @workspace = Workspace.new(root: working_directory)
+      @workspace = WorkspaceFactory.build(
+        root: working_directory,
+        guardrails: ConfigFiles.workspace_guardrails_enabled?(config),
+        config: config
+      )
       @full_config = config
       @config = pan_config(config)
       @host = @config.fetch("host", DEFAULT_HOST).to_s
@@ -234,12 +239,18 @@ module Kward
         write_json(socket, 200, transcript: transcript_items, session: active_session_payload, workspace: @workspace.root.to_s)
       when ["GET", "/sessions"]
         write_json(socket, 200, sessions: session_payloads, activeSessionId: @session.id)
+      when ["GET", "/skill-capture/sessions"]
+        write_json(socket, 200, sessions: skill_capture_sessions)
       when ["GET", "/events"]
         stream_events(socket)
       when ["POST", "/turn"]
         handle_turn(socket, request[:body], request[:headers])
       when ["POST", "/sessions"]
         handle_session_action(socket, request[:body], request[:headers])
+      when ["POST", "/skill-capture/draft"]
+        handle_skill_capture_draft(socket, request[:body], request[:headers])
+      when ["POST", "/skill-capture/save"]
+        handle_skill_capture_save(socket, request[:body], request[:headers])
       else
         write_response(socket, 404, { "Content-Type" => "text/plain; charset=utf-8" }, "Not found\n")
       end
@@ -308,6 +319,42 @@ module Kward
       write_json(socket, 400, ok: false, error: "Invalid JSON")
     end
 
+    def handle_skill_capture_draft(socket, body, headers)
+      return write_json(socket, 415, ok: false, error: "Content-Type must be application/json") unless json_request?(headers)
+
+      params = JSON.parse(body.empty? ? "{}" : body)
+      draft = skill_capture.generate(params.fetch("sessionPath"))
+      write_json(socket, 200, ok: true, content: draft.content, sourcePath: draft.source_path, name: draft.name, description: draft.description)
+    rescue JSON::ParserError
+      write_json(socket, 400, ok: false, error: "Invalid JSON")
+    rescue Skills::Capture::Error => error
+      write_json(socket, 422, ok: false, error: error.message)
+    end
+
+    def handle_skill_capture_save(socket, body, headers)
+      return write_json(socket, 415, ok: false, error: "Content-Type must be application/json") unless json_request?(headers)
+
+      params = JSON.parse(body.empty? ? "{}" : body)
+      draft = skill_capture.save(params.fetch("content"), overwrite: params["overwrite"] == true)
+      write_json(socket, 200, ok: true, path: skill_capture.skill_path(draft.name), name: draft.name, description: draft.description)
+    rescue JSON::ParserError
+      write_json(socket, 400, ok: false, error: "Invalid JSON")
+    rescue Skills::Capture::ConflictError => error
+      write_json(socket, 409, ok: false, error: error.message)
+    rescue Skills::Capture::Error => error
+      write_json(socket, 422, ok: false, error: error.message)
+    end
+
+    def skill_capture_sessions
+      @session_store.capture_candidates.map do |session|
+        { path: session.path, name: session.name, firstMessage: session.first_message, workspaceRoot: session.cwd, modifiedAt: session.modified_at.utc.iso8601(3) }
+      end
+    end
+
+    def skill_capture
+      @skill_capture ||= Skills::Capture.new(session_store: @session_store, client: @client, config_dir: @session_store.config_dir)
+    end
+
     def update_session(params)
       return { status: 409, ok: false, error: "Wait for queued turns to finish before changing sessions" } if turns_pending?
 

data/lib/kward/permissions/policy.rb

@@ -0,0 +1,171 @@
+require "uri"
+
+# Namespace for Kward's permission-policy runtime.
+module Kward
+  module Permissions
+    # Evaluates the opt-in permission policy for model-requested tool calls.
+    #
+    # The policy is intentionally a decision layer, not a process sandbox. It
+    # can prevent Kward from starting a tool, but it cannot constrain a shell
+    # command after it has begun. OS-enforced sandboxing belongs at a lower
+    # process boundary.
+    class Policy
+      MODES = %w[ask read-only workspace-write deny-by-default].freeze
+      NETWORK_TOOLS = %w[web_search fetch_content fetch_raw].freeze
+      FILE_CHANGE_TOOLS = %w[write_file edit_file].freeze
+
+      Decision = Struct.new(:action, :reason, keyword_init: true) do
+        def allowed?
+          action == :allow
+        end
+
+        def approval_required?
+          action == :ask
+        end
+
+        def denied?
+          action == :deny
+        end
+      end
+
+      def self.from_config(config)
+        permissions = config["permissions"].is_a?(Hash) ? config["permissions"] : {}
+        new(
+          enabled: permissions["enabled"] == true,
+          mode: permissions["mode"],
+          allow: permissions["allow"],
+          ask: permissions["ask"],
+          deny: permissions["deny"],
+          write_scopes: permissions.key?("write_scopes") ? permissions["write_scopes"] : nil
+        )
+      end
+
+      def initialize(enabled: false, mode: "ask", allow: [], ask: [], deny: [], write_scopes: nil)
+        @enabled = enabled == true
+        @mode = normalize_mode(mode)
+        @allow = normalize_rules(allow)
+        @ask = normalize_rules(ask)
+        @deny = normalize_rules(deny)
+        @write_scopes = normalize_scopes(write_scopes)
+        @session_allowed_tools = {}
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      # Allows this model tool for the remaining lifetime of this policy object.
+      # A matching deny or ask rule still takes precedence over this temporary grant.
+      def allow_for_session!(tool_name)
+        @session_allowed_tools[tool_name.to_s] = true
+      end
+
+      def decision_for(tool_name, arguments, source: nil)
+        return Decision.new(action: :allow, reason: "permissions disabled") unless enabled?
+
+        request = request_for(tool_name, arguments, source: source)
+        return Decision.new(action: :deny, reason: "matched deny rule") if matches?(@deny, request)
+        return Decision.new(action: :ask, reason: "matched ask rule") if matches?(@ask, request)
+        return Decision.new(action: :allow, reason: "matched allow rule") if matches?(@allow, request)
+        return Decision.new(action: :allow, reason: "allowed for this session") if @session_allowed_tools[request.fetch("tool")]
+
+        default_decision(request)
+      end
+
+      private
+
+      def normalize_mode(mode)
+        value = mode.to_s
+        MODES.include?(value) ? value : "ask"
+      end
+
+      def normalize_rules(rules)
+        Array(rules).filter_map do |rule|
+          next unless rule.is_a?(Hash)
+
+          rule.transform_keys(&:to_s).slice("tool", "path", "host", "command", "source")
+        end
+      end
+
+      def normalize_scopes(scopes)
+        return nil if scopes.nil?
+
+        Array(scopes).map(&:to_s).reject(&:empty?)
+      end
+
+      def request_for(tool_name, arguments, source:)
+        name = tool_name.to_s
+        args = arguments.to_h
+        {
+          "tool" => name,
+          "path" => args["path"] || args[:path],
+          "host" => request_host(name, args),
+          "command" => args["command"] || args[:command],
+          "source" => source.to_s
+        }.compact.transform_values(&:to_s)
+      end
+
+      def request_host(name, arguments)
+        return nil unless %w[fetch_content fetch_raw].include?(name)
+
+        URI.parse((arguments["url"] || arguments[:url]).to_s).host
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def matches?(rules, request)
+        rules.any? { |rule| rule_matches?(rule, request) }
+      end
+
+      def rule_matches?(rule, request)
+        return false if rule.empty?
+
+        rule.all? do |field, pattern|
+          value = request[field]
+          value && glob_match?(pattern.to_s, value)
+        end
+      end
+
+      def glob_match?(pattern, value)
+        expression = Regexp.escape(pattern).gsub("\\*\\*", ".*").gsub("\\*", "[^/]*")
+        Regexp.new("\\A#{expression}\\z").match?(value)
+      end
+
+      def default_decision(request)
+        return Decision.new(action: :deny, reason: "read-only mode") if @mode == "read-only" && risky?(request)
+        return Decision.new(action: :deny, reason: "deny-by-default mode") if @mode == "deny-by-default" && risky?(request)
+
+        if file_change?(request) && outside_write_scopes?(request)
+          return Decision.new(action: :deny, reason: "path outside write scopes")
+        end
+
+        if @mode == "workspace-write" && file_change?(request)
+          return Decision.new(action: :allow, reason: "workspace write mode")
+        end
+
+        return Decision.new(action: :allow, reason: "read-only tool") unless risky?(request)
+
+        Decision.new(action: :ask, reason: "#{request.fetch("tool")} requires approval")
+      end
+
+      def file_change?(request)
+        FILE_CHANGE_TOOLS.include?(request.fetch("tool"))
+      end
+
+      def network?(request)
+        NETWORK_TOOLS.include?(request.fetch("tool")) || request["source"] == "mcp"
+      end
+
+      def risky?(request)
+        file_change?(request) || request.fetch("tool") == "run_shell_command" || network?(request)
+      end
+
+      def outside_write_scopes?(request)
+        return false if @write_scopes.nil?
+
+        path = request["path"]
+        path.nil? || !@write_scopes.any? { |scope| glob_match?(scope, path) }
+      end
+    end
+  end
+end

data/lib/kward/plugin_registry.rb

@@ -34,6 +34,10 @@ module Kward
       end
     end
 
+    # Registered plugin-owned tab runtime. Its factory receives a
+    # `PluginTabHost` and its persisted descriptor, then returns a driver.
+    TabType = Struct.new(:id, :name, :title, :singleton, :rpc, :transcript_events, :path, :handler, keyword_init: true)
+
     # Read-only event passed to plugin transcript observers.
     TranscriptEvent = Struct.new(:type, :payload, keyword_init: true) do
       def to_h
@@ -264,6 +268,23 @@ module Kward
       def interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", &block)
         @registry.register_interactive_command(name, rows: rows, fps: fps, description: description, argument_hint: argument_hint, path: @path, &block)
       end
+
+      # Registers a plugin-owned tab type for the interactive CLI. `id` is a
+      # durable identifier used in persisted tab layouts and must not change.
+      # The factory receives a `PluginTabHost` and a descriptor hash.
+      #
+      # @param name [String] command name used by `/tab open <name>`
+      # @param id [String] stable persisted tab type identifier
+      # @param title [String] default tab label
+      # @param singleton [Symbol] `:global` for one shared plugin runtime
+      # @param transcript_events [Boolean] allow global transcript observers to receive this tab's events
+      # @yieldparam host [PluginTabHost] supported host dependencies
+      # @yieldparam descriptor [Hash] persisted tab descriptor
+      # @return [void]
+      # @api public
+      def tab_type(name, id:, title: nil, singleton: nil, rpc: false, transcript_events: false, &block)
+        @registry.register_tab_type(name, id: id, title: title, singleton: singleton, rpc: rpc, transcript_events: transcript_events, path: @path, &block)
+      end
     end
 
     # Mutable singleton guard used while loading trusted plugin files.
@@ -282,6 +303,8 @@ module Kward
       @reserved_commands = reserved_commands.map(&:to_s)
       @commands = {}
       @interactive_commands = {}
+      @tab_types = {}
+      @tab_types_by_id = {}
       @footer = nil
       @footer_path = nil
       @transcript_event_handlers = []
@@ -312,6 +335,18 @@ module Kward
       @interactive_commands[name.to_s]
     end
 
+    def tab_types
+      @tab_types.values
+    end
+
+    def tab_type_for(name)
+      @tab_types[name.to_s]
+    end
+
+    def tab_type_for_id(id)
+      @tab_types_by_id[id.to_s]
+    end
+
     def footer_renderer
       @footer
     end
@@ -366,7 +401,7 @@ module Kward
       previous_path = self.class.loading_path
       self.class.loading_registry = self
       self.class.loading_path = path
-      Kernel.load(path)
+      Kernel.load(path, true)
       @paths << path
     rescue StandardError => e
       warn "Warning: skipping Kward plugin #{path}: #{e.message}"
@@ -429,6 +464,23 @@ module Kward
       )
     end
 
+    def register_tab_type(name, id:, title: nil, singleton: nil, rpc: false, transcript_events: false, path: nil, &handler)
+      name = name.to_s
+      id = id.to_s
+      raise "Plugin tab type name is invalid: #{name}" unless name.match?(COMMAND_NAME_PATTERN)
+      raise "Plugin tab type id is required" if id.empty?
+      raise "Plugin tab type #{name} requires a handler" unless handler
+
+      if @tab_types.key?(name) || @tab_types_by_id.key?(id)
+        warn "Warning: skipping duplicate Kward plugin tab type #{id}: #{path}"
+        return nil
+      end
+
+      tab_type = TabType.new(id: id, name: name, title: title.to_s.empty? ? name.capitalize : title.to_s, singleton: singleton&.to_sym, rpc: rpc == true, transcript_events: transcript_events == true, path: path, handler: handler)
+      @tab_types[name] = tab_type
+      @tab_types_by_id[id] = tab_type
+    end
+
     def register_footer(path: nil, &renderer)
       raise "Plugin footer requires a renderer" unless renderer
 
@@ -500,7 +552,7 @@ module Kward
       end
     end
 
-    def transcript_event(type, payload)
+    def transcript_event(type, payload = {})
       TranscriptEvent.new(
         type: type,
         payload: DeepCopy.freeze(DeepCopy.dup(payload))

data/lib/kward/prompt_interface/approval_prompt.rb

@@ -0,0 +1,62 @@
+require "json"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  class PromptInterface
+    # Tool-approval overlay built on the structured question modal.
+    module ApprovalPrompt
+      # Asks the captain to approve a model-requested tool call. Cancellation is
+      # intentionally a denial so a closed or interrupted overlay never permits
+      # a side effect.
+      def ask_tool_approval(tool_name:, args:, reason: nil)
+        summary, details = tool_approval_details(tool_name, args)
+        question = (["The agent wants to #{summary}."] + Array(details) + [reason.to_s].reject(&:empty?)).join("\n")
+        answers = ask_user_question([
+          {
+            header: "Approval required · #{tool_approval_title(tool_name)}",
+            question: question,
+            options: [
+              { label: "Allow once", description: "Run this tool call." },
+              { label: "Allow this tool for this session", description: "Run this call and future calls to #{tool_name}." },
+              { label: "Deny", description: "Do not run this tool call." }
+            ]
+          }
+        ])
+        answer = answers&.first
+        return { denied_message: answer[:answer] } if answer&.fetch(:custom, false) && !answer[:answer].to_s.empty?
+
+        case answer&.fetch(:answer, nil)
+        when "Allow once" then true
+        when "Allow this tool for this session" then :allow_for_session
+        else false
+        end
+      end
+
+      private
+
+      def tool_approval_title(tool_name)
+        case tool_name.to_s
+        when "run_shell_command" then "Shell command"
+        when "write_file" then "Write file"
+        when "edit_file" then "Edit file"
+        when "fetch_content", "fetch_raw" then "Network request"
+        when "web_search" then "Web search"
+        else tool_name.to_s.tr("_", " ").capitalize
+        end
+      end
+
+      def tool_approval_details(tool_name, args)
+        action = case tool_name.to_s
+                 when "run_shell_command" then "run this shell command"
+                 when "write_file" then "write this file"
+                 when "edit_file" then "edit this file"
+                 when "read_file", "read_skill" then "read these resources"
+                 when "fetch_content", "fetch_raw" then "make this network request"
+                 when "web_search" then "search the web"
+                 else "use #{tool_name}"
+                 end
+        [action, ["Arguments:\n#{JSON.pretty_generate(args.to_h)}"]]
+      end
+    end
+  end
+end

data/lib/kward/prompt_interface/editor/controller.rb

@@ -153,11 +153,11 @@ module Kward
             pending_deletions << line[1..].to_s
           elsif line.start_with?("+")
             deleted = pending_deletions.shift
-            rows << side_by_side_diff_row(deleted && "- #{deleted}", "+ #{line[1..]}", width)
+            rows.concat(side_by_side_diff_rows(deleted && "- #{deleted}", "+ #{line[1..]}", width))
           else
             rows.concat(flush_side_by_side_deletions(pending_deletions, width))
             text = line.start_with?(" ") ? line[1..].to_s : line
-            rows << side_by_side_diff_row("  #{text}", "  #{text}", width)
+            rows.concat(side_by_side_diff_rows("  #{text}", "  #{text}", width))
           end
         end
 
@@ -170,7 +170,17 @@ module Kward
       end
 
       def flush_side_by_side_deletions(lines, width)
-        lines.shift(lines.length).map { |line| side_by_side_diff_row("- #{line}", nil, width) }
+        lines.shift(lines.length).flat_map { |line| side_by_side_diff_rows("- #{line}", nil, width) }
+      end
+
+      def side_by_side_diff_rows(left, right, width)
+        return [side_by_side_diff_row(left, right, width)] unless current_editor_soft_wrap?
+
+        left_lines = side_by_side_diff_cell_lines(left, width)
+        right_lines = side_by_side_diff_cell_lines(right, width)
+        [left_lines.length, right_lines.length].max.times.map do |index|
+          side_by_side_diff_row(left_lines[index], right_lines[index], width)
+        end
       end
 
       def side_by_side_diff_row(left, right, width)
@@ -184,6 +194,17 @@ module Kward
         visible_truncate(value, width)
       end
 
+      def side_by_side_diff_cell_lines(text, width)
+        return [""] if text.nil?
+
+        value = text.to_s
+        prefix = value.start_with?("- ", "+ ", "  ") ? value[0, 2] : ""
+        content = value.delete_prefix(prefix)
+        return [prefix] if content.empty?
+
+        content.chars.each_slice([width - prefix.length, 1].max).map { |characters| "#{prefix}#{characters.join}" }
+      end
+
       def side_by_side_diff_column_width
         content_width = [screen_width - 4, 1].max
         gutter_width = [[999.to_s.length, 4].max + 3, 1].max
@@ -220,6 +241,7 @@ module Kward
         @editor_text_width = nil
         @editor_save_as_active = false
         @editor_save_as_buffer = ""
+        @editor_save_callback = nil
         @editor_state = nil
         @prompt_label = "You>"
         self.composer_input = ""
@@ -1150,6 +1172,17 @@ module Kward
           return true
         end
 
+        if @editor_save_callback
+          result = @editor_save_callback.call(@editor_state.buffer)
+          if result.to_s.empty?
+            close_editor
+            return true
+          end
+
+          @editor_state.status = result.to_s
+          return false
+        end
+
         if path.to_s.strip.empty? && @editor_state.path.to_s.empty?
           if prompt_for_path
             begin_editor_save_as

data/lib/kward/prompt_interface/question_prompt.rb

@@ -337,11 +337,12 @@ module Kward
 
       def question_overlay_rows(width)
         title = "Question #{@question_state[:index]}/#{@question_state[:total]} · #{@question_state[:header]}"
-        lines = [
-          overlay_text_line(@question_state[:question].to_s, :bold),
+        content_width = [overlay_card_width(width) - 4, 1].max
+        lines = question_text_rows(@question_state[:question], content_width, :bold)
+        lines.concat([
           overlay_text_line("↑/↓ select · Enter choose · Esc cancel", :muted),
           overlay_blank_line
-        ]
+        ])
         question_choices.each_with_index do |choice, index|
           selected = index == question_selection_index
           lines << overlay_choice_line(choice_text(choice, selected: selected), selected: selected)
@@ -349,6 +350,14 @@ module Kward
         overlay_card_rows(title, lines, width)
       end
 
+      def question_text_rows(text, width, style)
+        text.to_s.split("\n", -1).flat_map do |line|
+          wrapped = ANSI.wrap_visible(line, width)
+          wrapped = [""] if wrapped.empty?
+          wrapped.map { |row| overlay_text_line(row, style) }
+        end
+      end
+
       def choice_text(choice, selected: false)
         if choice[:custom]
           selected ? "Type a custom answer below." : "Type something."

data/lib/kward/prompt_interface.rb

@@ -25,6 +25,7 @@ require_relative "prompt_interface/file_overlay"
 require_relative "prompt_interface/project_browser"
 require_relative "prompt_interface/selection_prompt"
 require_relative "prompt_interface/question_prompt"
+require_relative "prompt_interface/approval_prompt"
 require_relative "prompt_interface/git_prompt"
 require_relative "prompt_interface/overlay_renderer"
 require_relative "prompt_interface/editor/renderer"
@@ -75,6 +76,7 @@ module Kward
     include ProjectBrowser
     include SelectionPrompt
     include QuestionPrompt
+    include ApprovalPrompt
     include GitPrompt
     include OverlayRenderer
     include EditorRenderer
@@ -362,6 +364,24 @@ module Kward
       run_editor
     end
 
+    # Opens an in-memory document editor. The callback receives edited content
+    # when the user saves; return an error message to keep the editor open.
+    def review_document(title:, content:, &on_save)
+      raise ArgumentError, "review_document requires a save callback" unless on_save
+
+      start(render: false)
+      opened = @mutex.synchronize do
+        @editor_save_callback = on_save
+        open_scratchpad(:markdown, content: content).tap do
+          @editor_state.status = "#{title} · Ctrl+S save · Ctrl+Q cancel"
+          render_prompt_locked
+        end
+      end
+      return false unless opened
+
+      run_editor
+    end
+
     def run_editor
       loop do
         key = read_key(nonblock: true)

data/lib/kward/prompts/commands.rb

@@ -33,7 +33,9 @@ module Kward
       { name: "tab", description: "Manage tabs.", argument_hint: "[1-n|move|close|new|name]" },
       { name: "status", description: "Show the current status message.", argument_hint: "" },
       { name: "stats", description: "Show telemetry logging stats.", argument_hint: "[range]" },
+      { name: "sandbox", description: "Inspect or configure model command sandboxing.", argument_hint: "[status|off|read_only|workspace_write|network allow|network deny]" },
       { name: "hooks", description: "Inspect lifecycle hooks.", argument_hint: "[list|events|logs|doctor|trust|untrust]" },
+      { name: "skill", description: "Activate a skill or capture one from a saved session.", argument_hint: "<name>|capture" },
       { name: "memory", description: "Inspect and manage Kward memory.", argument_hint: "[enable|disable|auto-summary|core|add|list|forget|promote|relax|inspect|why|summarize]" }
     ].freeze
     BUILTIN_RESERVED_COMMAND_NAMES = BUILTIN_COMMANDS.map { |command| command[:name] }.freeze

data/lib/kward/prompts.rb

@@ -38,6 +38,8 @@ module Kward
     # @return [Array<Hash>] section hashes with label, content, and optional source
     # @api public
     def prompt_sections(workspace_root: Dir.pwd, include_workspace_personality: true, model: nil, reasoning_effort: nil, now: Time.now, memory_context: nil, plugin_context: nil)
+      return replacement_prompt_sections if ConfigFiles.replacement_system_prompt?
+
       sections = [prompt_section("Built-in system prompt", base_prompt)]
       sections << prompt_section(config_agents_prompt_label, config_agents_prompt, source: config_agents_prompt_source)
       sections << prompt_section("Memory context", memory_context) unless memory_context.to_s.empty?
@@ -53,11 +55,11 @@ module Kward
 
     def base_prompt
       <<~PROMPT.strip
-        You are Kward, a concise practical CLI coding agent. Use tools to understand and modify software projects. Inspect files before changing them, make the smallest correct change, preserve existing style, and summarize what changed. Be honest about limitations.
+        You are Kward, a concise practical CLI coding agent. Use tools to understand and modify software projects. Only call tools advertised for the current turn. Inspect files before changing them, make the smallest correct change, preserve existing style, and summarize what changed. Be honest about limitations.
 
-        For web research, use web_search to discover sources, fetch_content for important human-readable pages, and fetch_raw for machine-readable resources such as JSON, YAML, XML, RSS, OpenAPI specs, and plain text. Prefer official or primary sources and cite or mention the URLs you relied on.
+        When web tools are available, use web_search to discover sources, fetch_content for important human-readable pages, and fetch_raw for machine-readable resources such as JSON, YAML, XML, RSS, OpenAPI specs, and plain text. Prefer official or primary sources and cite or mention the URLs you relied on. Use code_search for package, GitHub repository, and source-code research.
 
-        Manage code context deliberately. Prefer context_for_task, summarize_file_structure, and read_file mode="outline"/"preview" before broad reads. Escalate to read_file mode="range" for exact lines, and use mode="full" only when focused context is insufficient. Use context_budget_stats when asked about context savings.
+        Manage code context deliberately. Prefer context_for_task, summarize_file_structure, and read_file mode="outline"/"preview" before broad reads. Escalate to read_file mode="range" for exact lines, and use mode="full" only when focused context is insufficient. If output is compacted or replaced with a duplicate reference, use retrieve_tool_output to inspect the needed original detail. Use context_budget_stats when asked about context savings. When a material requirement is ambiguous, use ask_user_question when it is available; otherwise state the assumption.
       PROMPT
     end
 
@@ -73,6 +75,7 @@ module Kward
     end
 
     def config_agents_prompt_source
+      return nil unless ConfigFiles.include_config_principles?
       return ConfigFiles.config_principles_path if File.exist?(ConfigFiles.config_principles_path)
       return ConfigFiles.config_agents_path if File.exist?(ConfigFiles.config_agents_path)
 
@@ -112,6 +115,14 @@ module Kward
       "Workspace AGENTS.md hint"
     end
 
+    def replacement_prompt_sections
+      path = ConfigFiles.system_prompt_file_path
+      content = ConfigFiles.system_prompt_file
+      return [] if content.to_s.empty?
+
+      [prompt_section("Custom system prompt (replacement)", content, source: path)]
+    end
+
     def prompt_section(label, content, source: nil)
       return nil if content.to_s.empty?
 
@@ -123,8 +134,8 @@ module Kward
 
       lines = [
         "Agent Skills are available.",
-        "When a task matches a skill's description, use read_skill to load its instructions before proceeding.",
-        "Use read_skill with a relative path to read referenced files inside a skill directory.",
+        "When read_skill is available and a task matches a skill's description, use it to load the instructions before proceeding.",
+        "When using read_skill, use a relative path to read referenced files inside a skill directory.",
         "Available skills:"
       ]
       skills.each do |skill|