## Configuration & Prompts


## HooksSettings


Base settings class for hook configuration, backed by environment variables with `HOOKS_` prefix.


Usage

``` python
HooksSettings()
```


## build_settings()


Build settings from a conf module via an explicit [HooksSettings](configuration-prompts.md#captain_hook.HooksSettings) subclass or auto-inferred fields.


Usage

``` python
build_settings(module, prefix="HOOKS_")
```


## Prompt


Fluent builder for structured LLM prompts with system text, XML context sections, and a question.


Usage

``` python
Prompt(*, system_text="", contexts=(), ask_text="")
```


Chain `.system()`, `.context(tag, content)`, and `.ask()` to build prompts. `str()` renders the full prompt with XML-wrapped context blocks. Context content is treated as untrusted data: any occurrence of a block's own tag delimiters inside its content is entity-escaped at render time, so embedded text can never close the block early and inject instructions outside it.


#### Parameter Attributes


`system_text: str = ``""`  

`contexts: tuple[tuple[str, str], …] = ()`    

`ask_text: str = ``""`  


#### Methods

| Name | Description |
|----|----|
| [from_template()](#captain_hook.Prompt.from_template) | Render `text` into a system-only prompt, substituting `{identifier}` placeholders from `vars`. |
| [load()](#captain_hook.Prompt.load) | Load a prompt from a `.md` file and render it via [from_template()](configuration-prompts.md#captain_hook.Prompt.from_template). |


##### from_template()


Render `text` into a system-only prompt, substituting `{identifier}` placeholders from `vars`.


Usage

``` python
from_template(text, **vars)
```


Only `{identifier}` (a brace-wrapped Python identifier) is a placeholder; every other brace is literal. JavaScript object braces (`{model: 'sonnet'}`), `${shell}` interpolations, empty `{}`, and doubled `{x}` braces all pass through unchanged -- there is no escape sequence and format specs are not placeholders. Substitution is single-pass, so inserted values are never re-scanned for further placeholders.


##### Parameters


`text: str`  
Template text; `{identifier}` placeholders are replaced, all other braces stay literal.

`**vars: object`  
Values for the `{identifier}` placeholders.


##### Returns


`A: `<a href="configuration-prompts.html#captain_hook.Prompt" class="gdls-link gdls-code"><code>Prompt</code></a>  
class:[Prompt](configuration-prompts.md#captain_hook.Prompt) whose system text is the rendered template.


##### Raises


`KeyError`  
If an `{identifier}` placeholder has no matching entry in `vars`.


##### load()


Load a prompt from a `.md` file and render it via [from_template()](configuration-prompts.md#captain_hook.Prompt.from_template).


Usage

``` python
load(name, *, base=None, **vars)
```


Resolution searches directories in order, returning the first existing file: the `base` directory if given (otherwise a `prompts/` directory beside the calling module), then the framework's bundled `captain_hook/prompts/`. The file path is `<dir>/<name>.md`; [name](files-commands.md#captain_hook.Call.name) may contain `/` to nest.


##### Parameters


`name: str`  
Prompt name without the `.md` suffix; may include `/` for nesting.

`base: str | Path | None = None`  
Optional directory to search instead of the caller-relative `prompts/`.

`**vars: object`  
Values for the file's `{identifier}` placeholders; every other brace (JS objects, `${...}`, `{...}`) stays literal (see [from_template()](configuration-prompts.md#captain_hook.Prompt.from_template)).


##### Returns


`A: `<a href="configuration-prompts.html#captain_hook.Prompt" class="gdls-link gdls-code"><code>Prompt</code></a>  
class:[Prompt](configuration-prompts.md#captain_hook.Prompt) whose system text is the rendered file contents.


##### Raises


`FileNotFoundError`  
If no matching file exists in any searched directory.

`KeyError`  
If the file references an `{identifier}` placeholder not supplied in `**vars`.