@sourcegraph/amp-sdk 0.1.0-20251014160341-g7c5de51 → 0.1.0-20251021152627-g8658f12

package/README.md

@@ -191,6 +191,38 @@ for await (const message of execute({
 }
 ```
 
+### Tool Permissions
+
+Control which tools Amp can use with fine-grained permissions:
+
+```typescript
+import { execute, createPermission } from '@sourcegraph/amp-sdk'
+
+for await (const message of execute({
+	prompt: 'List files and run tests',
+	options: {
+		permissions: [
+			// Allow listing files
+			createPermission('Bash', 'allow', { matches: { cmd: 'ls *' } }),
+			// Allow running tests
+			createPermission('Bash', 'allow', { matches: { cmd: 'npm test' } }),
+			// Ask before reading sensitive files
+			createPermission('Read', 'ask', { matches: { path: '/etc/*' } }),
+		],
+	},
+})) {
+	// Process messages
+}
+```
+
+Permission rules support:
+
+- **Pattern matching**: Use `*` wildcards and regex patterns
+- **Context control**: Restrict rules to main thread or sub-agents
+- **Delegation**: Delegate permission decisions to external programs
+
+Learn more about permissions in the [manual](https://ampcode.com/manual#permissions) and the [appendix](https://ampcode.com/manual/appendix#permissions-reference).
+
 ## Advanced Usage
 
 ### Interactive Progress Tracking

package/dist/index.d.ts

@@ -5,17 +5,16 @@
  * run Amp programmatically in Node.js applications. It wraps the Amp CLI
  * with the --stream-json flag to provide structured output.
  */
-import { type ExecuteOptions, type StreamMessage, type UserInputMessage } from './types.js';
-/**
- * Execute a command with Amp CLI and return an async iterator of messages
- *
- * @param options Execute configuration including prompt and options
- * @returns Async iterator of stream messages from Amp CLI
- */
+import { type ExecuteOptions, type Permission, type PermissionMatchCondition, type StreamMessage, type UserInputMessage } from './types.js';
+/** Execute a command with Amp CLI and return an async iterator of messages */
 export declare function execute(options: ExecuteOptions): AsyncIterable<StreamMessage>;
-/**
- * Helper function to create streaming input messages
- */
+/** Create a user input message for streaming conversations */
 export declare function createUserMessage(text: string): UserInputMessage;
+/** Create a permission object for controlling tool usage */
+export declare function createPermission(tool: string, action: 'allow' | 'reject' | 'ask' | 'delegate', options?: {
+    matches?: Record<string, PermissionMatchCondition>;
+    context?: 'thread' | 'subagent';
+    to?: string;
+}): Permission;
 export * from './types.js';
 //# sourceMappingURL=index.d.ts.map